搜索

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 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "american ninja" }'

{
  "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 "
}

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

仅在不需要 API 密钥时才能使用此端点。如果需要 API 密钥，请使用 POST 路径。

详细了解如何使用每个搜索参数.

curl \
  -X GET 'http://localhost:7700/indexes/movies/search?q=american%20ninja'

{
  "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
预期值：任何字符串
默认值：null

设置搜索词。

你可以通过设置 q 参数搜索提到 shifu 的电影

curl \
  -X POST 'http://localhost:7700/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 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
--data-binary '{ "q": "\"african american\" horror" }'

在单词或短语前使用减号 (-) 运算符以将其从搜索结果中排除。

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

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

否定搜索可与词组搜索一起使用

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

参数：offset
期望值：任何正整数
默认值：0

设置搜索结果的起点，有效跳过给定数量的文档。

使用 offset 和 limit 查询仅返回搜索结果总数的估算值。

您可以通过组合 offset 和 limit 查询来对搜索结果进行分页。

如果您想跳过查询中的第一个结果，请将 offset 设置为 1

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

参数：limit
期望值：任何正整数
默认值：20

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

您可以通过组合 offset 和 limit 查询来对搜索结果进行分页。

如果您希望您的查询仅返回 两个文档，请将 limit 设置为 2

curl \
  -X POST 'http://localhost:7700/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 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "",
    "hitsPerPage": 15
  }'

参数: page
期望值：任何正整数
默认值: 1

请求特定的结果页面。页面使用 hitsPerPage 搜索参数计算。

包含 page 的查询是详尽无遗的，并且不返回 estimatedTotalHits。相反，响应主体将包括两个新字段：totalHits 和 totalPages。

如果将 page 设置为 0，Meilisearch 会处理你的请求，但不返回任何文档。在这种情况下，响应主体将包括 facetDistribution、totalPages 和 totalHits 的详尽值。

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

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

curl \
  -X POST 'http://localhost:7700/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 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "thriller",
    "filter": [
      [
        "genres = Horror",
        "genres = Mystery"
      ],
      "director = \"Jordan Peele\""
    ]
  }'

如果你的文档包含 _geo 数据, 则可以使用内置筛选规则 _geoRadius 和 _geoBoundingBox 根据其地理位置筛选结果。

_geoRadius(lat, lng, distance_in_meters)

curl \
  -X POST 'http://localhost:7700/indexes/restaurants/search' \
  -H 'Content-type:application/json' \
  --data-binary '{ "filter": "_geoRadius(45.472735, 9.184019, 2000)" }'

如果任何参数无效或缺失, Meilisearch 将返回错误代码 invalid_search_filter。

参数: facets
预期值: attribute 数组或 ["*"]
默认值: null 为每个给定的分面返回匹配当前搜索查询的文档数。此参数可以取两个值

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

默认情况下, facets 为每个分面字段返回最多 100 个分面值。你可以使用 faceting 索引设置 的 maxValuesPerFacet 属性更改此值。

设置 facets 时, 搜索结果对象包括 facetDistribution 和 facetStats 字段。

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 包含每个分面中所有文档的最小 (min) 和最大 (max) 数值。仅考虑数值

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

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

给定一个电影评分数据库, 以下代码示例返回每个类型的 蝙蝠侠 电影的数量以及最低和最高评分

curl \
  -X POST 'http://localhost:7700/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 'http://localhost:7700/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 'http://localhost:7700/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 中所有属性裁剪后的值。

假设你有一个包含以下字符串的字段：唐纳泰罗是一只熟练聪明的海龟。莱昂纳多是最熟练的海龟。拉斐尔是最强壮的海龟。

裁剪时，Meilisearch 会尝试尊重句子边界。例如，如果你搜索的词条是 莱昂纳多，你的 cropLength 是 6，Meilisearch 会优先保留这个句子并返回：莱昂纳多是最熟练的海龟。

如果一个查询只包含一个搜索词条，Meilisearch 会以该词条第一次出现的位置为中心进行裁剪。如果你搜索 海龟，并且你的 cropLength 是 7，Meilisearch 会返回该单词的第一个实例：唐纳泰罗是一只熟练聪明的海龟。

如果一个查询包含多个搜索词条，Meilisearch 会以最多唯一匹配的词条周围为中心进行裁剪，优先考虑彼此之间距离更近且符合原始查询顺序的词条。如果你搜索 熟练的海龟，cropLength 是 6，Meilisearch 会返回 莱昂纳多是最熟练的海龟。

如果 Meilisearch 在一个字段中找不到任何查询词条，裁剪会从该字段的第一个单词开始。如果你搜索 米开朗基罗，cropLength 是 4，这个字符串出现在另一个字段中，Meilisearch 会返回 唐纳泰罗是一只熟练的…。

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

curl \
  -X POST 'http://localhost:7700/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 'http://localhost:7700/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 'http://localhost:7700/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 'http://localhost:7700/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 'http://localhost:7700/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 'http://localhost:7700/indexes/books/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "science fiction",
    "sort": ["price:asc"]
  }'

在处理包含地理位置数据的文件时，您可以使用 _geoPoint 根据位置与特定地理位置的距离对结果进行排序。

_geoPoint 是一個排序函數，需要兩個浮點數來表示位置的緯度和經度。您還必須指定排序應該是升序 (asc) 還是降序 (desc)

curl \
  -X POST 'http://localhost:7700/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 會先傳回包含所有查詢字詞的文件。如果沒有足夠包含所有查詢字詞的結果來符合請求的 limit，Meilisearch 會從查詢的結尾開始逐一移除查詢字詞。

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

