文件

/documents 路由允許您建立、管理和刪除文件。

深入瞭解文件。

使用 POST 取得文件

POST/indexes/{index_uid}/documents/fetch

取得一組文件。

使用 offset 和 limit 瀏覽文件。

警告

如果沒有先將屬性明確加入filterableAttributes 清單，filter 將無法運作。請參閱我們的專屬指南，深入瞭解篩選條件。

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

主體

名稱	類型	預設值	描述
`offset`	整數	`0`	要跳過的文件數
`limit`	整數	`20`	要傳回的文件數
`fields`	字串陣列/`null`	`*`	要顯示的文件屬性 (區分大小寫，以逗號分隔)
`filter`	字串/字串陣列的陣列/`null`	不適用	根據 `filterableAttributes` 清單中的屬性來精簡結果
`retrieveVectors`	布林值	`false`	返回帶有搜尋結果的文件向量資料

注意

傳送空的酬載（--data-binary '{}'）將會返回索引中的所有文件。

回應

名稱	類型	描述
`結果`	陣列	文件陣列
`offset`	整數	跳過的文件數量
`limit`	整數	返回的文件數量
`總數`	整數	索引中的文件總數

範例

curl \
  -X POST https://127.0.0.1:7700/indexes/books/documents/fetch \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "filter": "(rating > 3 AND (genres = Adventure OR genres = Fiction)) AND language = English",
    "fields": ["title", "genres", "rating", "language"],
    "limit": 3
  }'

回應：`200 Ok`

json

{
  "results":[
    {
      "title":"The Travels of Ibn Battuta",
      "genres":[
        "Travel",
        "Adventure"
      ],
      "language":"English",
      "rating":4.5
    },
    {
      "title":"Pride and Prejudice",
      "genres":[
        "Classics",
        "Fiction",
        "Romance",
        "Literature"
      ],
      "language":"English",
      "rating":4
    },
    …
  ],
  "offset":0,
  "limit":3,
  "total":5
}

使用 GET 取得文件

危險

此端點將在不久的將來被棄用。請考慮改用 POST /indexes/{index_uid}/documents/fetch。

GET/indexes/{index_uid}/documents

取得一組文件。

使用查詢參數 offset 和 limit，您可以瀏覽所有文件。filter 必須是字串。若要建立篩選運算式，請使用 AND 或 OR。

警告

如果沒有先將屬性明確加入filterableAttributes 清單，filter 將無法運作。請參閱我們的專屬指南，深入瞭解篩選條件。

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

查詢參數

查詢參數	預設值	描述
`offset`	`0`	要跳過的文件數
`limit`	`20`	要傳回的文件數
`fields`	`*`	要顯示的文件屬性 (區分大小寫，以逗號分隔)
`filter`	不適用	根據 `filterableAttributes` 清單中的屬性來精簡結果
`retrieveVectors`	`false`	返回帶有搜尋結果的文件向量資料

回應

名稱	類型	描述
`結果`	陣列	文件陣列
`offset`	整數	跳過的文件數量
`limit`	整數	返回的文件數量
`總數`	整數	索引中的文件總數

範例

curl \
  -X GET 'https://127.0.0.1:7700/indexes/movies/documents?limit=2&filter=genres=action'

回應：`200 Ok`

json

{
  "results":[
    {
      "id": 364,
      "title": "Batman Returns",
      "overview": "While Batman deals with a deformed man calling himself the Penguin, an employee of a corrupt businessman transforms into the Catwoman.",
      "genres": [
        "Action",
        "Fantasy"
      ],
      "poster": "https://image.tmdb.org/t/p/w500/jKBjeXM7iBBV9UkUcOXx3m7FSHY.jpg",
      "release_date": 708912000
    },
    {
      "id": 13851,
      "title":" Batman: Gotham Knight",
      "overview": "A collection of key events mark Bruce Wayne's life as he journeys from beginner to Dark Knight.",
      "genres": [
        "Animation",
        "Action",
        "Adventure"
      ],
      "poster": "https://image.tmdb.org/t/p/w500/f3xUrqo7yEiU0guk2Ua3Znqiw6S.jpg",
      "release_date": 1215475200
    }
  ],
  "offset": 0,
  "limit": 2,
  "total": 5403
}

