设置
/settings 路由允许您为指定索引自定义搜索设置
使用 /settings 路由可以自定义指定索引的搜索设置。您可以通过更新设置端点一次性修改所有索引设置，或者使用子路由来配置单个设置。
关于索引设置的概念性概述，请参阅索引说明。要了解索引配置的基础知识，请参考索引配置教程。
设置界面
Meilisearch Cloud 除了提供 /settings 路由外，还提供了用户友好的图形界面来管理索引设置。Cloud 界面能提供更即时可见的反馈，与搜索预览结合使用时，有助于调整相关性排序。
设置对象
默认情况下，设置对象如下所示。所有字段均可修改。
所有设置
此路由允许您一次性检索、配置或重置索引的所有设置。
获取设置
获取索引的设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
示例
响应：200 Ok
更新设置
更新索引的设置。
将设置项设为 null 会将其重置为默认值。
设置路由的更新是部分更新。这意味着请求体中未提供的参数将保持不变。
如果提供的索引不存在，将会被创建。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
Body
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
dictionary | 字符串数组 | 空 | Meilisearch 应视为单个术语处理的字符串列表 |
displayedAttributes | 字符串数组 | 所有属性: ["*"] | 返回文档中显示的字段 |
distinctAttribute | 字符串 | null | 搜索返回给定字段具有不同值的文档 |
faceting | 对象 | 默认对象 | 分面设置 |
filterableAttributes | 字符串或对象数组 | 空 | 用作过滤器和分面的属性 |
pagination | 对象 | 默认对象 | 分页设置 |
proximityPrecision | 字符串 | "byWord" | 计算邻近度排序规则时的精确级别 |
facetSearch | 布尔值 | true | 启用或禁用分面搜索功能 |
prefixSearch | 字符串 | "indexingTime" | Meilisearch 何时应仅返回匹配查询开头的结果 |
rankingRules | 字符串数组 | ["words","typo","proximity","attribute","sort","exactness"] | 按重要性排序的排序规则列表 |
searchableAttributes | 字符串数组 | 所有属性: ["*"] | 按重要性排序的用于搜索匹配查询词的字段 |
searchCutoffMs | 整数 | null, 或 1500ms | 搜索查询的最大持续时间 |
separatorTokens | 字符串数组 | 空 | 分隔术语开始和结束的字符列表 |
nonSeparatorTokens | 字符串数组 | 空 | 不用于分隔术语开始和结束的字符列表 |
sortableAttributes | 字符串数组 | 空 | 用于排序搜索结果的属性 |
stopWords | 字符串数组 | 空 | 搜索查询中出现时被 Meilisearch 忽略的单词列表 |
synonyms | 对象 | 空 | 被视为相似的相关单词列表 |
typoTolerance | 对象 | 默认对象 | 拼写容错设置 |
embedders | 对象 | 默认对象 | 执行基于语义的搜索查询所需的嵌入器 |
chat experimental | 对象 | 默认对象 | 执行基于对话的查询的聊天设置 |
示例
如果 Meilisearch 在更新请求中的任何设置时遇到错误，它会立即停止处理请求并返回错误信息。在这种情况下，数据库设置将保持不变。返回的错误信息仅针对遇到的第一个错误。
响应：202 Accepted
你可以使用这个 taskUid 来获取任务状态的更多详细信息。
重置设置
将所有索引设置重置为它们的默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid标识符 |
示例
响应：202 Accepted
你可以使用这个 taskUid 来获取任务状态的更多详细信息。
自定义词典
允许用户通过添加自定义术语的补充词典，指示 Meilisearch 将字符串组视为单个术语。
这在处理包含大量领域特定词汇的数据集时特别有用，也适用于日语等不以空格分隔单词的语言。
对于空格分隔的语言，自定义词典在某些用例中也很实用，例如包含 "J. R. R. Tolkien" 和 "W. E. B. Du Bois" 等名称的数据集。
获取词典
获取索引的用户自定义词典。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
示例
响应：200 OK
更新词典
更新索引的用户自定义词典。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
请求体
示例
响应: 202 Accepted
使用返回的 taskUid 来获取任务状态的更多详情。
重置字典
将索引的字典重置为其默认值 []。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 202 Accepted
使用返回的 taskUid 来获取任务状态的更多详情。
展示属性
添加到 displayedAttributes 列表中的属性会出现在搜索结果中。displayedAttributes 仅影响搜索端点，对使用 POST 获取文档和使用 GET 获取文档端点没有影响。
默认情况下，displayedAttributes 数组等于数据集中的所有字段。此行为由值 ["*"] 表示。
获取展示属性
获取索引的展示属性。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
示例
响应：200 Ok
更新展示属性
更新索引的展示属性。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
请求体
字符串数组。每个字符串应为选定索引中存在的属性。
如果属性包含对象，可以使用点标记法指定其一个或多个键，例如 "displayedAttributes": ["release_date.year"]。
如果字段不存在，不会抛出错误。
示例
响应：202 Accepted
您可以使用此 taskUid 获取任务状态的更多详细信息。
重置展示属性
将索引的展示属性重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
示例
响应: 202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详情。
去重属性
去重属性（distinct attribute）是一个字段，其值在返回的文档中始终保持唯一。
更新去重属性会重新索引该索引中的所有文档，这可能需要一些时间。我们建议先更新索引设置再添加文档，这样可以减少内存消耗。
获取去重属性
获取索引的去重属性。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
示例
响应: 200 Ok
更新去重属性
更新索引的去重属性字段。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
请求体
一个字符串。该字符串应为选定索引中存在的属性。
如果属性包含对象，可以使用点表示法将其一个或多个键设置为该配置的值，例如 "distinctAttribute": "product.skuid"。
如果字段不存在，不会抛出错误。
示例
响应：202 Accepted
您可以使用此 taskUid 来获取任务状态的更多详细信息。
重置去重属性
将索引的去重属性重置为其默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
示例
响应: 202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详情。
分面搜索
使用 Meilisearch，您可以创建分面搜索界面。此设置允许您：
- 定义
facets搜索参数返回的最大值数量 - 按值计数或字母数字顺序对分面值进行排序
分面搜索对象
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
maxValuesPerFacet | 整型 | 100 | 每个分面返回的最大分面值数量。值按字母升序排列 |
sortFacetValuesBy | 对象 | 所有分面值按字母数字升序排列 ("*": "alpha") | 自定义分面排序方式：按值计数降序 (count) 或按字母数字升序 (alpha) |
获取分面搜索设置
获取索引的分面搜索设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
示例
响应：200 OK
更新分面设置
部分更新索引的分面设置。请求体中未提供的参数将保持不变。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
请求体
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
maxValuesPerFacet | 整数 | 100 | 每个分面返回的最大分面值数量。值按字母升序排列 |
sortFacetValuesBy | 对象 | 所有分面值按字母数字升序排列 ("*": "alpha") | 自定义分面排序方式：按值数量降序(count)或按字母数字升序(alpha) |
假设某个查询的搜索结果中包含 colors 分面的三个值：blue、green 和 red。如果将 maxValuesPerFacet 设置为 2，Meilisearch 在响应体的 facetDistribution 对象中只会返回 blue 和 green。
将 maxValuesPerFacet 设置为较高值可能会对性能产生负面影响。
示例
以下代码示例将 maxValuesPerFacet 设置为 2，按数量降序排列 genres 分面，其他所有分面按字母数字升序排列：
响应: 202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详细信息。
重置分面设置
将索引的分面设置重置为默认值。将 sortFacetValuesBy 设为 null（--data-binary '{ "sortFacetValuesBy": null }'）会将其恢复为默认值（"*": "alpha"）。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid |
示例
响应：200 OK
您可以使用返回的 taskUid 来获取任务状态的更多详细信息。
可筛选属性
filterableAttributes 列表中的属性可以用作筛选器或分面。
更新可筛选属性会重新索引索引中的所有文档，这可能需要一些时间。为了减少内存消耗，建议先更新索引设置再添加文档。
可筛选属性对象
filterableAttributes 可以是一个包含字符串或可筛选属性对象的数组。
可筛选属性对象必须包含以下字段：
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
attributePatterns | 字符串数组 | [] | 表示可筛选字段的字符串列表 |
features | 对象 | {"facetSearch": false, "filters": {"equality": true, "comparison": false} | 列出为指定属性启用的筛选类型 |
attributePatterns
属性模式可以以 * 通配符开头或结尾来匹配多个字段：customer_*, attribute*。
features
features 允许你决定为指定属性启用哪些筛选功能。它接受以下字段：
facetSearch: 是否为指定属性启用分面搜索。布尔值，默认为falsefilter: 列出指定属性的筛选类型。必须是一个对象并接受以下字段：equality: 启用=,!=,IN,EXISTS,IS NULL,IS EMPTY,NOT,AND和OR。布尔值，默认为truecomparison: 启用>,>=,<,<=,TO,EXISTS,IS NULL,IS EMPTY,NOT,AND和OR。布尔值，默认为false
计算 comparison 筛选器是资源密集型操作。禁用它们可能会带来更好的搜索和索引性能。equality 筛选器使用较少的资源，对性能影响有限。
可筛选属性和保留属性
使用简单的字符串语法来匹配保留属性。Meilisearch 的保留字段总是以下划线 (_) 开头，例如 _geo 和 _vector。
如果设置为可筛选属性，保留属性会忽略 features 字段并自动激活所有搜索功能。保留字段不会被通配符 attributePatterns（如 _*）匹配。
获取可筛选属性
获取索引的可筛选属性列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应：200 Ok
更新可筛选属性
更新索引的可筛选属性列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
主体
一个字符串数组，包含可在查询时用作筛选器的属性。当使用字符串数组格式时，所有筛选类型都对指定的属性启用。
你也可以使用对象数组：
如果指定的字段不存在，Meilisearch 会静默忽略它。
如果某个属性包含对象，你可以使用点表示法将其一个或多个键设置为该配置的值："filterableAttributes": ["release_date.year"] 或 "attributePatterns": ["release_date.year"]。
示例
响应：202 Accepted
你可以使用这个 taskUid 来获取任务状态的更多详情。
重置可筛选属性
将索引的可筛选属性列表重置为其默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详情。
本地化属性
默认情况下，Meilisearch 会自动检测文档中使用的语言。此设置允许您明确定义数据集中存在的语言以及这些语言所在的字段。
本地化属性会影响 searchableAttributes、filterableAttributes 和 sortableAttributes。
为单个索引配置多种语言可能会对性能产生负面影响。
locales 和 localizedAttributes 有相同的目的：当 Meilisearch 的语言自动检测不如预期时，明确指定搜索使用的语言。
如果您认为 Meilisearch 因为查询文本而检测到错误的语言，请使用 locales 明确设置搜索语言。
如果您认为 Meilisearch 因为文档内容而检测到错误的语言，请在索引级别使用 localizedAttributes 明确设置文档语言。
为了完全控制 Meilisearch 在索引时和搜索时的语言检测方式，请同时设置 locales 和 localizedAttributes。
本地化属性对象
localizedAttributes 必须是一个包含 locale 对象的数组，其默认值为 []。
每个 locale 对象必须包含以下字段：
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
locales | 字符串数组 | [] | 表示一个或多个 ISO-639 语言环境的字符串列表 |
attributePatterns | 字符串数组 | [] | 表示哪些字段对应指定语言环境的字符串列表 |
locales
Meilisearch 支持以下 ISO-639-3 三字母 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 对应的 ISO-639-1 两字母等效代码。
你还可以将 locales 设置为空数组。在这种情况下，Meilisearch 会自动检测关联的 attributePatterns 的语言。
attributePatterns
属性模式可以以 * 通配符开头或结尾来匹配多个字段：en_*, *-ar。
你也可以将 attributePatterns 设置为 *，这样 Meilisearch 会将所有字段视为属于关联的语言环境。
获取本地化属性设置
获取索引的本地化属性设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
示例
响应：200 OK
更新本地化属性设置
更新索引的本地化属性设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
请求体
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
localizedAttributes | 对象数组 | [] | 为特定属性显式设置一个或多个语言环境 |
示例
响应：202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详细信息。
重置本地化属性设置
将索引的本地化属性重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的uid |
示例
响应：202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详情。
分页
为了保护您的数据库免受恶意爬取，Meilisearch 默认限制每次搜索返回 1000 条结果。此设置允许您配置每次搜索返回的最大结果数。
maxTotalHits 优先级高于搜索参数如 limit、offset、hitsPerPage 和 page。
例如，如果您将 maxTotalHits 设置为 100，无论 offset 的值如何配置，您都无法访问超过 100 条的搜索结果。
要了解更多关于使用 Meilisearch 分页搜索结果的详情，请参阅我们的专用指南。
分页对象
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
maxTotalHits | 整数 | 1000 | Meilisearch 可以返回的搜索结果最大数量 |
获取分页设置
获取索引的分页设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
示例
响应: 200 OK
更新分页设置
部分更新索引的分页设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
请求体
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
maxTotalHits | 整数 | 1000 | Meilisearch 可以返回的最大搜索结果数量 |
将 maxTotalHits 设置为高于默认值会负面影响搜索性能。将 maxTotalHits 设置为超过 20000 的值可能导致查询需要数秒才能完成。
示例
响应：202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详情。
重置分页设置
将索引的分页设置重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid标识符 |
示例
响应：202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详情。
邻近精度
计算词语之间的距离是一项资源密集型操作。降低此操作的精度可能会显著提高性能，并且在大多数用例中对结果相关性影响很小。Meilisearch 在根据邻近度对结果进行排序以及用户执行短语搜索时会使用词语距离。
proximityPrecision 接受以下字符串值之一：
"byWord"：精确计算查询词之间的距离。精度更高，但可能导致索引时间更长。这是默认设置"byAttribute"：判断多个查询词是否出现在同一属性中。精度较低，但索引时间更短
获取邻近度精度设置
获取索引的邻近度精度设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid |
示例
响应：200 OK
更新邻近度精度设置
更新索引的邻近度精度设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid |
请求体
示例
响应：202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详细信息。
重置邻近度精度设置
将索引的邻近度精度设置重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详情。
分面搜索
为分面搜索处理可筛选属性是一项资源密集型操作。此功能默认启用，但禁用它可能会加快索引速度。
facetSearch 接受一个布尔值。如果设置为 false，将禁用整个索引的分面搜索。当分面搜索被禁用时，尝试访问 /facet-search 端点会返回错误。
获取分面搜索设置
获取索引的分面搜索设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 200 OK
更新分面搜索设置
更新索引的分面搜索设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
请求体
示例
响应: 202 Accepted
使用返回的 taskUid 获取更多关于任务状态的详细信息。
重置分面搜索设置
将索引的分面搜索设置重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
示例
响应: 202 Accepted
使用返回的 taskUid 获取更多关于任务状态的详细信息。
前缀搜索
前缀搜索是 Meilisearch 匹配以特定查询词开头的文档的过程，而不仅仅是精确匹配。这是一个资源密集型操作，默认在索引期间进行。
使用 prefixSearch 可以更改前缀搜索的工作方式。它接受以下字符串之一：
"indexingTime"：在索引期间计算前缀搜索。这是默认行为"disabled"：不计算前缀搜索。可能会加快索引速度，但会严重影响搜索结果的相关性
获取前缀搜索设置
获取索引的前缀搜索设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应：200 OK
更新前缀搜索设置
更新索引的前缀搜索设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
请求体
示例
响应: 202 Accepted
使用返回的 taskUid 来获取任务状态的更多详情。
重置前缀搜索设置
将索引的前缀搜索设置重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的uid |
示例
响应: 202 Accepted
使用返回的 taskUid 来获取任务状态的更多详情。
排序规则
排序规则是内置的规则，根据特定标准对搜索结果进行排序。它们按照 rankingRules 数组中出现的顺序依次应用。
排序规则数组
| 名称 | 描述 |
|---|---|
"words" | 按匹配查询词项的数量降序排序结果 |
"typo" | 按拼写错误数量升序排序结果 |
"proximity" | 按匹配查询词项之间的距离升序排序结果 |
"attribute" | 根据属性排序顺序排序结果 |
"sort" | 根据查询时决定的参数排序结果 |
"exactness" | 根据匹配词与查询词的相似度排序结果 |
默认顺序
获取排序规则
获取索引的排序规则。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 200 Ok
更新排序规则
更新索引的排序规则。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
请求体
一个按重要性顺序排列的排序规则数组。
要创建自定义排序规则，需提供一个属性名后接冒号(:)和排序方向：asc表示升序，desc表示降序。
- 升序排序（按值从小到大排序）：
attribute_name:asc - 降序排序（按值从大到小排序）：
attribute_name:desc
如果某些文档不包含自定义排序规则中定义的属性，该排序规则的执行将不可预测，搜索结果可能不会按预期排序。
请确保所有文档都包含自定义排序规则中使用的属性。例如，若设置自定义排序规则desc(year)，需确保所有文档都包含year属性。
示例
响应：202 Accepted
您可以使用此taskUid来获取任务状态的更多详细信息。
重置排序规则
将索引的排序规则重置为默认值。
重置排序规则与删除排序规则不同。要删除排序规则，请使用更新排序规则端点。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的uid |
示例
响应：202 Accepted
您可以使用此 taskUid 来获取任务状态的更多详细信息。
可搜索属性
searchableAttributes 列表中属性关联的值会被用于匹配查询词。列表的顺序也决定了属性排序顺序。
默认情况下，searchableAttributes 数组等于数据集中的所有字段。此行为由值 ["*"] 表示。
更新可搜索属性将重新索引索引中的所有文档，这可能需要一些时间。我们建议先更新索引设置，然后再添加文档，这样可以减少内存消耗。
获取可搜索属性
获取索引的可搜索属性。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
示例
响应：200 Ok
更新可搜索属性
更新索引的可搜索属性。
由于实现上的缺陷，手动更新 searchableAttributes 会改变 JSON 响应中文档字段的显示顺序。这一行为不一致，将在未来版本中修复。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid 标识符 |
请求体
一个字符串数组。每个字符串应是选定索引中存在的属性。数组应按重要性顺序给出：从最重要的属性到最不重要的属性。
如果属性包含对象，可以使用点标记法将其一个或多个键设为该设置的值："searchableAttributes": ["release_date.year"]。
如果字段不存在，不会抛出错误。
示例
在这个例子中，当文档在 title 字段有匹配时，会比在 overview 字段有匹配的文档获得更高的相关性评分。
响应: 202 Accepted
你可以使用这个 taskUid 来获取任务状态的更多详情。
重置可搜索属性
将索引的可搜索属性重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的uid标识符 |
示例
响应: 202 Accepted
你可以使用这个 taskUid 来获取任务状态的更多详情。
搜索超时
配置搜索查询的最大持续时间。Meilisearch 会中断任何超过超时阈值的搜索操作。
默认情况下，Meilisearch 会在 1500 毫秒后中断搜索。
获取搜索超时设置
获取索引的搜索超时阈值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
示例
响应: 200 Ok
更新搜索截止时间
更新索引的搜索截止时间值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
请求体
一个整数，表示以毫秒为单位的截止时间值。
示例
响应: 202 Accepted
使用此 taskUid 可以获取更多关于任务状态的详细信息。
重置搜索截止时间
将索引的搜索截止时间重置为默认值 null。这相当于设置 1500 毫秒的截止时间。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
示例
响应: 202 Accepted
分隔符标记
配置字符串作为自定义分隔符标记，用于指示单词的结束和开始位置。
separatorTokens 列表中的标记会被添加到 Meilisearch 默认的分隔符列表之上。如需从默认列表中移除分隔符，请使用 nonSeparatorTokens 设置。
获取分隔符标记
获取索引的自定义分隔符标记列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
示例
响应: 200 Ok
更新分隔符标记
更新索引的自定义分隔符标记列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的 uid |
请求体
一个字符串数组，每个字符串表示一个单词分隔符。
示例
响应: 202 Accepted
使用此 taskUid 获取更多关于任务状态的详细信息。
重置分隔符标记
将索引的自定义分隔符标记列表重置为默认值 []。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid |
示例
响应: 202 Accepted
使用此 taskUid 获取更多关于任务状态的详细信息。
非分隔符标记
从 Meilisearch 默认的单词分隔符列表中移除标记。
获取非分隔符标记
获取索引的非分隔符标记列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid |
示例
响应: 200 Ok
更新非分隔符标记
更新索引的非分隔符标记列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
请求体
一个字符串数组，每个字符串表示单词分隔符列表中存在的一个标记。
示例
响应：202 Accepted
使用此 taskUid 获取更多关于任务状态的详细信息。
重置非分隔符标记
将索引的非分隔符标记列表重置为默认值 []。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应：202 Accepted
使用此 taskUid 获取更多关于任务状态的详细信息。
可排序属性
这些属性可以在使用 sort 搜索参数 对搜索结果进行排序时使用。
更新可排序属性会重新索引该索引中的所有文档，这可能需要一些时间。我们建议先更新索引设置再添加文档，这样可以减少内存消耗。
获取可排序属性
获取一个索引的可排序属性列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 200 Ok
更新可排序属性
更新索引的可排序属性列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
请求体
一个字符串数组。每个字符串应该是所选索引中存在的一个属性。
如果某个属性包含对象，可以使用点标记法将其一个或多个键设置为该配置的值："sortableAttributes": ["author.surname"]。
如果字段不存在，不会抛出错误。
示例
响应：202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详情。
重置可排序属性
将索引的可排序属性列表重置为其默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid标识符 |
示例
响应：202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详情。
停用词
添加到 stopWords 列表中的词将在未来的搜索查询中被忽略。
更新停用词会导致索引中的所有文档重新索引，这可能需要一些时间。我们建议先更新索引设置再添加文档，这样可以减少内存消耗。
停用词与数据集中使用的语言密切相关。例如，大多数包含英文文档的数据集中会频繁出现 the 和 of 这样的词。而意大利语数据集则会从忽略 a、la 或 il 等词中受益。
这个由法国开发者维护的网站提供了不同语言的停用词列表。请注意，根据您的数据集和使用场景，可能需要调整这些列表以获得最佳效果。
获取停用词
获取索引的停用词列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应：200 Ok
更新停用词
更新索引的停用词列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
请求体
一个字符串数组。每个字符串应为单个单词。
如果已存在停用词列表，它将被覆盖（替换）。
示例
响应：202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详情。
重置停用词
将索引的停用词列表重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid标识符 |
示例
响应：202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详情。
同义词
synonyms 对象包含单词及其对应的同义词。在 Meilisearch 中，同义词在计算搜索结果时被视为等同于其关联词。
获取同义词
获取索引的同义词列表。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应：200 OK
更新同义词
更新索引的同义词列表。同义词会进行规范化处理。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
请求体
一个包含所有同义词及其关联词的对象。通过数组形式为单词设置关联的同义词。
示例
响应：202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详细信息。
重置同义词
将索引的同义词列表重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 202 Accepted
您可以使用这个 taskUid 来获取任务状态的更多详细信息。
拼写容错
拼写容错功能帮助用户在搜索查询包含拼写错误或打字错误时仍能找到相关结果。此设置允许您配置拼错单词的最小长度，以及为特定单词或属性禁用拼写容错。
拼写容错对象
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
enabled | 布尔值 | true | 是否启用拼写容错功能 |
minWordSizeForTypos.oneTypo | 整数 | 5 | 允许1个拼写错误的最小单词长度；必须介于0和twoTypos之间 |
minWordSizeForTypos.twoTypos | 整数 | 9 | 允许2个拼写错误的最小单词长度；必须介于oneTypo和255之间 |
disableOnWords | 字符串数组 | 空数组 | 禁用拼写容错功能的单词列表 |
disableOnAttributes | 字符串数组 | 空数组 | 禁用拼写容错功能的属性列表 |
disableOnNumbers | 布尔值 | false | 是否禁用数字的拼写容错功能 |
获取拼写容错设置
获取索引的拼写容错设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的uid |
示例
响应: 200 OK
更新拼写容错设置
部分更新索引的拼写容错设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid 标识符 |
请求体
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
enabled | Boolean | true | 是否启用拼写容错功能 |
minWordSizeForTypos.oneTypo | Integer | 5 | 允许1个拼写错误的最小单词长度；必须介于0和twoTypos之间 |
minWordSizeForTypos.twoTypos | Integer | 9 | 允许2个拼写错误的最小单词长度；必须介于oneTypo和255之间 |
disableOnWords | 字符串数组 | 空数组 | 禁用拼写容错功能的单词列表 |
disableOnAttributes | 字符串数组 | 空数组 | 禁用拼写容错功能的属性字段列表 |
disableOnNumbers | Boolean | false | 是否禁用数字的拼写容错功能 |
示例
响应: 202 Accepted
您可以使用返回的taskUid来获取任务状态的更多详细信息。
重置拼写容错设置
将索引的拼写容错设置重置为默认值。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | 字符串 | 请求索引的uid标识符 |
示例
响应: 202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详细信息。
嵌入器(Embedders)
嵌入器将文档和查询转换为向量嵌入(vector embeddings)。要使用AI驱动的搜索功能，您必须配置至少一个嵌入器。
嵌入器对象
嵌入器对象最多可包含 256 个嵌入器配置。每个嵌入器配置必须指定唯一名称：
这些嵌入器配置可包含以下字段：
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
source | 字符串 | 空 | 用于生成文档嵌入向量的第三方工具。必须是 openAi、huggingFace、ollama、rest 或 userProvided |
url | 字符串 | http://localhost:11434/api/embeddings | Meilisearch 查询嵌入器时使用的 URL |
apiKey | 字符串 | 空 | Meilisearch 向嵌入器发送请求时的认证令牌。若未提供，Meilisearch 会尝试从环境变量读取 |
model | 字符串 | 空 | 嵌入器生成向量时使用的模型 |
documentTemplate | 字符串 | {% for field in fields %} {% if field.is_searchable and not field.value == nil %}{{ field.name }}: {{ field.value }} {% endif %} {% endfor %} | 定义 Meilisearch 发送给嵌入器的数据模板 |
documentTemplateMaxBytes | 整型 | 400 | 渲染后文档模板的最大允许字节数 |
dimensions | 整型 | 空 | 所选模型的向量维度数。若未提供，Meilisearch 会尝试推断该值 |
revision | 字符串 | 空 | 模型修订哈希 |
distribution | 对象 | 空 | 描述搜索结果的天然分布。必须包含 mean 和 sigma 两个字段，每个字段的值需在 0 到 1 之间 |
request | 对象 | 空 | 表示 Meilisearch 向远程嵌入器发送请求的 JSON 值 |
response | 对象 | 空 | 表示 Meilisearch 期望从远程嵌入器接收响应的 JSON 值 |
binaryQuantized | 布尔值 | 空 | 设为 true 后，会将所有向量维度永久转换为 1-bit 值 |
indexingEmbedder | 对象 | 空 | 配置索引期间向量化文档的嵌入器 |
searchEmbedder | 对象 | 空 | 配置向量化搜索查询的嵌入器 |
pooling | 字符串 | "useModel" | Hugging Face 嵌入器的池化方法 |
获取嵌入器设置
获取为索引配置的嵌入器。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 200 OK
更新嵌入器设置
部分更新索引的嵌入器设置。当此设置更新时，Meilisearch 可能会重新索引所有文档并重新生成它们的嵌入向量。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
请求体
将 embedder 设置为 null 可从嵌入器列表中移除该嵌入器。
source
使用 source 配置嵌入器的数据源。该参数对应一个能从文档生成嵌入向量的服务。
Meilisearch 支持以下数据源：
openAihuggingFaceollamarestuserProvidedcomposite实验性
rest 是一个通用数据源，兼容任何提供 REST API 的嵌入服务提供商。
使用 userProvided 时需手动生成嵌入向量。这种情况下，你必须在文档的 _vectors 字段中包含向量数据，同时需要为搜索查询生成向量。
该字段为必填项。
复合嵌入器 实验性
选择 composite 可在索引阶段使用一个嵌入器，在搜索阶段使用另一个嵌入器。必须与 indexingEmbedder 和 searchEmbedder 配合使用。
此为实验性功能。需通过实验性功能端点激活：
url
Meilisearch 通过 url 查询来为搜索请求和文档生成向量嵌入。url 必须指向一个兼容 REST 的嵌入服务。你也可以使用 url 来配置代理，例如需要通过代理访问 openAi 的情况。
当使用 rest 类型的嵌入服务时，此字段为必填项。
当使用 ollama 和 openAi 嵌入服务时，此字段为可选。ollama 的 URL 必须以 /api/embed 或 /api/embeddings 结尾。
此字段与 huggingFace 和 userProvided 类型的嵌入服务不兼容。
apiKey
Meilisearch 向嵌入服务发送请求时使用的认证令牌。
当使用受保护的 rest 嵌入服务时，此字段为必填项。
对于 openAI 和 ollama 嵌入服务，此字段为可选。如果不指定 apiKey，Meilisearch 会尝试分别从环境变量 OPENAI_API_KEY 和 MEILI_OLLAMA_URL 中读取。
此字段与 huggingFace 和 userProvided 类型的嵌入服务不兼容。
model
嵌入服务生成向量时使用的模型。以下是 Meilisearch 官方支持的模型：
openAi:text-embedding-3-small,text-embedding-3-large,openai-text-embedding-ada-002huggingFace: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
documentTemplate 是一个包含 Liquid 模板的字符串。Meilisearch 会为每个文档解析该模板，并将生成的文本发送给嵌入器（embedder）。嵌入器随后基于这段文本生成文档向量。
您可以使用以下上下文变量：
{{doc.FIELD}}:doc代表文档本身。FIELD必须对应所有文档中都存在的属性，该值会被替换为输入文档中对应字段的值{{fields}}: 出现在索引中任何文档的所有field列表。该列表中的每个field对象具有以下属性：name: 字段属性名value: 字段值is_searchable: 该字段是否存在于可搜索属性列表中
如果文档中不存在某个 field，其 value 将为 nil。
为了获得最佳效果，建议构建只包含高度相关数据的简短模板。如果处理长字段，考虑截断它。如果不手动设置，documentTemplate 将包含所有可搜索且非空的文档字段，这可能导致性能和相关性不理想。
该字段与 userProvided 嵌入器不兼容。
该字段是可选的，但对于其他所有嵌入器强烈建议使用。
documentTemplateMaxBytes
渲染后文档模板的最大字节数。过长的文本会被截断以符合配置的限制。
documentTemplateMaxBytes 必须为整数，默认值为 400。
该字段与 userProvided 嵌入器不兼容。
该字段对其他所有嵌入器是可选的。
dimensions
所选模型中的维度数量。如果未提供，Meilisearch 会尝试推断该值。
在大多数情况下，dimensions 应与所选模型的维度数完全相同。将 dimensions 设置为低于模型维度数的值可能会带来性能提升，但仅支持以下 OpenAI 模型：
openAi:text-embedding-3-small,text-embedding-3-large
对于 userProvided 嵌入器，此字段是必填项。
对于 openAi、huggingFace、ollama 和 rest 嵌入器，此字段是可选项。
revision
使用此字段可以指定模型的特定版本。
对于 huggingFace 嵌入器，此字段是可选项。
此字段与其他所有嵌入器不兼容。
request
request 必须是一个 JSON 对象，其结构和数据应与发送给 rest 嵌入器的请求完全一致。
Meilisearch 应发送给嵌入器的输入文本字段必须替换为 "{{text}}"：
如果在单个请求中发送多个文档，请将输入字段替换为 ["{{text}}", "{{..}}"]：
使用 rest 嵌入器时，此字段是必填项。
此字段与其他所有嵌入器不兼容。
response
response 必须是一个 JSON 对象，其结构和数据应与你期望从 rest embedder 获得的响应一致。
包含嵌入向量本身的字段必须替换为 "{{embedding}}"：
如果单个响应包含多个嵌入向量，那么包含嵌入向量本身的字段必须是一个包含两项的数组。第一项需声明单个嵌入向量的位置和结构，第二项应为 "{{..}}"：
使用 rest embedder 时，此字段为必填项。
此字段与所有其他 embedder 不兼容。
distribution（分布调整）
由于数学上的原因，语义搜索结果的 _rankingScore 往往会紧密聚集在一个平均值周围，这个值取决于所使用的嵌入器和模型。这可能导致相关语义结果被低估，而不相关的语义结果被高估，与关键词搜索结果相比显得不够平衡。
在配置嵌入器时使用 distribution 参数，可以通过仿射变换来校正语义搜索结果的 _rankingScore：
配置 distribution 需要一定的试错过程：您需要执行语义搜索并观察结果。根据结果的 rankingScore 和相关性，为该索引添加观察到的 mean 和 sigma 值。
distribution 是一个可选字段，兼容所有嵌入器来源。它必须是一个包含两个字段的对象：
mean：介于0和1之间的数字，表示在使用distribution设置前”较为相关”结果的语义分数sigma：介于0和1之间的数字，表示”非常相关”结果与”较为相关”结果之间，以及”较为相关”结果与”不相关”结果之间的_rankingScore平均绝对差异
更改 distribution 不会触发重新索引操作。
headers
headers 必须是一个 JSON 对象，其键表示要发送给 embedders 的额外请求头名称，值表示这些额外请求头的值。
默认情况下，Meilisearch 向 rest embedders 发送所有请求时会附带以下请求头：
Authorization: Bearer EMBEDDER_API_KEY（仅在提供了apiKey时发送）Content-Type: application/json
如果 headers 包含上述任一字段，则显式声明的值会覆盖默认值。
使用 rest embedder 时该字段是可选的。
该字段与所有其他类型的 embedder 不兼容。
binaryQuantized
当设置为 true 时，通过用 1 比特值表示每个维度来压缩向量。这会降低语义搜索的相关性，但能大幅减少数据库大小。
在处理大型 Meilisearch 项目时，此选项可能很有用。如果您的项目包含超过一百万份文档且使用维度超过 1400 的模型，可以考虑启用此选项。
启用 binaryQuantized 是不可逆的操作。 一旦启用，Meilisearch 会转换所有向量并丢弃所有无法用 1 比特表示的向量数据。恢复向量原始值的唯一方法是在新的 embedder 中重新向量化整个索引。
pooling
配置 Meilisearch 应如何将单个 token 合并为单个 embedding。
pooling 必须是以下字符串之一：
"useModel"：Meilisearch 将从模型配置中获取 pooling 方法。新建 embedder 的默认值"forceMean"：始终使用 mean pooling。在 Meilisearch <=v1.13 中创建的 embedder 的默认值"forceCls"：始终使用 CLS pooling
如果不确定，请使用 "useModel"。"forceMean" 和 "forceCls" 是兼容性选项，某些 embedder 和模型可能需要这些选项。
对于 huggingFace 来源的 embedder，pooling 是可选的。
对于所有其他来源的 embedder，pooling 是无效的。
indexingEmbedder 和 searchEmbedder experimental
当使用复合嵌入器时，可以配置 Meilisearch 在向量化文档和搜索查询时分别使用的嵌入器。
indexingEmbedder 通常受益于远程提供商的高带宽和速度，使其能够快速向量化大批量文档。而 searchEmbedder 则可能受益于本地处理查询的低延迟特性。
这两个字段都必须是对象，并且接受与常规嵌入器相同的字段，但有以下例外：
indexingEmbedder和searchEmbedder必须使用相同的模型来生成嵌入向量indexingEmbedder和searchEmbedder必须具有相同的dimension（维度）和pooling（池化）方法source字段对indexingEmbedder和searchEmbedder都是必填项- 子嵌入器不能将
source设置为composite或userProvided binaryQuantized和distribution不是有效的子嵌入器字段，必须始终在主嵌入器中声明documentTemplate和documentTemplateMaxBytes对searchEmbedder是无效字段- 如果适用，
documentTemplate和documentTemplateMaxBytes对indexingEmbedder是必填字段
当使用 composite 源时，indexingEmbedder 和 searchEmbedder 是必填项。
indexingEmbedder 和 searchEmbedder 与所有其他嵌入器源不兼容。
示例
响应：202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详情。
重置嵌入器设置
移除索引中的所有嵌入器配置。
如需移除单个嵌入器，请使用更新嵌入器设置端点并将目标嵌入器设置为 null。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的uid标识符 |
示例
响应：202 Accepted
您可以使用返回的 taskUid 来获取任务状态的更多详情。
对话功能 实验性
此为实验性功能。请使用 Meilisearch Cloud 用户界面或实验性功能端点激活：
对话式查询允许您以更接近人类对话的方式与搜索引擎交互。该功能支持您提出问题，并根据文档内容获取相关答案。
Chat 对象
索引设置中的 chat 对象包含多个配置项，用于设置对话式查询功能。
这些 embedder 对象可能包含以下字段：
| 名称 | 类型 | 默认值 | 描述 |
|---|---|---|---|
description | 字符串 | 空 | 索引的描述。用于帮助 LLM 决定在生成答案时使用哪个索引 |
documentTemplate | 字符串 | {% for field in fields %} {% if field.is_searchable and not field.value == nil %}{{ field.name }}: {{ field.value }} {% endif %} {% endfor %} | 定义 Meilisearch 发送给 LLM 的数据模板 |
documentTemplateMaxBytes | 整数 | 400 | 渲染后的文档模板允许的最大字节数 |
searchParameters | 对象 | 空 | 当 LLM 执行搜索请求时使用的搜索参数 |
搜索参数对象
对应于搜索参数对象的子集：
hybridlimitsortdistinctmatchingStrategyattributesToSearchOnrankingScoreThreshold
获取索引聊天设置
获取为索引配置的聊天设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |
示例
响应: 200 OK
更新索引聊天设置
部分更新索引的聊天设置。
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
index_uid * | String | 请求索引的 uid |