v1.1: Add new filter rule _geoBoundingBox

.code-samples.meilisearch.yaml

@@ -693,6 +693,11 @@ geosearch_guide_filter_usage_2: |-
     -X POST 'http://localhost:7700/indexes/restaurants/search' \
     -H 'Content-type:application/json' \
     --data-binary '{ "filter": "_geoRadius(45.472735, 9.184019, 2000) AND type = pizza" }'
+geosearch_guide_filter_usage_3: |-
+  curl \
+    -X POST 'http://localhost:7700/indexes/restaurants/search' \
+    -H 'Content-type:application/json' \
+    --data-binary '{ "filter": "_geoBoundingBox([45.494181, 9.214024], [45.449484, 9.179175])" }'
 geosearch_guide_sort_settings_1: |-
   curl \
     -X PUT 'http://localhost:7700/indexes/restaurants/settings/sortable-attributes' \

.vuepress/public/sample-template.yaml

@@ -102,6 +102,7 @@ search_parameter_guide_sort_1: |-
 geosearch_guide_filter_settings_1: |-
 geosearch_guide_filter_usage_1: |-
 geosearch_guide_filter_usage_2: |-
+geosearch_guide_filter_usage_3: |-
 geosearch_guide_sort_settings_1: |-
 geosearch_guide_sort_usage_1: |-
 geosearch_guide_sort_usage_2: |-

learn/advanced/filtering_and_faceted_search.md

@@ -342,23 +342,13 @@ If you only want recent `Planet of the Apes` movies that weren't directed by `Ti
 release_date > 1577884550 AND (NOT director = "Tim Burton" AND director EXISTS)
 ```
 
-### Filtering with `_geoRadius`
+### Filtering by geographic location
 
-If your documents contain `_geo` data, you can use the `_geoRadius` built-in filter rule to filter results according to their geographic position.
-
-`_geoRadius` establishes a circular area based on a central point and a radius. Results beyond this area will be excluded from your search. This filter rule requires three parameters: `lat`, `lng` and `distance_in_meters`.
-
-```
-_geoRadius(lat, lng, distance_in_meters)
-```
-
-`lat` and `lng` must be floating point numbers indicating a geographic position. `distance_in_meters` must be an integer indicating the radius covered by the `_geoRadius` filter.
-
-When using a <a id="downloadRestaurants" href="/restaurants.json" download="restaurants.json"> dataset of restaurants</a> containing geopositioning data, we can filter our search so it only includes places within two kilometers of our location:
+If your documents contain `_geo` data, you can filter results according to their geographic position using one of our built-in geosearch filter rules:
 
 <CodeSamples id="geosearch_guide_filter_usage_1" />
 
-[You can read more about filtering results with `_geoRadius` in our geosearch guide.](/learn/advanced/geosearch.md#filtering-results-with-georadius)
+[Read more about filtering results with `_geoRadius` and `_geoBoundingBox` in our geosearch guide.](/learn/advanced/geosearch.md#filtering-results-with-georadius-and-geoboundingbox)
 
 ### Filtering by nested fields
 

learn/advanced/geosearch.md

@@ -109,45 +109,55 @@ If your dataset is formatted as CSV, the file header must have a `_geo` column.
 "3", "Artico Gelateria Tradizionale", "Via Dogana, 1, 20123 Milan, Italy", "ice cream", 10, "48.8826517,2.3352748"
 ```
 
-## Filtering results with `_geoRadius`
+## Filtering results with `_geoRadius` and `_geoBoundingBox`
 
-You can use `_geo` data to filter queries and make sure you only receive results located within a certain geographic area.
+You can use `_geo` data to filter queries so you only receive results located within a given geographic area.
 
 ### Configuration
 
 In order to filter results based on their location, you must add the `_geo` attribute to the `filterableAttributes` list:
 
 <CodeSamples id="geosearch_guide_filter_settings_1" />
 