取得單一文件

GET/indexes/{index_uid}/documents/{document_id}

使用文件的唯一 ID 取得單一文件。

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`
`document_id` *	字串/整數	請求文件的文件 ID

查詢參數

查詢參數	預設值	描述
`fields`	`*`	要顯示的文件屬性 (區分大小寫，以逗號分隔)
`retrieveVectors`	`false`	返回帶有搜尋結果的文件向量資料

範例

curl \
  -X GET 'https://127.0.0.1:7700/indexes/movies/documents/25684?fields=id,title,poster,release_date'

回應：`200 Ok`

json

{
  "id": 25684,
  "title": "American Ninja 5",
  "poster": "https://image.tmdb.org/t/p/w1280/iuAQVI4mvjI83wnirpD8GVNRVuY.jpg",
  "release_date": "1993-01-01"
}

新增或取代文件

POST/indexes/{index_uid}/documents

新增文件陣列，或在文件已存在時取代它們。如果提供的索引不存在，將會建立它。

如果您傳送已存在的文件（相同的文件 ID），整個現有文件將會被新文件覆寫。新文件中不再存在的欄位將被移除。如需文件的部分更新，請參閱新增或更新文件端點。

此端點接受以下內容類型

application/json
application/x-ndjson
text/csv

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

查詢參數

查詢參數	預設值	描述
`primaryKey`	`null`	索引的主索引鍵
`csvDelimiter`	`","`	設定分隔 CSV 欄位的字元。必須是包含一個 ASCII 字元的字串。

警告

設定 csvDelimiter 且傳送內容類型不是 CSV 的資料，將導致 Meilisearch 擲回錯誤。

如果您想在新增文件時設定索引的主索引鍵，只能在第一次將文件新增到索引時執行。在此之後，如果提供 primaryKey 參數，將會被忽略。

主體

文件陣列。每個文件都以 JSON 物件表示。

json

[
  {
    "id": 287947,
    "title": "Shazam",
    "poster": "https://image.tmdb.org/t/p/w1280/xnopI5Xtky18MPhK40cZAGAOVeV.jpg",
    "overview": "A boy is given the ability to become an adult superhero in times of need with a single magic word.",
    "release_date": "2019-03-23"
  }
]

`_vectors`

_vectors 是一個特殊的文件屬性，包含一個物件，其中包含 AI 驅動搜尋的向量嵌入。

_vectors 物件的每個索引鍵必須是已設定的嵌入器的名稱，且對應於具有兩個欄位 embeddings 和 regenerate 的巢狀物件

json

[
  {
    "id": 452,
    "title": "Female Trouble",
    "overview": "Delinquent high school student Dawn Davenport runs away from home and embarks upon a life of crime.",
    "_vectors": {
      "default": {
        "embeddings": [0.1, 0.2, 0.3],
        "regenerate": false
      },
      "ollama": {
        "embeddings": [0.4, 0.12, 0.6],
        "regenerate": true
      }
    }
  }
]

embeddings 是一個選填欄位。它必須是一個數字陣列，表示該文件的單一嵌入。它也可以是一個數字陣列的陣列，表示該文件的多個嵌入。embeddings 預設為 null。

regenerate 是一個必填欄位。它必須是布林值。如果 regenerate 為 true，Meilisearch 會立即自動為該文件產生嵌入，並且每次更新文件時都會產生。如果 regenerate 為 false，Meilisearch 會在文件更新時保留嵌入的最後一個值。

您也可以使用陣列簡寫將嵌入新增至文件

json

"_vectors": {
  "default": [0.003, 0.1, 0.75]
}

使用簡寫新增的向量嵌入在 Meilisearch 產生新的嵌入時不會被取代。上面的範例等同於

json

"default": {
  "embeddings": [0.003, 0.1, 0.75],
  "regenerate": false
}

注意

如果 _vectors 內的嵌入器索引鍵是空的或 null，Meilisearch 會將該文件視為沒有該嵌入器的任何嵌入。然後，此文件會在 AI 驅動搜尋期間最後返回。

範例

curl \
  -X POST 'https://127.0.0.1:7700/indexes/movies/documents' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    {
      "id": 287947,
      "title": "Shazam",
      "poster": "https://image.tmdb.org/t/p/w1280/xnopI5Xtky18MPhK40cZAGAOVeV.jpg",
      "overview": "A boy is given the ability to become an adult superhero in times of need with a single magic word.",
      "release_date": "2019-03-23"
    }
  ]'

回應：`202 Accepted`

json

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "documentAdditionOrUpdate",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

您可以使用此 taskUid 來取得有關任務狀態的更多詳細資料。

新增或更新文件

PUT/indexes/{index_uid}/documents

新增文件列表，或在它們已存在時更新它們。如果提供的索引不存在，將會建立它。

如果您傳送已存在的文件（相同的文件 ID），舊文件將僅根據新文件的欄位進行部分更新。因此，新文件中不存在的任何欄位都將保留且保持不變。

若要完整覆寫文件，請查看新增或取代文件路由。

如果您想透過此路由設定索引的主索引鍵，您只能在第一次將文件新增到索引時執行。如果您在將文件新增到索引後嘗試設定主索引鍵，任務將會返回錯誤。

此端點接受以下內容類型

application/json
application/x-ndjson
text/csv

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

查詢參數

查詢參數	預設值	描述
`primaryKey`	`null`	文件的主索引鍵
`csvDelimiter`	`","`	設定分隔 CSV 欄位的字元。必須是包含一個 ASCII 字元的字串。

警告

設定 csvDelimiter 且傳送內容類型不是 CSV 的資料，將導致 Meilisearch 擲回錯誤。

主體

文件陣列。每個文件都以 JSON 物件表示。

json

[
  {
    "id": 287947,
    "title": "Shazam ⚡️"
  }
]

範例

curl \
  -X PUT 'https://127.0.0.1:7700/indexes/movies/documents' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    {
      "id": 287947,
      "title": "Shazam ⚡️",
      "genres": "comedy"
    }
  ]'

此文件是新增或取代文件中找到的文件的更新。

文件因為具有相同主索引鍵值 id: 287947 而匹配。此路由將更新 title 欄位，因為它從 Shazam 變更為 Shazam ⚡️，並將新的 genres 欄位新增至該文件。文件的其餘部分將保持不變。

回應：`202 Accepted`

json

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "documentAdditionOrUpdate",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

您可以使用此 taskUid 來取得有關任務狀態的更多詳細資料。

使用函數更新文件實驗性

POST/indexes/{index_uid}/documents/edit

使用RHAI 函數，直接在 Meilisearch 中編輯一個或多個文件。

啟用使用函數更新文件

這是一項實驗性功能。使用實驗性功能端點來啟用它

curl \
  -X PATCH 'https://127.0.0.1:7700/experimental-features/' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "editDocumentsByFunction": true
  }'

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

查詢參數

查詢參數	預設值	描述
`函數`	`null`	包含 RHAI 函數的字串
`filter`	`null`	包含篩選運算式的字串
`內容`	`null`	Meilisearch 應該為編輯函數提供的資料物件

curl \
-X POST 'https://127.0.0.1:7700/indexes/INDEX_NAME/documents/edit' \
-H 'Content-Type: application/json' \
--data-binary '{
  "function": "doc.title = `${doc.title.to_upper()}`"
}'

刪除所有文件

DELETE/indexes/{index_uid}/documents

刪除指定索引中的所有文件。

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

範例

curl \
  -X DELETE 'https://127.0.0.1:7700/indexes/movies/documents'

回應：`202 Accepted`

json

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "documentDeletion",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

您可以使用此 taskUid 來取得有關任務狀態的更多詳細資料。

刪除單一文件

DELETE/indexes/{index_uid}/documents/{document_id}

根據唯一 ID 刪除單一文件。

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`
`document_id` *	字串/整數	請求文件的文件 ID

