From c1cabab123318086e625036bfb8828380cee6c4c Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 7 Sep 2022 16:54:38 +0200 Subject: [PATCH 1/8] filters: add new operators, update existing behaviour with v0.29 fixes --- reference/api/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/search.md b/reference/api/search.md index 7c4bf4cbd7..b161313397 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -346,7 +346,7 @@ If you want your query to return only **two** documents, set `limit` to `2`: Uses filter expressions to refine search results. Attributes used as filter criteria must be added to the [`filterableAttributes` list](/reference/api/settings.md#filterable-attributes). -[Read our guide on filtering, faceted search and filter expressions.](/learn/advanced/filtering_and_faceted_search.md) +For more information on how to use filters and build filter expressions, [read our guide on filtering, faceted search and filter expressions](/learn/advanced/filtering_and_faceted_search.md). #### Example From 49cb23cb5027d33f27adda74f9b25eb07fbb084c Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 7 Sep 2022 18:08:19 +0200 Subject: [PATCH 2/8] filters: update with v0.29 changes --- learn/advanced/filtering_and_faceted_search.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 8ddb609c12..4b02e884e7 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -102,10 +102,14 @@ The [`GET` route of the search endpoint](/reference/api/search.md#search-in-an-i String expressions combine conditions using the following filter operators and parentheses: -- `NOT` only returns documents that do not satisfy a condition : `NOT genres = horror` +- `NOT` returns all documents that do not satisfy a condition, including results missing the specified attribute. The expression `NOT genres = horror` returns all documents whose `genre` is not `horror` and documents missing a `genres` field - `AND` operates by connecting two conditions and only returns documents that satisfy both of them: `genres = horror AND director = 'Jordan Peele'` - `OR` connects two conditions and returns results that satisfy at least one of them: `genres = horror OR genres = comedy` - `TO` is equivalent to `>= AND <=`. The expression `release_date 795484800 TO 972129600` translates to `release_date >= 795484800 AND release_date <= 972129600` +- `IN [valueA, valueB]` selects all documents whose specified field contains at least one of the specified values. The expression `genres IN [horror, comedy]` returns all documents whose `genre` is either `horror`, `comedy`, or both +- `EXIST` checks for the existence of a field. Fields with empty or null values still count as existing. The expression `release_date NOT EXIST` returns all documents without a `release_date` + +When creating an expression with a field name or value identical to a filter operator such as `AND` or `NOT`, you must wrap it in quotation marks: `title = "NOT" AND title = "AND"`. ::: tip String expressions are read left to right. `NOT` takes precedence over `AND` and `AND` takes precedence over `OR`. You can use parentheses to ensure expressions are correctly parsed. From eb57a7f34d2b4caa9d4cac9672984b7a6f533aeb Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 8 Sep 2022 13:20:58 +0200 Subject: [PATCH 3/8] filters: polish wording --- learn/advanced/filtering_and_faceted_search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 4b02e884e7..060fbaa7ac 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -106,7 +106,7 @@ String expressions combine conditions using the following filter operators and p - `AND` operates by connecting two conditions and only returns documents that satisfy both of them: `genres = horror AND director = 'Jordan Peele'` - `OR` connects two conditions and returns results that satisfy at least one of them: `genres = horror OR genres = comedy` - `TO` is equivalent to `>= AND <=`. The expression `release_date 795484800 TO 972129600` translates to `release_date >= 795484800 AND release_date <= 972129600` -- `IN [valueA, valueB]` selects all documents whose specified field contains at least one of the specified values. The expression `genres IN [horror, comedy]` returns all documents whose `genre` is either `horror`, `comedy`, or both +- `IN [valueA, valueB]` selects all documents whose chosen field contains at least one of the specified values. The expression `genres IN [horror, comedy]` returns all documents whose `genres` includes either `horror`, `comedy`, or both - `EXIST` checks for the existence of a field. Fields with empty or null values still count as existing. The expression `release_date NOT EXIST` returns all documents without a `release_date` When creating an expression with a field name or value identical to a filter operator such as `AND` or `NOT`, you must wrap it in quotation marks: `title = "NOT" AND title = "AND"`. From df6d88ea980d6aae807778ae55cb33d449145a49 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 8 Sep 2022 13:25:47 +0200 Subject: [PATCH 4/8] filters: improve filter expression example --- learn/advanced/filtering_and_faceted_search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 060fbaa7ac..7c34ece84d 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -109,7 +109,7 @@ String expressions combine conditions using the following filter operators and p - `IN [valueA, valueB]` selects all documents whose chosen field contains at least one of the specified values. The expression `genres IN [horror, comedy]` returns all documents whose `genres` includes either `horror`, `comedy`, or both - `EXIST` checks for the existence of a field. Fields with empty or null values still count as existing. The expression `release_date NOT EXIST` returns all documents without a `release_date` -When creating an expression with a field name or value identical to a filter operator such as `AND` or `NOT`, you must wrap it in quotation marks: `title = "NOT" AND title = "AND"`. +When creating an expression with a field name or value identical to a filter operator such as `AND` or `NOT`, you must wrap it in quotation marks: `title = "NOT" OR title = "AND"`. ::: tip String expressions are read left to right. `NOT` takes precedence over `AND` and `AND` takes precedence over `OR`. You can use parentheses to ensure expressions are correctly parsed. From ec8780e0e1aa69a10967667c5f23cd8f546c75a2 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 8 Sep 2022 17:31:35 +0200 Subject: [PATCH 5/8] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Clémentine Urquizar - curqui --- learn/advanced/filtering_and_faceted_search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 7c34ece84d..fc077d0d9b 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -102,12 +102,12 @@ The [`GET` route of the search endpoint](/reference/api/search.md#search-in-an-i String expressions combine conditions using the following filter operators and parentheses: -- `NOT` returns all documents that do not satisfy a condition, including results missing the specified attribute. The expression `NOT genres = horror` returns all documents whose `genre` is not `horror` and documents missing a `genres` field +- `NOT` returns all documents that do not satisfy a condition, including results missing the specified attribute. The expression `NOT genres = horror` returns all documents whose `genres` do not contain `horror` and all documents missing a `genres` field - `AND` operates by connecting two conditions and only returns documents that satisfy both of them: `genres = horror AND director = 'Jordan Peele'` - `OR` connects two conditions and returns results that satisfy at least one of them: `genres = horror OR genres = comedy` - `TO` is equivalent to `>= AND <=`. The expression `release_date 795484800 TO 972129600` translates to `release_date >= 795484800 AND release_date <= 972129600` - `IN [valueA, valueB]` selects all documents whose chosen field contains at least one of the specified values. The expression `genres IN [horror, comedy]` returns all documents whose `genres` includes either `horror`, `comedy`, or both -- `EXIST` checks for the existence of a field. Fields with empty or null values still count as existing. The expression `release_date NOT EXIST` returns all documents without a `release_date` +- `EXISTS` checks for the existence of a field. Fields with empty or null values still count as existing. The expression `release_date NOT EXISTS` returns all documents without a `release_date` When creating an expression with a field name or value identical to a filter operator such as `AND` or `NOT`, you must wrap it in quotation marks: `title = "NOT" OR title = "AND"`. From 378881bad860e01d5c4d8dc03a89f36b01df8c1f Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 15 Sep 2022 14:16:54 +0200 Subject: [PATCH 6/8] filter: address SME feedback --- learn/advanced/filtering_and_faceted_search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index fc077d0d9b..4948d7cc10 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -102,11 +102,11 @@ The [`GET` route of the search endpoint](/reference/api/search.md#search-in-an-i String expressions combine conditions using the following filter operators and parentheses: -- `NOT` returns all documents that do not satisfy a condition, including results missing the specified attribute. The expression `NOT genres = horror` returns all documents whose `genres` do not contain `horror` and all documents missing a `genres` field +- `NOT` returns all documents that do not satisfy a condition. The expression `NOT genres = horror` returns all documents whose `genres` do not contain `horror` and all documents missing a `genres` field - `AND` operates by connecting two conditions and only returns documents that satisfy both of them: `genres = horror AND director = 'Jordan Peele'` - `OR` connects two conditions and returns results that satisfy at least one of them: `genres = horror OR genres = comedy` - `TO` is equivalent to `>= AND <=`. The expression `release_date 795484800 TO 972129600` translates to `release_date >= 795484800 AND release_date <= 972129600` -- `IN [valueA, valueB]` selects all documents whose chosen field contains at least one of the specified values. The expression `genres IN [horror, comedy]` returns all documents whose `genres` includes either `horror`, `comedy`, or both +- `IN [valueA, valueB, …, valueN]` selects all documents whose chosen field contains at least one of the specified values. The expression `genres IN [horror, comedy]` returns all documents whose `genres` includes either `horror`, `comedy`, or both - `EXISTS` checks for the existence of a field. Fields with empty or null values still count as existing. The expression `release_date NOT EXISTS` returns all documents without a `release_date` When creating an expression with a field name or value identical to a filter operator such as `AND` or `NOT`, you must wrap it in quotation marks: `title = "NOT" OR title = "AND"`. From bba66057e51d767f6bed09b57130e1a7573e6fa8 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 26 Sep 2022 14:55:54 +0200 Subject: [PATCH 7/8] Update reference/api/search.md Co-authored-by: Maryam <90181761+maryamsulemani97@users.noreply.github.com> --- reference/api/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/search.md b/reference/api/search.md index b161313397..90348576db 100644 --- a/reference/api/search.md +++ b/reference/api/search.md @@ -346,7 +346,7 @@ If you want your query to return only **two** documents, set `limit` to `2`: Uses filter expressions to refine search results. Attributes used as filter criteria must be added to the [`filterableAttributes` list](/reference/api/settings.md#filterable-attributes). -For more information on how to use filters and build filter expressions, [read our guide on filtering, faceted search and filter expressions](/learn/advanced/filtering_and_faceted_search.md). +For more information on how to use filters and build filter expressions, [read our guide on filtering, faceted search, and filter expressions](/learn/advanced/filtering_and_faceted_search.md). #### Example From 818abb0b794d5b89da7756d50aa14e779392e8e5 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 27 Sep 2022 13:17:28 +0200 Subject: [PATCH 8/8] filter expressions: clarify new `NOT` behaviour --- learn/advanced/filtering_and_faceted_search.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/learn/advanced/filtering_and_faceted_search.md b/learn/advanced/filtering_and_faceted_search.md index 4948d7cc10..5e8f003b33 100644 --- a/learn/advanced/filtering_and_faceted_search.md +++ b/learn/advanced/filtering_and_faceted_search.md @@ -224,6 +224,12 @@ You can use this filter when searching for `Planet of the Apes`: +`NOT director = "Tim Burton"` will include both documents that do not contain `"Tim Burton"` in its `director` field and documents without a `director` field. To return only documents that have a `director` field, expand the filter expression with the `EXISTS` operator: + +```SQL +rating >= 3 AND (NOT director = "Tim Burton" AND director EXISTS) +``` + ## Filtering with `_geoRadius` If your documents contain `_geo` data, you can use the `_geoRadius` built-in filter rule to filter results according to their geographic position.