主字段
Meilisearch 中的索引是文档的集合。文档由字段组成,每个字段包含一个属性和一个值。
主字段是所有文档中必须存在的特殊字段。其属性是主键,其值是文档 ID。它唯一地标识索引中的每个文档,确保同一索引中不可能有两个完全相同的文档。
假设我们有一个图书索引。每个文档都包含多个字段,其中包含图书的author
(作者)、title
(标题)和price
(价格)等数据。更重要的是,每个文档都包含一个主字段,由索引的主键id
和一个唯一 ID组成。
[
{
"id": 1,
"title": "Diary of a Wimpy Kid: Rodrick Rules",
"author": "Jeff Kinney",
"genres": ["comedy","humor"],
"price": 5.00
},
{
"id": 2,
"title": "Black Leopard, Red Wolf",
"author": "Marlon James",
"genres": ["fantasy","drama"],
"price": 5.00
}
]
除了主键之外,同一索引中的文档不要求共享属性。此数据集中的图书可以缺少title
或genre
属性,但只要它具有id
属性,Meilisearch 仍能成功对其进行索引。
主键是主字段的属性。
每个索引都有一个主键,这是一个必须在同一索引中所有文档之间共享的属性。如果您尝试向索引添加文档,即使只有一个文档缺少主键,所有文档都将不会被存储。
{
"id": 1,
"title": "Diary of a Wimpy Kid",
"author": "Jeff Kinney",
"genres": ["comedy","humor"],
"price": 5.00
}
上述索引中的每个文档都由一个主字段标识,该主字段包含主键id
和一个唯一的文档 ID 值。
文档 ID
文档 ID 是与主键关联的值。它是主字段的一部分,充当给定索引中每个文档的唯一标识符。
索引中的两个文档可以拥有除主键之外的所有属性的相同值。如果同一索引中的两个文档具有相同的 ID,则它们被视为同一个文档,并且前一个文档将被覆盖。
Meilisearch 中的文档添加请求是原子性的。这意味着,即使批次中单个文档的主字段值格式不正确,也会发生错误,并且 Meilisearch 将不会索引该批次中的任何文档。
正确
错误
文档 ID 必须是整数或字符串。如果 ID 是字符串,则只能包含字母数字字符 (a-z
, A-Z
, 0-9
)、连字符 (-
) 和下划线 (_
)。
设置主键
您可以显式设置主键,或让 Meilisearch 从您的数据集中推断。无论您选择哪种方式,一个索引一次只能有一个主键,并且当索引中存在文档时,主键不能更改。
在索引创建时设置主键
手动创建索引时,您可以明确指出您希望该索引使用的主键。
以下代码创建一个名为 books
的索引,并将其主键设置为 reference_number
{
"taskUid": 1,
"indexUid": "books",
"status": "enqueued",
"type": "indexCreation",
"enqueuedAt": "2022-09-20T12:06:24.364352Z"
}
在添加文档时设置主键
向空索引添加文档时,您可以显式将索引的主键设置为文档添加请求的一部分。
以下代码向 books
索引添加一个文档,并将其主键设置为 reference_number
响应
{
"taskUid": 1,
"indexUid": "books",
"status": "enqueued",
"type": "documentAdditionOrUpdate",
"enqueuedAt": "2022-09-20T12:08:55.463926Z"
}
使用更新索引端点更改主键
当索引中存在文档时,主键不能更改。因此,要更改已包含文档的索引的主键,您必须删除该索引中的所有文档,更改主键,然后再次添加它们。
以下代码将主键更新为title
响应
{
"taskUid": 1,
"indexUid": "books",
"status": "enqueued",
"type": "indexUpdate",
"enqueuedAt": "2022-09-20T12:10:06.444672Z"
}
Meilisearch 猜测您的主键
假设您在未事先设置主键的情况下向索引添加文档。在这种情况下,Meilisearch 将自动在您的第一个文档中查找以不区分大小写的方式以字符串 id
结尾的属性(例如,uid
、BookId
、ID
),并将其设置为主键。
如果 Meilisearch 发现多个以 id
结尾的属性或找不到合适的属性,它将抛出错误。在这两种情况下,文档添加过程都将被中断,并且不会向您的索引添加任何文档。
主键错误
本节介绍一些主键错误以及如何解决它们。
index_primary_key_multiple_candidates_found
当您第一次向索引添加文档且 Meilisearch 找到多个以 id
结尾的属性时,会发生此错误。可以通过手动设置索引的主键来解决。
{
"uid": 4,
"indexUid": "books",
"status": "failed",
"type": "documentAdditionOrUpdate",
"canceledBy": null,
"details": {
"receivedDocuments": 5,
"indexedDocuments": 5
},
"error": {
"message": "The primary key inference failed as the engine found 2 fields ending with `id` in their names: 'id' and 'author_id'. Please specify the primary key manually using the `primaryKey` query parameter.",
"code": "index_primary_key_multiple_candidates_found",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#index-primary-key-multiple-candidates-found"
},
"duration": "PT0.006002S",
"enqueuedAt": "2023-01-17T10:44:42.625574Z",
"startedAt": "2023-01-17T10:44:42.626041Z",
"finishedAt": "2023-01-17T10:44:42.632043Z"
}
index_primary_key_no_candidate_found
当您第一次向索引添加文档且其中没有一个文档具有以 id
结尾的属性时,会发生此错误。可以通过手动设置索引的主键,或者确保您添加的所有文档都包含 id
属性来解决。
{
"uid": 1,
"indexUid": "books",
"status": "failed",
"type": "documentAdditionOrUpdate",
"canceledBy": null,
"details": {
"receivedDocuments": 5,
"indexedDocuments": null
},
"error": {
"message": "The primary key inference failed as the engine did not find any field ending with `id` in its name. Please specify the primary key manually using the `primaryKey` query parameter.",
"code": "index_primary_key_no_candidate_found",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#index-primary-key-no-candidate-found"
},
"duration": "PT0.006579S",
"enqueuedAt": "2023-01-17T10:19:14.464858Z",
"startedAt": "2023-01-17T10:19:14.465369Z",
"finishedAt": "2023-01-17T10:19:14.471948Z"
}
invalid_document_id
当您的文档 ID 格式不正确时,会发生此情况。文档 ID 只能是整数或字符串类型,由字母数字字符 a-z A-Z 0-9
、连字符 -
和下划线 _
组成。
{
"uid": 1,
"indexUid": "books",
"status": "failed",
"type": "documentAdditionOrUpdate",
"canceledBy": null,
"details": {
"receivedDocuments": 5,
"indexedDocuments": null
},
"error": {
"message": "Document identifier `1@` is invalid. A document identifier can be of type integer or string, only composed of alphanumeric characters (a-z A-Z 0-9), hyphens (-) and underscores (_).",
"code": "invalid_document_id",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#invalid_document_id"
},
"duration": "PT0.009738S",
"enqueuedAt": "2021-12-30T11:28:59.075065Z",
"startedAt": "2021-12-30T11:28:59.076144Z",
"finishedAt": "2021-12-30T11:28:59.084803Z"
}
missing_document_id
当您的索引已有一个主键,但您尝试添加的文档中缺少此属性时,会发生此错误。
{
"uid": 1,
"indexUid": "books",
"status": "failed",
"type": "documentAdditionOrUpdate",
"canceledBy": null,
"details": {
"receivedDocuments": 1,
"indexedDocuments": null
},
"error": {
"message": "Document doesn't have a `id` attribute: `{\"title\":\"Solaris\",\"author\":\"Stanislaw Lem\",\"genres\":[\"science fiction\"],\"price\":5.0.",
"code": "missing_document_id",
"type": "invalid_request",
"link": "https://docs.meilisearch.com/errors#missing_document_id"
},
"duration": "PT0.007899S",
"enqueuedAt": "2021-12-30T11:23:52.304689Z",
"startedAt": "2021-12-30T11:23:52.307632Z",
"finishedAt": "2021-12-30T11:23:52.312588Z"
}