搜索

Meilisearch 提供了两条路由来执行搜索：

• POST 路由：当使用 API 认证时，这是首选路由，因为它允许预检请求缓存，能提供更好的性能
• GET 路由：除非有特殊原因（例如特定的缓存需求），否则不建议使用此路由

您可以在本文末尾找到两条路由所接受参数的完整说明。

​

使用 POST 在索引中搜索

在指定索引中搜索匹配特定查询的文档。

当需要 API 密钥时，这是执行搜索的首选端点，因为它允许缓存预检请求。缓存预检请求能显著提高搜索速度。

​

路径参数

​

请求体

​

响应

​

搜索结果总数的精确统计与估算统计

默认情况下，Meilisearch 仅返回查询结果总数的估算值：estimatedTotalHits。这是因为 Meilisearch 优先考虑相关性和性能，而非提供详尽的搜索结果总数。当使用 estimatedTotalHits 时，可通过 offset 和 limit 参数在搜索结果间导航。

如需获取精确的搜索结果总数，请在查询中使用 hitsPerPage 和 page 搜索参数。该查询的响应会将 estimatedTotalHits 替换为 totalHits，并额外包含基于 hitsPerPage 计算的总页数字段：totalPages。使用 totalHits 和 totalPages 可能会略微降低性能，但在创建诸如数字页码选择器等 UI 元素时推荐使用。

无论是 estimatedTotalHits 还是 totalHits，其数值均不能超过 索引设置 maxTotalHits 中配置的上限。

您可以通过我们专门的分页指南了解更多信息。

​

示例

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "american ninja" }'

​

响应：200 Ok

{
  "hits": [
    {
      "id": 2770,
      "title": "American Pie 2",
      "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
      "overview": "整个团队都回来了，比以往任何时候都更亲密。他们决定通过在沙滩别墅共度夏天来进一步加深感情。他们计划举办一个盛大的...",
      "release_date": 997405200
    },
    {
      "id": 190859,
      "title": "American Sniper",
      "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
      "overview": "美国海军海豹突击队队员克里斯·凯尔将保护战友视为唯一使命，成为美国历史上最致命的狙击手之一。他精准的枪法不仅拯救了无数生命，也使他成为首要...",
      "release_date": 1418256000
    },
    …
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 976,
  "processingTimeMs": 35,
  "query": "american "
}

​

使用 GET 方法在索引中搜索

在指定索引中搜索匹配特定查询的文档。

此端点仅应在不需要 API 密钥时使用。如果需要 API 密钥，请改用 POST 路由。

​

路径参数

​

查询参数

​

响应

​

示例

curl \
  -X GET 'MEILISEARCH_URL/indexes/movies/search?q=american%20ninja'

​

响应: 200 Ok

{
  "hits": [
    {
      "id": 2770,
      "title": "American Pie 2",
      "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
      "overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
      "release_date": 997405200
    },
    {
      "id": 190859,
      "title": "American Sniper",
      "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
      "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
      "release_date": 1418256000
    },
    …
  ],
  "offset": 0,
  "limit": 20,
  "estimatedTotalHits": 976,
  "processingTimeMs": 35,
  "query": "american "
}

​

搜索参数

以下是使用搜索端点时当前可用的所有搜索参数的详细说明。除非另有说明，所有参数都适用于 GET /indexes/{index_uid}/search、POST /indexes/{index_uid}/search 和 /multi-search 路由。

​

查询 (q)

参数: q

期望值: 任意字符串

默认值: null

设置搜索关键词。

​

示例

您可以通过设置 q 参数来搜索提及 shifu 的电影：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "shifu" }'

这将返回在至少一个属性中包含您查询词项的文档列表。

{
  "hits": [
    {
      "id": 50393,
      "title": "Kung Fu Panda Holiday",
      "poster": "https://image.tmdb.org/t/p/w500/rV77WxY35LuYLOuQvBeD1nyWMuI.jpg",
      "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace.",
      "release_date": 1290729600,
      "genres": [
        "Animation",
        "Family",
        "TV Movie"
      ]
    }
  ],
  "query": "shifu"
}

