设置

使用/settings路由为给定索引自定义搜索设置。您可以使用更新设置端点一次修改所有索引设置，或者使用子路由配置单个设置。

有关索引设置的概念概述，请参阅索引说明。要了解有关索引配置基础知识的更多信息，请参阅索引配置教程。

设置界面

Meilisearch 云用户可以通过索引界面和/settings路由管理索引设置。托管自己的Meilisearch实例的用户只能通过/settings路由管理索引设置。

设置对象

默认情况下，设置对象如下所示。所有字段都是可修改的。

json

{
  "displayedAttributes": [
    "*"
  ],
  "searchableAttributes": [
    "*"
  ],
  "filterableAttributes": [],
  "sortableAttributes": [],
  "rankingRules":
  [
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness"
  ],
  "stopWords": [],
  "nonSeparatorTokens": [],
  "separatorTokens": [],
  "dictionary": [],
  "synonyms": {},
  "distinctAttribute": null,
  "typoTolerance": {
    "enabled": true,
    "minWordSizeForTypos": {
      "oneTypo": 5,
      "twoTypos": 9
    },
    "disableOnWords": [],
    "disableOnAttributes": []
  },
  "faceting": {
    "maxValuesPerFacet": 100
  },
  "pagination": {
    "maxTotalHits": 1000
  },
  "proximityPrecision": "byWord",
  "searchCutoffMs": null
}

名称	类型	默认值	描述
`字典`	字符串数组	空	Meilisearch 应将其解析为单个术语的字符串列表
`displayedAttributes`	字符串数组	所有属性：`["*"]`	返回的文档中显示的字段
`distinctAttribute`	字符串	`null`	搜索返回具有给定字段的不同（不同）值的文档
`faceting`	对象	默认对象	分面设置
`filterableAttributes`	字符串数组	空	用作过滤器和分面的属性
`pagination`	对象	默认对象	分页设置
`proximityPrecision`	字符串	`"byWord"`	计算邻近度排名规则时的精度级别
`rankingRules`	字符串数组	`["words",` `"typo",` `"proximity",` `"attribute",` `"sort",` `"exactness"]`	排名规则列表，按重要性排序
`searchableAttributes`	字符串数组	所有属性：`["*"]`	在其中搜索匹配查询词的字段，按重要性顺序排序
`searchCutoffMs`	整数	`null` 或 1500 毫秒	搜索查询的最大持续时间
`separatorTokens`	字符串数组	空	分隔一个术语开始和结束位置的字符列表
`nonSeparatorTokens`	字符串数组	空	不分隔一个术语开始和结束位置的字符列表
`sortableAttributes`	字符串数组	空	用于对搜索结果排序的属性
`stopWords`	字符串数组	空	Meilisearch 在搜索查询中存在时忽略的词列表
`synonyms`	对象	空	类似处理的关联词列表
`typoTolerance`	对象	默认对象	错字容忍设置
`embedders`	对象的对象	默认对象	执行基于含义的搜索查询所需的嵌入器

名称	类型	默认值	描述
`maxValuesPerFacet`	整数	`100`	为每个分面返回的分面值的最大数量。值按升序字典顺序排序
`sortFacetValuesBy`	对象	所有分面值都按升序字母数字顺序排序 (`"*": "alpha"`)	自定义分面顺序以按降序值计数 (`count`) 或升序字母数字顺序 (`alpha`) 进行排序

名称	类型	默认值	描述
`maxValuesPerFacet`	整数	`100`	为每个分面返回的分面值的最大数量。值按升序字典顺序排序
`sortFacetValuesBy`	对象	所有分面值都按升序字母数字顺序排序 (`"*": "alpha"`)	自定义分面顺序以按降序值计数 (`count`) 或升序字母数字顺序 (`alpha`) 进行排序

本地化属性

默认情况下，Meilisearch 会自动检测文档中使用的语言。此设置允许您明确定义数据集中存在哪些语言以及在哪些字段中存在。

本地化属性会影响searchableAttributes、filterableAttributes和sortableAttributes。

`locales` 和 `localizedAttributes`

locales 和 localizedAttributes 具有相同的目标：在 Meilisearch 的语言自动检测无法按预期工作时，明确指定搜索中使用的语言。

如果您认为 Meilisearch 由于查询文本而检测到错误的语言，请使用 locales 明确设置搜索语言。

如果您认为 Meilisearch 由于文档而检测到错误的语言，请使用 localizedAttributes 在索引级别明确设置文档语言。

为了完全控制 Meilisearch 在索引和搜索时检测语言的方式，请同时设置 locales 和 localizedAttributes。

本地化属性对象

localizedAttributes 必须是一个语言环境对象的数组。其默认值为 []。

