mirror of https://github.com/apache/druid.git
157 lines
5.2 KiB
Markdown
157 lines
5.2 KiB
Markdown
---
|
|
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: [Druid SQL](../querying/sql.md) and [native queries](../querying/querying.md).
|
|
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](../querying/filters.md).
|
|
|
|
## 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](../ingestion/data-formats.md) 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`:
|
|
|
|
```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 [Ingestion spec reference](../ingestion/ingestion-spec.md).
|
|
For general information on loading data in Druid, see [Ingestion](../ingestion/index.md).
|
|
|
|
## Spatial filters
|
|
|
|
A [filter](../querying/filters.md) 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": <name_of_spatial_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.
|
|
|
|
### 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|
|