This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« Geo-distance query Geo-polygon query »
Elastic Docs ›Elasticsearch Guide [master] ›Query DSL ›Geo queries

Geo-grid query

edit

Geo-grid query

edit

Matches geo_point and geo_shape values that intersect a grid cell from a GeoGrid aggregation.

The query is designed to match the documents that fall inside a bucket of a geogrid aggregation by providing the key of the bucket. For geohash and geotile grids, the query can be used for geo_point and geo_shape fields. For geo_hex grid, it can only be used for geo_point fields.

Example

edit

Assume the following the following documents are indexed:

resp = client.indices.create(
    index="my_locations",
    mappings={
        "properties": {
            "location": {
                "type": "geo_point"
            }
        }
    },
)
print(resp)

resp1 = client.index(
    index="my_locations",
    id="1",
    refresh=True,
    document={
        "location": "POINT(4.912350 52.374081)",
        "city": "Amsterdam",
        "name": "NEMO Science Museum"
    },
)
print(resp1)

resp2 = client.index(
    index="my_locations",
    id="2",
    refresh=True,
    document={
        "location": "POINT(4.405200 51.222900)",
        "city": "Antwerp",
        "name": "Letterenhuis"
    },
)
print(resp2)

resp3 = client.index(
    index="my_locations",
    id="3",
    refresh=True,
    document={
        "location": "POINT(2.336389 48.861111)",
        "city": "Paris",
        "name": "Musée du Louvre"
    },
)
print(resp3)
response = client.indices.create(
  index: 'my_locations',
  body: {
    mappings: {
      properties: {
        location: {
          type: 'geo_point'
        }
      }
    }
  }
)
puts response

response = client.index(
  index: 'my_locations',
  id: 1,
  refresh: true,
  body: {
    location: 'POINT(4.912350 52.374081)',
    city: 'Amsterdam',
    name: 'NEMO Science Museum'
  }
)
puts response

response = client.index(
  index: 'my_locations',
  id: 2,
  refresh: true,
  body: {
    location: 'POINT(4.405200 51.222900)',
    city: 'Antwerp',
    name: 'Letterenhuis'
  }
)
puts response

response = client.index(
  index: 'my_locations',
  id: 3,
  refresh: true,
  body: {
    location: 'POINT(2.336389 48.861111)',
    city: 'Paris',
    name: 'Musée du Louvre'
  }
)
puts response
const response = await client.indices.create({
  index: "my_locations",
  mappings: {
    properties: {
      location: {
        type: "geo_point",
      },
    },
  },
});
console.log(response);

const response1 = await client.index({
  index: "my_locations",
  id: 1,
  refresh: "true",
  document: {
    location: "POINT(4.912350 52.374081)",
    city: "Amsterdam",
    name: "NEMO Science Museum",
  },
});
console.log(response1);

const response2 = await client.index({
  index: "my_locations",
  id: 2,
  refresh: "true",
  document: {
    location: "POINT(4.405200 51.222900)",
    city: "Antwerp",
    name: "Letterenhuis",
  },
});
console.log(response2);

const response3 = await client.index({
  index: "my_locations",
  id: 3,
  refresh: "true",
  document: {
    location: "POINT(2.336389 48.861111)",
    city: "Paris",
    name: "Musée du Louvre",
  },
});
console.log(response3);
PUT /my_locations
{
  "mappings": {
    "properties": {
      "location": {
        "type": "geo_point"
      }
    }
  }
}

PUT /my_locations/_doc/1?refresh
{
  "location" : "POINT(4.912350 52.374081)",
  "city": "Amsterdam",
  "name": "NEMO Science Museum"
}

PUT /my_locations/_doc/2?refresh
{
  "location" : "POINT(4.405200 51.222900)",
  "city": "Antwerp",
  "name": "Letterenhuis"
}

PUT /my_locations/_doc/3?refresh
{
  "location" : "POINT(2.336389 48.861111)",
  "city": "Paris",
  "name": "Musée du Louvre"
}

geohash grid

edit

Using a geohash_grid aggregation, it is possible to group documents depending on their geohash value:

resp = client.search(
    index="my_locations",
    size=0,
    aggs={
        "grouped": {
            "geohash_grid": {
                "field": "location",
                "precision": 2
            }
        }
    },
)
print(resp)
response = client.search(
  index: 'my_locations',
  body: {
    size: 0,
    aggregations: {
      grouped: {
        geohash_grid: {
          field: 'location',
          precision: 2
        }
      }
    }
  }
)
puts response
const response = await client.search({
  index: "my_locations",
  size: 0,
  aggs: {
    grouped: {
      geohash_grid: {
        field: "location",
        precision: 2,
      },
    },
  },
});
console.log(response);
GET /my_locations/_search
{
  "size" : 0,
  "aggs" : {
     "grouped" : {
        "geohash_grid" : {
           "field" : "location",
           "precision" : 2
        }
     }
  }
}
{
  "took" : 10,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 3,
      "relation" : "eq"
    },
    "max_score" : null,
    "hits" : [ ]
  },
  "aggregations" : {
    "grouped" : {
      "buckets" : [
        {
          "key" : "u1",
          "doc_count" : 2
        },
        {
          "key" : "u0",
          "doc_count" : 1
        }
      ]
    }
  }
}

