From 797fe721a411989490e70255b0867351b6098f8f Mon Sep 17 00:00:00 2001 From: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> Date: Tue, 10 Sep 2024 14:57:18 +0200 Subject: [PATCH] feat: add optimize docs (#6159) * feat: add optimize to the sidebar * feat: add optimize in the getting started section * fix: add optimize url * feat: add optimize docs * fix: add optimize icons * feat: add more sections to optmize docs * feat: add optimize to footer * feat: add note on using optimize * fix: correct spelling for usecase * feat: add more on indexes * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Nikolas * Update content/700-optimize/400-recommendations.mdx Co-authored-by: Nikolas * Update content/700-optimize/400-recommendations.mdx Co-authored-by: Nikolas * Update content/700-optimize/400-recommendations.mdx Co-authored-by: Nikolas * Update content/700-optimize/400-recommendations.mdx Co-authored-by: Nikolas * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Nikolas * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Nikolas * Update content/700-optimize/200-getting-started.mdx * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Nikolas * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Nikolas * feat: add enhancements on recommendations * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Nikolas * Update content/700-optimize/300-recording.mdx Co-authored-by: Nikolas * Update content/700-optimize/300-recording.mdx Co-authored-by: Nikolas * fix: rename file to recordings * Update ormLinkSectionWrapper * feat: add ai explainer section to the docs * feat: add ai limitations for optimize * feat: add more faq items * feat: new content changes * fix: remove random line * fix: optimize api key section * feat: improve getting started section * fix: add more feedback * fix: broken link on ai-explainer * feat: add ms sql server to optimize * feat: update optimize url * feat: update API key getting steps * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/100-getting-started/index.mdx * Update content/100-getting-started/index.mdx * Update content/700-optimize/index.mdx * Update content/700-optimize/200-getting-started.mdx * feat: move optimize * fix: replace to prisma ai * fix: paraphrase to be more accurate * fix: clear recommendations page * enhance: add links * feat: more specific instructions * feat: add prisma queries * feat: add more limitations * Update content/700-optimize/index.mdx * Update content/700-optimize/index.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/700-optimize/400-recommendations/300-full-table-scans-caused-by-like-operations.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/700-optimize/400-recommendations/200-queries-on-unindexed-columns.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/700-optimize/200-getting-started.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * Update content/700-optimize/400-recommendations/100-excessive-number-of-rows-returned.mdx Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> * fix: update performance page * feat: add a limitation and an faq * Update content/700-optimize/index.mdx Co-authored-by: Ankur Datta <64993082+ankur-arch@users.noreply.github.com> * feat: add callout #DA-1328 * feat: make callout the main focus in getting started * fix: add links --------- Co-authored-by: carlagn Co-authored-by: Nikolas Co-authored-by: Jon Harrell <4829245+jharrell@users.noreply.github.com> --- cSpell.json | 3 +- content/100-getting-started/index.mdx | 23 ++++- .../100-query-optimization-performance.mdx | 10 +- content/500-platform/10-about.mdx | 27 ++++++ content/700-optimize/200-getting-started.mdx | 92 +++++++++++++++++++ content/700-optimize/300-recordings.mdx | 47 ++++++++++ .../100-excessive-number-of-rows-returned.mdx | 30 ++++++ .../200-queries-on-unindexed-columns.mdx | 85 +++++++++++++++++ ...-table-scans-caused-by-like-operations.mdx | 33 +++++++ .../400-recommendations/_category_.json | 4 + .../400-recommendations/index.mdx | 15 +++ content/700-optimize/450-prisma-ai.mdx | 18 ++++ .../700-optimize/500-performance-metrics.mdx | 29 ++++++ content/700-optimize/600-faq.mdx | 31 +++++++ .../700-optimize/700-known-limitations.mdx | 53 +++++++++++ content/700-optimize/index.mdx | 90 ++++++++++++++++++ docusaurus.config.ts | 9 +- sidebars.ts | 15 +++ src/components/GettingStarted/index.tsx | 15 +++ src/css/all.css | 4 + src/data/indexData.ts | 6 ++ src/pages/index.module.scss | 2 +- 22 files changed, 633 insertions(+), 8 deletions(-) create mode 100644 content/700-optimize/200-getting-started.mdx create mode 100644 content/700-optimize/300-recordings.mdx create mode 100644 content/700-optimize/400-recommendations/100-excessive-number-of-rows-returned.mdx create mode 100644 content/700-optimize/400-recommendations/200-queries-on-unindexed-columns.mdx create mode 100644 content/700-optimize/400-recommendations/300-full-table-scans-caused-by-like-operations.mdx create mode 100644 content/700-optimize/400-recommendations/_category_.json create mode 100644 content/700-optimize/400-recommendations/index.mdx create mode 100644 content/700-optimize/450-prisma-ai.mdx create mode 100644 content/700-optimize/500-performance-metrics.mdx create mode 100644 content/700-optimize/600-faq.mdx create mode 100644 content/700-optimize/700-known-limitations.mdx create mode 100644 content/700-optimize/index.mdx diff --git a/cSpell.json b/cSpell.json index 3f7734f70c..d33f8cd6b2 100644 --- a/cSpell.json +++ b/cSpell.json @@ -100,7 +100,8 @@ "Nikolas", "Supavisor", "inshellisense", - "janedoe" + "janedoe", + "unindexed" ], "patterns": [ { diff --git a/content/100-getting-started/index.mdx b/content/100-getting-started/index.mdx index b16fcc0d07..06dd149a1e 100644 --- a/content/100-getting-started/index.mdx +++ b/content/100-getting-started/index.mdx @@ -13,6 +13,7 @@ import { Bolt, BorderBox, BoxTitle, + Inspect, Database, Grid, LinkCard, @@ -33,11 +34,12 @@ Explore our products that make it easy to build and scale data-driven applicatio [**Prisma ORM**](/orm/overview/introduction/what-is-prisma) is a next-generation Node.js and TypeScript ORM that unlocks a new level of developer experience when working with databases thanks to its intuitive data model, automated migrations, type-safety & auto-completion. +[**Prisma Optimize**](/optimize/) helps you analyze queries, generate insights, and provides recommendations to make your database queries faster. + [**Prisma Accelerate**](/accelerate) is a global database cache with scalable connection pooling to make your queries fast. [**Prisma Pulse**](/pulse) allows you to react to database changes with type-safe model streams in real-time. - @@ -195,3 +197,22 @@ Build real-time applications by subscribing to data changes in your database usi link="https://github.com/prisma/prisma-examples?tab=readme-ov-file#prisma-pulse" /> + +## Prisma Optimize + +Make your database queries faster by using the insights and recommendations generated by Prisma Optimize. + + + + + diff --git a/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx b/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx index ec29e1502c..d9d8bd4461 100644 --- a/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx +++ b/content/200-orm/200-prisma-client/100-queries/100-query-optimization-performance.mdx @@ -5,15 +5,17 @@ metaDescription: 'How Prisma optimizes queries under the hood' tocDepth: 3 --- - - This guide describes ways to optimize query performance, debug performance issues, and how to tackle common performance issues such as the [n+1 problem](#solving-the-n1-problem). - +:::tip + +To debug slow queries, you can use [Prisma Optimize](/optimize) and follow the [recommendations](/optimize/recommendations) provided to improve query performance in your app. + +::: ## Debugging performance issues -To help you debug and diagnose performance issues, you can [log query events at client level](/orm/prisma-client/observability-and-logging/logging#event-based-logging), which allows you to see the generated queries, parameters, and durations. +To help you debug and diagnose performance issues, you can [log query events at client level](/orm/prisma-client/observability-and-logging/logging#event-based-logging), which allows you to see the generated queries, parameters, and durations. Alternatively, if you are only interested in the time taken to run a query, you can implement [logging middleware](/orm/prisma-client/client-extensions/middleware/logging-middleware). diff --git a/content/500-platform/10-about.mdx b/content/500-platform/10-about.mdx index bbebf30d48..8101b778d9 100644 --- a/content/500-platform/10-about.mdx +++ b/content/500-platform/10-about.mdx @@ -42,6 +42,33 @@ In each workspace, you can: - manage billing, i.e. select a [subscription plan](https://www.prisma.io/pricing?utm_source=docs&utm_medium=platform-docs), configure payment methods, or view the invoice history. - view the usage of your enabled PDP products across all projects in that workspace. - invite other users to collaborate in the workspace. +- access the [Optimize dashboard](https://console.prisma.io/optimize?utm_source=docs&utm_medium=optimize-docs) to measure query performance and receive AI-powered recommendations. + +#### Optimize + +You can access Optimize within your [Prisma Data Platform account](https://console.prisma.io/optimize) workspace. + +##### Accessing the Optimize dashboard + +To access the Optimize dashboard in your desired workspace: + +1. Click the **Optimize** tab on the left navigation. +2. Click the **Launch Optimize** button. + +##### Generating an Optimize API key + +To obtain the Optimize API key: + +1. Navigate to the workspace where you want to use Optimize. +2. Ensure that Optimize is launched. If it isn't, click the **Launch Optimize** button. +3. If it isn't launched, spot the text in the Optimize dashboard that says, "Start by creating your first API key __here__ and start using Optimize," and click the __here__ link. +4. Click your profile name in the top right corner of the navbar. +5. Select **Settings**. +6. Click **Create API key**. +7. Enter a name for the API key in the **Name** field, then click **Create**. +8. Copy the API key and store it securely. This will be used in your project's [`.env` file](/optimize/getting-started#23-add-the-optimize-api-key-to-your-env-file) via the `"OPTIMIZE_API_KEY"`. Finally, click the **"I've stored it securely"** button. + +You now have your Optimize API key. ### Project diff --git a/content/700-optimize/200-getting-started.mdx b/content/700-optimize/200-getting-started.mdx new file mode 100644 index 0000000000..dbb83d0b18 --- /dev/null +++ b/content/700-optimize/200-getting-started.mdx @@ -0,0 +1,92 @@ +--- +title: 'Getting Started' +metaTitle: 'Getting started with Prisma Optimize' +metaDescription: 'Learn how to quickly set up and start using Prisma Optimize.' +tocDepth: 3 +toc: true +--- + +## Prerequisites + +Before you begin with Prisma Optimize, ensure you have the following: + +- A [Prisma Data Platform account](https://console.prisma.io). +- A project using [Prisma Client](/orm/prisma-client) version `5.0.0` or higher (we recommend using the latest version). +- A PostgreSQL, MySQL/MariaDB, CockroachDB, or MS SQL Server database. + +:::note + +Prisma Optimize is intended for use in local environments. Learn more in the [FAQ](/optimize/faq#can-i-use-prisma-optimize-in-production). + +::: + +## 1. Launch Optimize + +1. Log in to your [Prisma Data Platform account](https://console.prisma.io/optimize?utm_source=docs&utm_medium=optimize-page). +2. Follow the instructions to access and launch Prisma Optimize. + +## 2. Add Optimize to your application + +### 2.1. Update Your `schema.prisma` file + +In the `generator` block of your Prisma schema, add the `tracing` preview feature: + +```prisma +generator client { + provider = "prisma-client-js" + previewFeatures = ["tracing"] +} +``` + +Then, generate the Prisma Client: + +```bash +npx prisma generate +``` + +### 2.2. Install the Optimize Prisma Client extension + +Install the latest versions of Prisma Client and the Optimize extension: + +```bash +npm install @prisma/client@latest @prisma/extension-optimize +``` + +### 2.3. Add the Optimize API Key to your `.env` file + +Generate a Prisma Optimize API key and add it to your `.env` file: + +```bash +OPTIMIZE_API_KEY="YOUR_OPTIMIZE_API_KEY" +``` + +### 2.4. Extend your Prisma Client instance + +Extend your existing Prisma Client instance with the Optimize extension: + +```ts +import { PrismaClient } from "@prisma/client"; +import { withOptimize } from "@prisma/extension-optimize"; + +const prisma = new PrismaClient().$extends( + withOptimize({ token: process.env.OPTIMIZE_API_KEY }), +); +``` + +### 2.5. Use Prisma Optimize to generate insights + +Follow these steps to start generating query insights with Prisma Optimize: + +1. In the Optimize dashboard, click the **Start recording** button, then run your app and execute some Prisma queries while recording is active. +2. After your app runs and generates insights based on the executed Prisma queries, click the **Stop recording** button. +3. Explore [individual query details](/optimize/recordings#data-captured-in-a-recording-session) by clicking on them, and check the **Recommendations** tab for any suggested improvements to enhance query performance. + + :::info + Use [Prisma AI](/optimize/prisma-ai) to understand recommendations and apply them within your Prisma model context. + ::: + +For a hands-on learning experience, try out the [step-by-step example](https://github.com/prisma/prisma-examples/tree/latest/optimize/starter). + +## Need help? + +If you need assistance, reach out in the `#help-and-questions` channel on our [Discord](https://pris.ly/discord), or connect with our community to see how others are using Optimize. diff --git a/content/700-optimize/300-recordings.mdx b/content/700-optimize/300-recordings.mdx new file mode 100644 index 0000000000..2ae1727832 --- /dev/null +++ b/content/700-optimize/300-recordings.mdx @@ -0,0 +1,47 @@ +--- +title: 'Recordings' +metaTitle: 'Optimize: Recordings' +metaDescription: "Learn about using Optimize's recording feature." +tocDepth: 3 +toc: true +--- + +The recordings feature helps developers debug and isolate sets of queries into distinct sessions, known as recordings. This targeted approach enables precise performance analysis and optimization by preventing the mixing of queries from different applications or test rounds, leading to clearer insights and more effective debugging. + +## Managing a recording session + +You can manually start and stop recording sessions via the [Optimize dashboard](https://console.prisma.io/optimize) by clicking the **Start Recording** and **Stop Recording** buttons. + +:::warning +A recording will automatically stop if the 10k query limit is reached or if the Prisma schema of the app is changed. +::: + +## Identifying a recording session + +You can rename and tag your recording sessions for easy identification and context. Click on the default name of the session and type the desired name. + +## Data captured in a recording session + +Each recording session captures detailed insights about the queries executed in your app, including: + +- All queries executed during the session. +- The raw query generated and sent to the database by Prisma ORM as **Raw Query**. +- The number of times a query pattern was executed, listed as **Count**. +- [Query performance metrics](/optimize/performance-metrics). +- Errors encountered during query execution. + +Each recording can include up to 10k queries. There are no limits on storage retention. + +## Recommendations from a recording session + +When a recording session ends, Optimize generates recommendations such as: + +- [Excessive number of rows returned](/optimize/recommendations/excessive-number-of-rows-returned) +- [Full table scans caused by LIKE operations](/optimize/recommendations/full-table-scans-caused-by-like-operations) +- [Queries on unindexed columns](/optimize/recommendations/queries-on-unindexed-columns) + +:::info +Use [Prisma AI](/optimize/prisma-ai) to ask follow-up questions about a recommendation. +::: + +Learn more about the recommendations generated by Optimize [here](/optimize/recommendations). diff --git a/content/700-optimize/400-recommendations/100-excessive-number-of-rows-returned.mdx b/content/700-optimize/400-recommendations/100-excessive-number-of-rows-returned.mdx new file mode 100644 index 0000000000..45c2f128f8 --- /dev/null +++ b/content/700-optimize/400-recommendations/100-excessive-number-of-rows-returned.mdx @@ -0,0 +1,30 @@ +--- +title: 'Excessive number of rows returned' +metaTitle: 'Optimize Recommendations: Excessive number of rows returned' +metaDescription: "Learn about the recommendation provided by Optimize for excessive number of rows returned." +tocDepth: 3 +toc: true +--- + +Optimize provides recommendations to help you identify and resolve performance issues caused by excessive number of rows returned from a query. + +The following query targeting a `User` model does not provide a [`take` option](/orm/reference/prisma-client-reference#findmany): + +```ts +await prisma.user.findMany({ where: { email: "janedoe@gmail.com" }}) +``` + +## What is the problem? + +When a query is executed without specifying a limit, it will return all relevant rows, which can lead to several issues: + +### User experience + +- **Viewing data:** Users typically need only a portion of the data at any given time, not all of it at once. +- **Impact on the user's device:** Displaying all the data at once can strain the user's device resources. For example, loading thousands of rows in a web application can slow down or freeze the browser, consuming significant memory and CPU resources. +- **Waiting time:** Retrieving a large number of rows can significantly increase the time it takes to get the data from the database to the user's device. + +### Resource Utilization + +- **Unnecessary data load:** Processing more data than required wastes valuable resources. +- **Memory usage:** Excessive memory consumption can lead to inefficiency and, in severe cases, cause the system to run out of memory, disrupting the service. diff --git a/content/700-optimize/400-recommendations/200-queries-on-unindexed-columns.mdx b/content/700-optimize/400-recommendations/200-queries-on-unindexed-columns.mdx new file mode 100644 index 0000000000..26b6225236 --- /dev/null +++ b/content/700-optimize/400-recommendations/200-queries-on-unindexed-columns.mdx @@ -0,0 +1,85 @@ +--- +title: 'Queries on unindexed columns' +metaTitle: 'Optimize Recommendations: Queries on unindexed columns' +metaDescription: "Learn about the recommendation provided by Optimize for queries on unindexed columns." +tocDepth: 3 +toc: true +--- + +Optimize provides recommendations to help you identify and resolve performance issues caused by missing database indexes. + +The following queries targeting the `User` model use a [`where` property](/orm/prisma-client/queries/filtering-and-sorting) to filter on columns that do not have indexes: + +```ts +await prisma.user.findFirst({ + where: { + name: "Marc" + } +}) + +await prisma.user.findFirst({ + where: { + name: "Jon" + } +}) + +await prisma.user.count({ + where: { + name: "Nikolas" + } +}) +``` + +## What is the problem? + +An index allows the database to retrieve data more quickly, similar to how an index in a book helps you locate information without reading every page. + +When using Prisma with a `where` property, if no indexes are defined for the relevant columns, the database may need to scan every row in the table (a *“full table scan”*) to find matches. This can be undesirable for several reasons: + +### User experience + +For large datasets, if the database must scan the entire table to find matching rows, users will experience longer waiting times. + +### Resource utilization + +- **High CPU usage:** Scanning large tables can significantly increase CPU usage, degrading overall system performance. +- **Memory consumption:** More memory is required to process and store data during a full table scan. +- **Disk I/O:** Full table scans increase disk input/output operations, potentially slowing down other database activities. + +:::warning + +While these issues might not appear in development due to smaller datasets, they can become *significant* problems in production, where datasets are typically much larger. + +::: + + +## More on database indexes + +### How indexes work + +Indexes create a data structure that stores the indexed column's values along with pointers to the corresponding rows in the table. When you query the database using an indexed column, the database can use this index to quickly locate the relevant rows instead of scanning the entire table. + +### The trade-offs of indexing + +- **Space vs. time:** Indexing requires additional storage space to save index data, but it significantly speeds up data retrieval. +- **Update overhead:** Every time data is added to, updated in, or removed from your table, there is an overhead to keep the indexes up to date, which can slow down write operations. + +### When to use indexes + +- **Large datasets:** Indexes are particularly beneficial for tables with a large number of rows. +- **Frequent queries with filtering or sorting:** Use indexes on columns that are frequently used for [filtering or sorting](/orm/prisma-client/queries/filtering-and-sorting#filtering). +- **Looking up related data:** Use indexes on foreign key columns to speed up the retrieval of related records, such as when using [`include`](/orm/prisma-client/queries/relation-queries#include-a-relation). + +### When not to use indexes + +- **Small tables:** For tables with very few rows, the overhead of maintaining indexes might not be worth the performance gain. +- **Write-heavy tables:** Indexes can slow down write operations (`create`, `update`, `delete`) because the index needs to be updated as well. Avoid excessive indexing on models with frequent write operations. +- **Infrequently accessed tables:** If a table is rarely accessed, the benefits of indexing may not justify the overhead. +- **Columns with large data:** Indexing columns with large data can lead to higher storage requirements and might not provide significant performance improvements. +- **Rarely filtered columns:** If a table is often accessed but rarely filtered by a specific column, creating an index on that column may not be beneficial. + +:::warning + +Even if you index a column, the database may not always use it. Many database management systems, such as PostgreSQL and MySQL, have a *query optimizer* that evaluates multiple execution plans and selects the one it estimates to be most efficient. In some cases, this may involve ignoring an existing index in favor of a different execution plan that it determines will perform better for that specific query. + +::: \ No newline at end of file diff --git a/content/700-optimize/400-recommendations/300-full-table-scans-caused-by-like-operations.mdx b/content/700-optimize/400-recommendations/300-full-table-scans-caused-by-like-operations.mdx new file mode 100644 index 0000000000..312f879849 --- /dev/null +++ b/content/700-optimize/400-recommendations/300-full-table-scans-caused-by-like-operations.mdx @@ -0,0 +1,33 @@ +--- +title: 'Full table scans caused by LIKE operations' +metaTitle: 'Optimize Recommendations: Full table scans caused by LIKE operations' +metaDescription: "Learn about the recommendation provided by Optimize for full table scans caused by Like operations." +tocDepth: 3 +toc: true +--- + +Optimize provides recommendations to help you identify and resolve performance issues caused by full table scans from `LIKE` operations. + +The following query targeting the `User` model provides `contains` and `endsWith` as options, which translate to `LIKE` and `ILIKE` SQL operators. + +```jsx +await prisma.user.findMany({ + where: { + email: { contains: "gmail.com" }, + name: { endsWith: "Burk" } + } +}) +``` + +## What is the problem? + +`LIKE` and `ILIKE` operators in SQL can lead to full table scans, potentially impacting performance, especially with larger datasets: + +### UX + +- **Slower load times:** Full table scans can significantly increase the time it takes to retrieve data, leading to longer wait times for users. + +### Resource utilization + +- **Increased resource usage:** Full table scans increase CPU, memory usage, and disk I/O, straining system resources for your database. +- **Increased costs:** In serverless database pricing plans, more intensive resource usage can translate into higher costs. diff --git a/content/700-optimize/400-recommendations/_category_.json b/content/700-optimize/400-recommendations/_category_.json new file mode 100644 index 0000000000..258ab00c98 --- /dev/null +++ b/content/700-optimize/400-recommendations/_category_.json @@ -0,0 +1,4 @@ +{ + "collapsed": false, + "collapsible": false +} diff --git a/content/700-optimize/400-recommendations/index.mdx b/content/700-optimize/400-recommendations/index.mdx new file mode 100644 index 0000000000..cb86fc11bf --- /dev/null +++ b/content/700-optimize/400-recommendations/index.mdx @@ -0,0 +1,15 @@ +--- +title: 'Recommendations' +metaTitle: 'Optimize: Recommendations' +metaDescription: "Learn about the recommendations provided by Optimize." +tocDepth: 3 +toc: true +--- + +Optimize provides recommendations focused on performance improvements such as indexing issues, excessive data retrieval, and inefficient query patterns. Recommendations include: + +:::info +Use [Prisma AI](/optimize/prisma-ai) to ask follow-up questions about any recommendation. +::: + + diff --git a/content/700-optimize/450-prisma-ai.mdx b/content/700-optimize/450-prisma-ai.mdx new file mode 100644 index 0000000000..188aba804a --- /dev/null +++ b/content/700-optimize/450-prisma-ai.mdx @@ -0,0 +1,18 @@ +--- +title: 'Prisma AI' +metaTitle: 'Optimize: Prisma AI' +metaDescription: "Learn about using Optimize's Prisma AI feature." +tocDepth: 3 +toc: true +--- + +Prisma AI enables you to ask follow-up questions on a provided [recommendation](/optimize/recommendations) for additional clarity. + +## Using the Prisma AI + +To interact with the Prisma AI: + +1. Select a recommendation from an Optimize [recording](/optimize/recordings). +2. Click the **Ask AI** button. + +Prisma AI helps you gain deeper insights into a recommendation and learn how to apply it effectively to your Prisma model. \ No newline at end of file diff --git a/content/700-optimize/500-performance-metrics.mdx b/content/700-optimize/500-performance-metrics.mdx new file mode 100644 index 0000000000..b636f2fd30 --- /dev/null +++ b/content/700-optimize/500-performance-metrics.mdx @@ -0,0 +1,29 @@ +--- +title: 'Performance metrics' +metaTitle: 'Optimize: Query performance metrics' +metaDescription: 'Learn about the query performance metrics provided by Optimize.' +tocDepth: 3 +toc: true +--- + +An Optimize recording session provides detailed insights into the latencies of executed queries, capturing key metrics such as average duration, 50th percentile, 99th percentile, and maximal query execution time. + +## Total query durations + +Prisma Optimize measures total latency for query patterns, enabling you to analyze and debug slow queries effectively. + +### Average query duration (**`AVG`**) + +The average query duration reveals the mean execution time across all queries, helping you assess overall performance trends and identify inefficiencies that impact the user experience. + +### 50th percentile (**`P50`**) + +The 50th percentile, or median, query duration indicates the time within which half of your queries complete. This metric offers a clear view of typical user performance, unaffected by outliers. + +### 99th percentile (**`P99`**) + +The 99th percentile query duration highlights the execution time for the slowest 1% of queries. This metric is crucial for uncovering and addressing performance bottlenecks that, while infrequent, can significantly impact user satisfaction. + +### Maximal query duration (**`MAX`**) + +The maximal query duration measures the time taken by the single slowest query. This metric helps identify extreme cases, providing insights into the worst performance scenarios your system might face, so you can diagnose and resolve outliers. diff --git a/content/700-optimize/600-faq.mdx b/content/700-optimize/600-faq.mdx new file mode 100644 index 0000000000..c2e97c8d90 --- /dev/null +++ b/content/700-optimize/600-faq.mdx @@ -0,0 +1,31 @@ +--- +title: "FAQ" +metaTitle: "Prisma Optimize: FAQ" +metaDescription: "Frequently asked questions about Prisma Optimize." +tocDepth: 3 +toc: true +--- + +## Does Optimize automatically implement optimizations? + +Prisma Optimize offers insights and recommendations on how to improve your database queries. It does not alter any existing queries or your Prisma schema. + +## How long is a recording session retained in Optimize? + +There are no limits on the storage retention period. Optimize will store a recording session until you explicitly delete it. + +## Do recommendation limits reset monthly? + +Yes, the recommendation usage resets at the beginning of each calendar month. For example, if you use 5 recommendations by the end of the month, your usage will reset to 0 at the start of the next month. + +## Can I get charged for exceeding the recommendation limit on the starter plan? + +Yes, if you’re on the starter plan, exceeding 5 recommendations in a billing cycle will result in a $5 charge at the end of that cycle. For more information, visit [our pricing page](https://www.prisma.io/pricing#optimize). + +## How does Optimize track viewed recommendations for billing? Are they counted based on generated or viewed recommendations? + +They are counted based on viewed recommendations. Once you click on a recommendation from the recommendations table and view the recommendation's detail page, it counts as being seen. + +## Can I use Prisma Optimize in production? + +No, Prisma Optimize is not intended for production use. It is specifically designed for local development, providing valuable insights and optimizations during that phase. While it’s technically possible to run it in a production environment, doing so could result in performance problems or unexpected behaviors, as Optimize is not built to handle the complexity and scale of production workloads. For the best experience, we recommend using Prisma Optimize solely in your development environment. \ No newline at end of file diff --git a/content/700-optimize/700-known-limitations.mdx b/content/700-optimize/700-known-limitations.mdx new file mode 100644 index 0000000000..e2d4a25363 --- /dev/null +++ b/content/700-optimize/700-known-limitations.mdx @@ -0,0 +1,53 @@ +--- +title: 'Known limitations' +metaTitle: 'Optimize: Known limitations' +metaDescription: 'Learn about known limitations of Optimize.' +tocDepth: 3 +toc: true +--- + +Below are the known limitations when using Prisma Optimize. If you are aware of any limitations that are missing, please let us know on the `#help-and-questions` channel in our community [Discord](https://pris.ly/discord). + +## Query limit on a recording session + +Each [recording session](/optimize/recordings) can contain a maximum of 10,000 queries. Once this limit is reached, the recording session will end. + +## Recording limit per workspace + +Each [workspace](/platform/about#workspace) can contain a maximum of 100 [recordings](/optimize/recordings). + +## Scope and constraints for the Prisma AI + +While [Prisma AI](/optimize/prisma-ai) can provide helpful guidance to implement a [recommendation](/optimize/recommendations), there are some important limitations to keep in mind: + +- **Information and accuracy**: The AI provides advice based on a broad, general knowledge base and does not have direct access to Prisma ORM documentation. This may occasionally result in inaccuracies or outdated information. + +- **Limited context and adaptation**: The AI does not persist conversations or learn from previous interactions. Its responses are generalized and may not always address the specific needs of advanced users. + +- **Static knowledge and scope**: The AI's knowledge is static and may not include recent updates or best practices after a certain date. It provides advice only within the context of Prisma ORM and cannot modify or execute code, nor interact directly with user environments. + +## Using Prisma Accelerate client extension with the Optimize extension + +When using the [Optimize client extension](https://www.npmjs.com/package/@prisma/extension-optimize) with the [Accelerate client extension](https://www.npmjs.com/package/@prisma/extension-accelerate), ensure the Accelerate client extension is added last to your extended `PrismaClient`. This allows cacheable operations to be received by Optimize. + +```ts +const prisma = new PrismaClient() + .$extends( + withOptimize({ + token: process.env.OPTIMIZE_API_KEY, + }), + ) + .$extends(withAccelerate()); +``` + +### SQL references in MongoDB recommendations + +Prisma Optimize provides helpful recommendations for MongoDB users, though some explanations from [Prisma AI](/optimize/prisma-ai) may reference SQL-specific concepts. However, the [recommendations](/optimize/recommendations) remain useful and applicable to MongoDB environments. + +### Raw query visibility in MongoDB + +Raw queries are visible in MongoDB, though the parameters passed to them are not displayed. + +## Driver adapter compatibility + +Prisma Optimize is not yet compatible with [driver adapters](/orm/overview/databases/database-drivers#driver-adapters). However, as a workaround, you can run your queries locally using the regular Prisma Client along with Prisma Optimize to inspect and improve query performance. \ No newline at end of file diff --git a/content/700-optimize/index.mdx b/content/700-optimize/index.mdx new file mode 100644 index 0000000000..5b3d2cf93a --- /dev/null +++ b/content/700-optimize/index.mdx @@ -0,0 +1,90 @@ +--- +title: 'Optimize' +metaTitle: 'Prisma Optimize' +metaDescription: 'Prisma Optimize is a tool that helps you generate insights on your queries and recommends performance optimizations.' +sidebar_position: 0 +hide_table_of_contents: false +pagination_next: 'optimize/getting-started' +--- + +import { + Bolt, + BorderBox, + BoxTitle, + Database, + Grid, + LinkCard, + List, + SignalStream, + SquareLogo, +} from '@site/src/components/GettingStarted'; + +import { + IconTitle +} from '@site/src/components/shortcodes/index'; + + +Prisma Optimize + +[Prisma Optimize](https://www.prisma.io/data-platform/optimize?utm_source=docs). helps you generate insights and provides recommendations that can help you make your database queries faster. + +This helps you to: + +- Generate insights about your database queries +- Identify errors to help debug your database queries +- Receive recommendations and discuss them with an AI assistant to enhance query performance. + +Optimize aims to help developers of all skill levels write efficient database queries, reducing database load and making applications more responsive. + + + + + + + +## Supported databases + +Optimize works with the database you already have. + + + + + + + + + +## In this section + + diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 8f9d2bf9d5..6758168dd7 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -157,6 +157,13 @@ const config: Config = { className: "indigo", label: "ORM", }, + { + type: "docSidebar", + sidebarId: "optimizeSidebar", + position: "left", + className: "teal", + label: "Optimize", + }, { type: "docSidebar", sidebarId: "accelerateSidebar", @@ -264,7 +271,7 @@ const config: Config = { }, { label: "Optimize", - href: "https://www.prisma.io/blog/prisma-optimize-early-access", + href: "https://www.prisma.io/data-platform/optimize", target: "_self", customProps: { internal: true, diff --git a/sidebars.ts b/sidebars.ts index 9499130022..44118253a9 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -320,6 +320,21 @@ const sidebars: SidebarsConfig = { }, platformCategory, ], + optimizeSidebar: [ + { + type: "category", + label: "Optimize", + collapsible: false, + collapsed: false, + link: { + type: "doc", + id: "optimize/index", + }, + className: "firstTitle", + items: [{ type: "autogenerated", dirName: "700-optimize" }], + }, + platformCategory, + ], platformSidebar: [platformCategory], aboutSidebar: [ { diff --git a/src/components/GettingStarted/index.tsx b/src/components/GettingStarted/index.tsx index e2235cdaa0..7599f86d6b 100644 --- a/src/components/GettingStarted/index.tsx +++ b/src/components/GettingStarted/index.tsx @@ -36,6 +36,21 @@ export const Bolt = ({ color, width, height }: any) => ( ); +export const Inspect = ({ color, width, height }: any) => ( + + + +); + export const SignalStream = ({ color, height, width }: any) => (