索引
Prisma ORM 允许配置数据库索引、唯一约束和主键约束。此功能在 4.0.0
及更高版本中已正式可用。你可以在 3.5.0
及更高版本中通过 extendedIndexes
预览功能启用它。
版本 3.6.0
还通过新的 @@fulltext
属性引入了对 MySQL 和 MongoDB 中全文索引的内省和迁移支持,该属性可通过 fullTextIndex
预览功能使用。
如果你从低于 4.0.0 的版本升级,并且你的数据库已经使用了这些功能,那么索引配置和全文索引的这些更改可能会是重大更改。有关如何升级的更多信息,请参阅从以前版本升级。
索引配置
你可以使用以下属性参数配置索引、唯一约束和主键约束
-
length
参数允许你为String
和Bytes
类型索引值子部分的长度指定最大值- 适用于
@id
、@@id
、@unique
、@@unique
和@@index
属性 - 仅限 MySQL
- 适用于
-
sort
参数允许你指定约束或索引条目在数据库中的存储顺序- 适用于所有数据库中的
@unique
、@@unique
和@@index
属性,以及 SQL Server 中的@id
和@@id
属性
- 适用于所有数据库中的
-
type
参数允许你支持 PostgreSQL 默认BTree
访问方法以外的索引访问方法- 适用于
@@index
属性 - 仅限 PostgreSQL
- 支持的索引访问方法:
Hash
、Gist
、Gin
、SpGist
和Brin
- 适用于
-
clustered
参数允许你配置约束或索引是聚集还是非聚集的- 适用于
@id
、@@id
、@unique
、@@unique
和@@index
属性 - 仅限 SQL Server
- 适用于
有关每个功能首次引入的版本,请参阅相关部分。
使用 length
配置索引长度 (MySQL)
length
参数是 MySQL 特有的,允许你对 String
和 Byte
类型的列定义索引和约束。对于这些类型,如果完整值超出 MySQL 的索引大小限制,MySQL 要求你指定索引值子部分的最大长度。有关更多详细信息,请参阅 MySQL 文档。
length
参数适用于 @id
、@@id
、@unique
、@@unique
和 @@index
属性。它在 4.0.0 及更高版本中已正式可用,并在 3.5.0 及更高版本中作为 extendedIndexes
预览功能的一部分提供。
例如,以下数据模型声明了一个最大长度为 3000 个字符的 id
字段
model Id {
id String @id @db.VarChar(3000)
}
这在 MySQL 中无效,因为它超出了 MySQL 的索引存储限制,因此 Prisma ORM 拒绝此数据模型。生成的 SQL 将被数据库拒绝。
CREATE TABLE `Id` (
`id` VARCHAR(3000) PRIMARY KEY
)
length
参数允许你指定只有 id
值的一部分代表主键。在下面的示例中,使用了前 100 个字符
model Id {
id String @id(length: 100) @db.VarChar(3000)
}
如果你的数据模型中指定了 length
参数,Prisma Migrate 能够创建带有此参数的约束和索引。这意味着你可以在 Prisma schema 的 Byte
和 String
类型值上创建索引和约束。如果你不指定该参数,则该索引仍将覆盖完整值。
内省将获取现有数据库中存在的这些限制。这使得 Prisma ORM 能够支持以前被抑制的索引和约束,从而更好地支持使用此功能的 MySQL 数据库。
length
参数也可以用于复合主键,使用 @@id
属性,如以下示例所示
model CompoundId {
id_1 String @db.VarChar(3000)
id_2 String @db.VarChar(3000)
@@id([id_1(length: 100), id_2(length: 10)])
}
@@unique
和 @@index
属性可以使用类似的语法。
使用 sort
配置索引排序顺序
sort
参数适用于 Prisma ORM 支持的所有数据库。它允许你指定索引或约束的条目在数据库中的存储顺序。这会影响数据库是否能够对特定查询使用索引。
sort
参数适用于所有数据库的 @unique
、@@unique
和 @@index
。此外,SQL Server 也允许在 @id
和 @@id
上使用。它在 4.0.0 及更高版本中已正式可用,并在 3.5.0 及更高版本中作为 extendedIndexes
预览功能的一部分提供。
例如,以下表格
CREATE TABLE `Unique` (
`unique` INT,
CONSTRAINT `Unique_unique_key` UNIQUE (`unique` DESC)
)
现在被内省为
model Unique {
unique Int @unique(sort: Desc)
}
sort
参数也可以用于复合索引
model CompoundUnique {
unique_1 Int
unique_2 Int
@@unique([unique_1(sort: Desc), unique_2])
}
示例:同时使用 sort
和 length
以下示例演示了如何使用 sort
和 length
参数配置 Post
模型的索引和约束
model Post {
title String @db.VarChar(300)
abstract String @db.VarChar(3000)
slug String @unique(sort: Desc, length: 42) @db.VarChar(3000)
author String
created_at DateTime
@@id([title(length: 100, sort: Desc), abstract(length: 10)])
@@index([author, created_at(sort: Desc)])
}
使用 type
配置索引访问类型 (PostgreSQL)
type
参数可用于通过 @@index
属性配置 PostgreSQL 中的索引类型。可用的索引访问方法有 Hash
、Gist
、Gin
、SpGist
和 Brin
,以及默认的 BTree
索引访问方法。type
参数在 4.0.0 及更高版本中已正式可用。Hash
索引访问方法在 3.6.0 及更高版本中作为 extendedIndexes
预览功能的一部分提供,而 Gist
、Gin
、SpGist
和 Brin
索引访问方法在 3.14.0 及更高版本中以预览形式提供。
哈希 (Hash)
Hash
类型将索引数据以更快搜索和插入的格式存储,并且会占用更少的磁盘空间。但是,只有 =
和 <>
比较可以使用索引,因此其他比较运算符(如 <
和 >
)在使用 Hash
时会比使用默认 BTree
类型慢得多。
例如,以下模型在 value
字段上添加了一个 type
为 Hash
的索引
model Example {
id Int @id
value Int
@@index([value], type: Hash)
}
这转换为以下 SQL 命令
CREATE TABLE "Example" (
id INT PRIMARY KEY,
value INT NOT NULL
);
CREATE INDEX "Example_value_idx" ON "Example" USING HASH (value);
广义倒排索引 (GIN)
GIN 索引存储复合值,例如数组或 JsonB
数据。这对于加快查询一个对象是否是另一个对象的一部分非常有用。它通常用于全文搜索。
索引字段可以定义操作符类,该类定义了索引处理的操作符。
Prisma ORM 尚不支持使用函数(例如 to_tsvector
)来确定索引值的索引。以这种方式定义的索引在使用 prisma db pull
时将不可见。
例如,以下模型为 value
字段添加了一个 Gin
索引,并以 JsonbPathOps
作为允许使用该索引的操作符类
model Example {
id Int @id
value Json
// ^ field type matching the operator class
// ^ operator class ^ index type
@@index([value(ops: JsonbPathOps)], type: Gin)
}
这转换为以下 SQL 命令
CREATE TABLE "Example" (
id INT PRIMARY KEY,
value JSONB NOT NULL
);
CREATE INDEX "Example_value_idx" ON "Example" USING GIN (value jsonb_path_ops);
作为 JsonbPathOps
的一部分,@>
操作符由索引处理,从而加快了诸如 value @> '{"foo": 2}'
之类的查询。
GIN 支持的操作符类
Prisma ORM 通常支持 PostgreSQL 10 及更高版本提供的操作符类。如果操作符类要求字段类型是 Prisma ORM 尚不支持的类型,则使用字符串输入的 raw
函数允许你在不进行验证的情况下使用这些操作符类。
默认操作符类(标记为 ✅)可以从索引定义中省略。
操作符类 | 允许的字段类型(原生类型) | 默认 | 其他 |
---|---|---|---|
ArrayOps | 任意数组 | ✅ | CockroachDB 也可用 |
JsonbOps | Json (@db.JsonB ) | ✅ | CockroachDB 也可用 |
JsonbPathOps | Json (@db.JsonB ) | ||
raw("other") |
有关内置操作符类的更多信息,请阅读 官方 PostgreSQL 文档。
CockroachDB
GIN 和 BTree 是 CockroachDB 唯一支持的索引类型。标记为与 CockroachDB 配合使用的操作符类是该数据库上唯一允许并受 Prisma ORM 支持的。操作符类无法在 Prisma Schema Language 中定义:在 CockroachDB 上不需要或不允许使用 ops
参数。
广义搜索树 (GiST)
GiST 索引类型用于实现用户定义类型的索引方案。默认情况下,GiST 索引没有很多直接用途,但例如 B-Tree 索引类型就是使用 GiST 索引构建的。
例如,以下模型为 value
字段添加了一个 Gist
索引,并以 InetOps
作为将使用该索引的操作符
model Example {
id Int @id
value String @db.Inet
// ^ native type matching the operator class
// ^ index type
// ^ operator class
@@index([value(ops: InetOps)], type: Gist)
}
这转换为以下 SQL 命令
CREATE TABLE "Example" (
id INT PRIMARY KEY,
value INET NOT NULL
);
CREATE INDEX "Example_value_idx" ON "Example" USING GIST (value inet_ops);
比较 IP 地址的查询,例如 value > '10.0.0.2'
,将使用索引。
GiST 支持的操作符类
Prisma ORM 通常支持 PostgreSQL 10 及更高版本提供的操作符类。如果操作符类要求字段类型是 Prisma ORM 尚不支持的类型,则使用字符串输入的 raw
函数允许你在不进行验证的情况下使用这些操作符类。
操作符类 | 允许的字段类型(允许的原生类型) |
---|---|
InetOps | String (@db.Inet ) |
raw("other") |
有关内置操作符类的更多信息,请阅读 官方 PostgreSQL 文档。
空间分区 GiST (SP-GiST)
SP-GiST 索引是许多不同非平衡数据结构的一个很好的选择。如果查询与分区规则匹配,它可能非常快。
与 GiST 一样,SP-GiST 作为用户定义类型的构建块非常重要,它允许直接通过数据库实现自定义搜索操作符。
例如,以下模型为 value
字段添加了一个 SpGist
索引,并以 TextOps
作为使用该索引的操作符
model Example {
id Int @id
value String
// ^ field type matching the operator class
@@index([value], type: SpGist)
// ^ index type
// ^ using the default ops: TextOps
}
这转换为以下 SQL 命令
CREATE TABLE "Example" (
id INT PRIMARY KEY,
value TEXT NOT NULL
);
CREATE INDEX "Example_value_idx" ON "Example" USING SPGIST (value);
诸如 value LIKE 'something%'
之类的查询将通过索引加速。
SP-GiST 支持的操作符类
Prisma ORM 通常支持 PostgreSQL 10 及更高版本提供的操作符类。如果操作符类要求字段类型是 Prisma ORM 尚不支持的类型,则使用字符串输入的 raw
函数允许你在不进行验证的情况下使用这些操作符类。
默认操作符类(标记为 ✅)可以从索引定义中省略。
操作符类 | 允许的字段类型(原生类型) | 默认 | 支持的 PostgreSQL 版本 |
---|---|---|---|
InetOps | String (@db.Inet ) | ✅ | 10+ |
TextOps | String (@db.Text , @db.VarChar ) | ✅ | |
raw("other") |
有关内置操作符类的更多信息,请阅读 官方 PostgreSQL 文档。
块范围索引 (BRIN)
如果你有大量插入后不更改的数据,例如日期和时间值,BRIN 索引类型非常有用。如果你的数据非常适合该索引,它可以在最小空间中存储大量数据集。
例如,以下模型为 value
字段添加了一个 Brin
索引,并以 Int4BloomOps
作为将使用该索引的操作符
model Example {
id Int @id
value Int
// ^ field type matching the operator class
// ^ operator class ^ index type
@@index([value(ops: Int4BloomOps)], type: Brin)
}
这转换为以下 SQL 命令
CREATE TABLE "Example" (
id INT PRIMARY KEY,
value INT4 NOT NULL
);
CREATE INDEX "Example_value_idx" ON "Example" USING BRIN (value int4_bloom_ops);
诸如 value = 2
之类的查询现在将使用索引,该索引使用的空间仅为 BTree
或 Hash
索引的一小部分。
BRIN 支持的操作符类
Prisma ORM 通常支持 PostgreSQL 10 及更高版本提供的操作符类,并且某些受支持的操作符仅在 PostgreSQL 14 及更高版本中可用。如果操作符类要求字段类型是 Prisma ORM 尚不支持的类型,则使用字符串输入的 raw
函数允许你在不进行验证的情况下使用这些操作符类。
默认操作符类(标记为 ✅)可以从索引定义中省略。
操作符类 | 允许的字段类型(原生类型) | 默认 | 支持的 PostgreSQL 版本 |
---|---|---|---|
BitMinMaxOps | String (@db.Bit ) | ✅ | |
VarBitMinMaxOps | String (@db.VarBit ) | ✅ | |
BpcharBloomOps | String (@db.Char ) | 14+ | |
BpcharMinMaxOps | String (@db.Char ) | ✅ | |
ByteaBloomOps | Bytes (@db.Bytea ) | 14+ | |
ByteaMinMaxOps | Bytes (@db.Bytea ) | ✅ | |
DateBloomOps | DateTime (@db.Date ) | 14+ | |
DateMinMaxOps | DateTime (@db.Date ) | ✅ | |
DateMinMaxMultiOps | DateTime (@db.Date ) | 14+ | |
Float4BloomOps | Float (@db.Real ) | 14+ | |
Float4MinMaxOps | Float (@db.Real ) | ✅ | |
Float4MinMaxMultiOps | Float (@db.Real ) | 14+ | |
Float8BloomOps | Float (@db.DoublePrecision ) | 14+ | |
Float8MinMaxOps | Float (@db.DoublePrecision ) | ✅ | |
Float8MinMaxMultiOps | Float (@db.DoublePrecision ) | 14+ | |
InetInclusionOps | String (@db.Inet ) | ✅ | 14+ |
InetBloomOps | String (@db.Inet ) | 14+ | |
InetMinMaxOps | String (@db.Inet ) | ||
InetMinMaxMultiOps | String (@db.Inet ) | 14+ | |
Int2BloomOps | Int (@db.SmallInt ) | 14+ | |
Int2MinMaxOps | Int (@db.SmallInt ) | ✅ | |
Int2MinMaxMultiOps | Int (@db.SmallInt ) | 14+ | |
Int4BloomOps | Int (@db.Integer ) | 14+ | |
Int4MinMaxOps | Int (@db.Integer ) | ✅ | |
Int4MinMaxMultiOps | Int (@db.Integer ) | 14+ | |
Int8BloomOps | BigInt (@db.BigInt ) | 14+ | |
Int8MinMaxOps | BigInt (@db.BigInt ) | ✅ | |
Int8MinMaxMultiOps | BigInt (@db.BigInt ) | 14+ | |
NumericBloomOps | Decimal (@db.Decimal ) | 14+ | |
NumericMinMaxOps | Decimal (@db.Decimal ) | ✅ | |
NumericMinMaxMultiOps | Decimal (@db.Decimal ) | 14+ | |
OidBloomOps | Int (@db.Oid ) | 14+ | |
OidMinMaxOps | Int (@db.Oid ) | ✅ | |
OidMinMaxMultiOps | Int (@db.Oid ) | 14+ | |
TextBloomOps | String (@db.Text , @db.VarChar ) | 14+ | |
TextMinMaxOps | String (@db.Text , @db.VarChar ) | ✅ | |
TextMinMaxMultiOps | String (@db.Text , @db.VarChar ) | 14+ | |
TimestampBloomOps | DateTime (@db.Timestamp ) | 14+ | |
TimestampMinMaxOps | DateTime (@db.Timestamp ) | ✅ | |
TimestampMinMaxMultiOps | DateTime (@db.Timestamp ) | 14+ | |
TimestampTzBloomOps | DateTime (@db.Timestamptz ) | 14+ | |
TimestampTzMinMaxOps | DateTime (@db.Timestamptz ) | ✅ | |
TimestampTzMinMaxMultiOps | DateTime (@db.Timestamptz ) | 14+ | |
TimeBloomOps | DateTime (@db.Time ) | 14+ | |
TimeMinMaxOps | DateTime (@db.Time ) | ✅ | |
TimeMinMaxMultiOps | DateTime (@db.Time ) | 14+ | |
TimeTzBloomOps | DateTime (@db.Timetz ) | 14+ | |
TimeTzMinMaxOps | DateTime (@db.Timetz ) | ✅ | |
TimeTzMinMaxMultiOps | DateTime (@db.Timetz ) | 14+ | |
UuidBloomOps | String (@db.Uuid ) | 14+ | |
UuidMinMaxOps | String (@db.Uuid ) | ✅ | |
UuidMinMaxMultiOps | String (@db.Uuid ) | 14+ | |
raw("other") |
有关内置操作符类的更多信息,请阅读 官方 PostgreSQL 文档。
使用 clustered
配置索引是聚集还是非聚集 (SQL Server)
clustered
参数可用于配置 SQL Server 中的(非)聚集索引。它可用于 @id
、@@id
、@unique
、@@unique
和 @@index
属性。它在 4.0.0 及更高版本中已正式可用,并在 3.13.0 及更高版本中作为 extendedIndexes
预览功能的一部分提供。
例如,以下模型将 @id
配置为非聚集(而不是默认的聚集)
model Example {
id Int @id(clustered: false)
value Int
}
这转换为以下 SQL 命令
CREATE TABLE [Example] (
id INT NOT NULL,
value INT,
CONSTRAINT [Example_pkey] PRIMARY KEY NONCLUSTERED (id)
)
每个属性的 clustered
默认值如下
属性 | 值 |
---|---|
@id | true |
@@id | true |
@unique | false |
@@unique | false |
@@index | false |
一个表最多可以有一个聚集索引。
从以前版本升级
当为某些现有数据库的现有 Prisma schema 激活该功能时,这些索引配置更改可能是重大更改。启用使用它们所需的预览功能后,运行 prisma db pull
内省现有数据库以更新你的 Prisma schema,然后再使用 Prisma Migrate。
在以下情况下可能会发生重大更改
- 现有排序约束和索引: 早期版本的 Prisma ORM 将假定如果未明确指定顺序,则所需的排序顺序是升序。这意味着如果你有使用降序排序的现有约束或索引,并且在数据模型中未先指定此项就迁移数据库,则这是一项重大更改。
- 现有长度约束和索引: 在早期版本的 Prisma ORM 中,MySQL 中受长度约束的索引和约束无法在 Prisma schema 中表示。因此
prisma db pull
不会获取这些,你无法手动指定它们。当你运行prisma db push
或prisma migrate dev
时,如果它们已经存在于你的数据库中,则会被忽略。由于你现在可以指定这些,如果它们在你的数据模型中缺失但存在于数据库中,迁移命令将删除它们。 - 现有除
BTree
之外的索引 (PostgreSQL): 早期版本的 Prisma ORM 仅支持默认的BTree
索引类型。其他支持的索引(Hash
、Gist
、Gin
、SpGist
和Brin
)需要在迁移数据库之前添加。 - 现有(非)聚集索引 (SQL Server): 早期版本的 Prisma ORM 不支持将索引配置为聚集或非聚集。对于不使用默认值的索引,需要在迁移数据库之前添加它们。
在上述每种情况下,都可以通过在必要时在数据模型中正确指定这些属性来防止对数据库进行不必要的更改。最简单的方法是使用 prisma db pull
检索任何现有约束或配置。 或者,你也可以手动添加这些参数。这应该在升级后第一次使用 prisma db push
或 prisma migrate dev
之前完成。
全文索引 (MySQL 和 MongoDB)
fullTextIndex
预览功能在 3.6.0 及更高版本中提供了对 MySQL 和 MongoDB 中全文索引的内省和迁移支持。这可以使用 @@fulltext
属性进行配置。数据库中现有的全文索引在使用 db pull
内省后会添加到你的 Prisma schema 中,并且在 Prisma schema 中添加的新全文索引在使用 Prisma Migrate 时会在数据库中创建。这还可以防止以前无法正常工作的一些数据库 schema 中的验证错误。
目前,我们尚未在 Prisma Client for MongoDB 中启用全文搜索命令;可以在 MongoDB issue 中查看进展。
启用 fullTextIndex
预览功能
要启用 fullTextIndex
预览功能,请将 fullTextIndex
功能标志添加到 schema.prisma
文件的 generator
块中
generator client {
provider = "prisma-client-js"
previewFeatures = ["fullTextIndex"]
}
示例
以下示例演示了如何向 Post
模型的 title
和 content
字段添加 @@fulltext
索引
model Post {
id Int @id
title String @db.VarChar(255)
content String @db.Text
@@fulltext([title, content])
}
在 MongoDB 上,你可以使用 @@fulltext
索引属性(通过 fullTextIndex
预览功能)和 sort
参数,以升序或降序向全文索引添加字段。以下示例向 Post
模型的 title
和 content
字段添加了一个 @@fulltext
索引,并以降序对 title
字段进行排序
generator js {
provider = "prisma-client-js"
previewFeatures = ["fullTextIndex"]
}
datasource db {
provider = "mongodb"
url = env("DATABASE_URL")
}
model Post {
id String @id @map("_id") @db.ObjectId
title String
content String
@@fulltext([title(sort: Desc), content])
}
从以前版本升级
当为某些现有数据库的现有 Prisma schema 激活该功能时,这可能是重大更改。启用使用它们所需的预览功能后,运行 prisma db pull
内省现有数据库以更新你的 Prisma schema,然后再使用 Prisma Migrate。
早期版本的 Prisma ORM 使用 @@index
属性而不是 @@fulltext
属性转换全文索引。启用 fullTextIndex
预览功能后,运行 prisma db pull
将这些索引转换为 @@fulltext
,然后再使用 Prisma Migrate 进行迁移。如果你不这样做,现有索引将被删除,取而代之的是创建普通索引。