返回首页v1.14文档

    主键

    主字段

    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": "_Aabc012_"

    错误

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

    格式化文档 ID

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

    设置主键

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

    在索引创建时设置主键

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

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

    curl \
  -X POST 'MEILISEARCH_URL/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 'MEILISEARCH_URL/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 'MEILISEARCH_URL/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），并将其设置

    If Meilisearch finds multiple attributes ending with id or cannot find a suitable attribute, it will throw an error. In both cases, the document addition process will be interrupted and no documents will be added to your index.

    Primary key errors

    This section covers some primary key errors and how to resolve them.

    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"
}