diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index adb2a435fe..a10dce067e 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -986,3 +986,19 @@ getting_started_pagination: |- --data-binary '{ "maxTotalHits": 500 }' +search_parameter_guide_matching_strategy_1: | + curl \ + -X POST 'http://localhost:7700/indexes/movies/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "q": "big fat liar", + "matchingStrategy": "last" + }' +search_parameter_guide_matching_strategy_2: | + curl \ + -X POST 'http://localhost:7700/indexes/movies/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "q": "big fat liar", + "matchingStrategy": "all" + }' diff --git a/.vuepress/public/sample-template.yaml b/.vuepress/public/sample-template.yaml index 4a3a78fcc8..04ba936630 100644 --- a/.vuepress/public/sample-template.yaml +++ b/.vuepress/public/sample-template.yaml @@ -152,3 +152,5 @@ synonyms_guide_1: |- getting_started_faceting: |- getting_started_pagination: |- getting_started_front_end_integration_md: |- +search_parameter_guide_matching_strategy_1: |- +search_parameter_guide_matching_strategy_2: |- diff --git a/reference/api/search.md b/reference/api/search.md index b73e3bcd4a..186c80f08c 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -33,22 +33,23 @@ By default, [this endpoint returns a maximum of 1000 results](/learn/advanced/kn ### Body -| Search Parameter | Type | Default value | Description | -| :------------------------------------------------------ | :--------------- | :------------ | :------------------------------------------------- | -| **[`q`](#query-q)** | String | `""` | Query string | -| **[`offset`](#offset)** | Integer | `0` | Number of documents to skip | -| **[`limit`](#limit)** | Integer | `20` | Maximum number of documents returned | -| **[`filter`](#filter)** | Array of strings | `null` | Filter queries by an attribute's value | -| **[`facets`](#facets)** | Array of strings | `null` | Display the count of matches per facet | -| **[`attributesToRetrieve`](#attributes-to-retrieve)** | Array of strings | `["*"]` | Attributes to display in the returned documents | -| **[`attributesToCrop`](#attributes-to-crop)** | Array of strings | `null` | Attributes whose values have to be cropped | -| **[`cropLength`](#crop-length)** | Integer | `10` | Maximum length of cropped value in words | -| **[`cropMarker`](#crop-marker)** | String | `"…"` | String marking crop boundaries | -| **[`attributesToHighlight`](#attributes-to-highlight)** | Array of strings | `null` | Highlight matching terms contained in an attribute | -| **[`highlightPreTag`](#highlight-tags)** | String | `""` | String inserted at the start of a highlighted term | -| **[`highlightPostTag`](#highlight-tags)** | String | `""` | String inserted at the end of a highlighted term | -| **[`showMatchesPosition`](#show-matches-position)** | Boolean | `false` | Return matching terms location | -| **[`sort`](#sort)** | Array of strings | `null` | Sort search results by an attribute's value | +| Search Parameter | Type | Default value | Description | +| :------------------------------------------------------ | :--------------- | :------------ | :-------------------------------------------------- | +| **[`q`](#query-q)** | String | `""` | Query string | +| **[`offset`](#offset)** | Integer | `0` | Number of documents to skip | +| **[`limit`](#limit)** | Integer | `20` | Maximum number of documents returned | +| **[`filter`](#filter)** | Array of strings | `null` | Filter queries by an attribute's value | +| **[`facets`](#facets)** | Array of strings | `null` | Display the count of matches per facet | +| **[`attributesToRetrieve`](#attributes-to-retrieve)** | Array of strings | `["*"]` | Attributes to display in the returned documents | +| **[`attributesToCrop`](#attributes-to-crop)** | Array od strings | `null` | Attributes whose values have to be cropped | +| **[`cropLength`](#crop-length)** | Integer | `10` | Maximum length of cropped value in words | +| **[`cropMarker`](#crop-marker)** | String | `"…"` | String marking crop boundaries | +| **[`attributesToHighlight`](#attributes-to-highlight)** | Array of strings | `null` | Highlight matching terms contained in an attribute | +| **[`highlightPreTag`](#highlight-tags)** | String | `""` | String inserted at the start of a highlighted term | +| **[`highlightPostTag`](#highlight-tags)** | String | `""` | String inserted at the end of a highlighted term | +| **[`showMatchesPosition`](#show-matches-position)** | Boolean | `false` | Return matching terms location | +| **[`sort`](#sort)** | Array of strings | `null` | Sort search results by an attribute's value | +| **[`matchingStrategy`](#matching-strategy)** | String | `last` | Strategy used to match query terms within documents | [Learn more about how to use each search parameter](#search-parameters). @@ -127,22 +128,23 @@ By default, [this endpoint returns a maximum of 1000 results](/learn/advanced/kn ### Query parameters -| Search Parameter | Type | Default value | Description | -| :------------------------------------------------------ | :--------------- | :------------ | :------------------------------------------------- | -| **[`q`](#query-q)** | String | `""` | Query string | -| **[`offset`](#offset)** | Integer | `0` | Number of documents to skip | -| **[`limit`](#limit)** | Integer | `20` | Maximum number of documents returned | -| **[`filter`](#filter)** | Array of strings | `null` | Filter queries by an attribute's value | -| **[`facets`](#facets)** | Array of strings | `null` | Display the count of matches per facet | -| **[`attributesToRetrieve`](#attributes-to-retrieve)** | Array of strings | `["*"]` | Attributes to display in the returned documents | -| **[`attributesToCrop`](#attributes-to-crop)** | Array of strings | `null` | Attributes whose values have to be cropped | -| **[`cropLength`](#crop-length)** | Integer | `10` | Maximum length of cropped value in words | -| **[`cropMarker`](#crop-marker)** | String | `"…"` | String marking crop boundaries | -| **[`attributesToHighlight`](#attributes-to-highlight)** | Array of strings | `null` | Highlight matching terms contained in an attribute | -| **[`highlightPreTag`](#highlight-tags)** | String | `""` | String inserted at the start of a highlighted term | -| **[`highlightPostTag`](#highlight-tags)** | String | `""` | String inserted at the end of a highlighted term | -| **[`showMatchesPosition`](#show-matches-position)** | Boolean | `false` | Return matching terms location | -| **[`sort`](#sort)** | Array of strings | `null` | Sort search results by an attribute's value | +| Search Parameter | Type | Default value | Description | +| :------------------------------------------------------ | :--------------- | :------------ | :-------------------------------------------------- | +| **[`q`](#query-q)** | String | `""` | Query string | +| **[`offset`](#offset)** | Integer | `0` | Number of documents to skip | +| **[`limit`](#limit)** | Integer | `20` | Maximum number of documents returned | +| **[`filter`](#filter)** | Array of strings | `null` | Filter queries by an attribute's value | +| **[`facets`](#facets)** | Array of strings | `null` | Display the count of matches per facet | +| **[`attributesToRetrieve`](#attributes-to-retrieve)** | Array of strings | `["*"]` | Attributes to display in the returned documents | +| **[`attributesToCrop`](#attributes-to-crop)** | Array od strings | `null` | Attributes whose values have to be cropped | +| **[`cropLength`](#crop-length)** | Integer | `10` | Maximum length of cropped value in words | +| **[`cropMarker`](#crop-marker)** | String | `"…"` | String marking crop boundaries | +| **[`attributesToHighlight`](#attributes-to-highlight)** | Array of strings | `null` | Highlight matching terms contained in an attribute | +| **[`highlightPreTag`](#highlight-tags)** | String | `""` | String inserted at the start of a highlighted term | +| **[`highlightPostTag`](#highlight-tags)** | String | `""` | String inserted at the end of a highlighted term | +| **[`showMatchesPosition`](#show-matches-position)** | Boolean | `false` | Return matching terms location | +| **[`sort`](#sort)** | Array of strings | `null` | Sort search results by an attribute's value | +| **[`matchingStrategy`](#matching-strategy)** | String | `last` | Strategy used to match query terms within documents | [Learn more about how to use each search parameter](#search-parameters). @@ -211,22 +213,23 @@ This is not necessary when using the `POST` route or one of our [SDKs](/learn/wh ### Overview -| Search Parameter | Default value | Description | -| :------------------------------------------------------ | :------------ | :------------------------------------------------- | -| **[`q`](#query-q)** | `""` | Query string | -| **[`offset`](#offset)** | `0` | Number of documents to skip | -| **[`limit`](#limit)** | `20` | Maximum number of documents returned | -| **[`filter`](#filter)** | `null` | Filter queries by an attribute's value | -| **[`facets`](#facets)** | `null` | Display the count of matches per facet | -| **[`attributesToRetrieve`](#attributes-to-retrieve)** | `["*"]` | Attributes to display in the returned documents | -| **[`attributesToCrop`](#attributes-to-crop)** | `null` | Attributes whose values have to be cropped | -| **[`cropLength`](#crop-length)** | `10` | Maximum length of cropped value in words | -| **[`cropMarker`](#crop-marker)** | `"…"` | String marking crop boundaries | -| **[`attributesToHighlight`](#attributes-to-highlight)** | `null` | Highlight matching terms contained in an attribute | -| **[`highlightPreTag`](#highlight-tags)** | `""` | String inserted at the start of a highlighted term | -| **[`highlightPostTag`](#highlight-tags)** | `""` | String inserted at the end of a highlighted term | -| **[`showMatchesPosition`](#show-matches-position)** | `false` | Return matching terms location | -| **[`sort`](#sort)** | `null` | Sort search results by an attribute's value | +| Search Parameter | Type | Default value | Description | +| :------------------------------------------------------ | :--------------- | :------------ | :-------------------------------------------------- | +| **[`q`](#query-q)** | String | `""` | Query string | +| **[`offset`](#offset)** | Integer | `0` | Number of documents to skip | +| **[`limit`](#limit)** | Integer | `20` | Maximum number of documents returned | +| **[`filter`](#filter)** | Array of strings | `null` | Filter queries by an attribute's value | +| **[`facets`](#facets)** | Array of strings | `null` | Display the count of matches per facet | +| **[`attributesToRetrieve`](#attributes-to-retrieve)** | Array of strings | `["*"]` | Attributes to display in the returned documents | +| **[`attributesToCrop`](#attributes-to-crop)** | Array od strings | `null` | Attributes whose values have to be cropped | +| **[`cropLength`](#crop-length)** | Integer | `10` | Maximum length of cropped value in words | +| **[`cropMarker`](#crop-marker)** | String | `"…"` | String marking crop boundaries | +| **[`attributesToHighlight`](#attributes-to-highlight)** | Array of strings | `null` | Highlight matching terms contained in an attribute | +| **[`highlightPreTag`](#highlight-tags)** | String | `""` | String inserted at the start of a highlighted term | +| **[`highlightPostTag`](#highlight-tags)** | String | `""` | String inserted at the end of a highlighted term | +| **[`showMatchesPosition`](#show-matches-position)** | Boolean | `false` | Return matching terms location | +| **[`sort`](#sort)** | Array of strings | `null` | Sort search results by an attribute's value | +| **[`matchingStrategy`](#matching-strategy)** | String | `last` | Strategy used to match query terms within documents | ### Query (q) @@ -735,3 +738,27 @@ Queries using `_geoPoint` will always include a `geoDistance` field containing t ``` [You can read more about location-based sorting in our dedicated guide.](/learn/advanced/geosearch.md#sorting-results-with-geopoint) + +### Matching strategy + +**Parameter**: `matchingStrategy` +**Expected value**: `last` or `all` +**Default value**: `last` + +Defines the strategy used to match query terms in documents. + +#### `last` + +`last` returns documents containing all the query terms first. If there are not enough results containing all query terms to meet the requested `limit`, Meilisearch will remove one query term at a time, starting from the end of the query. + + + +With the above code sample, Meilisearch will first return documents that contain all three words. If the results don't meet the requested `limit`, it will also return documents containing only the first two terms, `big fat`, followed by documents containing only `big`. + +#### `all` + +`all` only returns documents that contain all query terms. Meilisearch will not match any more documents even if there aren't enough to meet the requested `limit`. + + + +The above code sample would only return documents containing all three words.