vtlim commented on code in PR #12555:
URL: https://github.com/apache/druid/pull/12555#discussion_r921694051
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
Review Comment:
```suggestion
Spatial dimensions are string columns that contain coordinates separated by
a comma.
```
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
+In the ingestion spec, you configure spatial dimensions in the
`dimensionsSpec` object of the `dataSchema` component.
+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).
+
+You can provide spatial dimensions in any of the [data
formats](../ingestion/data-formats.md) supported by Druid.
+The following example shows spatial dimensions in JSON format:
```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"
+ ]
+ }
+ ]
+ }
+ }
+ }
+ }
}
```
+The `spatialDimensions` array has the following elements:
+
+|Property|Description|Required|
+|--------|-----------|--------|
+|`dimName`|The name of a spatial dimension. You can construct a spatial
dimenion 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|
+
## 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 is a JSON object indicating which rows of data should be included in
the computation for a query.
Review Comment:
```suggestion
A [filter](../querying/filters.md) is a JSON object indicating which rows of
data should be included in the computation for a query.
```
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
+In the ingestion spec, you configure spatial dimensions in the
`dimensionsSpec` object of the `dataSchema` component.
+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).
+
+You can provide spatial dimensions in any of the [data
formats](../ingestion/data-formats.md) supported by Druid.
+The following example shows spatial dimensions in JSON format:
Review Comment:
```suggestion
The following example shows an ingestion spec with a spatial dimension named
`coordinates`, which is constructed from the input fields `lat` and `long`:
```
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
+In the ingestion spec, you configure spatial dimensions in the
`dimensionsSpec` object of the `dataSchema` component.
+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).
Review Comment:
Maybe move these lines to the end of the section, before spatial filters?
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
+In the ingestion spec, you configure spatial dimensions in the
`dimensionsSpec` object of the `dataSchema` component.
+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).
+
+You can provide spatial dimensions in any of the [data
formats](../ingestion/data-formats.md) supported by Druid.
+The following example shows spatial dimensions in JSON format:
```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"
+ ]
+ }
+ ]
+ }
+ }
+ }
+ }
}
```
+The `spatialDimensions` array has the following elements:
+
+|Property|Description|Required|
+|--------|-----------|--------|
+|`dimName`|The name of a spatial dimension. You can construct a spatial
dimenion 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|
Review Comment:
```suggestion
|`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|
```
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply spatial filters.
Review Comment:
```suggestion
This topic explains how to ingest and query spatial filters.
```
##########
docs/development/geo.md:
##########
@@ -78,25 +108,36 @@ The grammar for a spatial filter is as follows:
}
```
+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 [latitude,
longitude]|yes|
+|`maxCoords`|The list of maximum dimension coordinates in the form [latitude,
longitude]|yes|
Review Comment:
```suggestion
|`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|
```
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
+In the ingestion spec, you configure spatial dimensions in the
`dimensionsSpec` object of the `dataSchema` component.
+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).
+
+You can provide spatial dimensions in any of the [data
formats](../ingestion/data-formats.md) supported by Druid.
+The following example shows spatial dimensions in JSON format:
```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"
+ ]
+ }
+ ]
+ }
+ }
+ }
+ }
}
```
+The `spatialDimensions` array has the following elements:
Review Comment:
```suggestion
Each spatial dimension object in the `spatialDimensions` array is defined by
the following fields:
```
##########
docs/development/geo.md:
##########
@@ -78,25 +108,36 @@ The grammar for a spatial filter is as follows:
}
```
+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 [latitude,
longitude]|yes|
+|`maxCoords`|The list of maximum dimension coordinates in the form [latitude,
longitude]|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 coordinate for the corners of the polygon|yes|
+|`ordinate`|Vertical coordinate for the corners of the polygon|yes|
Review Comment:
```suggestion
|`abscissa`|Horizontal coordinates for the corners of the polygon|yes|
|`ordinate`|Vertical coordinates for the corners of the polygon|yes|
```
https://github.com/apache/druid/blob/master/processing/src/main/java/org/apache/druid/collections/spatial/search/PolygonBound.java#L82-L85
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
+In the ingestion spec, you configure spatial dimensions in the
`dimensionsSpec` object of the `dataSchema` component.
+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).
+
+You can provide spatial dimensions in any of the [data
formats](../ingestion/data-formats.md) supported by Druid.
+The following example shows spatial dimensions in JSON format:
```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"
+ ]
+ }
+ ]
+ }
+ }
+ }
+ }
}
```
+The `spatialDimensions` array has the following elements:
+
+|Property|Description|Required|
+|--------|-----------|--------|
+|`dimName`|The name of a spatial dimension. You can construct a spatial
dimenion 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|
+
## 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 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:
Review Comment:
This is a specific example and not a generic structure. We could add
something like the following:
```
"filter": {
"type": "spatial",
"dimension": <name_of_spatial_dimension>,
"bound": <bound_type>
}
```
That way we can have the generic grammar, then introduce a specific example.
##########
docs/development/geo.md:
##########
@@ -23,53 +23,83 @@ 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 apply 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 sting columns that contain coordinates separated by a
comma.
Review Comment:
I think this describes the result of ingestion a spatial dimension. Consider
starting with how a spatial dimension gets ingested? Possibly something like,
"Spatial dimensions are derived (generated? composed?) from two or more
specified input dimensions. Druid stores spatial dimensions as comma-separated
values in string columns."
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