使用上述程式碼範例，Meilisearch 首先會傳回包含所有三個字詞的文件。如果結果不符合所請求的 limit，它也會傳回僅包含前兩個字詞的文件，即 big fat，然後傳回僅包含 big 的文件。

all 只會傳回包含所有查詢字詞的文件。即使沒有足夠的文件來符合請求的 limit，Meilisearch 也不會再匹配任何文件。

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

上述程式碼範例只會傳回包含所有三個字詞的文件。

frequency 會先傳回包含所有查詢字詞的文件。如果沒有足夠包含所有查詢字詞的結果來符合請求的 limit，Meilisearch 會逐一移除查詢字詞，從資料集中出現頻率最高的那個字詞開始。frequency 實際上讓出現頻率較低的一組結果中較輕微的字詞有更高的加權。

curl \
  -X POST 'http://localhost:7700/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 'http://localhost:7700/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 是一个对象，包含一个针对每个活跃排名规则的嵌套对象。

每个排名规则会将其分数描述在自己的对象里。字段根据每个排名规则而异。

• order：应用此排名规则的顺序
• score：此规则的排名分数
• matchingWords：文档中与查询匹配的单词数量
• maxMatchingWords：文档中可以与查询匹配的最大单词数量

• order：应用此特定排名规则的顺序
• score：此规则的排名分数
• typoCount：纠正了文档与查询术语匹配的错别字数量
• maxTypoCount：接受的最大错别字数量

• order：应用此排名规则的顺序
• score：此规则的排名分数

• order：应用此排名规则的顺序
• score：此规则的排名分数
• attributeRankingOrderScore：从匹配属性的最大属性排名顺序计算的分数
• queryWordDistanceScore：从查询中单词的位置与匹配属性中单词位置之间的距离计算的分数

• order：应用此排名规则的顺序
• score：此规则的排名分数
• matchType：exactMatch、matchesStart 或 noExactMatch
  • exactMatch：文档包含一个匹配所有查询术语的属性，且没有其他单词插入其中，并且这些术语的顺序与给定的顺序一致
  • matchesStart：文档包含一个属性，其中所有查询术语的顺序与原始查询一致
  • noExactMatch：文档包含一个至少包含一个与原始查询匹配的查询术语的属性
• matchingWords：当 matchType 为 noExactMatch 时，属性中的完全匹配数量
• maxMatchingWords：当 matchType 为 noExactMatch 时，属性中的最大完全匹配数量

sort 排序规则不会作为单个字段显示在得分详细信息对象中。相反，每个已排序的属性都将以其自身的字段形式出现，后面跟着一个冒号 (:) 和排序方向：attribute:direction。

• order：应用此排名规则的顺序
• value：用于排序的字段的值

• order：应用此排名规则的顺序
• value：用于排序的字段的值
• distance：与 _geoDistance 相同

• order：应用此特定排名规则的顺序
• value：用于对文档进行排序的向量
• similarity：目标向量和值向量之间的相似度得分。1.0 表示完全相似，0.0 表示完全不相似

在 movies 中搜索 dragon 时，以下代码示例将返回 _rankingScoreDetail

curl \
  -X POST 'http://localhost:7700/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 'http://localhost:7700/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 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "adventure",
    "attributesToSearchOn": ["overview"]
  }'

结果不会包括在其他字段（如 title 或 genre）中包含 "adventure" 的文档，即使这些字段出现在 searchableAttributes 列表中。

参数：hybrid
预期值：具有两个字段的对象：embedder 和 semanticRatio
默认值：null

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

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

embedder 必须是指示使用 /settings 终结点配置的一个嵌入器的字符串。如果您未指定一个嵌入器，并且您的索引包含一个嵌入器，则 Meilisearch 会默认使用它。如果一个索引包含多个嵌入器，则 Meilisearch 将使用名为 default 的嵌入器。

semanticRatio 必须介于 0.0 和 1.0 之间，表示关键字结果和语义搜索结果之间的比例。0.0 导致 Meilisearch 仅返回关键字结果。1.0 导致 Meilisearch 仅返回基于含义的结果。默认为 0.5。

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

参数：vector
期望值：一个数字数组
默认值：null

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

当使用 userProvided 嵌入器执行搜索时，vector 是必需的。您还可以使用 vector 覆盖嵌入器的自动矢量生成功能。

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

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

参数：retrieveVectors
预期值：true 或 false
默认值：false

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

curl -X POST 'localhost:7700/indexes/INDEX_NAME/search' \
  -H 'content-type: application/json' \
  --data-binary '{
    "q": "kitchen utensils",
    "retrieveVectors": true,
    "hybrid": {
      "embedder": "default"
    }
  }'

{
  "hits": [
    {
      "id": 0,
      "title": "DOCUMENT NAME",
      "_vectors": {
        "default": {
          "embeddings": [0.1, 0.2, 0.3],
          "regenerate": true
        }
      }
      …
    },
    …
  ],
  …
}

参数：locales
期望值：受支持的 ISO-639-2B 语言环境 数组
默认值: []

默认情况下，Meilisearch 会自动检测查询的语言。使用此参数可以明确地说明查询的语言。

如果 locales 和 语言环境化属性索引设置 不匹配，则此参数优先。

curl \
-X POST 'http://localhost:7700/indexes/INDEX_NAME/search' \
-H 'Content-Type: application/json' \
--data-binary '{
  "q": "進撃の巨人",
  "locales": ["jpn"]
}'

{
  "hits": [
    {
      "id": 0,
      "title": "DOCUMENT NAME",
      "overview_cn": "OVERVIEW TEXT IN CHINESE",
      "overview_jp": "OVERVIEW TEXT IN JAPANESE"
    }
    …
  ],
  …
}