​

查询词项归一化

查询词项会经过归一化处理，移除非间距标记。因此，Meilisearch 在返回结果时会有效忽略重音和变音符号。例如，搜索 "sábia" 会返回包含 "sábia"、"sabiá" 和 "sabia" 的文档。

归一化还会将所有字母转换为小写。搜索 "Video" 会返回与搜索 "video"、"VIDEO" 或 "viDEO" 相同的结果。

​

占位符搜索

当未指定 q 参数时，Meilisearch 会执行占位符搜索。占位符搜索会返回索引中所有可搜索的文档，这些结果会受其他搜索参数影响，并按该索引的自定义排序规则排序。由于没有查询词，内置排序规则将不会生效。

如果索引没有设置排序或自定义排序规则，结果将按其内部数据库位置顺序返回。

​

短语搜索

如果用双引号(")包裹搜索词，Meilisearch 将只返回包含这些词且顺序完全匹配的文档。这称为短语搜索。

短语搜索不区分大小写，并忽略软分隔符如 -、, 和 :。在短语搜索中使用硬分隔符会将其拆分为多个独立的短语搜索："Octavia.Butler" 将返回与 "Octavia" "Butler" 相同的结果。

您可以在单个搜索请求中组合短语搜索和普通查询。此时，Meilisearch 会先获取与给定短语完全匹配的文档，然后继续其默认行为。

示例

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
--data-binary '{ "q": "\"african american\" horror" }'

​

排除搜索

在单词或短语前使用减号(-)运算符，可以从搜索结果中排除包含该内容的文档。

示例

以下查询返回所有不包含单词 “escape” 的文档：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "-escape" }'

排除搜索可与短语搜索结合使用：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "-\"escape room\"" }'

​

偏移量

参数: offset

期望值：任意正整数

默认值：0

设置搜索结果的起始点，实际上是跳过指定数量的文档。

使用 offset 和 limit 的查询只会返回搜索结果总数的估计值。

您可以通过结合使用 offset 和 limit 来分页显示搜索结果。

​

示例

如果您想跳过查询中的第一条结果，将 offset 设为 1：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "offset": 1
  }'

​

返回数量限制

参数：limit

期望值：任意正整数或零

默认值：20

设置单次查询返回文档的最大数量。

您可以通过结合使用 offset 和 limit 来分页显示搜索结果。

​

示例

如果您希望查询仅返回两条文档，将 limit 设为 2：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "limit": 2
  }'

​

每页结果数量

参数：hitsPerPage

期望值：任意正整数

默认值: 20

设置单次查询返回的最大文档数。此参数配置的值决定了总页数：如果 Meilisearch 找到一个查询共有 20 个匹配项，而你的 hitsPerPage 设置为 5，则 totalPages 为 4。

包含 hitsPerPage 的查询是精确计算，不会返回 estimatedTotalHits。相反，响应体将包含 totalHits 和 totalPages。

如果将 hitsPerPage 设为 0，Meilisearch 会处理请求但不返回任何文档。此时响应体将包含 totalHits 的精确值，同时也会包含 totalPages，但其值将为 0。

你可以使用 hitsPerPage 和 page 来实现搜索结果分页。

​

示例

以下示例返回查询的前 15 条结果：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "",
    "hitsPerPage": 15
  }'

​

Page

参数: page

期望值: 任意正整数

默认值: 1

请求特定的结果页码。页码是基于 hitsPerPage 搜索参数计算的。

包含 page 参数的查询是精确查询，不会返回 estimatedTotalHits。相反，响应体将包含两个新字段：totalHits 和 totalPages。

如果将 page 设为 0，Meilisearch 会处理请求但不返回任何文档。此时响应体将包含 facetDistribution、totalPages 和 totalHits 的精确值。

您可以使用 hitsPerPage 和 page 来实现搜索结果分页。

​

示例

以下示例返回搜索结果的第二页：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "",
    "page": 2
  }'

​

过滤器

参数: filter

期望值: 作为字符串或字符串数组的过滤表达式

