You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@druid.apache.org by fr...@apache.org on 2022/09/16 02:32:25 UTC
[druid] branch master updated: Documentation: Update spatial indexing example (#12555)
This is an automated email from the ASF dual-hosted git repository.
frankchen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/master by this push:
new 2218c8d23c Documentation: Update spatial indexing example (#12555)
2218c8d23c is described below
commit 2218c8d23ce1a29a22dea30c8b209d856109d8ba
Author: Katya Macedo <38...@users.noreply.github.com>
AuthorDate: Thu Sep 15 21:32:19 2022 -0500
Documentation: Update spatial indexing example (#12555)
* fix spatial indexing example
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update text and example
* Format JSON example
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Update docs/development/geo.md
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
* Accept review suggestions
Co-authored-by: Victoria Lim <vt...@users.noreply.github.com>
Co-authored-by: Frank Chen <fr...@apache.org>
---
docs/development/geo.md | 142 ++++++++++++++++++++++++++++++------------------
1 file changed, 90 insertions(+), 52 deletions(-)
diff --git a/docs/development/geo.md b/docs/development/geo.md
index f03cd65f50..1942552949 100644
--- a/docs/development/geo.md
+++ b/docs/development/geo.md
@@ -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.
+
+#### 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
-|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|
+The `radius` bound has the following elements:
-#### `radius`
+|Property|Description|Required|
+|--------|-----------|--------|
+|`coords`|Origin coordinates in the form [x, y]|yes|
+|`radius`|The float radius value|yes|
-|property|description|required?|
-|--------|-----------|---------|
-|coords|Origin coordinates in the form [x, y, z, …]|yes|
-|radius|The float radius value|yes|
+#### Polygon
-#### `polygon`
+The `polygon` bound has the following elements:
-|property|description|required?|
-|--------|-----------|---------|
-|abscissa|Horizontal coordinate for corners of the polygon|yes|
-|ordinate|Vertical coordinate for corners of the polygon|yes|
+|Property|Description|Required|
+|--------|-----------|--------|
+|`abscissa`|Horizontal coordinates for the corners of the polygon|yes|
+|`ordinate`|Vertical coordinates for the corners of the polygon|yes|
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@druid.apache.org
For additional commands, e-mail: commits-help@druid.apache.org