`/documents` 路由允许您创建、管理和删除文档。

了解更多关于文档的信息。

​
通过 POST 获取文档

POST
/indexes/{index_uid}/documents/fetch

获取一组文档。

使用 `offset` 和 `limit` 浏览文档。

`filter` 在未将属性明确添加到 `filterableAttributes` 列表之前将不起作用。在我们的专用指南中了解更多关于过滤器的信息。

​
路径参数

名称类型描述
index_uid *字符串请求索引的`uid`

​
请求体

名称类型默认值描述
offset整数0要跳过的文档数量
limit整数20要返回的文档数量
fields字符串数组/`null`*要显示的文档属性（区分大小写，逗号分隔）
filter字符串/字符串数组的数组/`null`不适用根据 `filterableAttributes` 列表中的属性细化结果
retrieveVectors布尔值false在搜索结果中返回文档向量数据
ids主键数组null根据主键返回文档

发送空载荷 (`--data-binary '{}'`) 将返回索引中的所有文档。

​
响应

名称类型描述
results数组一个文档数组
offset整数已跳过的文档数量
limit整数已返回的文档数量
total整数索引中的文档总数

​
返回的文档顺序

`/indexes/{index_uid}/documents/fetch` 和 `/indexes/{index_uid}/documents` 的响应不遵循主键的顺序返回文档。

​
示例

curl \
  -X POST MEILISEARCH_URL/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`

{
  "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`。

`filter` 在未将属性明确添加到 `filterableAttributes` 列表之前将不起作用。在我们的专用指南中了解更多关于过滤器的信息。

​
路径参数

名称类型描述
index_uid *字符串请求索引的`uid`

​
查询参数

查询参数默认值描述
offset0要跳过的文档数量
limit20要返回的文档数量
fields*要显示的文档属性（区分大小写，逗号分隔）
filter不适用根据 `filterableAttributes` 列表中的属性细化结果
retrieveVectorsfalse在搜索结果中返回文档向量数据
idsnull根据主键返回文档

​
响应

名称类型描述
results数组一个文档数组
offset整数已跳过的文档数量
limit整数已返回的文档数量
total整数索引中的文档总数

​
返回的文档顺序

`/indexes/{index_uid}/documents/fetch` 和 `/indexes/{index_uid}/documents` 的响应不遵循主键的顺序返回文档。

​
示例

curl \
  -X GET 'MEILISEARCH_URL/indexes/movies/documents?limit=2&filter=genres=action'

​
响应：`200 Ok`

{
  "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*要显示的文档属性（区分大小写，逗号分隔）
retrieveVectorsfalse在搜索结果中返回文档向量数据

​
示例

curl \
  -X GET 'MEILISEARCH_URL/indexes/movies/documents/25684?fields=id,title,poster,release_date'

​
响应：`200 Ok`

{
  "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`

​
查询参数

查询参数默认值描述
primaryKeynull索引的主键
csvDelimiter","配置 CSV 字段分隔字符。必须是包含单个 ASCII 字符的字符串。

配置 `csvDelimiter` 并发送非 CSV 内容类型的数据将导致 Meilisearch 抛出错误。

如果您想在添加文档时设置索引的主键，则只能在**首次添加文档**到索引时进行。此后，如果提供了 `primaryKey` 参数，它将被忽略。

​
请求体

一个文档数组。每个文档都表示为一个 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`）的嵌套对象。

[
  {
    "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 在文档更新时保留嵌入的最后值。

您也可以使用数组简写向文档添加嵌入

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

使用简写添加的向量嵌入在 Meilisearch 生成新嵌入时不会被替换。上述示例等同于

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

如果 `_vectors` 中嵌入器的键为空或 `null`，Meilisearch 会将该文档视为没有该嵌入器的任何嵌入。此文档将在 AI 驱动的搜索中最后返回。

​
示例

curl \
  -X POST 'MEILISEARCH_URL/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`

{
    "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`

​
查询参数

查询参数默认值描述
primaryKeynull文档的主键
csvDelimiter","配置 CSV 字段分隔字符。必须是包含单个 ASCII 字符的字符串。

配置 `csvDelimiter` 并发送非 CSV 内容类型的数据将导致 Meilisearch 抛出错误。

​
请求体

一个文档数组。每个文档都表示为一个 JSON 对象。

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

​
示例

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

此文档是添加或替换文档中找到的文档的更新。

文档匹配是因为它们具有相同的主键值 `id: 287947`。此路由将更新 `title` 字段（从 `Shazam` 更改为 `Shazam ⚡️`），并向该文档添加新的 `genres` 字段。文档的其余部分将保持不变。

​
响应：`202 Accepted`

{
    "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 'MEILISEARCH_URL/experimental-features/' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "editDocumentsByFunction": true
  }'

​
路径参数

名称类型描述
index_uid *字符串请求索引的`uid`

​
查询参数

查询参数默认值描述
functionnull包含 RHAI 函数的字符串
filternull包含筛选表达式的字符串
contextnull一个对象，包含 Meilisearch 应为编辑函数提供的数据

​
function

`function` 必须是包含 RHAI 函数的字符串，Meilisearch 将其应用于所有选定文档。默认情况下，此函数可以访问一个名为 `doc` 的变量，它代表您当前正在编辑的文档。这是一个必填字段。

​
filter

`filter` 必须是包含筛选表达式的字符串。当您只想将 `function` 应用于数据库中的部分文档时，请使用 `filter`。

​
context

使用 `context` 将数据传递到 `function` 范围。默认情况下，函数只能访问它正在编辑的文档。

​
示例

curl \
-X POST 'MEILISEARCH_URL/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 'MEILISEARCH_URL/indexes/movies/documents'

​
响应：`202 Accepted`

{
    "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 'MEILISEARCH_URL/indexes/movies/documents/25684'

​
响应：`202 Accepted`

{
    "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`

​
请求体

一个筛选表达式，表示为字符串或字符串数组的数组，用于要删除的文档。

`filter` 在未将属性明确添加到 `filterableAttributes` 列表之前将不起作用。在我们的专用指南中了解更多关于过滤器的信息。

"filter": "rating > 3.5"

发送空载荷 (`--data-binary '{}'`) 将返回 `bad_request` 错误。

​
示例

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

​
响应：`202 Accepted`

{
    "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 的数字数组。

[23488, 153738, 437035, 363869]

​
示例

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

​
响应：`202 Accepted`

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

您可以使用此 `taskUid` 获取任务状态的更多详细信息。