默认值: []

使用过滤表达式来优化搜索结果。用作过滤条件的属性必须添加到 filterableAttributes 列表中。

更多信息请参阅如何使用过滤器和构建过滤表达式的指南。

​

示例

您可以使用逻辑连接符以字符串语法编写过滤表达式：

"(genres = horror OR genres = mystery) AND director = 'Jordan Peele'"

您也可以用数组形式编写相同的过滤器：

[["genres = horror", "genres = mystery"], "director = 'Jordan Peele'"]

然后您可以在搜索查询中使用该过滤器：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "thriller",
    "filter": [
      [
        "genres = Horror",
        "genres = Mystery"
      ],
      "director = \"Jordan Peele\""
    ]
  }'

​

使用 _geoRadius 和 _geoBoundingBox 过滤结果

如果您的文档包含 _geo 地理数据，您可以使用内置的 _geoRadius 和 _geoBoundingBox 过滤规则来根据地理位置筛选结果。

如果任何参数无效或缺失，Meilisearch 会返回 invalid_search_filter 错误。

​

分面搜索

参数: facets

期望值: 一个包含 attribute 的数组或 ["*"]

默认值: null 返回每个给定分面(facet)中匹配当前搜索查询的文档数量。该参数可接受两种值：

• 属性数组：facets=["attributeA", "attributeB", …]
• 星号——这将返回filterableAttributes中所有分面的计数

默认情况下，facets为每个分面字段返回最多100个分面值。您可以通过faceting索引设置中的maxValuesPerFacet属性来修改此限制。

当设置facets时，搜索结果对象将包含facetDistribution和facetStats字段。

​

facetDistribution

facetDistribution包含按给定分面值分布的匹配文档数量。每个分面表示为一个对象：

{
  …
 "facetDistribution": {
    "FACET_A": {
      "FACET_VALUE_X": 6,
      "FACET_VALUE_Y": 1,
    },
    "FACET_B": {
      "FACET_VALUE_Z": 3,
      "FACET_VALUE_W": 9,
    },
  },
  …
}

facetDistribution为传递给facets参数的每个属性包含一个对象。每个对象包含该属性返回的值及具有该值的匹配文档计数。Meilisearch不会返回空的分面。

​

facetStats

facetStats包含每个分面中所有文档的最小值(min)和最大值(max)。仅考虑数值类型：

{
  …
"facetStats": {
  "rating": {
    "min": 2.5,
    "max": 4.7
    }
  }
  …
}

如果没有匹配文档包含某个分面的数值，则该分面不会出现在facetStats对象中。facetStats会忽略字符串值，即使字符串中包含数字。

​

示例

假设有一个电影评分数据库，以下代码示例返回按类型分组的 Batman 电影数量以及最低和最高评分：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movie_ratings/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "Batman",
    "facets": ["genres", "rating"]
  }'

响应显示了 genres 和 rating 的分面分布。由于 rating 是数值字段，您可以在 facetStats 中获取其最小值和最大值。

{
  …
  "estimatedTotalHits": 22,
  "query": "Batman",
  "facetDistribution": {
    "genres": {
      "Action": 20,
      "Adventure": 7,
      …
      "Thriller": 3
    },
    "rating": {
      "2": 1,
      …
      "9.8": 1
    }
  },
  "facetStats": {
    "rating": {
      "min": 2.0,
      "max": 9.8
    }
  }
}

了解更多关于分面分布的信息，请参阅分面搜索指南。

​

搜索时的去重属性

参数: distinct

期望值: filterableAttributes 列表中的一个 attribute

默认值: null

将 filterableAttributes 列表中的一个属性定义为去重属性。去重属性表示对于指定字段具有相同值的文档是等价的，在搜索结果中只应返回最相关的一个。

此行为类似于 distinctAttribute 索引设置，但可以在搜索时配置。distinctAttribute 作为默认的去重属性值，您可以用 distinct 覆盖它。

​

示例

curl \
  -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "QUERY TERMS",
    "distinct": "ATTRIBUTE_A"
  }'

​