语言环境对象必须具有以下字段

名称	类型	默认值	描述
`locales`	字符串数组	`[]`	指示一个或多个 ISO-639 语言环境的字符串列表
`attribute_patterns`	字符串数组	`[]`	指示哪些字段对应于指定的语言环境的字符串列表

Meilisearch 支持以下 locales：epo、eng、rus、cmn、spa、por、ita、ben、fra、deu、ukr、kat、ara、hin、jpn、heb、yid、pol、amh、jav、kor、nob、dan、swe、fin、tur、nld、hun、ces、ell、bul、bel、mar、kan、ron、slv、hrv、srp、mkd、lit、lav、est、tam、vie、urd、tha、guj、uzb、pan、aze、ind、tel、pes、mal、ori、mya、nep、sin、khm、tuk、aka、zul、sna、afr、lat、slk、cat、tgl、hye。

您也可以为 locales 分配一个空数组。在这种情况下，Meilisearch 将自动检测关联的 attributePatterns 的语言。

`attributePatterns`

属性模式可以在开头或结尾使用 * 通配符来匹配多个字段：en_*、*-ar。

您也可以将 attributePatterns 设置为 *，在这种情况下，Meilisearch 将将所有字段视为在关联的语言环境中。

获取本地化属性设置

GET/indexes/{index_uid}/settings/localized-attributes

获取索引的本地化属性设置。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/localized-attributes'

响应：`200 OK`

json

{
  "localizedAttributes": [
    {"locales": ["jpn"], "attributePatterns": ["*_ja"]}
  ]
}

更新本地化属性设置

PUT/indexes/{index_uid}/settings/localized-attributes

更新索引的本地化属性设置。

路径参数

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

主体

{
  "localizedAttributes": [
    {
     "locale": [<String>, …],
     "attributePatterns": [<String>, …],
    }
  ]
}

名称	类型	默认值	描述
`localizedAttributes`	对象数组	`[]`	为一个或多个属性明确设置特定的语言环境

示例

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "INDEX_NAME",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

重置分页设置

RESET/indexes/{index_uid}/settings/localized-attributes

将索引的本地化属性重置为其默认值。

路径参数

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

示例

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "INDEX_NAME",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

分页

为了保护您的数据库免受恶意抓取，Meilisearch 每个搜索的默认结果限制为 1000 条。此设置允许您配置每个搜索返回的最大结果数。

maxTotalHits 优先于搜索参数，如 limit、offset、hitsPerPage 和 page。

例如，如果您将 maxTotalHits 设置为 100，无论 offset 配置的值如何，您都无法访问超过 100 的搜索结果。

要了解有关使用 Meilisearch 对搜索结果进行分页的更多信息，请参阅我们的专用指南。

分页对象

名称	类型	默认值	描述
`maxTotalHits`	整数	`1000`	Meilisearch 可以返回的最大搜索结果数

获取分页设置

GET/indexes/{index_uid}/settings/pagination

获取索引的分页设置。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/pagination'

响应：`200 OK`

json

{
  "maxTotalHits": 1000
}

更新分页设置

PATCH/indexes/{index_uid}/settings/pagination

部分更新索引的分页设置。

路径参数

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

主体

{maxTotalHits: <Integer>}

名称	类型	默认值	描述
`maxTotalHits`	整数	`1000`	Meilisearch 可以返回的最大搜索结果数

警告

将 maxTotalHits 设置为高于默认值的值会对搜索性能产生负面影响。将 maxTotalHits 设置为超过 20000 的值可能会导致查询花费数秒才能完成。

示例

curl \
  -X PATCH 'http://localhost:7700/indexes/books/settings/pagination' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "maxTotalHits": 100
  }'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

重置分页设置

将索引的分页设置重置为其默认值。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/pagination'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

邻近精度

计算单词之间的距离是一个资源密集型操作。降低此操作的精度可以显着提高性能，并且在大多数用例中对结果相关性几乎没有影响。Meilisearch 在根据邻近度对结果进行排名以及用户执行短语搜索时使用单词距离。

proximityPrecision 接受以下字符串值之一

"byWord"：计算查询词之间的精确距离。更高的精度，但可能会导致更长的索引时间。这是默认设置
"byAttribute"：确定多个查询词是否出现在同一个属性中。较低的精度，但索引时间较短

获取邻近精度设置

GET/indexes/{index_uid}/settings/proximity-precision

获取索引的邻近精度设置。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/proximity-precision'

响应：`200 OK`

json

{
  "proximityPrecision": "byWord"
}

更新邻近精度设置

PUT/indexes/{index_uid}/settings/proximity-precision

更新索引的分页设置。

路径参数

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

主体

