文档

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

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

使用 POST 获取文档

POST/indexes/{index_uid}/documents/fetch

获取一组文档。

使用 offset 和 limit 浏览文档。

警告

在没有首先将属性显式添加到 filterableAttributes 列表的情况下，filter 将不起作用。在我们的专用指南中了解更多关于过滤器的信息。

路径参数

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

请求体

名称	类型	默认值	描述
`offset`	整数	`0`	要跳过的文档数量
`limit`	整数	`20`	要返回的文档数量
`fields`	字符串数组/`null`	`*`	要显示的文档属性（区分大小写，逗号分隔）
`filter`	字符串/字符串数组的数组/`null`	N/A	根据 `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`

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`	N/A	根据 `filterableAttributes` 列表中的属性优化结果
`retrieveVectors`	`false`	返回带有搜索结果的文档向量数据
`ids`	`null`	根据文档的主键返回文档

响应

名称	类型	描述
`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`

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 'MEILISEARCH_URL/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 '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`

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 '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`

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

路径参数

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

查询参数

查询参数	默认值	描述
`function`	`null`	包含 RHAI 函数的字符串
`filter`	`null`	包含过滤器表达式的字符串
`context`	`null`	一个对象，包含 Meilisearch 应该提供给编辑函数的数据

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`

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 'MEILISEARCH_URL/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 MEILISEARCH_URL/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 'MEILISEARCH_URL/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

使用实验性功能更新文档 实验性

激活使用函数更新文档功能

路径参数

查询参数

function

filter

context

示例

删除所有文档

路径参数

示例

响应: 202 Accepted

删除一个文档

路径参数

示例

响应: 202 Accepted

通过过滤器删除文档

路径参数

请求体

警告

警告

示例

响应: 202 Accepted

批量删除文档

危险

路径参数

请求体

示例

响应: 202 Accepted

这有帮助吗？

响应: `200 Ok`

响应: `200 Ok`

响应: `200 Ok`

`_vectors`

响应: `202 Accepted`

响应: `202 Accepted`

使用实验性功能更新文档实验性

`function`

`filter`

`context`

响应: `202 Accepted`

响应: `202 Accepted`

响应: `202 Accepted`

响应: `202 Accepted`