搜索

Meilisearch 公开了两个路由来执行搜索

• 一个 POST 路由：当使用 API 身份验证时，这是首选路由，因为它允许预检请求缓存和更好的性能
• 一个 GET 路由：不建议使用此路由，除非您有充分的理由这样做（例如，特定的缓存能力）

您可以在本文末尾找到这两个路由接受的参数的详尽描述。

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

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

了解有关如何使用每个搜索参数的更多信息.

默认情况下，Meilisearch 仅返回查询中搜索结果总数的估计值：estimatedTotalHits。发生这种情况是因为 Meilisearch 优先考虑相关性和性能，而不是提供详尽的搜索结果数量。使用estimatedTotalHits时，请使用offset和limit在搜索结果之间导航。

如果您需要搜索结果的总数，请在查询中使用hitsPerPage和page搜索参数。此查询的响应将estimatedTotalHits替换为totalHits，并包含一个额外的字段，其中包含基于hitsPerPage的搜索结果页数：totalPages。使用totalHits和totalPages可能会导致性能略有下降，但建议在创建诸如编号的页面选择器之类的 UI 元素时使用。

estimatedTotalHits和totalHits都不能超过maxTotalHits索引设置中配置的限制。

您可以在我们的专用指南中阅读有关分页的更多信息。

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

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

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

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

负向搜索可以与短语搜索一起使用

curl \
  -X POST 'https://127.0.0.1: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 'https://127.0.0.1:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "shifu",
    "offset": 1
  }'

参数: limit
预期值: 任何正整数
默认值: 20

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

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

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

curl \
  -X POST 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1: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 忽略字符串值，即使字符串包含数字也是如此。

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

curl \
  -X POST 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1: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 中存在的所有属性的裁剪值。

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

Meilisearch 在裁剪时会尽量遵循句子边界。例如，如果您的搜索词是 Leonardo 并且您的 cropLength 是 6，则 Meilisearch 将优先保持句子完整并返回：Leonardo is the most skilled turtle.

如果查询仅包含单个搜索词，则 Meilisearch 会在该词的第一次出现时进行裁剪。如果您搜索 turtle 并且您的 cropLength 是 7，则 Meilisearch 将返回该词的第一个实例：Donatello is a skilled and smart turtle.

如果查询包含多个搜索词，则 Meilisearch 会将裁剪居中于最大数量的唯一匹配项，并优先考虑彼此更接近且遵循原始查询顺序的词。如果您使用 cropLength 为 6 搜索 skilled turtle，则 Meilisearch 将返回 Leonardo is the most skilled turtle。

如果 Meilisearch 在字段中未找到任何查询词，则裁剪从该字段中的第一个词开始。如果您使用 cropLength 为 4 搜索 Michelangelo 并且此字符串存在于另一个字段中，则 Meilisearch 将返回 Donatello is a skilled …。

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

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

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

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

curl \
  -X POST 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{
    "q": "big fat liar",
    "matchingStrategy": "all"
  }'

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

frequency 首先返回包含所有查询词的文档。 如果没有足够的结果包含所有查询词以满足请求的限制，则 Meilisearch 将一次删除一个查询词，从数据集中最频繁出现的词开始。 frequency 可以有效地为一组结果中出现频率较低的词赋予更高的权重。

curl \
  -X POST 'https://127.0.0.1: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 'https://127.0.0.1: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 'https://127.0.0.1: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 和 facet 分布中。

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

curl \
-X POST 'https://127.0.0.1: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 'https://127.0.0.1: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 端点配置的嵌入器。在执行 AI 驱动的搜索时，必须指定有效的嵌入器。

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": "EMBEDDER_NAME"
    }
  }'

参数：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],
    "embedder": "EMBEDDER_NAME"
  }'

参数：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": "EMBEDDER_NAME"
    }
  }'

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

参数：locales
预期值：支持的 ISO-639 区域设置数组
默认值: []

默认情况下，Meilisearch 会自动检测查询的语言。使用此参数显式声明查询的语言。

如果 locales 和 本地化属性索引设置之间不匹配，则此参数优先。

curl \
-X POST 'https://127.0.0.1:7700/indexes/INDEX_NAME/search' \
-H 'Content-Type: application/json' \
--data-binary '{
  "q": "QUERY TEXT IN JAPANESE",
  "locales": ["jpn"]
}'

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