範例

curl \
  -X DELETE 'https://127.0.0.1:7700/indexes/movies/documents/25684'

回應：`202 Accepted`

json

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "documentDeletion",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

您可以使用此 taskUid 來取得有關任務狀態的更多詳細資料。

依篩選條件刪除文件

POST/indexes/{index_uid}/documents/delete

根據篩選條件刪除一組文件。

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

主體

以字串或字串陣列的陣列形式撰寫的篩選運算式，用於要刪除的文件。

警告

如果沒有先將屬性明確加入filterableAttributes 清單，filter 將無法運作。請參閱我們的專屬指南，深入瞭解篩選條件。

 "filter": "rating > 3.5"

警告

傳送空的酬載（--data-binary '{}'）將會返回 bad_request 錯誤。

範例

curl \
  -X POST https://127.0.0.1:7700/indexes/movies/documents/delete \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "filter": "genres = action OR genres = adventure"
  }'

回應：`202 Accepted`

json

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "documentDeletion",
    "enqueuedAt": "2023-05-15T08:38:48.024551Z"
}

您可以使用此 taskUid 來取得有關任務狀態的更多詳細資料。

依批次刪除文件

危險

此端點將在不久的將來被棄用。請考慮改用 POST /indexes/{index_uid}/documents/delete。