"byWord"|"byAttribute"

示例

curl \
  -X PUT 'http://localhost:7700/indexes/books/settings/proximity-precision' \
  -H 'Content-Type: application/json' \
  --data-binary '"byAttribute"'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-04-14T15:50:29.821044Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

重置邻近精度设置

将索引的邻近精度设置重置为其默认值。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/proximity-precision'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-04-14T15:51:47.821044Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

排名规则

排名规则是根据特定条件对搜索结果进行排名的内置规则。它们按其在 rankingRules 数组中出现的顺序应用。

要了解有关排名规则的更多信息，请参阅我们的专用指南。

排名规则数组

名称	描述
`"words"`	按匹配查询词的数量递减对结果排序
`"typo"`	按拼写错误的数量递增对结果排序
`"proximity"`	按匹配查询词之间的距离递增对结果排序
`"attribute"`	根据属性排名顺序对结果排序
`"sort"`	根据查询时确定的参数对结果排序
`"exactness"`	根据匹配词与查询词的相似度对结果排序

默认顺序

json

[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness"
]

获取排名规则

GET/indexes/{index_uid}/settings/ranking-rules

获取索引的排名规则。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/ranking-rules'

响应：`200 Ok`

json

[
  "words",
  "typo",
  "proximity",
  "attribute",
  "sort",
  "exactness",
  "release_date:desc"
]

更新排名规则

PUT/indexes/{index_uid}/settings/ranking-rules

更新索引的排名规则。

路径参数

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

主体

[<String>, <String>, …]

一个按重要性顺序包含排名规则的数组。

要创建自定义排名规则，请提供属性后跟冒号 (:)，以及用于升序的 asc 或用于降序的 desc。

要应用升序排序（按值递增排序结果）：attribute_name:asc
要应用降序排序（按值递减排序结果）：attribute_name:desc

警告

如果某些文档不包含自定义排名规则中定义的属性，则排名规则的应用未定义，并且搜索结果可能不会按预期排序。

确保自定义排名规则中使用的任何属性都存在于所有文档中。例如，如果您设置自定义排名规则 desc(year)，请确保所有文档都包含属性 year。

要了解有关排名规则的更多信息，请参阅我们的专用指南。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/ranking-rules' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "words",
    "typo",
    "proximity",
    "attribute",
    "sort",
    "exactness",
    "release_date:asc",
    "rank:desc"
  ]'

响应：`202 已接受`

json

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

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

重置排名规则

DELETE/indexes/{index_uid}/settings/ranking-rules

将索引的排名规则重置为其默认值。

提示

重置排名规则与删除它们并不相同。要删除排名规则，请使用更新排名规则端点。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/ranking-rules'

响应：`202 已接受`

json

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

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

可搜索属性

与 searchableAttributes 列表中的属性关联的值将被搜索以匹配查询词。列表的顺序也决定了属性排名顺序。

默认情况下，searchableAttributes 数组等于数据集中所有字段。此行为由值 ["*"] 表示。

警告

更新可搜索属性将重新索引索引中的所有文档，这可能需要一些时间。我们建议您先更新索引设置，然后再添加文档，因为这可以减少 RAM 消耗。

要了解有关可搜索属性的更多信息，请参阅我们的专用指南。

获取可搜索属性

GET/indexes/{index_uid}/settings/searchable-attributes

获取索引的可搜索属性。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/searchable-attributes'

响应：`200 Ok`

json

[
  "title",
  "overview",
  "genres",
  "release_date.year"
]

更新可搜索属性

PUT/indexes/{index_uid}/settings/searchable-attributes

更新索引的可搜索属性。

警告

由于实现错误，手动更新 searchableAttributes 将更改 JSON 响应中文档字段的显示顺序。此行为不一致，将在未来版本中修复。

路径参数

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

主体

[<String>, <String>, …]

一个字符串数组。每个字符串都应为所选索引中存在的属性。数组应按重要性顺序给出：从最重要的属性到最不重要的属性。

如果某个属性包含对象，则可以使用点表示法将一个或多个键设置为此设置的值："searchableAttributes": ["release_date.year"]。

警告

如果字段不存在，则不会抛出错误。

要了解有关可搜索属性的更多信息，请参阅我们的专用指南。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/searchable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "title",
    "overview",
    "genres"
  ]'

在此示例中，在 title 中匹配的文档将比在 overview 中匹配的另一个文档更相关。

响应：`202 已接受`

json

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

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

重置可搜索属性

DELETE/indexes/{index_uid}/settings/searchable-attributes

将索引的可搜索属性重置为默认值。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/searchable-attributes'

响应：`202 已接受`

json

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

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

搜索截止时间

