Spatial filters

info

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:

Property	Description	Required
dimName	The 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
dims	The 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:

Property	Description	Required
minCoords	The list of minimum dimension coordinates in the form [x, y]	yes
maxCoords	The list of maximum dimension coordinates in the form [x, y]	yes

Radius

The radius bound has the following elements:

Property	Description	Required
coords	Center coordinates in the form [x, y]	yes
radius	The float radius value according to specified unit	yes
radiusUnit	String 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:

Property	Description	Required
abscissa	Horizontal coordinates for the corners of the polygon	yes
ordinate	Vertical coordinates for the corners of the polygon	yes