要检索的属性

参数: attributesToRetrieve

期望值: 一个 attribute 数组或 ["*"]

默认值: ["*"]

配置返回文档中将被检索的属性。

如果未指定值，attributesToRetrieve 会使用 displayedAttributes 列表，该列表默认包含文档中的所有属性。

​

示例

要仅获取 overview 和 title 字段，将 attributesToRetrieve 设置为 ["overview", "title"]。

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "attributesToRetrieve": [
      "overview",
      "title"
    ]
  }'

​

裁剪属性

参数: attributesToCrop

期望值: 属性数组或 ["*"]

默认值: null

将返回结果中选定字段裁剪到 cropLength 参数指定的长度。当设置 attributesToCrop 时，每个返回的文档会包含一个名为 _formatted 的额外字段。该对象包含选定属性的裁剪版本。

默认情况下，裁剪边界由省略号字符（…）标记。您可以通过使用 cropMarker 搜索参数来更改此标记。

可选地，您可以为 attributesToCrop 中的任何属性指定自定义裁剪长度：attributesToCrop=["attributeNameA:5", "attributeNameB:9"]。如果配置了这些值，它们将优先于 cropLength。

除了提供单个属性外，您还可以使用 ["*"] 作为通配符：attributesToCrop=["*"]。这将使 _formatted 包含 attributesToRetrieve 中所有属性的裁剪值。

​

裁剪算法

假设某个字段包含以下字符串：Donatello is a skilled and smart turtle. Leonardo is the most skilled turtle. Raphael is the strongest turtle.

Meilisearch 在裁剪时会尽量保持句子完整性。例如，当搜索词是 Leonardo 且 cropLength 设为 6 时，系统会优先保留完整句子，返回：Leonardo is the most skilled turtle.

如果查询只包含单个搜索词，Meilisearch 会围绕该词的首次出现位置进行裁剪。例如搜索 turtle 且 cropLength 设为 7 时，将返回该词的第一个实例：Donatello is a skilled and smart turtle.

如果查询包含多个搜索词，Meilisearch 会以最多唯一匹配项为中心进行裁剪，优先保留彼此接近且符合原始查询顺序的词组。例如搜索 skilled turtle 且 cropLength 设为 6 时，将返回 Leonardo is the most skilled turtle.

如果 Meilisearch 在字段中找不到任何查询词，则从该字段的首个单词开始裁剪。例如搜索 Michelangelo 且 cropLength 设为 4 时（假设该词存在于其他字段），将返回 Donatello is a skilled …。

​

示例

如果你使用 shifu 作为搜索查询，并将 cropLength 参数的值设置为 5：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "attributesToCrop": ["overview"],
    "cropLength": 5
  }'

你将会得到以下响应，其中 _formatted 对象包含裁剪后的文本：

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "…this year Shifu informs Po…",
    "release_date": 1290729600
  }
}

​

裁剪长度

参数：cropLength

期望值：正整数

默认值：10

配置在使用 attributesToCrop 时裁剪值中显示的总单词数。如果未配置 attributesToCrop，cropLength 不会对返回结果产生影响。

查询词会被计入裁剪值的长度。如果 cropLength 设置为 2 并且你搜索一个词（例如 shifu），裁剪后的字段将总共包含两个单词（例如 "…Shifu informs…"）。

停用词也会计入这个数字。如果 cropLength 设置为 2 并且你搜索一个词（例如 grinch），裁剪结果可能包含一个停用词（例如 "…the Grinch…"）。

如果 attributesToCrop 使用 attributeName:number 语法为某个属性指定自定义裁剪长度，则该值优先于 cropLength。

​

裁剪标记

参数: cropMarker
期望值: 字符串
默认值: "…"

设置一个字符串作为使用 attributesToCrop 参数时的裁剪边界标记。裁剪标记会插入在裁剪内容的两侧。如果未配置 attributesToCrop，cropMarker 不会对返回的搜索结果产生影响。

如果将 cropMarker 设为 null 或空字符串，返回结果中将不包含任何标记。