配置搜索查询的最大持续时间。Meilisearch 将中断任何超过截止值的搜索。

默认情况下，Meilisearch 在 1500 毫秒后中断搜索。

获取搜索截止时间

GET/indexes/{index_uid}/settings/search-cutoff-ms

获取索引的搜索截止值。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms'

响应：`200 Ok`

json

null

更新搜索截止时间

PUT/indexes/{index_uid}/settings/search-cutoff-ms

更新索引的搜索截止值。

路径参数

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

主体

一个表示以毫秒为单位的截止值的整数。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms' \
  -H 'Content-Type: application/json' \
  --data-binary '150'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-03-21T06:33:41.000000Z"
}

使用此 taskUid 获取有关任务状态的更多详细信息。

重置搜索截止时间

DELETE/indexes/{index_uid}/settings/search-cutoff-ms

将索引的搜索截止值重置为其默认值 null。这转换为 1500 毫秒的截止时间。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/search-cutoff-ms'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2023-03-21T07:05:16.000000Z"
}

分隔符标记

将字符串配置为自定义分隔符标记，指示单词的结束和开始位置。

separatorTokens 列表中的标记添加到 Meilisearch 的默认分隔符列表的顶部。要从默认列表中删除分隔符，请使用 nonSeparatorTokens 设置。

获取分隔符标记

GET/indexes/{index_uid}/settings/separator-tokens

获取索引的自定义分隔符标记列表。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/articles/settings/separator-tokens'

响应：`200 Ok`

json

[]

更新分隔符标记

PUT/indexes/{index_uid}/settings/separator-tokens

更新索引的自定义分隔符标记列表。

路径参数

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

主体

["|", "&hellip;"]

一个字符串数组，每个字符串指示一个单词分隔符。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/articles/settings/separator-tokens' \
  -H 'Content-Type: application/json'  \
  --data-binary '["|", "&hellip;"]'

响应：`202 已接受`

json

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

使用此 taskUid 获取有关任务状态的更多详细信息。

重置分隔符标记

DELETE/indexes/{index_uid}/settings/separator-tokens

将索引的自定义分隔符标记列表重置为其默认值 []。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/articles/settings/separator-tokens'

响应：`202 已接受`

json

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

使用此 taskUid 获取有关任务状态的更多详细信息。

非分隔符标记

从 Meilisearch 的默认单词分隔符列表中删除标记。

获取非分隔符标记

GET/indexes/{index_uid}/settings/non-separator-tokens

获取索引的非分隔符标记列表。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/articles/settings/non-separator-tokens'

响应：`200 Ok`

json

[]

更新非分隔符标记

PUT/indexes/{index_uid}/settings/non-separator-tokens

更新索引的非分隔符标记列表。

路径参数

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

主体

["@", "#"]

一个字符串数组，每个字符串指示单词分隔符列表中存在的标记。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/articles/settings/non-separator-tokens' \
  -H 'Content-Type: application/json'  \
  --data-binary '["@", "#"]'

响应：`202 已接受`

json

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

使用此 taskUid 获取有关任务状态的更多详细信息。

重置非分隔符标记

DELETE/indexes/{index_uid}/settings/non-separator-tokens

将索引的非分隔符标记列表重置为其默认值 []。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/articles/settings/separator-tokens'

响应：`202 已接受`

json

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

使用此 taskUid 获取有关任务状态的更多详细信息。

可排序属性

使用 sort 搜索参数对搜索结果进行排序时可以使用这些属性。

警告

更新可排序属性将重新索引索引中的所有文档，这可能需要一些时间。我们建议您先更新索引设置，然后再添加文档，因为这可以减少 RAM 消耗。

要了解有关可排序属性的更多信息，请参阅我们的专用指南。

获取可排序属性

GET/indexes/{index_uid}/settings/sortable-attributes

获取索引的可排序属性。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/sortable-attributes'

响应：`200 Ok`

json

[
  "price",
  "author.surname"
]

更新可排序属性

PUT/indexes/{index_uid}/settings/sortable-attributes

更新索引的可排序属性列表。

您可以在我们的专用指南中阅读有关查询时排序的更多信息。

路径参数

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

主体

[<String>, <String>, …]

字符串数组。每个字符串都应是选定索引中存在的属性。

如果某个属性包含对象，则可以使用点表示法将一个或多个键设置为此设置的值："sortableAttributes": ["author.surname"]。

警告

如果字段不存在，则不会抛出错误。

要了解有关可排序属性的更多信息，请参阅我们的专用指南。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/books/settings/sortable-attributes' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "price",
    "author"
  ]'

响应：`202 已接受`

json

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

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

重置可排序属性

DELETE/indexes/{index_uid}/settings/sortable-attributes