-Note that Meilisearch will rebuild your index whenever you update `filterableAttributes`. Depending on the size of your dataset, this might take a considerable amount of time.
+Meilisearch will rebuild your index whenever you update `filterableAttributes`. Depending on the size of your dataset, this might take a considerable amount of time.
 
 [You can read more about configuring `filterableAttributes` in our dedicated filtering guide.](/learn/advanced/filtering_and_faceted_search.md#configuring-filters)
 
 ### Usage
 
-First, ensure your documents contain valid geolocation data and that you have added the `_geo` attribute to the `filterableAttributes` list. Then, you can use the [`filter` search parameter](/reference/api/search.md#filter) along with `_geoRadius`, a special filter rule, to ensure Meilisearch only returns results located within a specific geographic area.
+Use the [`filter` search parameter](/reference/api/search.md#filter) along with `_geoRadius` or `_geoBoundingBox`. These are special filter rules that ensure Meilisearch only returns results located within a specific geographic area.
 
-`_geoRadius` establishes a circular area based on a central point and a radius. Results beyond this area will be excluded from your search. This filter rule requires three parameters: `lat`, `lng` and `distance_in_meters`.
+### `_geoRadius`
+
+`_geoRadius` establishes a circular area based on a central point and a radius. This filter rule requires three parameters: `lat`, `lng` and `distance_in_meters`.
 
 ```
 _geoRadius(lat, lng, distance_in_meters)
 ```
 
-`lat` and `lng` must be floating point numbers indicating a geographic position. `distance_in_meters` must be an integer indicating the radius covered by the `_geoRadius` filter. If any of these three parameters are invalid or missing, Meilisearch will return an [`invalid_search_filter`](/reference/errors/error_codes.md#invalid-search-filter) error.
+`lat` and `lng` must be floating point numbers indicating a geographic position. `distance_in_meters` must be an integer indicating the radius covered by the `_geoRadius` filter.
 
-[You can read more about using `filter` in our dedicated guide.](/learn/advanced/filtering_and_faceted_search.md#using-filters)
+### `_geoBoundingBox`
 
-::: warning
-`_geo`, `_geoDistance`, and `_geoPoint` are not valid filter rules. Trying to use any of them with the `filter` search parameter will result in an [`invalid_search_filter`](/reference/errors/error_codes.md#invalid-search-filter) error.
-:::
+`_geoBoundingBox` establishes a rectangular area based on the coordinates for its top right and bottom left corners. This filter rule requires two arrays:
+
+```
+_geoBoundingBox([{lat}, {lng}], [{lat}, {lng}])
+```
+
+`lat` and `lng` must be floating point numbers indicating a geographic position. The first array indicates the geographic coordinates of the top right corner of the rectangular area. The second array indicates the coordinates of the bottom left corner of the rectangular area.
 
 ### Examples
 
-`_geoRadius` works like any other filter rule. Using our <a id="downloadRestaurants" href="/restaurants.json" download="restaurants.json">example dataset</a>, we can search for places to eat near the center of Milan:
+Using our <a id="downloadRestaurants" href="/restaurants.json" download="restaurants.json">example dataset</a>, we can search for places to eat near the center of Milan with `_geoRadius`:
 
 <CodeSamples id="geosearch_guide_filter_usage_1" />
 
-The results should look like this:
+We also make a similar query using `_geoBoundingBox`:
+
+<CodeSamples id="geosearch_guide_filter_usage_3" />
+
+In both cases, the results should look like this:
 
 ```json
 [
@@ -176,12 +186,10 @@ The results should look like this:
 ]
 ```
 
-It is also possible to use `_geoRadius` together with other filters. We can narrow down our previous search so it only includes pizzerias:
+It is also possible to combine `_geoRadius` and `_geoBoundingBox` with other filters. We can narrow down our previous search so it only includes pizzerias:
 
 <CodeSamples id="geosearch_guide_filter_usage_2" />
 
-The above command will only work if you have previously added `type` to `filterableAttributes`.
-
 ```json
 [
   {
@@ -198,6 +206,12 @@ The above command will only work if you have previously added `type` to `filtera
 ]
 ```
 
+The above command will only work if you have previously added `type` to `filterableAttributes`.
+
+::: warning
+`_geo`, `_geoDistance`, and `_geoPoint` are not valid filter rules. Trying to use any of them with the `filter` search parameter will result in an [`invalid_search_filter`](/reference/errors/error_codes.md#invalid-search-filter) error.
+:::
+
 ## Sorting results with `_geoPoint`
 
 You can use `_geo` data to sort results based on their distance from a specific location.

reference/api/search.md

@@ -453,11 +453,14 @@ You can then use the filter in a search query:
 
 <CodeSamples id="faceted_search_walkthrough_filter_1" />
 
-#### Filtering results with `_geoRadius`
+#### Filtering results with `_geoRadius` and `_geoBoundingBox`
 
-If your documents contain `_geo` data, you can use the `_geoRadius` built-in filter rule to filter results according to their geographic position.
+If your documents contain `_geo` data, you can use the `_geoRadius` and `_geoBoundingBox` built-in filter rules to filter results according to their geographic position.
 
-`_geoRadius` establishes a circular area based on a central point and a radius. Results beyond this area will be excluded from your search. This filter rule requires three parameters: `lat`, `lng` and `distance_in_meters`.
+:::: tabs
+
+::: tab _geoRadius
+`_geoRadius` establishes a circular area based on a central point and a radius. This filter rule requires three parameters: `lat`, `lng` and `distance_in_meters`.
 
 ```json
 _geoRadius(lat, lng, distance_in_meters)
@@ -466,6 +469,25 @@ _geoRadius(lat, lng, distance_in_meters)
 `lat` and `lng` should be geographic coordinates expressed as floating point numbers. `distance_in_meters` indicates the radius of the area within which you want your results and should be an integer.
 
 <CodeSamples id="geosearch_guide_filter_usage_1" />
+:::
+
+::: tab _geoBoundingBox
+`_geoBoundingBox` establishes a rectangular area based on the coordinates for its top right and bottom left corners. This filter rule requires two arrays of geographic coordinates:
+
+```
+_geoBoundingBox([{lat}, {lng}], [{lat}, {lng}])
+```
+
+`lat` and `lng` should be geographic coordinates expressed as floating point numbers. The first array indicates the top right corner and the second array indicates the bottom left corner of the bounding box.
+
+<CodeSamples id="geosearch_guide_filter_usage_3" />
+
+Meilisearch will throw an error if the top right corner is under the bottom left corner.
+
+:::
+::::
+
+If any parameters are invalid or missing, Meilisearch returns an [`invalid_search_filter`](/reference/errors/error_codes.md#invalid-search-filter) error.
 
 ### Facets
 

reference/errors/error_codes.md

@@ -243,7 +243,7 @@ This error occurs if:
 
 - The syntax for the [`sort`](/reference/api/search.md#sort) parameter is invalid
 - The attribute used for sorting is not defined in the [`sortableAttributes`](/reference/api/settings.md#sortable-attributes) list or the `sort` ranking rule is missing from the settings
-- A reserved keyword like `_geo`, `_geoDistance`, or `_geoPoint` is used as a filter
+- A reserved keyword like `_geo`, `_geoDistance`, `_geoRadius`, or `_geoBoundingBox` is used as a filter
 
 ## `invalid_settings_displayed_attributes`
 
@@ -272,7 +272,7 @@ This error occurs if:
 - The [settings payload](/reference/api/settings.md#body) has an invalid format
 - A non-existent ranking rule is specified
 - A custom ranking rule is malformed
-- A reserved keyword like `_geo`, `_geoDistance`, or `_geoPoint` is used as a custom ranking rule
+- A reserved keyword like `_geo`, `_geoDistance`, `_geoRadius`, `_geoBoundingBox`, or `_geoPoint` is used as a custom ranking rule
 
 ## `invalid_settings_searchable_attributes`