返回首页v1.10文档

    主键

    主字段

    在 Meilisearch 中，一个索引是文档的集合。文档由字段组成，每个字段包含一个属性和一个值。

    主字段是一个特殊字段，必须存在于所有文档中。它的属性是**主键**，它的值是**文档 ID**。它唯一地标识索引中的每个文档，确保**不可能在同一个索引中存在两个完全相同的文档**。

    示例

    假设我们有一个书籍索引。每个文档包含一些字段，其中包含书籍的作者、标题和价格数据。更重要的是，每个文档都包含一个**主字段**，其中包含索引的**主键**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
  }
]

    除了主键之外，**同一索引中的文档不需要共享属性**。此数据集中的一本书可能缺少标题或类型属性，但只要它具有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": "_Aabc012_"

    错误

    "id": "@BI+* ^5h2%"

    文档 ID 格式

    文档 ID 必须是整数或字符串。如果 ID 是字符串，则只能包含字母数字字符（a-z、A-Z、0-9）、连字符（-）和下划线（_）。

    设置主键

    您可以显式设置主键，也可以让 Meilisearch 从您的数据集中推断它。无论您选择哪种方式，索引一次只能拥有一个主键，并且在索引中存在文档时，主键无法更改。

    在索引创建时设置主键

    在手动创建索引时，您可以显式指定要使用的索引主键。

    以下代码创建了一个名为 books 的索引，并将 reference_number 设置为其主键

    curl \
  -X POST 'https://127.0.0.1:7700/indexes' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "uid": "books",
    "primaryKey": "reference_number"
  }'
    {
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "indexCreation",
  "enqueuedAt": "2022-09-20T12:06:24.364352Z"
}

    在添加文档时设置主键

    在向空索引添加文档时，您可以将索引的主键作为文档添加请求的一部分显式设置。

    以下代码将文档添加到 books 索引中，并将 reference_number 设置为该索引的主键

    curl \
  -X POST 'https://127.0.0.1:7700/indexes/books/documents?primaryKey=reference_number' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    {
      "reference_number": 287947,
      "title": "Diary of a Wimpy Kid",
      "author": "Jeff Kinney",
      "genres": [
        "comedy",
        "humor"
      ],
      "price": 5.00
    }
  ]'

    响应

    {
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "documentAdditionOrUpdate",
  "enqueuedAt": "2022-09-20T12:08:55.463926Z"
}

    使用更新索引端点更改主键

    在索引中存在文档时，无法更改主键。因此，要更改已包含文档的索引的主键，您必须先删除该索引中的所有文档，更改主键，然后重新添加它们。

    以下代码将主键更新为 title

    curl \
  -X PATCH 'https://127.0.0.1:7700/indexes/books' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "primaryKey": "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"
}