docs: add support for partial indexes (filtered indexes)#7478
docs: add support for partial indexes (filtered indexes)#7478jay-l-e-e wants to merge 6 commits intoprisma:mainfrom
Conversation
…support Add comprehensive documentation for the new `partialIndexes` preview feature, which enables `where` argument on `@@index`, `@@unique`, and `@unique` attributes for PostgreSQL, SQLite, SQL Server, and CockroachDB. Ref: prisma/prisma-engines#5749, prisma/prisma#6974
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughDocumentation adds Prisma Schema support for partial (filtered) indexes via a new Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Fix all issues with AI agents
In `@content/200-orm/050-overview/500-databases/800-sql-server/index.mdx`:
- Around line 257-258: The sentence mentions only @@unique and @@index but omits
field-level `@unique`; update the wording in the partialIndexes paragraph to list
all three supported attributes by adding "@unique" to the list so it reads
something like "`@@unique`, `@@index`, and `@unique`", referencing the
partialIndexes Preview feature and the `where` argument to keep the messaging
consistent with other docs (e.g., unsupported-database-features.mdx).
In `@content/200-orm/300-prisma-migrate/050-getting-started.mdx`:
- Around line 245-257: The description incorrectly calls the example a "stored
procedure" while the SQL defines a trigger function; update the prose to say it
"creates a trigger function" (or, if you intended a stored procedure, replace
the SQL to define a PROCEDURE instead). Specifically, align the text around the
example with the SQL that defines the function notify_on_insert() with RETURNS
TRIGGER and LANGUAGE plpgsql so readers aren’t confused about trigger functions
vs procedures.
In
`@content/200-orm/300-prisma-migrate/300-workflows/80-unsupported-database-features.mdx`:
- Around line 49-58: The description incorrectly calls the example a "stored
procedure" while the SQL defines a trigger function; update the copy that
precedes the SQL snippet to call it a "trigger function" (or simply "function")
so it matches the SQL which creates "CREATE OR REPLACE FUNCTION
notify_on_insert()" with "RETURNS TRIGGER", and ensure any surrounding
explanatory text refers to trigger functions rather than stored procedures.
In `@content/200-orm/500-reference/100-prisma-schema-reference.mdx`:
- Around line 2044-2057: The signature for `@unique` currently only shows the raw
form and should reflect both accepted forms; update the `@unique` (and similarly
@@unique and @@index) signature to include both where: raw(String)? and where:
object? (or use a union-like hint such as where: raw(String)? | object?) or add
a one-line note directly beneath each signature stating "where can be raw(\"SQL
expression\") or an object literal (e.g. { field: value })" so the table and
signature are consistent with the argument description.
🧹 Nitpick comments (4)
content/200-orm/300-prisma-migrate/300-workflows/80-unsupported-database-features.mdx (1)
18-28: Two adjacent tip blocks could be consolidated for better readability.Lines 18–22 and 24–28 render as two consecutive
:::tipcallouts. Merging them into a single tip would reduce visual clutter and read more naturally, since both are brief supplementary notes in the same introductory section.content/200-orm/100-prisma-schema/20-data-model/30-indexes.mdx (2)
546-582: SQL output tabs only cover the@@uniqueexample; consider adding the@@indextranslation too.The Prisma schema example on lines 546–556 defines two indexes — a
@@uniqueand a@@index— but the SQL tabs (lines 560–582) only show the generated SQL for the unique index. A reader following along might wonder what the@@indexwithWHERE "deletedAt" IS NULLcompiles to across each database. Adding a second SQL snippet (or a brief note that the pattern is analogous) would make this section self-contained.
660-676: Introspection section accurately reflects normalized PostgreSQL output.The example showing
raw("(status = 'active'::text)")with the parentheses and explicit::textcast is a helpful detail — it tells readers not to be surprised when the introspectedraw()string doesn't exactly match what they originally wrote. One minor observation: it might be worth adding a one-liner mentioning that SQLite and SQL Server introspection output may differ in form (e.g., no type cast), so readers on those databases aren't caught off guard.content/200-orm/500-reference/100-prisma-schema-reference.mdx (1)
2266-2280: Two consecutive notes produce identical "previous" signatures — consider merging.Lines 2270–2274 ("Before the
partialIndexesPreview feature") and lines 2276–2280 ("Before version 4.0.0, or before version 3.5.0 with theextendedIndexesPreview feature") both resolve to the exact same signature:@@unique(_ fields: FieldReference[], name: String?, map: String?)This is because the 4.0.0 GA signature already included
mapand didn't yet havewhere, making the "before partialIndexes" note a duplicate. Consider collapsing these into a single note, e.g.:Note: Before the
partialIndexesPreview feature (and before version 4.0.0 / 3.5.0 withextendedIndexes), the signature was: …This avoids readers seeing two identical blocks and wondering what the difference is.
content/200-orm/050-overview/500-databases/800-sql-server/index.mdx
Outdated
Show resolved
Hide resolved
content/200-orm/300-prisma-migrate/300-workflows/80-unsupported-database-features.mdx
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@content/200-orm/500-reference/100-prisma-schema-reference.mdx`:
- Around line 2268-2270: The @@unique signature is incorrectly formatted as a
blockquote; replace the leading ">" blockquote with a fenced code block like the
other signatures — wrap the line beginning with "@@unique(_ fields:
FieldReference[], name: String?, map: String?, where: raw(String) | { field:
value }?)" in a ```prisma no-lines ... ``` fenced code block (matching the style
used for `@unique` and @@index) so the @@unique signature renders consistently.
🧹 Nitpick comments (1)
content/200-orm/500-reference/100-prisma-schema-reference.mdx (1)
2272-2284: Two consecutive notes show the same previous @@unique signature — one is redundant.The "before the
partialIndexesPreview feature" note (lines 2274–2278) and the "before version 4.0.0" note (lines 2280–2284) both display the identical signature:@@unique(_ fields: FieldReference[], name: String?, map: String?)Because the pre-
partialIndexessignature is the same as the pre-4.0.0 signature, having both notes back-to-back is redundant and may confuse readers into thinking there were two distinct intermediate forms. Consider collapsing them into a single note, or removing thepartialIndexes-specific note since the 4.0.0 note already covers that state.For comparison, the
@@indexsection (lines 2528–2532) only has thepartialIndexes-specific note and the 3.0.0 note — and those actually show different signatures (mapvsname), so both are warranted there.
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
content/200-orm/500-reference/100-prisma-schema-reference.mdx (1)
2268-2284:⚠️ Potential issue | 🟡 MinorRedundant consecutive historical notes with identical signatures for
@@unique.Lines 2274–2278 ("Before the
partialIndexesPreview feature") and lines 2280–2284 ("Before version 4.0.0") show the exact same old signature:@@unique(_ fields: FieldReference[], name: String?, map: String?)Having two back-to-back notes with identical content will confuse readers who expect each note to convey a distinct change. Since the
@@uniquesignature didn't gain any new top-level parameters between 4.0.0 and the introduction ofpartialIndexes, I'd suggest removing the "before partialIndexes" note (lines 2274–2278) entirely — the 4.0.0 note already covers that era.Suggested fix
> **Note**: The `where` argument accepts either `raw("SQL expression")` for raw SQL predicates or an object literal like `{ field: value }` for type-safe conditions. See [Configuring partial indexes](/orm/prisma-schema/data-model/indexes#configuring-partial-indexes-with-where) for details. -> **Note**: Before the `partialIndexes` Preview feature, the signature was: -> -> ```prisma no-lines -> @@unique(_ fields: FieldReference[], name: String?, map: String?) -> ``` - > **Note**: Before version 4.0.0, or before version 3.5.0 with the `extendedIndexes` Preview feature enabled, the signature was:
🧹 Nitpick comments (1)
content/200-orm/500-reference/100-prisma-schema-reference.mdx (1)
2057-2061: Missingclusteredin the@uniquesignature, and no "before partialIndexes" historical note.Two things to consider here:
The arguments table (line 2049) documents
clusteredas a valid argument for@unique, but the signature on line 2057 omits it. Since this line was touched in this PR, it's a good opportunity to bring the signature in sync with the table.The
@@unique(line 2274) and@@index(line 2528) sections both include a "beforepartialIndexes" historical note showing the old signature. The@uniquesection lacks an equivalent note, which is an inconsistency readers comparing these sections would notice.Suggested fix
-@unique(map: String?, length: number?, sort: String?, where: raw(String) | { field: value }?) +@unique(map: String?, length: number?, sort: String?, clustered: Boolean?, where: raw(String) | { field: value }?)And consider adding a historical note analogous to the ones in
@@uniqueand@@index:> **Note**: Before the `partialIndexes` Preview feature, the signature was: > > ```prisma no-lines > `@unique`(map: String?, length: number?, sort: String?, clustered: Boolean?) > ```
|
@AmanVarshney01 @ArthurGamby Hi, The PR related to this documentation change has just been merged. Once this change is included in the next release, the docs will likely need to be updated as well. Since I’m not sure who is responsible for which section, I’ve tagged the two people who seemed most relevant. I would appreciate it if you could review the PR. Thank you! |
1 participant
Description
Add documentation for the new Partial Indexes (Filtered Indexes) feature, introduced via the
partialIndexesPreview feature flag (prisma/prisma-engines#5749).Partial indexes allow defining
WHEREconditions on@unique,@@unique, and@@indexattributes, supporting bothraw()SQL syntax and type-safe object literal syntax.Changes
New content
30-indexes.mdx— Added a new "Configuring partial indexes withwhere" section covering:partialIndexesPreview featureraw()SQL syntax with multi-database SQL output examples (PostgreSQL, SQLite, SQL Server)wherewith other index arguments (name,map)raw()output format)Reference updates
prisma-schema-reference.mdx— Addedwhereargument to@unique,@@unique, and@@indexargument tables and signatures; removed "Define partial indexes withWHERE" from@@indexunsupported features listclient-preview-features.mdx— AddedpartialIndexesto the currently active Preview features tabledatabase-features.mdx— UpdatedWHERErow in indexes table to reflect Prisma schema and Migrate supportRemoved outdated "unsupported" references
unsupported-database-features.mdx(schema) — Removed "partial indexes" from the unsupported features list; added tip pointing to the newwhereargumentunsupported-database-features.mdx(migrate) — Removed "Partial indexes" from the unsupported list; added tip; replaced partial index SQL example with stored proceduredevelopment-and-production.mdx— Replaced "partial index" with "trigger" in PSL limitation examplesnative-database-types.mdx— Replaced "partial index" with "trigger" in PSL limitation examplesgetting-started.mdx— Replaced partial index SQL snippet with stored procedure in baselining exampleDatabase-specific notes
sql-server/index.mdx— Added note aboutpartialIndexesPreview feature to the filtered index sectionRelated
Summary by CodeRabbit
New Features
Documentation
Migrations