Skip to content

v0.29: add new search parameter matchingStrategy #1865

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 9 commits into from
Sep 29, 2022
Merged

v0.29: add new search parameter matchingStrategy #1865

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
1da54a3
update tables
maryamsulemani97 Sep 6, 2022
2dcf312
update search.md
maryamsulemani97 Sep 7, 2022
470e255
Update reference/api/search.md
maryamsulemani97 Sep 7, 2022
789af6d
Update reference/api/search.md
maryamsulemani97 Sep 7, 2022
81f18af
Update reference/api/search.md
maryamsulemani97 Sep 20, 2022
20fb282
update based on review
maryamsulemani97 Sep 20, 2022
1648faa
Apply suggestions from code review
maryamsulemani97 Sep 27, 2022
4e9b8dc
remove space
maryamsulemani97 Sep 27, 2022
b31f9df
Merge branch 'v0.29' into v0.29--Add-new-search-parameter-matchingStr…
maryamsulemani97 Sep 29, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .code-samples.meilisearch.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}'
2 changes: 2 additions & 0 deletions .vuepress/public/sample-template.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: |-
123 changes: 75 additions & 48 deletions reference/api/search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 | `"<em>"` | String inserted at the start of a highlighted term |
| **[`highlightPostTag`](#highlight-tags)** | String | `"</em>"` | 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 | `"<em>"` | String inserted at the start of a highlighted term |
| **[`highlightPostTag`](#highlight-tags)** | String | `"</em>"` | 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).

Expand Down Expand Up @@ -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 | `"<em>"` | String inserted at the start of a highlighted term |
| **[`highlightPostTag`](#highlight-tags)** | String | `"</em>"` | 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 | `"<em>"` | String inserted at the start of a highlighted term |
| **[`highlightPostTag`](#highlight-tags)** | String | `"</em>"` | 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).

Expand Down Expand Up @@ -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)** | `"<em>"` | String inserted at the start of a highlighted term |
| **[`highlightPostTag`](#highlight-tags)** | `"</em>"` | 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 | `"<em>"` | String inserted at the start of a highlighted term |
| **[`highlightPostTag`](#highlight-tags)** | String | `"</em>"` | 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)

Expand Down Expand Up @@ -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.

<CodeSamples id="search_parameter_guide_matching_strategy_1" />

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`.

<CodeSamples id="search_parameter_guide_matching_strategy_2" />

The above code sample would only return documents containing all three words.