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

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

​
使用 POST 获取文档

POST
/indexes/{index_uid}/documents/fetch

获取一组文档。

使用 offset 和 limit 参数来浏览文档。

如果没有先将属性显式添加到 filterableAttributes 列表，filter 将无法工作。在我们的专属指南中了解更多关于过滤器的信息。

​
路径参数

名称类型描述
index_uid *String请求索引的 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。

除非先将属性显式添加到 filterableAttributes 列表，否则 filter 将无法工作。在我们的专用指南中了解更多关于过滤器的信息。

​
路径参数

名称类型描述
index_uid *String请求索引的 uid

​
查询参数

查询参数默认值描述
offset0跳过的文档数量
limit20返回的文档数量
fields*要显示的文档属性（区分大小写，逗号分隔）
filterN/A根据 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": "蝙蝠侠归来",
      "overview": "当蝙蝠侠对付一个自称企鹅的畸形人时，一位腐败商人的雇员变成了猫女。",
      "genres": [
        "动作",
        "奇幻"
      ],
      "poster": "https://image.tmdb.org/t/p/w500/jKBjeXM7iBBV9UkUcOXx3m7FSHY.jpg",
      "release_date": 708912000
    },
    {
      "id": 13851,
      "title": "蝙蝠侠：哥谭骑士",
      "overview": "一系列关键事件标志着布鲁斯·韦恩从初学者到黑暗骑士的成长历程。",
      "genres": [
        "动画",
        "动作",
        "冒险"
      ],
      "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": "一个男孩获得能力，在需要时可以通过一句魔法咒语变成成年超级英雄。",
      "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 *String请求索引的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来获取任务状态的更多详细信息。

​
使用函数更新文档 experimental

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 *String请求索引的 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

​
请求体

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

在将属性显式添加到 filterableAttributes 列表 之前，filter 不会生效。在我们的专用指南中了解更多关于筛选器的信息。

 "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 *String目标索引的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 来获取任务状态的更多详情。