裁剪标记仅在被移除内容的位置添加。例如，如果裁剪后的文本包含字段值的第一个单词，则不会在裁剪结果的开头添加裁剪标记。

​

示例

当搜索 shifu 时，可以使用 cropMarker 来修改默认的 …：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "cropMarker": "[…]",
    "attributesToCrop": ["overview"]
  }'

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "[…]But this year Shifu informs Po that as Dragon Warrior,[…]",
    "release_date": 1290729600
  }
}

​

高亮属性

参数: attributesToHighlight
期望值: 属性数组或 ["*"]

默认值: null

在指定属性中高亮匹配的查询词项。attributesToHighlight 仅对以下类型的值有效：字符串、数字、数组、对象。

当设置此参数时，返回的文档会包含一个 _formatted 对象，其中包含被高亮的词项。

可以使用 ["*"] 代替属性列表：attributesToHighlight=["*"]。这种情况下，所有出现在 attributesToRetrieve 中的属性都会被自动分配给 attributesToHighlight。

默认情况下，高亮元素会被包裹在 <em> 和 </em> 标签中。您可以通过使用 highlightPreTag 和 highlightPostTag 搜索参数 来修改这个行为。

​

示例

以下查询会高亮显示 overview 属性中的匹配内容：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "winter feast",
    "attributesToHighlight": ["overview"]
  }'

高亮后的文本版本可以在每个返回文档的 _formatted 对象中找到：

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "The <em>Winter Feast</em> is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal <em>Winter Feast</em> at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
    "release_date": 1290729600
  }
}

​

高亮标签

参数: highlightPreTag 和 highlightPostTag

期望值: 字符串

默认值：分别为 "<em>" 和 "</em>"

highlightPreTag 和 highlightPostTag 分别配置在由 attributesToHighlight 高亮的单词前后插入的字符串。如果未配置 attributesToHighlight，则 highlightPreTag 和 highlightPostTag 不会对返回的搜索结果产生影响。

可以使用 highlightPreTag 和 highlightPostTag 将高亮术语包裹在任意文本字符串中，不仅限于 HTML 标签："<em>"、"<strong>"、"*" 和 "__" 都是支持的合法值。

如果将 highlightPreTag 或 highlightPostTag 设置为 null 或空字符串，则分别不会在高亮术语的开头或结尾插入任何内容。

​

示例

以下查询将高亮匹配项包裹在带有 class 属性的 <span> 标签中：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "winter feast",
    "attributesToHighlight": ["overview"],
    "highlightPreTag": "<span class=\"highlight\">",
    "highlightPostTag": "</span>"
  }'

你可以在 _formatted 属性中找到高亮的查询词：

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_formatted": {
    "id": 50393,
    "title": "Kung Fu Panda Holiday",
    "poster": "https://image.tmdb.org/t/p/w1280/gp18R42TbSUlw9VnXFqyecm52lq.jpg",
    "overview": "The <span class=\"highlight\">Winter Feast</span> is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal <span class=\"highlight\">Winter Feast</span> at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
    "release_date": 1290729600
  }
}

​

显示匹配位置

参数：showMatchesPosition

期望值：true 或 false

默认值: false

在搜索响应中添加一个 _matchesPosition 对象，该对象包含查询词在所有字段中的每个匹配位置。当您需要比我们内置的高亮功能提供更多控制时，这个功能非常有用。showMatchesPosition 仅适用于字符串、数字以及字符串和数字的数组。

字段中匹配词的起始位置由 start 表示，其长度由 length 表示。

​

示例

如果将 showMatchesPosition 设置为 true 并搜索 winter feast：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "winter feast",
    "showMatchesPosition": true
  }'

你会在响应中获取到 _matchesPosition 对象中包含的匹配位置信息。注意 Meilisearch 如何因为空格而将 winter 和 feast 分开搜索：