将索引的可排序属性列表重置回其默认值。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/sortable-attributes'

响应：`202 已接受`

json

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

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

停用词

添加到 stopWords 列表中的单词在将来的搜索查询中将被忽略。

警告

更新停用词将重新索引索引中的所有文档，这可能需要一些时间。我们建议您先更新索引设置，然后再添加文档，因为这可以减少 RAM 消耗。

提示

停用词与数据集中使用的语言密切相关。例如，大多数包含英文文档的数据集将包含无数次的 the 和 of。相反，意大利语数据集将受益于忽略诸如 a、la 或 il 之类的单词。

这个由法国开发者维护的网站提供了不同语言中可能停用词的列表。请注意，根据您的数据集和用例，您需要调整这些列表以获得最佳结果。

获取停用词

GET/indexes/{index_uid}/settings/stop-words

获取索引的停用词列表。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/stop-words'

响应：`200 Ok`

json

[
  "of",
  "the",
  "to"
]

更新停用词

PUT/indexes/{index_uid}/settings/stop-words

更新索引的停用词列表。

路径参数

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

主体

[<String>, <String>, …]

一个字符串数组。每个字符串都应该是一个单词。

如果已存在停用词列表，它将被覆盖（替换）。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/stop-words' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    "the",
    "of",
    "to"
  ]'

响应：`202 已接受`

json

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

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

重置停用词

DELETE/indexes/{index_uid}/settings/stop-words

将索引的停用词列表重置为其默认值。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/stop-words'

响应：`202 已接受`

json

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

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

同义词

synonyms 对象包含单词及其相应的同义词。在 Meilisearch 中，同义词被认为与其实际关联的单词相同，用于计算搜索结果。

要了解有关同义词的更多信息，请参阅我们的专用指南。

获取同义词

GET/indexes/{index_uid}/settings/synonyms

获取索引的同义词列表。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/movies/settings/synonyms'

响应：`200 OK`

json

{
  "wolverine": [
    "xmen",
    "logan"
  ],
  "logan": [
    "wolverine",
    "xmen"
  ],
  "wow": [
    "world of warcraft"
  ]
}

更新同义词

PUT/indexes/{index_uid}/settings/synonyms

更新索引的同义词列表。同义词是标准化的。

路径参数

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

主体

{
  <String>: [<String>, <String>, …],
  …
}

一个包含所有同义词及其关联单词的对象。将关联单词添加到数组中以设置单词的同义词。

要了解有关同义词的更多信息，请参阅我们的专用指南。

示例

curl \
  -X PUT 'http://localhost:7700/indexes/movies/settings/synonyms' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "wolverine": [
      "xmen",
      "logan"
    ],
    "logan": [
      "wolverine",
      "xmen"
    ],
    "wow": ["world of warcraft"]
  }'

响应：`202 已接受`

json

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

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

重置同义词

DELETE/indexes/{index_uid}/settings/synonyms

将索引的同义词列表重置为其默认值。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/movies/settings/synonyms'

响应：`202 已接受`

json

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

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

错字容错

错字容错帮助用户即使在搜索查询包含拼写错误或错字时也能找到相关结果。此设置允许您配置错字的最小词大小，并为特定单词或属性禁用错字容错。

要详细了解错字容错，请参阅我们的专门指南。

错字容错对象

名称	类型	默认值	描述
`启用`	布尔值	`true`	是否启用错字容错
`minWordSizeForTypos.oneTypo`	整数	`5`	接受 1 个错字的最小词大小；必须介于`0`和`twoTypos`之间
`minWordSizeForTypos.twoTypos`	整数	`9`	接受 2 个错字的最小词大小；必须介于`oneTypo`和`255`之间
`disableOnWords`	字符串数组	空	禁用错字容错功能的单词数组
`disableOnAttributes`	字符串数组	空	禁用错字容错功能的属性数组

获取错字容错设置

GET/indexes/{index_uid}/settings/typo-tolerance

获取索引的错字容错设置。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/books/settings/typo-tolerance'

响应：`200 OK`

json

{
  "enabled": true,
  "minWordSizeForTypos": {
    "oneTypo": 5,
    "twoTypos": 9
  },
  "disableOnWords": [],
  "disableOnAttributes": []
}

更新错字容错设置

PATCH/indexes/{index_uid}/settings/typo-tolerance

部分更新索引的错字容错设置。

路径参数

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

主体

{
  "enabled": <Boolean>,
  "minWordSizeForTypos": {
    "oneTypo": <Integer>,
    "twoTypos": <Integer>
  },
  "disableOnWords": [<String>, <String>, …],
  "disableOnAttributes": [<String>, <String>, …]
}

