搜尋

Meilisearch 公開了兩個路由來執行搜尋

• 一個 POST 路由：當使用 API 身份驗證時，這是首選路由，因為它允許預檢請求快取和更好的效能
• 一個 GET 路由：不建議使用此路由，除非您有充分的理由這樣做（例如，特定的快取能力）

您可以在本文末尾找到這兩個路由接受的參數的詳細說明。

在給定的索引中搜尋符合特定查詢的文件。

當需要 API 金鑰時，這是執行搜尋的首選端點，因為它允許快取預檢請求。快取預檢請求可以顯著提高搜尋速度。

深入了解如何使用每個搜尋參數.

預設情況下，Meilisearch 只會在查詢中返回搜尋結果總數的估計值：estimatedTotalHits。發生這種情況是因為 Meilisearch 優先考慮相關性和效能，而不是提供詳盡的搜尋結果數。使用 estimatedTotalHits 時，請使用 offset 和 limit 在搜尋結果之間導覽。

如果您需要搜尋結果的總數，請在查詢中使用 hitsPerPage 和 page 搜尋參數。此查詢的回應會以 totalHits 取代 estimatedTotalHits，並包含一個額外的欄位，其中包含根據您的 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"
    }
    …
  ],
  …
}