Skip to content

Add _geo_list documentation #3479

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

Open
jhf wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add _geo_list documentation #3479

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
40 changes: 29 additions & 11 deletions learn/filtering_and_sorting/geosearch.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,9 @@ Meilisearch allows you to filter and sort results based on their geographic loca

## Preparing documents for location-based search

To start filtering documents based on their geographic location, you must make sure they contain a valid `_geo` or `_geojson` field. If you also want to sort documents geogeraphically, they must have a valid `_geo` field.
To start filtering documents based on their geographic location, you must make sure they contain a valid `_geo`, `_geojson`, or `_geo_list` field. If you also want to sort documents geographically, they must have a valid `_geo` or `_geo_list` field.

`_geo` and `_geojson` are reserved fields. If you include one of them in your documents, Meilisearch expects its value to conform to a specific format.
`_geo`, `_geojson`, and `_geo_list` are reserved fields. If you include any of them in your documents, Meilisearch expects their values to conform to a specific format.

When using JSON and NDJSON, `_geo` must contain an object with two keys: `lat` and `lng`. Both fields must contain either a floating point number or a string indicating, respectively, latitude and longitude:

Expand Down Expand Up @@ -52,16 +52,34 @@ Meilisearch does not support transmeridian shapes. If your document includes a t

**Meilisearch does not support polygons with holes**. If your polygon consists of an external ring and an inner empty space, Meilisearch ignores the hole and treats the polygon as a solid shape.

`_geo_list` must be a non-empty array of objects, each containing `lat` and `lng` keys. Use `_geo_list` when a single document represents multiple discrete locations, such as a company with several offices:

```json
{
…
"_geo_list": [
{ "lat": 48.8566, "lng": 2.3522 },
{ "lat": 45.4642, "lng": 9.1900 },
{ "lat": 41.9028, "lng": 12.4964 }
]
}
```

`null` values within the array are ignored and treated as if the point were absent.

<Note>
### Using `_geo` and `_geojson` together
### Using `_geo`, `_geojson`, and `_geo_list` together

`_geo`, `_geojson`, and `_geo_list` can coexist on the same document. `_geo_list` works with all three geo filter functions (`_geoRadius`, `_geoBoundingBox`, `_geoPolygon`) and with `_geoPoint` sorting.

If your application requires both sorting by distance to a point and filtering by shapes other than a circle or a rectangle, you will need to add both `_geo` and `_geojson` to your documents.
When filtering, a document matches if *any* point across all its geo fields falls within the specified area. When sorting with `_geoPoint`, Meilisearch uses the *closest* point from all geo fields.

When handling documents with both fields, Meilisearch:
When handling documents with multiple geo fields, Meilisearch:

- Ignores `_geojson` values when sorting
- Ignores `_geo` values when filtering with `_geoPolygon`
- Matches both `_geo` and `_geojson` values when filtering with `_geoRadius` and `_geoBoundingBox`
- Merges points from `_geo`, `_geojson`, and `_geo_list` when filtering with `_geoRadius` and `_geoBoundingBox`
- Merges points from `_geo` and `_geo_list` when sorting with `_geoPoint`
Comment on lines +75 to +82
Copy link

@coderabbitai coderabbitai bot Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Clarify sorting scope to avoid contradiction with _geojson exclusion.

Line 75 says _geoPoint uses the closest point from “all geo fields,” but Line 79/82 says _geojson is ignored for sorting. Please narrow Line 75 wording to sortable geo fields only.

