Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add docs for more geo functions #1297

Merged
merged 3 commits into from
Nov 19, 2024
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 182 additions & 0 deletions docs/reference/sql/functions/geo.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,18 @@ are enabled when you have `common-function/geo` feature turned on (default: on).

<TOCInline toc={toc} />

## Geo Types

Convert data between geospatial types.

### `wkt_point_from_latlng`

Convert latitude and longitude to WKT point.

```sql
SELECT wkt_point_from_latlng(37.76938, -122.3889) AS point;
```

## Geohash

See [more about geohash encoding
Expand Down Expand Up @@ -154,6 +166,23 @@ Arguments:
h3_child_pos_to_cell(25, h3_latlng_to_cell(37.76938, -122.3889, 8), 11);
```

### `h3_cells_contains`

Return true if given cells contains cell, or cell's parent.

Arguments:

- cell set: it can be int64/uint64/string array, and comma-separated string cell
ID.
- cell index: the cell to test

```sql
SELECT
h3_cells_contains('86283470fffffff,862834777ffffff, 862834757ffffff, 86283471fffffff, 862834707ffffff', '8b283470d112fff') AS R00,
h3_cells_contains(['86283470fffffff', '862834777ffffff', '862834757ffffff', '86283471fffffff', '862834707ffffff'], '8b283470d112fff') AS R11,
h3_cells_contains([604189641255419903, 604189643000250367, 604189642463379455, 604189641523855359, 604189641121202175], 604189641792290815) AS R21;
```

### `h3_grid_disk`

Returns cells with k distances of given cell.
Expand Down Expand Up @@ -207,6 +236,37 @@ FROM
);
```

### `h3_distance_sphere_km`

Returns sphere distance between centroid of two cells, in km

```sql
SELECT
round(h3_distance_sphere_km(cell1, cell2), 5) AS sphere_distance
FROM
(
SELECT
h3_string_to_cell('86283082fffffff') AS cell1,
h3_string_to_cell('86283470fffffff') AS cell2
);

```

### `h3_distance_degree`

Returns euclidean distance between centroid of two cells, in degree.

```sql
SELECT
round(h3_distance_degree(cell1, cell2), 14) AS euclidean_distance
FROM
(
SELECT
h3_string_to_cell('86283082fffffff') AS cell1,
h3_string_to_cell('86283470fffffff') AS cell2
);
```

## S2

Learn [more about S2 encoding](http://s2geometry.io/).
Expand Down Expand Up @@ -267,3 +327,125 @@ Example output:
```json
[[-122.3888,37.77001],[-122.3839,37.76928],[-122.3889,37.76938],[-122.382,37.7693]]
```

## Spatial Relation

### `st_contains`

Test spatial relationship between two objects: contains.

Arguments: two spatial objects encoded with WKT.

```sql
SELECT
st_contains(polygon1, p1),
st_contains(polygon2, p1),
FROM
(
SELECT
wkt_point_from_latlng(37.383287, -122.01325) AS p1,
'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1,
'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2,
);

```

### `st_within`

Test spatial relationship between two objects: within.

Arguments: two spatial objects encoded with WKT.

```sql
SELECT
st_within(p1, polygon1),
st_within(p1, polygon2),
ROM
(
SELECT
wkt_point_from_latlng(37.383287, -122.01325) AS p1,
'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1,
'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2,
);

```


### `st_intersects`

Test spatial relationship between two objects: intersects.

Arguments: two spatial objects encoded with WKT.

```sql
SELECT
st_intersects(polygon1, polygon2),
st_intersects(polygon1, polygon3),
FROM
(
SELECT
'POLYGON ((-122.031661 37.428252, -122.139829 37.387072, -122.135365 37.361971, -122.057759 37.332222, -121.987707 37.328946, -121.943754 37.333041, -121.919373 37.349145, -121.945814 37.376705, -121.975689 37.417345, -121.998696 37.409164, -122.031661 37.428252))' AS polygon1,
'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon2,
'POLYGON ((-122.089628 37.450332, -122.20535 37.378342, -122.093062 37.36088, -122.044301 37.372886, -122.089628 37.450332))' AS polygon3,
);

```


## Spatial Measurement

### `st_distance`

Returns WGS84(SRID: 4326) euclidean distance between two geometry object, in
degree.

Arguments: two spatial objects encoded with WKT.

```sql
SELECT
st_distance(p1, p2) AS euclidean_dist,
st_distance(p1, polygon1) AS euclidean_dist_pp,
FROM
(
SELECT
wkt_point_from_latlng(37.76938, -122.3889) AS p1,
wkt_point_from_latlng(38.5216, -121.4247) AS p2,
'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon1,
);
```

### `st_distance_sphere_m`

Return great circle distance between two point, in meters.

Arguments: two spatial objects encoded with WKT.

```sql
SELECT
st_distance_sphere_m(p1, p2) AS sphere_dist_m,
FROM
(
SELECT
wkt_point_from_latlng(37.76938, -122.3889) AS p1,
wkt_point_from_latlng(38.5216, -121.4247) AS p2,
);

```

### `st_area`

Returns area of given geometry object.

Arguments: the spatial object encoded with WKT.

```sql
SELECT
st_area(p1) as area_point,
st_area(polygon1) as area_polygon,
FROM
(
SELECT
wkt_point_from_latlng(37.76938, -122.3889) AS p1,
'POLYGON ((-121.491698 38.653343, -121.582353 38.556757, -121.469721 38.449287, -121.315883 38.541721, -121.491698 38.653343))' AS polygon1,
);
```
Loading