diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/_index.md b/content/v2.0/reference/flux/stdlib/experimental/geo/_index.md index e1d1986e0..2a96d422e 100644 --- a/content/v2.0/reference/flux/stdlib/experimental/geo/_index.md +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/_index.md @@ -80,6 +80,7 @@ Define geographic regions using the following shapes: - [box](#box) - [circle](#circle) +- [point](#point) - [polygon](#polygon) ### box @@ -116,6 +117,20 @@ Define a circular region by specifying an object containing the following proper } ``` +### point +Define a point region by specifying and object containing the following properties: + +- **lat**: latitude in decimal degrees (WGS 84) _(Float)_ +- **lon**: longitude in decimal degrees (WGS 84) _(Float)_ + +##### Example point region +```js +{ + lat: 40.671659, + lon: -73.936631 +} +``` + ### polygon Define a custom polygon region using an object containing the following properties: @@ -136,3 +151,38 @@ Define a custom polygon region using an object containing the following properti ] } ``` + +## GIS geometry definitions +Many functions in the Geo package manipulate data based on geographic information system (GIS) data. +Define GIS geometry using the following: + +- Any [region type](#region-definitions) _(typically [point](#point))_ +- [linestring](#linestring) + +### linestring +Define a geographic linestring path using an object containing the following properties: + +- **linestring**: string containing comma-separatedlongitude and latitude + coordinate pairs (`lon lat,`): + +```js +{ + linestring: "39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433" +} +``` + +## Distance units +The Geo package supports the following units of measurement for distance: + +- `m` - meters +- `km` - kilometers _(default)_ +- `mile` - miles + +### Define distance units +Use the Geo package `units` option to define custom units of measurement: + +```js +import "experimental/geo" + +option geo.units = {distance: "mile"} +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/filterrows.md b/content/v2.0/reference/flux/stdlib/experimental/geo/filterrows.md index 11c59240a..e7da63ad3 100644 --- a/content/v2.0/reference/flux/stdlib/experimental/geo/filterrows.md +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/filterrows.md @@ -196,19 +196,30 @@ filterRows = ( maxSize=-1, level=-1, s2cellIDLevel=-1, - correlationKey=["_time"], strict=true ) => { + _columns = + |> columns(column: "_value") + |> tableFind(fn: (key) => true ) + |> getColumn(column: "_value") _rows = - tables - |> gridFilter( - region, - minSize: minSize, - maxSize: maxSize, - level: level, - s2cellIDLevel: s2cellIDLevel - ) - |> toRows(correlationKey) + if contains(value: "lat", set: _columns) then + tables + |> gridFilter( + region: region, + minSize: minSize, + maxSize: maxSize, + level: level, + s2cellIDLevel: s2cellIDLevel) + else + tables + |> gridFilter( + region: region, + minSize: minSize, + maxSize: maxSize, + level: level, + s2cellIDLevel: s2cellIDLevel) + |> toRows() _result = if strict then _rows diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/s2celllatlon.md b/content/v2.0/reference/flux/stdlib/experimental/geo/s2celllatlon.md new file mode 100644 index 000000000..0593a5bfb --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/s2celllatlon.md @@ -0,0 +1,36 @@ +--- +title: geo.s2CellLatLon() function +description: > + The `geo.s2CellLatLon()` function returns the latitude and longitude of the + center of an S2 cell. +menu: + v2_0_ref: + name: geo.s2CellLatLon + parent: Geo +weight: 401 +v2.0/tags: [functions, geo] +related: + - /v2.0/query-data/flux/geo/ +--- + +The `geo.s2CellLatLon()` function returns the latitude and longitude of the +center of an S2 cell. + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.s2CellLatLon( + token: "89c284" +) + +// Returns {lat: 40.812535546624574, lon: -73.55941282728273} +``` + +## Parameters + +### token +S2 cell ID token. + +_**Data type:** String_ diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/shapedata.md b/content/v2.0/reference/flux/stdlib/experimental/geo/shapedata.md index 4ab03fcf2..b519bb638 100644 --- a/content/v2.0/reference/flux/stdlib/experimental/geo/shapedata.md +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/shapedata.md @@ -32,8 +32,7 @@ import "experimental/geo" geo.shapeData( latField: "latitude", lonField: "longitude", - level: 10, - correlationKey: ["_time"] + level: 10 ) ``` @@ -57,12 +56,6 @@ when generating the S2 cell ID token. _**Data type:** Integer_ -### correlationKey -List of columns used to uniquely identify a row for output. -Default is `["_time"]`. - -_**Data type:** Array of strings_ - ## Examples ##### Shape data to meet the requirements of the Geo package diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/st_contains.md b/content/v2.0/reference/flux/stdlib/experimental/geo/st_contains.md new file mode 100644 index 000000000..ba8b37e58 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/st_contains.md @@ -0,0 +1,86 @@ +--- +title: geo.ST_Contains() function +description: > + The `geo.ST_Contains()` function tests if the specified region contains the specified + GIS geometry and returns `true` or `false`. +menu: + v2_0_ref: + name: geo.ST_Contains + parent: Geo +weight: 401 +v2.0/tags: [functions, geo, GIS] +related: + - /v2.0/query-data/flux/geo/ +--- + +The `geo.ST_Contains()` function tests if the specified region contains the specified +geographic information system (GIS) geometry and returns `true` or `false`. + +_**Function type:** Test_ + +```js +import "experimental/geo" + +geo.ST_Contains( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {lon: 39.7515, lat: 15.08433} +) + +// Returns false +``` + +## Parameters + +### region +The region to test. +Specify object properties for the shape. +_See [Region definitions](/v2.0/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Object_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/v2.0/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Object_ + +## Examples + +##### Test if geographic points are inside of a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_contains: geo.ST_Contains(region: region, geometry: {lat: r.lat, lon: r.lon}) + })) +``` + +##### Test if tracks are inside of a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> geo.asTracks() + |> geo.ST_LineString() + |> map(fn: (r) => ({ + r with st_contains: geo.ST_Contains(region: region, geometry: {linestring: r.st_linestring}) + })) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/st_distance.md b/content/v2.0/reference/flux/stdlib/experimental/geo/st_distance.md new file mode 100644 index 000000000..dd51bb969 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/st_distance.md @@ -0,0 +1,85 @@ +--- +title: geo.ST_Distance() function +description: > + The `geo.ST_Distance()` function returns the distance between the specified region + and specified GIS geometry. +menu: + v2_0_ref: + name: geo.ST_Distance + parent: Geo +weight: 401 +v2.0/tags: [functions, geo, GIS] +related: + - /v2.0/query-data/flux/geo/ +--- + +The `geo.ST_Distance()` function returns the distance between the specified region +and specified geographic information system (GIS) geometry. +Define distance units with the [`geo.units` option](/v2.0/reference/flux/stdlib/experimental/geo/#define-distance-units). + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.ST_Distance( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {lon: 39.7515, lat: 15.08433} +) + +// Returns 10734.184618677662 (km) +``` + +## Parameters + +### region +The region to test. +Specify object properties for the shape. +_See [Region definitions](/v2.0/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Object_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/v2.0/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Object_ + +## Examples + +##### Test if geographic points are inside of a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_contains: ST_Distance(region: region, geometry: {lat: r.lat, lon: r.lon}) + })) +``` + +##### Calculate the distance between geographic points and a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_distance: ST_Distance(region: region, geometry: {lat: r.lat, lon: r.lon}) + })) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/st_dwithin.md b/content/v2.0/reference/flux/stdlib/experimental/geo/st_dwithin.md new file mode 100644 index 000000000..4ee092ee4 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/st_dwithin.md @@ -0,0 +1,75 @@ +--- +title: geo.ST_DWithin() function +description: > + The `geo.ST_DWithin()` function tests if the specified region is within a defined + distance from the specified geographic information system (GIS) geometry and + returns `true` or `false`. +menu: + v2_0_ref: + name: geo.ST_DWithin + parent: Geo +weight: 401 +v2.0/tags: [functions, geo, GIS] +related: + - /v2.0/query-data/flux/geo/ +--- + +The `geo.ST_DWithin()` function tests if the specified region is within a defined +distance from the specified geographic information system (GIS) geometry and +returns `true` or `false`. + +_**Function type:** Test_ + +```js +import "experimental/geo" + +geo.ST_DWithin( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {lon: 39.7515, lat: 15.08433}, + distance: 1000.0 +) + +// Returns false +``` + +## Parameters + +### region +The region to test. +Specify object properties for the shape. +_See [Region definitions](/v2.0/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Object_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/v2.0/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Object_ + +### distance +Maximum allowed distance between the region and geometry. +_Define distance units with the [`geo.units` option](/v2.0/reference/flux/stdlib/experimental/geo/#define-distance-units)._ + +_**Data type:** Float_ + +## Examples + +##### Test if geographic points are within a distance from a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_within: geo.ST_DWithin(region: box, geometry: {lat: r.lat, lon: r.lon}, distance: 15.0) + })) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/st_intersects.md b/content/v2.0/reference/flux/stdlib/experimental/geo/st_intersects.md new file mode 100644 index 000000000..d0d3f2998 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/st_intersects.md @@ -0,0 +1,66 @@ +--- +title: geo.ST_Intersects() function +description: > + The `geo.ST_Intersects()` function tests if the specified geographic information + system (GIS) geometry intersects with the specified region and returns `true` or `false`. +menu: + v2_0_ref: + name: geo.ST_Intersects + parent: Geo +weight: 401 +v2.0/tags: [functions, geo, GIS] +related: + - /v2.0/query-data/flux/geo/ +--- + +The `geo.ST_Intersects()` function tests if the specified geographic information +system (GIS) geometry intersects with the specified region and returns `true` or `false`. + +_**Function type:** Test_ + +```js +import "experimental/geo" + +geo.ST_Intersects( + region: {lat: 40.7, lon: -73.3, radius: 20.0}, + geometry: {linestring: "39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433"} +) + +// Returns false +``` + +## Parameters + +### region +The region to test. +Specify object properties for the shape. +_See [Region definitions](/v2.0/reference/flux/stdlib/experimental/geo/#region-definitions)._ + +_**Data type:** Object_ + +### geometry +The GIS geometry to test. +Can be either point or linestring geometry. +_See [GIS geometry definitions](/v2.0/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Object_ + +## Examples + +##### Test if geographic points intersect with a region +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> map(fn: (r) => ({ + r with st_within: geo.ST_Intersects(region: box, geometry: {lat: r.lat, lon: r.lon}) + })) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/st_length.md b/content/v2.0/reference/flux/stdlib/experimental/geo/st_length.md new file mode 100644 index 000000000..33ce94a25 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/st_length.md @@ -0,0 +1,62 @@ +--- +title: geo.ST_Length() function +description: > + The `geo.ST_Length()` function returns the [spherical length or distance](https://mathworld.wolfram.com/SphericalDistance.html) + of the specified geographic information system (GIS) geometry. +menu: + v2_0_ref: + name: geo.ST_Length + parent: Geo +weight: 401 +v2.0/tags: [functions, geo, GIS] +related: + - /v2.0/query-data/flux/geo/ +--- + +The `geo.ST_Length()` function returns the [spherical length or distance](https://mathworld.wolfram.com/SphericalDistance.html) +of the specified geographic information system (GIS) geometry. +Define distance units with the [`geo.units` option](/v2.0/reference/flux/stdlib/experimental/geo/#define-distance-units). + +_**Function type:** Transformation_ + +```js +import "experimental/geo" + +geo.ST_Length( + geometry: {linestring: "39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433"} +) + +// Returns 346.1023974652474 (km) +``` + +## Parameters + +### geometry +The GIS geometry to measure. +Can be either point or linestring geometry. +Points will always return `0.0`. +_See [GIS geometry definitions](/v2.0/reference/flux/stdlib/experimental/geo/#gis-geometry-definitions)._ + +_**Data type:** Object_ + +## Examples + +##### Calculate the length of geographic paths +```js +import "experimental/geo" + +region = { + minLat: 40.51757813, + maxLat: 40.86914063, + minLon: -73.65234375, + maxLon: -72.94921875 +} + +data + |> geo.toRows() + |> geo.asTracks() + |> geo.ST_LineString() + |> map(fn: (r) => ({ + r with st_length: geo.ST_Length(geometry: {linestring: r.st_linestring}) + })) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/st_linestring.md b/content/v2.0/reference/flux/stdlib/experimental/geo/st_linestring.md new file mode 100644 index 000000000..32d7a6715 --- /dev/null +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/st_linestring.md @@ -0,0 +1,69 @@ +--- +title: geo.ST_LineString() function +description: > + The `geo.ST_LineString()` function converts a series of geographic points into + [linestring](/v2.0/reference/flux/stdlib/experimental/geo/#linestring). +menu: + v2_0_ref: + name: geo.ST_LineString + parent: Geo +weight: 401 +v2.0/tags: [functions, geo, GIS] +related: + - /v2.0/query-data/flux/geo/ +--- + +The `geo.ST_LineString()` function converts a series of geographic points into +[linestring](/v2.0/reference/flux/stdlib/experimental/geo/#linestring). +Group data into meaningful, ordered paths to before converting to linestring. +Rows in each table must have `lat` and `lon` columns. +Output tables contain a single row with a `st_linestring` column containing the resulting linestring. + +_**Function type:** Aggregate_ + +```js +import "experimental/geo" + +geo.ST_LineString() +``` + +## Examples + +### Convert a series of geographic points into linestring + +##### Input data + +| _time | id | lon | lat | +|:----- |:--: | ---: | ---: | +| 2020-01-01T00:00:00Z | a213b | 39.7515 | 14.01433 | +| 2020-01-02T00:00:00Z | a213b | 38.3527 | 13.9228 | +| 2020-01-03T00:00:00Z | a213b | 36.9978 | 15.08433 | + + +```js +import "experimental/geo" + +data + |> geo.ST_LineString() +``` + +##### Output data + +| id | st_linestring | +|:-- |:------------- | +| a213b | 39.7515 14.01433, 38.3527 13.9228, 36.9978 15.08433 | + +## Function definition +```js +ST_LineString = (tables=<-) => + tables + |> reduce(fn: (r, accumulator) => ({ + __linestring: accumulator.__linestring + (if accumulator.__count > 0 then ", " else "") + string(v: r.lat) + " " + string(v: r.lon), + __count: accumulator.__count + 1 + }), identity: { + __linestring: "", + __count: 0 + } + ) + |> rename(columns: {__linestring: "st_linestring"}) +``` diff --git a/content/v2.0/reference/flux/stdlib/experimental/geo/torows.md b/content/v2.0/reference/flux/stdlib/experimental/geo/torows.md index 57c3d07a0..7c6bb41b2 100644 --- a/content/v2.0/reference/flux/stdlib/experimental/geo/torows.md +++ b/content/v2.0/reference/flux/stdlib/experimental/geo/torows.md @@ -22,19 +22,9 @@ _**Function type:** Transformation_ ```js import "experimental/geo" -geo.toRows( - correlationKey: ["_time"] -) +geo.toRows() ``` -## Parameters - -### correlationKey -List of columns used to uniquely identify a row for output. -Default is `["_time"]`. - -_**Data type:** Array of strings_ - ## Examples ```js import "experimental/geo" @@ -49,9 +39,5 @@ from(bucket: "example-bucket") ```js toRows = (tables=<-, correlationKey=["_time"]) => tables - |> pivot( - rowKey: correlationKey, - columnKey: ["_field"], - valueColumn: "_value" - ) + |> v1.fieldsAsCols() ``` diff --git a/content/v2.0/reference/release-notes/flux.md b/content/v2.0/reference/release-notes/flux.md index 777415d37..f254d2597 100644 --- a/content/v2.0/reference/release-notes/flux.md +++ b/content/v2.0/reference/release-notes/flux.md @@ -22,7 +22,8 @@ InfluxDB until the next InfluxDB v2.0 release._ - Add functions to convert semantic monotype to AST type. - Add BigQuery support. - Rust flatbuffer serialization for `MonoType` and `TypeExpression`. -- Extend with Geo package functions and add unit support. +- Extend with Geo package with GIS functions and + [unit support](/v2.0/reference/flux/stdlib/experimental/geo/#distance-units). ### Bug fixes - String interpolation in arrays.