Suggested wording fix 
-When sorting with `_geoPoint`, Meilisearch uses the *closest* point from all geo fields.
+When sorting with `_geoPoint`, Meilisearch uses the *closest* point from `_geo` and `_geo_list`.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
When filtering, a document matches if *any* point across all its geo fields falls within the specified area. When sorting with `_geoPoint`, Meilisearch uses the *closest* point from all geo fields.
When handling documents with both fields, Meilisearch:
When handling documents with multiple geo fields, Meilisearch:
- Ignores `_geojson` values when sorting
- Ignores `_geo` values when filtering with `_geoPolygon`
- Matches both `_geo` and `_geojson` values when filtering with `_geoRadius` and `_geoBoundingBox`
- Merges points from `_geo`, `_geojson`, and `_geo_list` when filtering with `_geoRadius` and `_geoBoundingBox`
- Merges points from `_geo` and `_geo_list` when sorting with `_geoPoint`
When filtering, a document matches if *any* point across all its geo fields falls within the specified area. When sorting with `_geoPoint`, Meilisearch uses the *closest* point from `_geo` and `_geo_list`.
When handling documents with multiple geo fields, Meilisearch:
- Ignores `_geojson` values when sorting
- Ignores `_geo` values when filtering with `_geoPolygon`
- Merges points from `_geo`, `_geojson`, and `_geo_list` when filtering with `_geoRadius` and `_geoBoundingBox`
- Merges points from `_geo` and `_geo_list` when sorting with `_geoPoint`
🧰 Tools
🪛 LanguageTool

[style] ~76-~76: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...e closest point from all geo fields. When handling documents with multiple geo fi...

(ENGLISH_WORD_REPEAT_BEGINNING_RULE)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@learn/filtering_and_sorting/geosearch.mdx` around lines 75 - 82, Update the
description of sorting with `_geoPoint` to restrict “all geo fields” to only
sortable geo fields by name; replace the phrase with something like “all
sortable geo fields (e.g., `_geo` and `_geo_list`, excluding `_geojson`)” so it
no longer contradicts the later note that `_geojson` is ignored for sorting —
change the sentence mentioning `_geoPoint` accordingly in the geosearch
documentation.

</Note>

### Examples
Expand Down Expand Up @@ -149,15 +167,15 @@ 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"
```

CSV files do not support the `_geojson` attribute.
CSV files do not support the `_geojson` or `_geo_list` attributes.

## Filtering results with `_geoRadius`, `_geoBoundingBox`, and `_geoPolygon`

You can use `_geo` and `_geojson` data to filter queries so you only receive results located within a given geographic area.
You can use `_geo`, `_geojson`, and `_geo_list` data to filter queries so you only receive results located within a given geographic area.

### Configuration

To filter results based on their location, you must add `_geo` or `_geojson` to the `filterableAttributes` list:
To filter results based on their location, you must add `_geo`, `_geojson`, or `_geo_list` to the `filterableAttributes` list:

<CodeSamplesGeosearchGuideFilterSettings1 />

Expand Down Expand Up @@ -256,12 +274,12 @@ It is also possible to combine `_geoRadius`, `_geoBoundingBox`, and `_geoPolygon

### Configuration

Before using geosearch for sorting, you must add the `_geo` attribute to the [`sortableAttributes` list](/learn/filtering_and_sorting/sort_search_results):
Before using geosearch for sorting, you must add the `_geo` or `_geo_list` attribute to the [`sortableAttributes` list](/learn/filtering_and_sorting/sort_search_results):

<CodeSamplesGeosearchGuideSortSettings1 />

<Danger>
It is not possible to sort documents based on the `_geojson` attribute.
It is not possible to sort documents based on the `_geojson` attribute. Use `_geo` or `_geo_list` instead.
</Danger>

### Usage
Expand Down
2 changes: 1 addition & 1 deletion learn/getting_started/documents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ If a field contains an object, Meilisearch flattens it during indexing using dot
With [ranking rules](/learn/relevancy/ranking_rules), you can decide which fields are more relevant than others. For example, you may decide recent movies should be more relevant than older ones. You can also designate certain fields as displayed or searchable.

<Note>
Some features require Meilisearch to reserve attributes. For example, to use [geosearch functionality](/learn/filtering_and_sorting/geosearch) your documents must include a `_geo` field.
Some features require Meilisearch to reserve attributes. For example, to use [geosearch functionality](/learn/filtering_and_sorting/geosearch) your documents must include a `_geo`, `_geojson`, or `_geo_list` field.

Reserved attributes are always prefixed with an underscore (`_`).
</Note>
Expand Down