geo.gridFilter() function
The geo.gridFilter() function is experimental and subject to change at any time.
By using this function, you accept the risks of experimental functions.
The geo.gridFilter() function filters data by a specified geographic region.
It compares input data to a set of S2 Cell ID tokens located in the specified region.
S2 Grid cells may not perfectly align with the defined region, so results may include
data with coordinates outside the region, but inside S2 grid cells partially covered by the region.
Use toRows() and
geo.strictFilter()
after geo.gridFilter() to precisely filter points.
See Non-strict and strict filtering below.
Function type: Transformation
import "experimental/geo"
geo.gridFilter(
region: {lat: 40.69335938, lon: -73.30078125, radius: 20.0}
minSize: 24,
maxSize: -1,
level: -1,
s2cellIDLevel: -1
)
s2_cell_id must be part of the group key
To filter geo-temporal data with geo.gridFilter(), s2_cell_id must be part
of the group key.
To add s2_cell_id to the group key, use experimental.group:
import "experimental"
// ...
|> experimental.group(columns: ["s2_cell_id"], mode: "extend")
Non-strict and strict filtering
In most cases, the specified geographic region does not perfectly align with S2 grid cells.
- Non-strict filtering returns points that may be outside of the specified region but inside S2 grid cells partially covered by the region.
- Strict filtering returns only points inside the specified region.
S2 grid cell
Filter region
Returned point
Non-strict filtering
Strict filtering
Parameters
region
The region containing the desired data points. Specify record properties for the shape. See Region definitions.
Data type: Record
minSize
Minimum number of cells that cover the specified region.
Default is 24.
Data type: Integer
maxSize
Maximum number of cells that cover the specified region.
Default is -1.
Data type: Integer
level
S2 cell level of grid cells.
Default is -1.
Data type: Integer
level is mutually exclusive with minSize and maxSize and must be less than
or equal to s2cellIDLevel.
s2cellIDLevel
S2 Cell level used in s2_cell_id tag.
Default is -1.
Data type: Integer
When set to -1, gridFilter() attempts to automatically detect the S2 Cell ID level.
Examples
Filter data in a box-shaped region
import "experimental/geo"
from(bucket: "example-bucket")
|> range(start: -1h)
|> filter(fn: (r) => r._measurement == "example-measurement")
|> geo.gridFilter(
region: {
minLat: 40.51757813,
maxLat: 40.86914063,
minLon: -73.65234375,
maxLon: -72.94921875
}
)
Filter data in a circular region
import "experimental/geo"
from(bucket: "example-bucket")
|> range(start: -1h)
|> filter(fn: (r) => r._measurement == "example-measurement")
|> geo.gridFilter(
region: {
lat: 40.69335938,
lon: -73.30078125,
radius: 20.0
}
)
Filter data in a custom polygon region
import "experimental/geo"
from(bucket: "example-bucket")
|> range(start: -1h)
|> filter(fn: (r) => r._measurement == "example-measurement")
|> geo.gridFilter(
region: {
points: [
{lat: 40.671659, lon: -73.936631},
{lat: 40.706543, lon: -73.749177},
{lat: 40.791333, lon: -73.880327}
]
}
)
Support and feedback
Thank you for being part of our community! We welcome and encourage your feedback and bug reports for InfluxDB and this documentation. To find support, the following resources are available:
InfluxDB Cloud and InfluxDB Enterprise customers can contact InfluxData Support.