名称	类型	默认值	描述
`启用`	布尔值	`true`	是否启用错字容错
`minWordSizeForTypos.oneTypo`	整数	`5`	接受 1 个错字的最小词大小；必须介于`0`和`twoTypos`之间
`minWordSizeForTypos.twoTypos`	整数	`9`	接受 2 个错字的最小词大小；必须介于`oneTypo`和`255`之间
`disableOnWords`	字符串数组	空	禁用错字容错功能的单词数组
`disableOnAttributes`	字符串数组	空	禁用错字容错功能的属性数组

示例

curl \
  -X PATCH 'http://localhost:7700/indexes/books/settings/typo-tolerance' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "minWordSizeForTypos": {
      "oneTypo": 4,
      "twoTypos": 10
    },
    "disableOnAttributes": ["title"]
  }'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:56:44.991039Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

重置错字容错设置

DELETE/indexes/{index_uid}/settings/typo-tolerance

将索引的错字容错设置重置为其默认值。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/books/settings/typo-tolerance'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

嵌入器（实验性）

嵌入器将文档和查询转换为向量嵌入。您必须配置至少一个嵌入器才能使用 AI 驱动的搜索。

嵌入器对象

嵌入器对象最多可以包含 256 个嵌入器对象。每个嵌入器对象必须分配一个唯一的名称

json

{
  "default": {
    "source": "huggingFace",
    "model": "BAAI/bge-base-en-v1.5",
    "documentTemplate": "A movie titled '{{doc.title}}' whose description starts with {{doc.overview|truncatewords: 20}}"
  },
  "openai": {
    "source": "openAi",
    "apiKey": "OPENAI_API_KEY",
    "model": "text-embedding-3-small",
    "documentTemplate": "A movie titled {{doc.title}} whose description starts with {{doc.overview|truncatewords: 20}}",
  }
}

这些嵌入器对象可能包含以下字段

名称	类型	默认值	描述
`源`	字符串	空	将从文档生成嵌入的第三方工具。必须是`openAi`、`huggingFace`、`ollama`、`rest`或`userProvided`
`URL`	字符串	`http://localhost:11434/api/embeddings`	Meilisearch 查询嵌入器时联系的 URL
`API 密钥`	字符串	空	Meilisearch 应随每个请求发送给嵌入器的身份验证令牌。如果不存在，Meilisearch 将尝试从环境变量中读取它
`模型`	字符串	空	嵌入器在生成向量时使用的模型
`文档模板`	字符串	`{% for field in fields %}{{field.name}}: {{field.value}}\n{% endfor %}`	定义 Meilisearch 发送给嵌入器的数据的模板
`维度`	整数	空	所选模型中的维度数。如果未提供，Meilisearch 会尝试推断此值
`版本`	字符串	空	模型版本哈希
`分布`	对象	空	描述搜索结果的自然分布。必须包含两个字段，`mean`和`sigma`，每个字段包含一个介于`0`和`1`之间的数值
`请求`	对象	空	表示 Meilisearch 向远程嵌入器发出的请求的 JSON 值
`响应`	对象	空	表示 Meilisearch 预期从远程嵌入器接收到的请求的 JSON 值

获取嵌入器设置

GET/indexes/{index_uid}/settings/embedders

获取为索引配置的嵌入器。

路径参数

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

示例

curl \
  -X GET 'http://localhost:7700/indexes/INDEX_NAME/settings/embedders'

响应：`200 OK`

json

{
  "default": {
    "source":  "openAi",
    "apiKey": "OPENAI_API_KEY",
    "model": "text-embedding-3-small",
    "documentTemplate": "A movie titled {{doc.title}} whose description starts with {{doc.overview|truncatewords: 20}}",
    "dimensions": 1536
  }
}

更新嵌入器设置

PATCH/indexes/{index_uid}/settings/embedders

部分更新索引的嵌入器设置。当此设置更新时，Meilisearch 可能会重新索引所有文档并重新生成其嵌入。

路径参数

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

主体

json

{
  "default": {
    "source": <String>,
    "url": <String>,
    "apiKey": <String>,
    "model": <String>,
    "documentTemplate": <String>,
    "dimensions": <Integer>,
    "revision": <String>,
    "distribution": {
      "mean": <Float>,
      "sigma": <Float>
    },
    "request": { … },
    "response": { … },
    "headers": { … }
  }
}

将嵌入器设置为null以将其从嵌入器列表中删除。

`源`

使用source配置嵌入器的源。以下嵌入器可以自动为文档和查询生成向量

openAi
huggingFace
ollama

此外，使用rest通过提供 REST API 的任何嵌入器自动生成嵌入。

