Project: Druid (App Definition and Development / Database)
File: geo.md

id: geo title: "Spatial filters" <!-- ~ Licensed to the Apache Software Foundation (ASF) under one ~ or more contributor license agreements. See the NOTICE file ~ distributed with this work for additional information ~ regarding copyright ownership. The ASF licenses this file ~ to you under the Apache License, Version 2.0 (the ~ "License"); you may not use this file except in compliance ~ with the License. You may obtain a copy of the License at ~ ~ http://www.apache.org/licenses/LICENSE-2.0 ~ ~ Unless required by applicable law or agreed to in writing, ~ software distributed under the License is distributed on an ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY ~ KIND, either express or implied. See the License for the ~ specific language governing permissions and limitations ~ under the License. --> :::info Apache Druid supports two query languages: and . 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 . 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 supported by

The following example shows an ingestion spec with a spatial dimension named `coordinates`, which is constructed from the input fields `x` and `y`: ```json { "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 . For general information on loading data in Druid, see . A 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: ```json "filter": { "type": "spatial", "dimension": <nameofspatial_dimension>, "bound": <bound_type> } ``` The following example shows a spatial filter with a rectangular bound type: ```json "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. 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. 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| 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| 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|