mirror of
https://github.com/apache/druid.git
synced 2025-02-17 07:25:02 +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).
|
||||
> 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
|
||||
|
||||
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
|
||||
{
|
||||
"type": "hadoop",
|
||||
"dataSchema": {
|
||||
"dataSource": "DatasourceName",
|
||||
"parser": {
|
||||
"type": "string",
|
||||
"parseSpec": {
|
||||
"format": "json",
|
||||
"timestampSpec": {
|
||||
"column": "timestamp",
|
||||
"format": "auto"
|
||||
},
|
||||
"dimensionsSpec": {
|
||||
"dimensions": [],
|
||||
"spatialDimensions": [{
|
||||
"dimName": "coordinates",
|
||||
"dims": ["lat", "long"]
|
||||
}]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
"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
|
||||
|
||||
|property|description|required?|
|
||||
|--------|-----------|---------|
|
||||
|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|
|
||||
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.
|
||||
|
||||
The grammar for a spatial filter is as follows:
|
||||
The spatial filter has the following structure:
|
||||
|
||||
```json
|
||||
"filter" : {
|
||||
"type": "spatial",
|
||||
"dimension": "spatialDim",
|
||||
"bound": {
|
||||
"type": "rectangular",
|
||||
"minCoords": [10.0, 20.0],
|
||||
"maxCoords": [30.0, 40.0]
|
||||
}
|
||||
"filter": {
|
||||
"type": "spatial",
|
||||
"dimension": <name_of_spatial_dimension>,
|
||||
"bound": <bound_type>
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
#### `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?|
|
||||
|--------|-----------|---------|
|
||||
|minCoords|List of minimum dimension coordinates for coordinates [x, y, z, …]|yes|
|
||||
|maxCoords|List of maximum dimension coordinates for coordinates [x, y, z, …]|yes|
|
||||
#### Rectangular
|
||||
|
||||
#### `radius`
|
||||
The `rectangular` bound has the following elements:
|
||||
|
||||
|property|description|required?|
|
||||
|--------|-----------|---------|
|
||||
|coords|Origin coordinates in the form [x, y, z, …]|yes|
|
||||
|radius|The float radius value|yes|
|
||||
|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|
|
||||
|
||||
#### `polygon`
|
||||
#### Radius
|
||||
|
||||
|property|description|required?|
|
||||
|--------|-----------|---------|
|
||||
|abscissa|Horizontal coordinate for corners of the polygon|yes|
|
||||
|ordinate|Vertical coordinate for corners of the polygon|yes|
|
||||
The `radius` bound has the following elements:
|
||||
|
||||
|Property|Description|Required|
|
||||
|--------|-----------|--------|
|
||||
|`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