POST/indexes/{index_uid}/documents/delete-batch

根據文件 ID 陣列刪除一組文件。

路徑參數

名稱	類型	描述
`index_uid` *	字串	所要求索引的`uid`

主體

一個數字陣列，包含要刪除的文件唯一 ID。

json

[23488, 153738, 437035, 363869]

範例

curl \
  -X POST 'https://127.0.0.1:7700/indexes/movies/documents/delete-batch' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    23488,
    153738,
    437035,
    363869
  ]'

回應：`202 Accepted`

json

{
    "taskUid": 1,
    "indexUid": "movies",
    "status": "enqueued",
    "type": "documentDeletion",
    "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

您可以使用此 taskUid 來取得有關任務狀態的更多詳細資料。

編輯此頁面

這對您有幫助嗎？

想加入更多詳細資訊嗎？提出問題在我們的公開文件庫中。

文件

使用 POST 取得文件

警告

路徑參數

主體

注意

回應

範例

回應：200 Ok

使用 GET 取得文件

危險

警告

路徑參數

查詢參數

回應

範例

回應：200 Ok

取得單一文件

路徑參數

查詢參數

範例

回應：200 Ok

新增或取代文件

路徑參數

查詢參數

警告

主體

_vectors

注意

範例

回應：202 Accepted

新增或更新文件

路徑參數

查詢參數

警告

主體

範例

回應：202 Accepted

使用函數更新文件實驗性

啟用使用函數更新文件

路徑參數

查詢參數

函數

filter

內容

範例

刪除所有文件

路徑參數

範例

回應：202 Accepted

刪除單一文件

路徑參數

範例

回應：202 Accepted

依篩選條件刪除文件

路徑參數

主體

警告

警告

範例

回應：202 Accepted

依批次刪除文件

危險

路徑參數

主體

範例

回應：202 Accepted

這對您有幫助嗎？

回應：`200 Ok`

回應：`200 Ok`

回應：`200 Ok`

`_vectors`

回應：`202 Accepted`

回應：`202 Accepted`

`函數`

`filter`

`內容`

回應：`202 Accepted`

回應：`202 Accepted`

回應：`202 Accepted`

回應：`202 Accepted`