您还可以配置userProvided嵌入器。在这种情况下，您必须手动将向量数据包含在文档的_vector字段中。您还必须手动为搜索查询生成向量。

此字段是必填字段。

`URL`

Meilisearch 查询url以生成查询和文档的向量嵌入。url必须指向与 REST 兼容的嵌入器。您还可以使用url与代理一起使用，例如在从代理后面定位openAi时。

使用rest嵌入器时，此字段是必填字段。

使用ollama和openAi嵌入器时，此字段是可选字段。

此字段与huggingFace和userProvided嵌入器不兼容。

`API 密钥`

Meilisearch 应随每个请求发送给嵌入器的身份验证令牌。

如果使用受保护的rest嵌入器，则此字段是必填字段。

此字段对于openAI和ollama嵌入器是可选的。如果您未指定apiKey，Meilisearch 将尝试分别从环境变量OPENAI_API_KEY和MEILI_OLLAMA_URL中读取它。

此字段与huggingFace和userProvided嵌入器不兼容。

`模型`

嵌入器在生成向量时使用的模型。这些是 Meilisearch 官方支持的模型

openAi：openai-text-embedding-ada-002、text-embedding-3-small和text-embedding-3-large
huggingFace：BAAI/bge-base-en-v1.5

其他模型，例如HuggingFace 的 BERT 模型或 Ollama 和 REST 嵌入器提供的模型也可能与 Meilisearch 兼容。

此字段对于Ollama嵌入器是必填字段。

此字段对于openAi和huggingFace是可选的。默认情况下，Meilisearch 分别使用text-embedding-3-small和BAAI/bge-base-en-v1.5。

此字段与rest和userProvided嵌入器不兼容。

`文档模板`

documentTemplate是一个包含Liquid 模板的字符串。Meillisearch 为每个文档内插模板并将生成的文本发送给嵌入器。然后，嵌入器根据此文本生成文档向量。

您可以使用以下上下文值

{{doc.FIELD}}：doc代表文档本身。FIELD必须对应于所有文档中存在的属性，值将替换为输入文档中该字段的值
{{fields}}：索引中任何文档中出现的全部field的列表。此列表中的每个field对象具有两个属性：name和value。如果文档中不存在field，则value为nil

为了获得最佳效果，请构建仅包含高度相关数据的简短模板。如果使用长字段，请考虑截断它。如果您未手动设置，则documentTemplate将包含所有文档字段。这可能会导致性能和相关性不佳。

此字段是可选字段，但强烈建议所有嵌入器使用。

`维度`

所选模型中的维度数。如果未提供，Meilisearch 会尝试推断此值。

在大多数情况下，dimensions应与您选择的模型的精确值相同。将dimensions设置为低于模型的值可能会提高性能，并且仅在以下 OpenAI 模型中受支持

openAi：text-embedding-3-small、text-embedding-3-large

此字段对于userProvided嵌入器是必填字段。

此字段对于openAi、huggingFace、ollama和rest嵌入器是可选字段。

`版本`

使用此字段使用模型的特定版本。

此字段对于huggingFace嵌入器是可选字段。

此字段与所有其他嵌入器不兼容。

`请求`

request必须是与您必须发送给rest嵌入器的请求具有相同结构和数据的 JSON 对象。

包含 Meilisearch 应发送给嵌入器的输入文本的字段必须替换为"{{text}}"

json

{
  "source": "rest",
  "request": {
    "prompt": "{{text}}"
    …
  },
  …
}

如果在单个请求中发送多个文档，请将输入字段替换为["{{text}}", "{{..}}"]

json

{
  "source": "rest",
  "request": {
    "prompt": ["{{text}}", "{{..}}"]
    …
  },
  …
}

使用rest嵌入器时，此字段是必填字段。

此字段与所有其他嵌入器不兼容。

`响应`

response必须是与您期望从rest嵌入器接收到的响应具有相同结构和数据的 JSON 对象。

包含嵌入本身的字段必须替换为"{{embedding}}"

json

{
  "source": "rest",
  "response": {
    "data": "{{embedding}}"
    …
  },
  …
}

如果单个响应包含多个嵌入，则包含嵌入本身的字段必须是一个包含两个项目的数组。一个必须声明单个嵌入的位置和结构，而第二个项目应为"{{..}}"

json

{
  "source": "rest",
  "response": {
    "data": [
      {
        "embedding": "{{embedding}}"
      },
      "{{..}}"
    ]
    …
  },
  …
}

使用rest嵌入器时，此字段是必填字段。

此字段与所有其他嵌入器不兼容。

`分布`

由于数学原因，语义搜索结果的_rankingScore倾向于紧密地集中在某个平均值附近，该平均值取决于所使用的嵌入器和模型。与关键字搜索结果相比，这可能导致相关语义命中被低估，而无关语义命中被高估。

