搜索

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 'MEILISEARCH_URL/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 'MEILISEARCH_URL/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 '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
预期值：任何正整数
默认值: 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\""
    ]
  }'

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

_geoRadius(lat, lng, distance_in_meters)

curl \
  -X POST 'MEILISEARCH_URL/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 '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 列表中定义一个属性作为 distinct 属性。Distinct 属性指示对于指定字段具有相同值的文档是等效的，并且在搜索结果中应仅返回最相关的一个。

此行为类似于 distinctAttribute 索引设置，但可以在搜索时配置。distinctAttribute 充当您可以与 distinct 覆盖的默认 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，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 '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 是一个排序函数，需要两个浮点数来指示位置的纬度和经度。您还必须指定排序应该是升序 (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 首先返回包含所有查询词的文档。如果包含所有查询词的结果不足以满足请求的 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 仅返回包含所有查询词的文档。即使没有足够的结果来满足请求的 limit，Meilisearch 也不会匹配更多文档。

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

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

frequency 首先返回包含所有查询词的文档。如果包含所有查询词的结果不足以满足请求的限制，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 是一个对象，其中包含每个活动排名规则的嵌套对象。

每个排名规则在其自己的对象中详细说明其分数。字段因排名规则而异。

• 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 '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）中包含 "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 '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"
    }
  }'

参数: retrieveVectors
期望值: true 或 false
默认值: false

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

curl -X POST 'MEILISEARCH_URL/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 和 localizedAttributes 索引设置之间存在不匹配，则此参数优先。

curl \
-X POST 'MEILISEARCH_URL/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"
    }
    …
  ],
  …
}