From 1bd6588d473b0b0e35d4f4e164317206fe81e069 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Thu, 27 Apr 2023 14:59:37 +0200 Subject: [PATCH 1/5] Introduce the spec of the IS EMPTY filter --- text/0118-search-api.md | 42 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index f9a4707e..b334ebd2 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -159,6 +159,12 @@ The grammar for the value of a filterable attribute is the same as the grammar f - In: * `attribute IN[value, value, etc.]` * `attribute NOT IN[value, value, etc.]` +- IS NULL: + * `attribute IS NULL` + * `attribute IS NOT NULL` +- IS EMPTY: + * `attribute IS EMPTY` + * `attribute IS NOT EMPTY` - AND: `filter AND filter` - OR: `filter OR filter` - NOT: `NOT filter` @@ -374,6 +380,42 @@ is equivalent to: } ``` +###### 3.1.2.1.13 Is Empty + +The `IS EMPTY` operator selects the documents for which the filterable attribute exists and is empty. If the attribute doesn't exists then it is not empty and the document will not be returned. It is a postfix operator that takes an attribute name as argument. + +The negated form of `IS EMPTY` can be written in two ways: +``` +attribute IS NOT EMPTY +NOT attribute IS EMPTY +``` +Both forms are equivalent. They select the documents for which the attribute is not empty. + +For example, with the documents: +```json +[{ + "id": 0, + "colour": [] +}, +{ + "id": 1, + "colour": null +}, +{ + "id": 2, + "colour": "" +}, +{ + "id": 3, + "colour": {} +}, +{ + "id": 4 +}] +``` +Then the filter `colour IS EMPTY` selects the document ids `[0,2,3]` while the filter `colour IS NOT EMPTY` or `NOT colour IS EMPTY` selects the document ids `[1,4]`. +``` + #### 3.1.3. `sort` - Type: Array of String (POST) | String (GET) From 8787bb13396b5e0c820a8df961477668e6ee557f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Thu, 27 Apr 2023 15:07:53 +0200 Subject: [PATCH 2/5] Introduce the spec of the IS NULL filter --- text/0118-search-api.md | 40 +++++++++++++++++++++++++++++++++++++--- 1 file changed, 37 insertions(+), 3 deletions(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index b334ebd2..ba9b7e98 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -159,12 +159,12 @@ The grammar for the value of a filterable attribute is the same as the grammar f - In: * `attribute IN[value, value, etc.]` * `attribute NOT IN[value, value, etc.]` -- IS NULL: - * `attribute IS NULL` - * `attribute IS NOT NULL` - IS EMPTY: * `attribute IS EMPTY` * `attribute IS NOT EMPTY` +- IS NULL: + * `attribute IS NULL` + * `attribute IS NOT NULL` - AND: `filter AND filter` - OR: `filter OR filter` - NOT: `NOT filter` @@ -414,7 +414,41 @@ For example, with the documents: }] ``` Then the filter `colour IS EMPTY` selects the document ids `[0,2,3]` while the filter `colour IS NOT EMPTY` or `NOT colour IS EMPTY` selects the document ids `[1,4]`. + +###### 3.1.2.1.13 Is Null + +The `IS NULL` operator selects the documents for which the filterable attribute exists and is `null`. If the attribute doesn't exists then it is not `null` and the document will not be returned. It is a postfix operator that takes an attribute name as argument. + +The negated form of `IS NULL` can be written in two ways: +``` +attribute IS NOT NULL +NOT attribute IS NULL +``` +Both forms are equivalent. They select the documents for which the attribute is not `null`. + +For example, with the documents: +```json +[{ + "id": 0, + "colour": [] +}, +{ + "id": 1, + "colour": null +}, +{ + "id": 2, + "colour": "" +}, +{ + "id": 3, + "colour": {} +}, +{ + "id": 4 +}] ``` +Then the filter `colour IS NULL` selects the document ids `[1]` while the filter `colour IS NOT NULL` or `NOT colour IS NULL` selects the document ids `[0,2,3,4]`. #### 3.1.3. `sort` From ea4b75791b0b4b833bde338dbd8c01d2a4f9ba49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Tue, 2 May 2023 10:34:23 +0200 Subject: [PATCH 3/5] Fix suggestions --- text/0118-search-api.md | 54 +++++++++++++++++++++++------------------ 1 file changed, 30 insertions(+), 24 deletions(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index ba9b7e98..2f969838 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -304,7 +304,7 @@ size = 0 OR NOT size = 2 -> selects [0,1] NOT (NOT size = 0) -> selects [0] ``` -###### 3.1.2.1.10 Exists +###### 3.1.2.1.10 EXISTS The `EXISTS` operator selects the documents for which the filterable attribute exists, even if its value is `null` or an empty array. It is a postfix operator that takes an attribute name as argument. @@ -331,7 +331,7 @@ For example, with the documents: ``` Then the filter `colour EXISTS` selects the document ids `[0,1]` while the filter `colour NOT EXISTS` or `NOT colour EXISTS` selects the document ids `[2]`. -###### 3.1.2.1.11 In +###### 3.1.2.1.11 IN The `IN[..]` operator is a more concise way to combine equality operators. It is a postfix operator that takes an attribute name on the left hand side and an array of values on the right hand side. An array of value is a comma-separated list of values delimited by square brackets. @@ -360,27 +360,7 @@ attribute != value1 AND attribute != value2 AND ... - The `_geoRadius` operator selects the documents whose geographical coordinates fall within a certain range of a given coordinate. See [GeoSearch](0059-geo-search.md) for more information. - The `_geoBoundingBox` operator selects the documents whose geographical coordinates fall within a square described by the given coordinates. See [GeoSearch](0059-geo-search.md) for more information. -##### 3.1.2.2. Array Syntax - -The array syntax is an alternative way to combine different filters with `OR` and `AND` operators. - -- Elements in the outer array are connected by `AND` operators -- Elements in the inner arrays are connected by `OR` operators - -Example: -```json -{ - "filter": [["genres = Comedy", "genres = Romance"], "director = 'Mati Diop'"] -} -``` -is equivalent to: -```json -{ - "filter": "(genres = Comedy OR genres = Romance) AND (director = 'Mati Diop')" -} -``` - -###### 3.1.2.1.13 Is Empty +###### 3.1.2.1.13 IS EMPTY The `IS EMPTY` operator selects the documents for which the filterable attribute exists and is empty. If the attribute doesn't exists then it is not empty and the document will not be returned. It is a postfix operator that takes an attribute name as argument. @@ -391,6 +371,11 @@ NOT attribute IS EMPTY ``` Both forms are equivalent. They select the documents for which the attribute is not empty. +Here is the list of JSON values that are considered empty: + - `""` + - `[]` + - `{}` + For example, with the documents: ```json [{ @@ -415,7 +400,7 @@ For example, with the documents: ``` Then the filter `colour IS EMPTY` selects the document ids `[0,2,3]` while the filter `colour IS NOT EMPTY` or `NOT colour IS EMPTY` selects the document ids `[1,4]`. -###### 3.1.2.1.13 Is Null +###### 3.1.2.1.13 IS NULL The `IS NULL` operator selects the documents for which the filterable attribute exists and is `null`. If the attribute doesn't exists then it is not `null` and the document will not be returned. It is a postfix operator that takes an attribute name as argument. @@ -450,6 +435,27 @@ For example, with the documents: ``` Then the filter `colour IS NULL` selects the document ids `[1]` while the filter `colour IS NOT NULL` or `NOT colour IS NULL` selects the document ids `[0,2,3,4]`. + +##### 3.1.2.2. Array Syntax + +The array syntax is an alternative way to combine different filters with `OR` and `AND` operators. + +- Elements in the outer array are connected by `AND` operators +- Elements in the inner arrays are connected by `OR` operators + +Example: +```json +{ + "filter": [["genres = Comedy", "genres = Romance"], "director = 'Mati Diop'"] +} +``` +is equivalent to: +```json +{ + "filter": "(genres = Comedy OR genres = Romance) AND (director = 'Mati Diop')" +} +``` + #### 3.1.3. `sort` - Type: Array of String (POST) | String (GET) From afab9b3a37873e7007b8ce613a1ca221cf565e00 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Tue, 2 May 2023 13:46:12 +0200 Subject: [PATCH 4/5] Uppercase the IN operator Co-authored-by: Guillaume Mourier --- text/0118-search-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index 2f969838..f800c571 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -156,7 +156,7 @@ The grammar for the value of a filterable attribute is the same as the grammar f - Exists: * `attribute EXISTS` * `attribute NOT EXISTS` -- In: +- IN: * `attribute IN[value, value, etc.]` * `attribute NOT IN[value, value, etc.]` - IS EMPTY: From 57c42f4ac65c79df98ca25a4a98fa421404acf0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20Renault?= Date: Tue, 2 May 2023 13:46:49 +0200 Subject: [PATCH 5/5] Fix a title number issue Co-authored-by: Guillaume Mourier --- text/0118-search-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0118-search-api.md b/text/0118-search-api.md index f800c571..0b3ca2c5 100644 --- a/text/0118-search-api.md +++ b/text/0118-search-api.md @@ -360,7 +360,7 @@ attribute != value1 AND attribute != value2 AND ... - The `_geoRadius` operator selects the documents whose geographical coordinates fall within a certain range of a given coordinate. See [GeoSearch](0059-geo-search.md) for more information. - The `_geoBoundingBox` operator selects the documents whose geographical coordinates fall within a square described by the given coordinates. See [GeoSearch](0059-geo-search.md) for more information. -###### 3.1.2.1.13 IS EMPTY +###### 3.1.2.1.12 IS EMPTY The `IS EMPTY` operator selects the documents for which the filterable attribute exists and is empty. If the attribute doesn't exists then it is not empty and the document will not be returned. It is a postfix operator that takes an attribute name as argument.