{
  "id": 50393,
  "title": "Kung Fu Panda Holiday",
  "poster": "https://image.tmdb.org/t/p/w500/rV77WxY35LuYLOuQvBeD1nyWMuI.jpg",
  "overview": "The Winter Feast is Po's favorite holiday. Every year he and his father hang decorations, cook together, and serve noodle soup to the villagers. But this year Shifu informs Po that as Dragon Warrior, it is his duty to host the formal Winter Feast at the Jade Palace. Po is caught between his obligations as the Dragon Warrior and his family traditions: between Shifu and Mr. Ping.",
  "release_date": 1290729600,
  "_matchesPosition": {
    "overview": [
      {
        "start": 4,
        "length": 6
      },
      {
        "start": 11,
        "length": 5
      },
      {
        "start": 234,
        "length": 6
      },
      {
        "start": 241,
        "length": 5
      }
    ]
  }
}

​

排序

参数: sort

期望值: 以数组或逗号分隔字符串形式提供的属性列表

默认值: null

根据指定的属性和排序顺序在查询时对搜索结果进行排序。

列表中的每个属性后必须跟一个冒号(:)和首选的排序顺序：升序(asc)或降序(desc)。

使用 POST 路由时，sort 需要一个字符串数组。

使用 GET 路由时，sort 需要一个逗号分隔的字符串。

在我们的专用指南中了解更多关于排序搜索结果的信息。

​

示例

你可以搜索从最便宜到最贵的科幻书籍：

curl \
  -X POST 'MEILISEARCH_URL/indexes/books/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "science fiction",
    "sort": ["price:asc"]
  }'

​

使用 _geoPoint 排序结果

当处理包含地理定位数据的文档时，你可以使用 _geoPoint 根据结果与特定地理位置的远近进行排序。

_geoPoint 是一个排序函数，需要两个浮点数表示位置的纬度和经度。你还必须指定排序是升序(asc)还是降序(desc)：

curl \
  -X POST 'MEILISEARCH_URL/indexes/restaurants/search' \
  -H 'Content-type:application/json' \
  --data-binary '{ "sort": ["_geoPoint(48.8561446,2.2978204):asc"] }'

使用 _geoPoint 的查询将始终包含一个 geoDistance 字段，表示文档位置与 _geoPoint 之间的距离（以米为单位）：

[
  {
    "id": 1,
    "name": "Nàpiz' Milano",
    "_geo": {
      "lat": 45.4777599,
      "lng": 9.1967508
    },
    "_geoDistance": 1532
  }
]

你可以在我们的专用指南中了解更多关于基于位置的排序信息。

​

匹配策略

参数: matchingStrategy

期望值: last, all, 或 frequency

默认值: last

定义文档中匹配查询词项的匹配策略。

​

last

last 首先返回包含所有查询词项的文档。如果包含所有查询词项的结果不足以满足请求的 limit，Meilisearch 将从查询末尾开始逐个移除查询词项。

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "big fat liar",
    "matchingStrategy": "last"
  }'

使用上述代码示例时，Meilisearch 会首先返回包含所有三个单词的文档。如果结果不足以满足请求的 limit，它还会返回仅包含前两个词项 big fat 的文档，然后是仅包含 big 的文档。

​

all

all 仅返回包含所有查询词项的文档。即使结果不足以满足请求的 limit，Meilisearch 也不会匹配更多文档。

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "big fat liar",
    "matchingStrategy": "all"
  }'

上述代码示例将只返回包含所有三个单词的文档。

​

frequency

frequency 首先返回包含所有查询词项的文档。如果包含所有查询词项的结果不足以满足请求的 limit，Meilisearch 将从数据集中出现频率最高的词项开始逐个移除查询词项。frequency 实际上会给予结果集中出现频率较低的词项更多权重。

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "white shirt",
    "matchingStrategy": "frequency"
  }'

在一个包含大量含有 "shirt" 词项的文档的数据集中，上述代码示例会优先返回包含 "white" 的文档。

​

排名分数

参数: showRankingScore

期望值: true 或 false

默认值: false

为每个文档添加全局排名分数字段 _rankingScore。_rankingScore 是一个介于 0.0 到 1.0 之间的数值。_rankingScore 越高，文档的相关性越强。

sort 排序规则不会影响 _rankingScore。相反，文档顺序由它们排序字段的值决定。

