124 lines
4.7 KiB
Markdown
124 lines
4.7 KiB
Markdown
---
|
|
title: Shape data to work with the Geo package
|
|
description: >
|
|
Functions in the Flux Geo package require **lat** and **lon** fields and an **s2_cell_id** tag.
|
|
Rename latitude and longitude fields and generate S2 cell ID tokens.
|
|
menu:
|
|
influxdb_v1:
|
|
name: Shape geo-temporal data
|
|
parent: Geo-temporal data
|
|
weight: 301
|
|
related:
|
|
- /flux/v0/stdlib/experimental/geo/
|
|
- /flux/v0/stdlib/experimental/geo/shapedata/
|
|
canonical: /influxdb/v2/query-data/flux/geo/shape-geo-data/
|
|
alt_links:
|
|
v2: /influxdb/v2/query-data/flux/geo/shape-geo-data/
|
|
list_code_example: |
|
|
```js
|
|
import "experimental/geo"
|
|
|
|
sampleGeoData
|
|
|> geo.shapeData(latField: "latitude", lonField: "longitude", level: 10)
|
|
```
|
|
---
|
|
|
|
Functions in the Geo package require the following data schema:
|
|
|
|
- an **s2_cell_id** tag containing the [S2 Cell ID](https://s2geometry.io/devguide/s2cell_hierarchy.html#s2cellid-numbering)
|
|
**as a token**
|
|
- a **`lat` field** field containing the **latitude in decimal degrees** (WGS 84)
|
|
- a **`lon` field** field containing the **longitude in decimal degrees** (WGS 84)
|
|
|
|
## Shape geo-temporal data
|
|
If your data already contains latitude and longitude fields, use the
|
|
[`geo.shapeData()`function](/flux/v0/stdlib/experimental/geo/shapedata/)
|
|
to rename the fields to match the requirements of the Geo package, pivot the data
|
|
into row-wise sets, and generate S2 cell ID tokens for each point.
|
|
|
|
```js
|
|
import "experimental/geo"
|
|
|
|
from(bucket: "example-bucket")
|
|
|> range(start: -1h)
|
|
|> filter(fn: (r) => r._measurement == "example-measurement")
|
|
|> geo.shapeData(
|
|
latField: "latitude",
|
|
lonField: "longitude",
|
|
level: 10
|
|
)
|
|
```
|
|
|
|
## Generate S2 cell ID tokens
|
|
The Geo package uses the [S2 Geometry Library](https://s2geometry.io/) to represent
|
|
geographic coordinates on a three-dimensional sphere.
|
|
The sphere is divided into [cells](https://s2geometry.io/devguide/s2cell_hierarchy),
|
|
each with a unique 64-bit identifier (S2 cell ID).
|
|
Grid and S2 cell ID accuracy are defined by a [level](https://s2geometry.io/resources/s2cell_statistics).
|
|
|
|
{{% note %}}
|
|
To filter more quickly, use higher S2 Cell ID levels,
|
|
but know that that higher levels increase [series cardinality](/influxdb/v1/concepts/glossary/#series-cardinality).
|
|
{{% /note %}}
|
|
|
|
The Geo package requires S2 cell IDs as tokens.
|
|
To generate add S2 cell IDs tokens to your data, use one of the following options:
|
|
|
|
- [Generate S2 cell ID tokens with Telegraf](#generate-s2-cell-id-tokens-with-telegraf)
|
|
- [Generate S2 cell ID tokens language-specific libraries](#generate-s2-cell-id-tokens-language-specific-libraries)
|
|
- [Generate S2 cell ID tokens with Flux](#generate-s2-cell-id-tokens-with-flux)
|
|
|
|
### Generate S2 cell ID tokens with Telegraf
|
|
Enable the [Telegraf S2 Geo (`s2geo`) processor](https://github.com/influxdata/telegraf/tree/master/plugins/processors/s2geo)
|
|
to generate S2 cell ID tokens at a specified `cell_level` using `lat` and `lon` field values.
|
|
|
|
Add the `processors.s2geo` configuration to your Telegraf configuration file (`telegraf.conf`):
|
|
|
|
```toml
|
|
[[processors.s2geo]]
|
|
## The name of the lat and lon fields containing WGS-84 latitude and
|
|
## longitude in decimal degrees.
|
|
lat_field = "lat"
|
|
lon_field = "lon"
|
|
|
|
## New tag to create
|
|
tag_key = "s2_cell_id"
|
|
|
|
## Cell level (see https://s2geometry.io/resources/s2cell_statistics.html)
|
|
cell_level = 9
|
|
```
|
|
|
|
Telegraf stores the S2 cell ID token in the `s2_cell_id` tag.
|
|
|
|
### Generate S2 cell ID tokens language-specific libraries
|
|
Many programming languages offer S2 Libraries with methods for generating S2 cell ID tokens.
|
|
Use latitude and longitude with the `s2.CellID.ToToken` endpoint of the S2 Geometry
|
|
Library to generate `s2_cell_id` tags. For example:
|
|
|
|
- **Go:** [s2.CellID.ToToken()](https://godoc.org/github.com/golang/geo/s2#CellID.ToToken)
|
|
- **Python:** [s2sphere.CellId.to_token()](https://s2sphere.readthedocs.io/en/latest/api.html#s2sphere.CellId)
|
|
- **JavaScript:** [s2.cellid.toToken()](https://github.com/mapbox/node-s2/blob/master/API.md#cellidtotoken---string)
|
|
|
|
### Generate S2 cell ID tokens with Flux
|
|
Use the [`geo.s2CellIDToken()` function](/flux/v0/stdlib/experimental/geo/s2cellidtoken/)
|
|
with existing longitude (`lon`) and latitude (`lat`) field values to generate and add the S2 cell ID token.
|
|
First, use the [`geo.toRows()` function](/flux/v0/stdlib/experimental/geo/torows/)
|
|
to pivot **lat** and **lon** fields into row-wise sets:
|
|
|
|
```js
|
|
import "experimental/geo"
|
|
|
|
from(bucket: "example-bucket")
|
|
|> range(start: -1h)
|
|
|> filter(fn: (r) => r._measurement == "example-measurement")
|
|
|> geo.toRows()
|
|
|> map(fn: (r) => ({ r with
|
|
s2_cell_id: geo.s2CellIDToken(point: {lon: r.lon, lat: r.lat}, level: 10)
|
|
}))
|
|
```
|
|
|
|
{{% note %}}
|
|
The [`geo.shapeData()`function](/flux/v0/stdlib/experimental/geo/shapedata/)
|
|
generates S2 cell ID tokens as well.
|
|
{{% /note %}}
|