在配置嵌入器以使用仿射变换校正返回的语义命中的_rankingScore时，请使用distribution

curl \
  -X PATCH 'http://localhost:7700/indexes/INDEX_NAME/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "default": {
        "source":  "huggingFace",
        "model": "MODEL_NAME",
        "distribution": {
          "mean": 0.7,
          "sigma": 0.3
        }
      }
    }
  }'

配置distribution需要一定程度的反复试验，您必须在其中执行语义搜索并监控结果。根据其rankingScore和相关性，为该索引添加观察到的mean和sigma值。

distribution是一个可选字段，与所有嵌入器源兼容。它必须是一个包含两个字段的对象

mean：一个介于0和1之间的数字，表示在使用distribution设置之前“有点相关”的命中的语义分数
sigma：一个介于0和1之间的数字，表示“非常相关”命中和“有点相关”命中以及“有点相关”命中和“不相关”命中之间_rankingScore的平均绝对差值。

更改distribution不会触发重新索引操作。

`headers`

headers必须是一个JSON对象，其键表示要发送到嵌入器的请求中额外标头的名称，其值表示这些额外标头的值。

默认情况下，Meilisearch 会将以下标头与所有发送到rest嵌入器的请求一起发送

Authorization: Bearer EMBEDDER_API_KEY（仅当提供apiKey时）
Content-Type: application/json

如果headers包含其中一个字段，则显式声明的值优先于默认值。

使用rest嵌入器时，此字段是可选的。

此字段与所有其他嵌入器不兼容。

示例

curl \
  -X PATCH 'http://localhost:7700/indexes/INDEX_NAME/settings' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "embedders": {
      "default": {
        "source":  "openAi",
        "apiKey": "anOpenAiApiKey",
        "model": "text-embedding-3-small",
        "documentTemplate": "A document titled '{{doc.title}}' whose description starts with {{doc.overview|truncatewords: 20}}"
      }
    }
  }'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "kitchenware",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2024-05-11T09:33:12.691402Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

重置嵌入器设置

DELETE/indexes/{index_uid}/settings/embedders

从您的索引中删除所有嵌入器。

要删除单个嵌入器，请使用更新嵌入器设置端点并将目标嵌入器设置为null。

路径参数

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

示例

curl \
  -X DELETE 'http://localhost:7700/indexes/INDEX_NAME/settings/embedders'

响应：`202 已接受`

json

{
  "taskUid": 1,
  "indexUid": "books",
  "status": "enqueued",
  "type": "settingsUpdate",
  "enqueuedAt": "2022-04-14T20:53:32.863107Z"
}

您可以使用返回的 taskUid 获取有关任务状态的更多详细信息。

编辑此页面

这有帮助吗？

想要包含更多细节？提出问题在我们公开的文档仓库中。

设置

设置界面

设置对象

所有设置

获取设置

路径参数

示例

响应：200 Ok

更新设置

路径参数

主体

示例

警告

响应：202 已接受

重置设置

路径参数

示例

响应：202 已接受

字典

提示

获取字典

路径参数

示例

响应：200 OK

更新字典

路径参数

主体

示例

响应：202 已接受

重置字典

路径参数

示例

响应：202 已接受

显示的属性

获取显示的属性

路径参数

示例

响应：200 Ok

更新显示的属性

路径参数

主体

警告

示例

响应：202 已接受

重置显示的属性

路径参数

示例

响应：202 已接受

唯一属性

警告

获取唯一属性

路径参数

示例

响应：200 Ok

更新唯一属性

路径参数

主体

警告

示例

响应：202 已接受

重置唯一属性

路径参数

示例

响应：202 已接受

分面

分面对象

获取分面设置

路径参数

示例

响应：200 OK

更新分面设置

路径参数

主体

注意

示例

响应：202 已接受

重置分面设置

路径参数

示例

响应：200 OK

响应：`200 Ok`

响应：`202 已接受`

响应：`202 已接受`

响应：`200 OK`

响应：`202 已接受`

响应：`202 已接受`

响应：`200 Ok`

响应：`202 已接受`

响应：`202 已接受`

响应：`200 Ok`

响应：`202 已接受`

响应：`202 已接受`

响应：`200 OK`

响应：`202 已接受`

响应：`200 OK`

响应：`200 Ok`

响应：`202 已接受`

响应：`202 已接受`

`locales`

`attributePatterns`

响应：`200 OK`

响应：`202 已接受`

响应：`202 已接受`

响应：`200 OK`

响应：`202 已接受`

响应：`202 已接受`

响应：`200 OK`

响应：`202 已接受`

响应：`202 已接受`