​

示例

下面的代码示例展示了在 movies 中搜索 dragon 时返回 _rankingScore 的情况：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "dragon",
    "showRankingScore": true
  }'

{
  "hits": [
    {
      "id": 31072,
      "title": "Dragon",
      "overview": "In a desperate attempt to save her kingdom…",
      …
      "_rankingScore": 0.92
    },
    {
      "id": 70057,
      "title": "Dragon",
      "overview": "A sinful martial arts expert wants…",
      …
      "_rankingScore": 0.91
    },
    …
  ],
  …
}

​

排名分数详情

参数: showRankingScoreDetails

可选值: true 或 false

默认值: false

为每个文档添加详细的全局排名分数字段 _rankingScoreDetails。_rankingScoreDetails 是一个对象，包含每个活跃排序规则的嵌套对象。

​

排名分数详情对象

每个排序规则在其独立对象中详细说明分数。字段因排序规则而异。

words

• order: 该排序规则被应用的顺序
• score: 该规则的排名分数
• matchingWords: 查询中与文档匹配的单词数量
• maxMatchingWords: 查询中能与文档匹配的最大单词数

typo（拼写纠错）

• order: 该特定排序规则应用的顺序
• score: 该规则的排序分数
• typoCount: 为使文档匹配查询词而纠正的拼写错误数量
• maxTypoCount: 可接受的最大拼写错误数

proximity（邻近度）

• order: 该排序规则应用的顺序
• score: 该规则的排序分数

attribute（属性）

• order: 该排序规则应用的顺序
• score: 该规则的排序分数
• attributeRankingOrderScore: 根据匹配属性的最大属性排序顺序计算得出的分数
• queryWordDistanceScore: 根据查询中词项位置与匹配属性中词项位置之间的距离计算得出的分数

exactness（精确度）

• order: 该排序规则应用的顺序
• score: 该规则的排序分数
• matchType: 可能为以下三种值之一：
  • exactMatch（完全匹配）: 文档包含一个属性，该属性完全匹配所有查询词项且中间没有其他词，且顺序与查询一致
  • matchesStart（起始匹配）: 文档包含一个属性，其中所有查询词项的顺序与原始查询一致
  • noExactMatch（非精确匹配）: 文档包含一个属性，其中至少有一个查询词项与原始查询匹配
• matchingWords: 当 matchType 为 noExactMatch 时，属性中精确匹配的词项数量
• maxMatchingWords: 当 matchType 为 noExactMatch 时，属性中可能的最大精确匹配词项数量

field_name:direction（字段名:方向）

sort 排序规则不会作为单独字段出现在分数详情对象中。相反，每个排序属性会作为自己的字段出现，后跟冒号 (:) 和排序方向：attribute:direction。

• order: 该排序规则应用的顺序
• value: 用于排序的字段值

_geoPoint(lat:lng):direction

• order: 该排序规则被应用的顺序
• value: 用于排序的字段值
• distance: 与 _geoDistance 相同

vectorSort(target_vector)

• order: 该特定排序规则被应用的顺序
• value: 用于文档排序的向量
• similarity: 目标向量与值向量之间的相似度得分。1.0 表示完全相似，0.0 表示完全不相似

​

示例

下面的代码示例展示了在 movies 索引中搜索 dragon 时返回的 _rankingScoreDetail：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "dragon",
    "showRankingScoreDetails": true
  }'

{
  "hits": [
    {
      "id": 31072,
      "title": "Dragon",
      "overview": "In a desperate attempt to save her kingdom…",
      …
      "_rankingScoreDetails": {
        "words": {
          "order": 0,
          "matchingWords": 4,
          "maxMatchingWords": 4,
          "score": 1.0
        },
        "typo": {
          "order": 2,
          "typoCount": 1,
          "maxTypoCount": 4,
          "score": 0.75
        },
        "name:asc": {
          "order": 1,
          "value": "Dragon"
        }
      }
    },
    …
  ],
  …
}

​

排名分数阈值

参数: rankingScoreThreshold

