Skip to content

Commit d01e3dc

Browse files
farhan-syahfarhan-syah
committed
docs(spatial): expand SQL function reference and fix H3 function name
Break out predicates, constructors, accessors/measures, and geometry operations into dedicated tables with a worked example, and correct h3_to_string/h3_encode to h3_latlngtocell. Mirror the same breakdown in the storage-engines overview with a link to the full reference.
1 parent 4713258 commit d01e3dc

2 files changed

Lines changed: 78 additions & 15 deletions

File tree

‎docs/sql/spatial-queries.rdx‎

Lines changed: 67 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -26,17 +26,72 @@ WHERE ST_Within(location, ST_GeomFromGeoJSON('{
2626

2727
## OGC Predicates
2828

29-
| Function | Description |
30-
| ----------------- | ----------------------------------- |
31-
| `ST_Contains` | Geometry A contains geometry B |
32-
| `ST_Intersects` | Geometries share any space |
33-
| `ST_Within` | Geometry A is within geometry B |
34-
| `ST_DWithin` | Within a given distance |
35-
| `ST_Distance` | Distance between two geometries |
36-
| `ST_Intersection` | Intersection geometry |
37-
| `ST_Buffer` | Buffer around geometry |
38-
| `ST_Envelope` | Bounding box |
39-
| `ST_Union` | Union of geometries |
29+
| Function | Description |
30+
| ----------------- | ---------------------------------------------------- |
31+
| `ST_Contains` | Geometry A contains geometry B |
32+
| `ST_Within` | Geometry A is within geometry B |
33+
| `ST_Intersects` | Geometries share any space |
34+
| `ST_Disjoint` | Geometries share no space |
35+
| `ST_DWithin` | Within a given geodesic distance in meters |
36+
| `ST_IsValid` | Whether a geometry is well-formed |
37+
38+
## Constructors
39+
40+
| Function | Result |
41+
| --------------------------------------------------- | ------------------------------------------------------------- |
42+
| `ST_Point(lng, lat)` | Point |
43+
| `ST_MakePoint(x, y [, z])` | Point |
44+
| `ST_GeomFromText(wkt [, srid])` | Geometry from WKT |
45+
| `ST_GeomFromGeoJSON(json)` | Geometry from GeoJSON |
46+
| `ST_GeomFromWKB(bytes [, srid])` | Geometry from WKB; accepts `X'...'` or its hex string |
47+
| `ST_MakeLine(point, point, ...)` | LineString |
48+
| `ST_MakePolygon(ring, ...)` | Polygon from arrays of `[lng, lat]` pairs |
49+
| `ST_MakeEnvelope(min_lng, min_lat, max_lng, max_lat)` | Rectangular Polygon |
50+
51+
## Accessors and Measures
52+
53+
Measures are geodesic — meters, and square meters for area.
54+
55+
| Function | Result |
56+
| ----------------------- | ------------------------------------------------------------------- |
57+
| `ST_AsText(geom)` | WKT rendering |
58+
| `ST_AsGeoJSON(geom)` | GeoJSON rendering |
59+
| `ST_X(geom)` / `ST_Y(geom)` | Ordinate of a Point; NULL for any other geometry |
60+
| `ST_GeometryType(geom)` | Type name, e.g. `Point` |
61+
| `ST_NPoints(geom)` | Total vertex count |
62+
| `ST_SRID(geom)` | Always `4326` — geometry is stored as GeoJSON, i.e. WGS 84 |
63+
| `ST_Distance(a, b)` | Distance between two geometries |
64+
| `ST_Length(geom)` | Length of linear components |
65+
| `ST_Perimeter(geom)` | Boundary length of areal components |
66+
| `ST_Area(geom)` | Area of areal components, less holes |
67+
68+
## Geometry Operations
69+
70+
| Function | Result |
71+
| ------------------------------------ | --------------------------------------------- |
72+
| `ST_Buffer(geom, meters [, segments])` | Geometry grown by a distance |
73+
| `ST_Envelope(geom)` | Bounding box |
74+
| `ST_Centroid(geom)` | Centroid, weighted by highest dimension |
75+
| `ST_Union(a, b)` | Union of geometries |
76+
| `ST_Intersection(a, b)` | Intersection geometry |
77+
78+
## Reading Stored Geometry
79+
80+
Every function above works in every position a geometry expression may appear —
81+
an `INSERT` value, a `SELECT` projection, and a predicate's query-geometry
82+
argument. Constructors nest, so a buffered point is a valid search area, and a
83+
bare string literal is read as WKT or GeoJSON.
84+
85+
```sql
86+
SELECT name, ST_AsText(location), ST_X(location), ST_Y(location)
87+
FROM restaurants;
88+
89+
SELECT name FROM restaurants
90+
WHERE ST_Within(location, ST_Buffer(ST_Point(-73.990, 40.750), 1000));
91+
92+
SELECT name FROM restaurants
93+
WHERE ST_DWithin(location, 'POINT(-73.990 40.750)', 1000);
94+
```
4095

4196
## Spatial Join
4297

@@ -48,7 +103,7 @@ WHERE ST_Contains(z.boundary, r.location);
48103
## H3 Hexagonal Indexing
49104

50105
```sql
51-
SELECT h3_to_string(h3_encode(40.748, -73.985, 9)) AS hex;
106+
SELECT h3_latlngtocell(40.748, -73.985, 9) AS hex;
52107
```
53108

54109
## Hybrid Spatial-Vector

‎docs/storage-engines/spatial.rdx‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ WHERE ST_Within(location, ST_GeomFromGeoJSON('{
4040
}'));
4141

4242
-- H3 hexagonal binning
43-
SELECT h3_to_string(h3_encode(40.748, -73.985, 9)) AS hex;
43+
SELECT h3_latlngtocell(40.748, -73.985, 9) AS hex;
4444

4545
-- Spatial join
4646
SELECT r.name, z.zone_name
@@ -54,9 +54,17 @@ WHERE ST_DWithin(location, ST_Point(-73.990, 40.750), 2000) AND embedding <-> $q
5454
LIMIT 10;
5555
```
5656

57-
## OGC Predicates
57+
## Geometry Functions
5858

59-
`ST_Contains`, `ST_Intersects`, `ST_Within`, `ST_DWithin`, `ST_Distance`, `ST_Intersection`, `ST_Buffer`, `ST_Envelope`, `ST_Union`.
59+
- **Predicates** — `ST_Contains`, `ST_Within`, `ST_Intersects`, `ST_Disjoint`, `ST_DWithin`, `ST_IsValid`
60+
- **Constructors** — `ST_Point`, `ST_MakePoint`, `ST_GeomFromText`, `ST_GeomFromWKB`, `ST_GeomFromGeoJSON`, `ST_MakeLine`, `ST_MakePolygon`, `ST_MakeEnvelope`
61+
- **Accessors** — `ST_AsText`, `ST_AsGeoJSON`, `ST_X`, `ST_Y`, `ST_GeometryType`, `ST_NPoints`, `ST_SRID`
62+
- **Measures** — `ST_Distance`, `ST_Length`, `ST_Perimeter`, `ST_Area` (geodesic, meters)
63+
- **Operations** — `ST_Buffer`, `ST_Envelope`, `ST_Centroid`, `ST_Union`, `ST_Intersection`
64+
65+
Each works in every geometry position — `INSERT` values, projections, and
66+
predicate arguments — and constructors nest. See
67+
[Spatial Queries](/docs/sql/spatial-queries) for the full reference.
6068

6169
## Format Support
6270

0 commit comments

Comments
 (0)