Skip to main content

Spatial filters

info

High-precision geospatial filters are available as a preview feature. They can offer a higher level of precision than the spatial filters described on this page. For more information, see High-precision geospatial filters

Apache Druid supports two query languages: Druid SQL and native queries. This document describes a feature that is only available in the native language.

Apache Druid supports filtering spatially indexed columns based on an origin and a bound.

This topic explains how to ingest and query spatial filters. For information on other filters supported by Druid, see Query filters.

Spatial indexing

Spatial indexing refers to ingesting data of a spatial data type, such as geometry or geography, into Druid.

Spatial dimensions are string columns that contain coordinates separated by a comma. In the ingestion spec, you configure spatial dimensions in the dimensionsSpec object of the dataSchema component.

You can provide spatial dimensions in any of the data formats supported by Druid. The following example shows an ingestion spec with a spatial dimension named coordinates, which is constructed from the input fields x and y:

{
"type": "hadoop",
"dataSchema": {
"dataSource": "DatasourceName",
"parser": {
"type": "string",
"parseSpec": {
"format": "json",
"timestampSpec": {
"column": "timestamp",
"format": "auto"
},
"dimensionsSpec": {
"dimensions": [
{
"type": "double",
"name": "x"
},
{
"type": "double",
"name": "y"
}
],
"spatialDimensions": [
{
"dimName": "coordinates",
"dims": [
"x",
"y"
]
}
]
}
}
}
}
}

Each spatial dimension object in the spatialDimensions array is defined by the following fields:

PropertyDescriptionRequired
dimNameThe name of a spatial dimension. You can construct a spatial dimension from other dimensions or it may already exist as part of an event. If a spatial dimension already exists, it must be an array of coordinate values.yes
dimsThe list of dimension names that comprise the spatial dimension.no

For information on how to use the ingestion spec to configure ingestion, see Ingestion spec reference. For general information on loading data in Druid, see Ingestion.

Spatial filters

A filter is a JSON object indicating which rows of data should be included in the computation for a query. You can filter on spatial structures, such as rectangles and polygons, using the spatial filter.

Spatial filters have the following structure:

"filter": {
"type": "spatial",
"dimension": <name_of_spatial_dimension>,
"bound": <bound_type>
}

The following example shows a spatial filter with a rectangular bound type:

"filter" : {
"type": "spatial",
"dimension": "spatialDim",
"bound": {
"type": "rectangular",
"minCoords": [10.0, 20.0],
"maxCoords": [30.0, 40.0]
}

The order of the dimension coordinates in the spatial filter must be equal to the order of the dimension coordinates in the spatialDimensions array.

Bound types

The bound property of the spatial filter object lets you filter on ranges of dimension values. You can define rectangular, radius, and polygon filter bounds.

Rectangular

The rectangular bound has the following elements:

PropertyDescriptionRequired
minCoordsThe list of minimum dimension coordinates in the form [x, y]yes
maxCoordsThe list of maximum dimension coordinates in the form [x, y]yes

Radius

The radius bound has the following elements:

PropertyDescriptionRequired
coordsCenter coordinates in the form [x, y]yes
radiusThe float radius value according to specified unityes
radiusUnitString value of radius unit in lowercase, default value is 'euclidean'. Allowed units are euclidean, meters, miles, kilometers.no

Polygon

The polygon bound has the following elements:

PropertyDescriptionRequired
abscissaHorizontal coordinates for the corners of the polygonyes
ordinateVertical coordinates for the corners of the polygonyes