期望值: 介于 0.0 和 1.0 之间的数字

默认值: null

排除低于指定排名分数的结果。

被排除的结果不计入 estimatedTotalHits、totalHits 和分面分布。

​

示例

以下查询仅返回排名分数大于 0.2 的结果：

curl \
-X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
-H 'Content-Type: application/json' \
--data-binary '{
    "q": "badman",
    "rankingScoreThreshold": 0.2
}'

​

在搜索时自定义搜索属性

参数: attributesToSearchOn

期望值: 以数组形式指定的可搜索属性列表

默认值: ["*"]

配置查询使其仅在指定属性中搜索词项。

除了属性列表外，你也可以传递通配符值 (["*"]) 或 null 给 attributesToSearchOn。这两种情况下，Meilisearch 都会在所有可搜索属性中查找匹配项。

attributesToSearchOn 中属性的顺序不会影响相关性。

​

示例

以下查询返回 overview 字段包含 "adventure" 的文档：

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "adventure",
    "attributesToSearchOn": ["overview"]
  }'

即使 title 或 genre 等字段存在于 searchableAttributes 列表中，结果也不会包含这些字段中含有 "adventure" 的文档。

​

混合搜索

参数: hybrid

期望值: 包含两个字段的对象：embedder 和 semanticRatio

默认值: null

配置 Meilisearch 根据查询的含义和上下文返回搜索结果。

hybrid 必须是一个对象，接受两个字段：embedder 和 semanticRatio。

embedder 必须是一个字符串，表示通过 /settings 端点配置的嵌入器。在执行 AI 驱动的搜索时，必须指定一个有效的嵌入器。

sematicRatio 必须是一个介于 0.0 和 1.0 之间的数字，表示关键词搜索和语义搜索结果的占比。0.0 表示仅返回关键词结果，1.0 表示仅返回基于语义的结果。默认值为 0.5。

​

示例

curl -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
  -H 'content-type: application/json' \
  --data-binary '{
    "q": "kitchen utensils",
    "hybrid": {
      "semanticRatio": 0.9,
      "embedder": "EMBEDDER_NAME"
    }
  }'

​

向量

参数: vector

期望值: 数字数组

默认值: null

使用自定义向量执行搜索查询。必须是一个数字数组，对应自定义向量的维度。

当使用 userProvided 嵌入器进行搜索时，vector 是必需的。你也可以使用 vector 来覆盖嵌入器的自动向量生成。

vector 的维度必须与嵌入器的维度匹配。

​

示例

curl -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
  -H 'content-type: application/json' \
  --data-binary '{ 
    "vector": [0, 1, 2],
    "hybrid": {
      "embedder": "EMBEDDER_NAME"
    }
  }'

​

在响应中显示 _vectors

参数: retrieveVectors

期望值: true 或 false

默认值: false

在搜索结果中返回文档嵌入数据。如果为 true，Meilisearch 将在每个文档的 _vectors 字段中显示向量数据。

​

示例

curl -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
  -H 'content-type: application/json' \
  --data-binary '{
    "q": "厨房用具",
    "retrieveVectors": true,
    "hybrid": {
      "embedder": "EMBEDDER_NAME"
    }
  }'

{
  "hits": [
    {
      "id": 0,
      "title": "文档名称",
      "_vectors": {
        "default": {
          "embeddings": [0.1, 0.2, 0.3],
          "regenerate": true
        }
      }
      …
    },
    …
  ],
  …
}

​

查询语言区域

参数: locales

期望值: 支持的 ISO-639 语言区域数组

默认值: []

默认情况下，Meilisearch 会自动检测查询语言。使用此参数可以显式指定查询语言。

当 locales 与本地化属性索引设置不匹配时，此参数优先级更高。

​

示例

curl \
-X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \
-H 'Content-Type: application/json' \
--data-binary '{
  "q": "日文查询文本",
  "locales": ["jpn"]
}'

{
  "hits": [
    {
      "id": 0,
      "title": "文档名称",
      "overview_jp": "日文概述文本"
    }
    …
  ],
  …
}