前往首頁v1.12文件

    主鍵

    主要欄位

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