mirror of
https://github.com/apache/druid.git
synced 2025-02-20 00:47:40 +00:00
Documentation: Update spatial indexing example (#12555)
* fix spatial indexing example * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update text and example * Format JSON example * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Update docs/development/geo.md Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> * Accept review suggestions Co-authored-by: Victoria Lim <vtlim@users.noreply.github.com> Co-authored-by: Frank Chen <frankchen@apache.org>
This commit is contained in:
Katya Macedo
GitHub
parent
68262e43f8
commit
2218c8d23c
@ -23,80 +23,118 @@ title: "Spatial filters"
|
|||||||
-->
|
-->
|
||||||
|
|
||||||
> Apache Druid supports two query languages: [Druid SQL](../querying/sql.md) and [native queries](../querying/querying.md).
|
> Apache Druid supports two query languages: [Druid SQL](../querying/sql.md) and [native queries](../querying/querying.md).
|
||||||
> This document describes functionality that is only available in the native language.
|
> This document describes a feature that is only available in the native language.
|
||||||
|
|
||||||
Apache Druid supports filtering specially spatially indexed columns based on an origin and a bound.
|
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
|
||||||
|
|
||||||
In any of the data specs, there is the option of providing spatial dimensions. For example, for a JSON data spec, spatial dimensions can be specified as follows:
|
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 `lat` and `long`:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"type": "hadoop",
|
"type": "hadoop",
|
||||||
"dataSchema": {
|
"dataSchema": {
|
||||||
"dataSource": "DatasourceName",
|
"dataSource": "DatasourceName",
|
||||||
"parser": {
|
"parser": {
|
||||||
"type": "string",
|
"type": "string",
|
||||||
"parseSpec": {
|
"parseSpec": {
|
||||||
"format": "json",
|
"format": "json",
|
||||||
"timestampSpec": {
|
"timestampSpec": {
|
||||||
"column": "timestamp",
|
"column": "timestamp",
|
||||||
"format": "auto"
|
"format": "auto"
|
||||||
},
|
},
|
||||||
"dimensionsSpec": {
|
"dimensionsSpec": {
|
||||||
"dimensions": [],
|
"dimensions": [
|
||||||
"spatialDimensions": [{
|
{
|
||||||
"dimName": "coordinates",
|
"type": "double",
|
||||||
"dims": ["lat", "long"]
|
"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
|
## Spatial filters
|
||||||
|
|
||||||
|property|description|required?|
|
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.
|
||||||
|dimName|The name of the spatial dimension. A spatial dimension may be constructed from multiple 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|A list of dimension names that comprise a spatial dimension.|no|
|
|
||||||
|
|
||||||
The grammar for a spatial filter is as follows:
|
The spatial filter has the following structure:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
"filter" : {
|
"filter": {
|
||||||
"type": "spatial",
|
"type": "spatial",
|
||||||
"dimension": "spatialDim",
|
"dimension": <name_of_spatial_dimension>,
|
||||||
"bound": {
|
"bound": <bound_type>
|
||||||
"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
|
### Bound types
|
||||||
|
|
||||||
#### `rectangular`
|
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.
|
||||||
|
|
||||||
|property|description|required?|
|
#### Rectangular
|
||||||
|--------|-----------|---------|
|
|
||||||
|minCoords|List of minimum dimension coordinates for coordinates [x, y, z, …]|yes|
|
|
||||||
|maxCoords|List of maximum dimension coordinates for coordinates [x, y, z, …]|yes|
|
|
||||||
|
|
||||||
#### `radius`
|
The `rectangular` bound has the following elements:
|
||||||
|
|
||||||
|property|description|required?|
|
|Property|Description|Required|
|
||||||
|--------|-----------|---------|
|
|--------|-----------|--------|
|
||||||
|coords|Origin coordinates in the form [x, y, z, …]|yes|
|
|`minCoords`|The list of minimum dimension coordinates in the form [x, y]|yes|
|
||||||
|radius|The float radius value|yes|
|
|`maxCoords`|The list of maximum dimension coordinates in the form [x, y]|yes|
|
||||||
|
|
||||||
#### `polygon`
|
#### Radius
|
||||||
|
|
||||||
|property|description|required?|
|
The `radius` bound has the following elements:
|
||||||
|--------|-----------|---------|
|
|
||||||
|abscissa|Horizontal coordinate for corners of the polygon|yes|
|
|Property|Description|Required|
|
||||||
|ordinate|Vertical coordinate for corners of the polygon|yes|
|
|--------|-----------|--------|
|
||||||
|
|`coords`|Origin coordinates in the form [x, y]|yes|
|
||||||
|
|`radius`|The float radius value|yes|
|
||||||
|
|
||||||
|
#### 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|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user