We can extract the documents on one of those buckets by executing a geo_grid query using the bucket key with the following syntax:

resp = client.search(
    index="my_locations",
    query={
        "geo_grid": {
            "location": {
                "geohash": "u0"
            }
        }
    },
)
print(resp)
const response = await client.search({
  index: "my_locations",
  query: {
    geo_grid: {
      location: {
        geohash: "u0",
      },
    },
  },
});
console.log(response);
GET /my_locations/_search
{
  "query": {
    "geo_grid" :{
      "location" : {
        "geohash" : "u0"
      }
    }
  }
}
{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my_locations",
        "_id" : "3",
        "_score" : 1.0,
        "_source" : {
          "location" : "POINT(2.336389 48.861111)",
          "city" : "Paris",
          "name" : "Musée du Louvre"
        }
      }
    ]
  }
}

geotile grid

edit

Using a geotile_grid aggregation, it is possible to group documents depending on their geotile value:

resp = client.search(
    index="my_locations",
    size=0,
    aggs={
        "grouped": {
            "geotile_grid": {
                "field": "location",
                "precision": 6
            }
        }
    },
)
print(resp)
response = client.search(
  index: 'my_locations',
  body: {
    size: 0,
    aggregations: {
      grouped: {
        geotile_grid: {
          field: 'location',
          precision: 6
        }
      }
    }
  }
)
puts response
const response = await client.search({
  index: "my_locations",
  size: 0,
  aggs: {
    grouped: {
      geotile_grid: {
        field: "location",
        precision: 6,
      },
    },
  },
});
console.log(response);
GET /my_locations/_search
{
  "size" : 0,
  "aggs" : {
     "grouped" : {
        "geotile_grid" : {
           "field" : "location",
           "precision" : 6
        }
     }
  }
}
{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 3,
      "relation" : "eq"
    },
    "max_score" : null,
    "hits" : [ ]
  },
  "aggregations" : {
    "grouped" : {
      "buckets" : [
        {
          "key" : "6/32/21",
          "doc_count" : 2
        },
        {
          "key" : "6/32/22",
          "doc_count" : 1
        }
      ]
    }
  }
}

We can extract the documents on one of those buckets by executing a geo_grid query using the bucket key with the following syntax:

resp = client.search(
    index="my_locations",
    query={
        "geo_grid": {
            "location": {
                "geotile": "6/32/22"
            }
        }
    },
)
print(resp)
const response = await client.search({
  index: "my_locations",
  query: {
    geo_grid: {
      location: {
        geotile: "6/32/22",
      },
    },
  },
});
console.log(response);
GET /my_locations/_search
{
  "query": {
    "geo_grid" :{
      "location" : {
        "geotile" : "6/32/22"
      }
    }
  }
}
{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my_locations",
        "_id" : "3",
        "_score" : 1.0,
        "_source" : {
          "location" : "POINT(2.336389 48.861111)",
          "city" : "Paris",
          "name" : "Musée du Louvre"
        }
      }
    ]
  }
}

geohex grid

edit

Using a geohex_grid aggregation, it is possible to group documents depending on their geohex value:

resp = client.search(
    index="my_locations",
    size=0,
    aggs={
        "grouped": {
            "geohex_grid": {
                "field": "location",
                "precision": 1
            }
        }
    },
)
print(resp)
const response = await client.search({
  index: "my_locations",
  size: 0,
  aggs: {
    grouped: {
      geohex_grid: {
        field: "location",
        precision: 1,
      },
    },
  },
});
console.log(response);
GET /my_locations/_search
{
  "size" : 0,
  "aggs" : {
     "grouped" : {
        "geohex_grid" : {
           "field" : "location",
           "precision" : 1
        }
     }
  }
}
{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 3,
      "relation" : "eq"
    },
    "max_score" : null,
    "hits" : [ ]
  },
  "aggregations" : {
    "grouped" : {
      "buckets" : [
        {
          "key" : "81197ffffffffff",
          "doc_count" : 2
        },
        {
          "key" : "811fbffffffffff",
          "doc_count" : 1
        }
      ]
    }
  }
}

We can extract the documents on one of those buckets by executing a geo_grid query using the bucket key with the following syntax:

resp = client.search(
    index="my_locations",
    query={
        "geo_grid": {
            "location": {
                "geohex": "811fbffffffffff"
            }
        }
    },
)
print(resp)
const response = await client.search({
  index: "my_locations",
  query: {
    geo_grid: {
      location: {
        geohex: "811fbffffffffff",
      },
    },
  },
});
console.log(response);
GET /my_locations/_search
{
  "query": {
    "geo_grid" :{
      "location" : {
        "geohex" : "811fbffffffffff"
      }
    }
  }
}
{
  "took" : 26,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 1,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "my_locations",
        "_id" : "3",
        "_score" : 1.0,
        "_source" : {
          "location" : "POINT(2.336389 48.861111)",
          "city" : "Paris",
          "name" : "Musée du Louvre"
        }
      }
    ]
  }
}
« Geo-distance query Geo-polygon query »