Geospatial functions

60 functions. Names resolve case-insensitively; an alias binds the same function as its canonical name. Each entry gives the signatures, the behaviour and an example.

geo_distance

Measures ellipsoidal surface separation in meters between two longitude/latitude positions.

geo_distance(float64,float64,float64,float64) -> float64

Returns the surface distance in meters using an ellipsoidal Earth model, with arguments ordered longitude1, latitude1, longitude2, latitude2 in degrees. Coincident valid positions return zero, and a NULL coordinate returns NULL. Nonfinite or invalid geographic coordinates raise INVALID_ARGUMENT; the operation has no stream state.

Example

geo_distance(0.0, 0.0, 0.0, 0.0)
-- → 0.0

geo_great_circle_angle

Returns the central angle in degrees between two geographic positions on a sphere.

geo_great_circle_angle(float64,float64,float64,float64) -> float64

Computes the spherical central angle for longitude/latitude pairs supplied in degrees, with longitude preceding latitude at both endpoints. The output is also degrees, not radians; antipodal positions have an angle of 180 degrees. Any NULL coordinate yields NULL, and invalid or nonfinite coordinates raise INVALID_ARGUMENT.

Example

geo_great_circle_angle(0.0, 0.0, 90.0, 0.0)
-- → 90.0

geo_great_circle_distance

Finds the shortest spherical surface route between coordinate pairs, expressed in meters.

geo_great_circle_distance(float64,float64,float64,float64) -> float64

Measures great-circle distance in meters on a spherical Earth from longitude1, latitude1, longitude2, latitude2, all in degrees. This is a surface route rather than a straight chord through the planet; identical points return zero. SQL NULL propagates, and unusable coordinate values raise INVALID_ARGUMENT.

Example

geo_great_circle_distance(10.0, 20.0, 10.0, 20.0)
-- → 0.0

geo_h3_cell_area_m2

Measures the actual footprint of an H3 cell in square meters.

geo_h3_cell_area_m2(uint64) -> float64

Computes the area of the specified H3 cell, accounting for its own boundary instead of using a resolution-wide average. The uint64 argument must encode a valid cell, including a valid pentagon; other identifiers raise INVALID_ARGUMENT. SQL NULL returns NULL, and the float64 result uses square meters.

Example

geo_h3_cell_area_m2(617700169958293503) > 0
-- → true

geo_h3_cell_area_rads2

Expresses an individual H3 footprint as a solid angle in square radians.

geo_h3_cell_area_rads2(uint64) -> float64

Returns the spherical area subtended by the given H3 cell in radians squared, without multiplying by an Earth-radius scale. The value depends on the actual cell geometry, including pentagon shape. NULL stays NULL, while a malformed cell index or an edge identifier raises INVALID_ARGUMENT.

Example

geo_h3_cell_area_rads2(617700169958293503) > 0
-- → true

geo_h3_distance

Counts grid steps along a traversable route between equally resolved H3 cells.

geo_h3_distance(uint64,uint64) -> int64

Returns the minimum number of H3 grid moves between two valid cells at the same resolution, with identical inputs producing zero. Resolution mismatch, invalid indexes or pentagon distortion that prevents a supported path raises INVALID_ARGUMENT. A NULL endpoint yields NULL; distance is an integer grid measure rather than meters.

Example

geo_h3_distance(617700169958293503, 617700169958293503)
-- → 0

geo_h3_edge_angle

Returns average angular edge size for an H3 resolution, measured in radians.

geo_h3_edge_angle(uint8) -> float64

Looks up the mean H3 edge length at the supplied resolution and expresses that length as an angle in radians. Its uint8 argument is a resolution from zero through 15, not a directed-edge identifier; an out-of-range resolution raises INVALID_ARGUMENT. SQL NULL produces NULL.

Example

geo_h3_edge_angle(9) > 0
-- → true

geo_h3_edge_length_km

Reports typical H3 edge distance in kilometers at a selected grid level.

geo_h3_edge_length_km(uint8) -> float64

Returns the average edge length for the requested H3 resolution, using kilometers. The argument must be a resolution from zero through 15; INVALID_ARGUMENT reports other values and NULL returns NULL. This resolution statistic does not measure the boundary of a particular directed edge.

Example

geo_h3_edge_length_km(0) > 0
-- → true

geo_h3_edge_length_m

Gives the mean boundary-segment length in meters for an H3 resolution.

geo_h3_edge_length_m(uint8) -> float64

Evaluates the H3 resolution-level average edge length and returns a float64 number of meters. Only resolution values zero through 15 are accepted, with INVALID_ARGUMENT outside that interval. NULL is preserved, and callers needing an individual edge measurement must supply its identifier to the exact-edge operation.

Example

geo_h3_edge_length_m(15) > 0
-- → true

geo_h3_exact_edge_length_km

Measures a particular directed H3 boundary in kilometers from its edge identifier.

geo_h3_exact_edge_length_km(uint64) -> float64

Computes the length of the supplied directed edge rather than a mean over all cells at its resolution. Its uint64 input must be a valid directed-edge index; an ordinary cell identifier or malformed index raises INVALID_ARGUMENT. SQL NULL produces NULL and the result is expressed in kilometers.

Example

geo_h3_exact_edge_length_km(1266218516299644927) > 0
-- → true

geo_h3_exact_edge_length_m

Returns meter length for the concrete border selected by a directed H3 edge.

geo_h3_exact_edge_length_m(uint64) -> float64

Measures the actual geometric boundary represented by a directed H3 edge, returning meters as float64. Cell identifiers do not select an edge and raise INVALID_ARGUMENT, as do invalid edge encodings. A NULL edge returns NULL; reversing direction does not change the physical border length.

Example

geo_h3_exact_edge_length_m(1266218516299644927) > 0
-- → true

geo_h3_exact_edge_length_rads

Computes angular extent of one directed H3 border in radians.

geo_h3_exact_edge_length_rads(uint64) -> float64

Returns the angular length of the specified directed H3 edge using its actual boundary geometry. The result is in radians rather than degrees or a linear unit, and opposite directions along the same boundary have equal extent. NULL remains NULL; a non-edge or invalid index raises INVALID_ARGUMENT.

Example

geo_h3_exact_edge_length_rads(1266218516299644927) > 0
-- → true

geo_h3_get_base_cell

Identifies the resolution-zero ancestor number encoded inside an H3 cell.

geo_h3_get_base_cell(uint64) -> uint8

Extracts the base-cell number from a valid H3 cell index, returning uint8 in the interval zero through 121. This number identifies a root of the hierarchy and is not itself a complete H3 cell identifier. SQL NULL gives NULL, and invalid cell encodings raise INVALID_ARGUMENT.

Example

geo_h3_get_base_cell(617700169958293503)
-- → 20

geo_h3_get_destination_index_from_unidirectional_edge

Extracts the receiving H3 cell at the end of a directed edge.

geo_h3_get_destination_index_from_unidirectional_edge(uint64) -> uint64

Returns the cell index reached by following the input directed edge from its origin. Direction matters: the returned cell is the destination rather than the cell stored as the edge’s origin. SQL NULL remains NULL, and invalid or non-edge uint64 identifiers raise INVALID_ARGUMENT.

Example

geo_h3_get_destination_index_from_unidirectional_edge(1266218516299644927)
  <> 617700169958293503
-- → true

geo_h3_get_faces

Lists icosahedron face numbers touched by an H3 cell’s footprint.

geo_h3_get_faces(uint64) -> array(uint8)

Returns an array of the icosahedron face identifiers intersected by the specified cell, with face numbers in zero through 19. Cells crossing an icosahedral boundary can report more than one face; the array describes geometry, not hierarchy levels. NULL input returns NULL, and an invalid cell index raises INVALID_ARGUMENT.

Example

array_length(geo_h3_get_faces(617700169958293503)) >= 1
-- → true

geo_h3_get_indexes_from_unidirectional_edge

Returns the ordered pair of departure and arrival cells for a directed H3 connection.

geo_h3_get_indexes_from_unidirectional_edge(uint64) -> tuple(uint64,uint64)

Decodes a valid directed edge into a tuple containing its origin first and destination second. The tuple’s order preserves the edge direction and both entries are full uint64 cell identifiers. A NULL edge gives NULL, while a cell ID or malformed edge encoding raises INVALID_ARGUMENT.

Example

tuple_element(
  geo_h3_get_indexes_from_unidirectional_edge(1266218516299644927),
  1
)
-- → 617700169958293503

geo_h3_get_origin_index_from_unidirectional_edge

Recovers the starting cell encoded by a directional H3 border identifier.

geo_h3_get_origin_index_from_unidirectional_edge(uint64) -> uint64

Returns the origin cell from which the supplied directed H3 edge departs. Reversing the edge would exchange this origin with its destination, so this accessor is direction-sensitive. SQL NULL yields NULL and an identifier that does not encode a valid directed edge raises INVALID_ARGUMENT.

Example

geo_h3_get_origin_index_from_unidirectional_edge(1266218516299644927)
-- → 617700169958293503

geo_h3_get_pentagon_indexes

Enumerates the twelve pentagonal H3 cells at a requested resolution.

geo_h3_get_pentagon_indexes(uint8) -> array(uint64)

Returns the full set of twelve pentagon cell indexes for an H3 resolution from zero through 15. The number of pentagons stays twelve at every level even as the overall grid grows. NULL resolution returns NULL and a resolution outside the supported interval raises INVALID_ARGUMENT.

Example

array_length(geo_h3_get_pentagon_indexes(0))
-- → 12

geo_h3_get_res0_indexes

Lists all 122 root cells that cover the globe in the H3 hierarchy.

geo_h3_get_res0_indexes() -> array(uint64)

Returns an array containing every H3 cell at resolution zero, including both hexagons and pentagons. The function takes no arguments and always produces 122 non-NULL uint64 cell identifiers; there is no input NULL case. It provides the hierarchy’s complete root set without allocating per-row stream state.

Example

array_length(geo_h3_get_res0_indexes())
-- → 122

geo_h3_get_resolution

Reads the grid refinement level from an H3 cell identifier.

geo_h3_get_resolution(uint64) -> uint8

Returns the resolution encoded in a valid H3 cell as uint8, ranging from zero at the root level through 15 at the finest supported level. It validates that the uint64 value is a cell before extracting the level; malformed identifiers raise INVALID_ARGUMENT. SQL NULL produces NULL.

Example

geo_h3_get_resolution(617700169958293503)
-- → 9

geo_h3_get_unidirectional_edge

Constructs an H3 edge directed from one adjacent cell toward another.

geo_h3_get_unidirectional_edge(uint64,uint64) -> uint64

Builds a directed-edge index from the supplied origin and destination cell indexes, preserving their order. Both cells must be valid, adjacent and at the same resolution; equal cells, non-neighbors and malformed inputs raise INVALID_ARGUMENT. A NULL endpoint returns NULL.

Example

geo_h3_get_unidirectional_edge(617700169958293503, 617700169958293503)
-- → INVALID_ARGUMENT

geo_h3_get_unidirectional_edge_boundary

Returns latitude/longitude vertices describing a directed H3 boundary segment.

geo_h3_get_unidirectional_edge_boundary(uint64) -> array(tuple(float64,float64))

Expands a directed-edge identifier into its boundary points, represented as latitude/longitude tuples in degrees. A boundary may contain additional vertices where the projection crosses an icosahedron face; callers must not assume exactly two points. SQL NULL stays NULL, and invalid edge encodings raise INVALID_ARGUMENT.

Example

array_length(geo_h3_get_unidirectional_edge_boundary(1266218516299644927)) >= 2
-- → true

geo_h3_get_unidirectional_edges_from_hexagon

Enumerates outgoing H3 connections from a cell, omitting the absent pentagon direction.

geo_h3_get_unidirectional_edges_from_hexagon(uint64) -> array(uint64)

Returns directed-edge identifiers for every valid edge leaving the supplied H3 cell. Ordinary hexagons contribute six outgoing edges, while pentagons contribute five with the missing direction omitted rather than represented by an invalid placeholder. NULL returns NULL; an invalid cell index raises INVALID_ARGUMENT.

Example

array_length(geo_h3_get_unidirectional_edges_from_hexagon(617700169958293503))
-- → 6

geo_h3_hex_area_km2

Reports average hexagon coverage in square kilometers for an H3 grid level.

geo_h3_hex_area_km2(uint8) -> float64

Returns the average area of H3 hexagons at the requested resolution, expressed in square kilometers. This is a resolution statistic rather than the actual footprint of a chosen cell or pentagon. SQL NULL yields NULL, and any resolution outside zero through 15 raises INVALID_ARGUMENT.

Example

geo_h3_hex_area_km2(9) > 0
-- → true

geo_h3_hex_area_m2

Provides mean hexagonal footprint in square meters at a specified H3 resolution.

geo_h3_hex_area_m2(uint8) -> float64

Looks up the H3 hexagon area averaged across the selected resolution and returns square meters. The measurement does not identify a particular cell and does not treat pentagons as ordinary hexagons. NULL input remains NULL; the resolution must lie from zero through 15 or INVALID_ARGUMENT is raised.

Example

geo_h3_hex_area_m2(15) > 0
-- → true

geo_h3_hex_ring

Lists H3 cells lying exactly a chosen number of grid moves from an origin.

geo_h3_hex_ring(uint64,uint32) -> array(uint64)

Returns the ring at exactly k grid steps from the supplied cell, rather than all cells within that radius; k=0 returns the origin alone. Invalid indexes and grid distortion that prevents ring traversal raise INVALID_ARGUMENT, and output exceeding the value budget raises RESOURCE_LIMIT. A NULL argument yields NULL.

Example

geo_h3_hex_ring(617700169958293503, 0)
-- → [617700169958293503]

geo_h3_indexes_are_neighbors

Tests whether two H3 cells at the same level share a border.

geo_h3_indexes_are_neighbors(uint64,uint64) -> bool

Returns true when the two valid H3 cells share an edge and false when they do not, including when they are identical. Inputs must use the same resolution; malformed indexes or a resolution mismatch raise INVALID_ARGUMENT. If either operand is SQL NULL, the result is NULL rather than false.

Example

geo_h3_indexes_are_neighbors(617700169958293503, 617700169958293503)
-- → false

geo_h3_is_pentagon

Identifies five-sided H3 cells from their validated indexes.

geo_h3_is_pentagon(uint64) -> bool

Returns true for an H3 pentagon and false for an ordinary hexagonal cell. The check applies at every supported resolution, not only to the twelve base pentagons. SQL NULL remains NULL; a malformed cell index raises INVALID_ARGUMENT rather than being treated as a valid hexagon.

Example

geo_h3_is_pentagon(617700169958293503)
-- → false

geo_h3_is_res_class_iii

Tests whether an H3 cell uses an odd, rotated Class III grid resolution.

geo_h3_is_res_class_iii(uint64) -> bool

Returns true for Class III resolutions, the odd-numbered H3 levels, and false for even Class II levels. The predicate derives orientation class from a valid cell index rather than checking polygon shape. NULL gives NULL, and an invalid cell encoding raises INVALID_ARGUMENT.

Example

geo_h3_is_res_class_iii(617700169958293503)
-- → true

geo_h3_is_valid

Checks whether an unsigned identifier encodes a well-formed H3 cell.

geo_h3_is_valid(uint64) -> bool

Returns true for a structurally valid H3 cell index and false for invalid bit patterns or identifiers representing another H3 object such as a directed edge. A malformed index is an ordinary false result, not an INVALID_ARGUMENT failure. SQL NULL still produces NULL; incompatible argument types raise TYPE_MISMATCH.

Example

geo_h3_is_valid(0)
-- → false

geo_h3_line

Builds a shortest traversable sequence of H3 cells joining two endpoints.

geo_h3_line(uint64,uint64) -> array(uint64)

Returns a cell path containing both endpoints in traversal order, with identical endpoints yielding a one-element array. Inputs must be valid cells at equal resolution; incompatible paths caused by distortion raise INVALID_ARGUMENT explicitly. NULL returns NULL, and a path exceeding the output-value budget raises RESOURCE_LIMIT.

Example

geo_h3_line(617700169958293503, 617700169958293503)
-- → [617700169958293503]

geo_h3_num_hexagons

Counts every H3 cell at a resolution, including the twelve pentagons.

geo_h3_num_hexagons(uint8) -> uint64

Returns the total grid population at resolution r, equal to 2+120*7^r. Despite the historical name, the count includes pentagonal cells and therefore starts at 122 for resolution zero. SQL NULL gives NULL, and a resolution outside zero through 15 raises INVALID_ARGUMENT.

Example

geo_h3_num_hexagons(1)
-- → 842

geo_h3_point_dist_km

Measures spherical separation in kilometers using latitude-first point coordinates.

geo_h3_point_dist_km(float64,float64,float64,float64) -> float64

Computes the H3 spherical point distance from latitude1, longitude1, latitude2, longitude2, with all coordinates in degrees. The returned float64 distance is in kilometers and becomes zero for coincident positions. A NULL coordinate produces NULL; nonfinite or invalid latitude/longitude values raise INVALID_ARGUMENT.

Example

geo_h3_point_dist_km(45.0, 10.0, 45.0, 10.0)
-- → 0.0

geo_h3_point_dist_m

Returns meter separation between two latitude/longitude points under H3’s spherical model.

geo_h3_point_dist_m(float64,float64,float64,float64) -> float64

Evaluates spherical point-to-point distance with latitude before longitude for each position, interpreting input angles in degrees. The linear output is measured in meters rather than an H3 grid-step count. SQL NULL propagates, coincident points have zero distance and invalid coordinates raise INVALID_ARGUMENT.

Example

geo_h3_point_dist_m(0.0, 0.0, 0.0, 0.0)
-- → 0.0

geo_h3_point_dist_rads

Returns angular separation in radians from latitude/longitude coordinates supplied in degrees.

geo_h3_point_dist_rads(float64,float64,float64,float64) -> float64

Computes the central angle between latitude-first geographic point pairs using H3’s spherical distance calculation. Inputs are degrees while the output is radians, so antipodal points have angular distance pi. NULL coordinates yield NULL, and invalid or nonfinite geographic values raise INVALID_ARGUMENT.

Example

geo_h3_point_dist_rads(0.0, 0.0, 0.0, 0.0)
-- → 0.0

geo_h3_polygon_to_cells

Finds H3 cells whose centers fall inside a polygon’s outer ring and outside its holes.

geo_h3_polygon_to_cells(array(array(tuple(float64,float64))),uint8) -> array(uint64)

Covers a polygon at the chosen H3 resolution using cell-center containment, with latitude/longitude degree tuples and the first ring as the exterior. Subsequent rings are holes; malformed rings or resolution outside zero through 15 raise INVALID_ARGUMENT. A NULL input gives NULL and coverage exceeding the output-value budget raises RESOURCE_LIMIT.

Example

geo_h3_polygon_to_cells(NULL, 9)
-- → NULL

geo_h3_to_center_child

Selects the central descendant of an H3 cell at an explicitly finer resolution.

geo_h3_to_center_child(uint64,uint8) -> uint64

Returns the center child reached by refining the supplied H3 cell to the requested level. The target must be finer than the source and no greater than 15; invalid cells or incompatible resolutions raise INVALID_ARGUMENT. SQL NULL propagates, and the result remains one cell identifier regardless of refinement depth.

Example

geo_h3_get_resolution(geo_h3_to_center_child(617700169958293503, 10))
-- → 10

geo_h3_to_children

Expands an H3 ancestor into all descendants at a selected finer grid level.

geo_h3_to_children(uint64,uint8) -> array(uint64)

Returns all children of the input cell at the explicitly requested finer resolution, handling pentagon ancestry according to H3’s hierarchy. Invalid indexes or target levels that are not finer or exceed 15 raise INVALID_ARGUMENT; oversized expansions raise RESOURCE_LIMIT. SQL NULL gives NULL, and the array contains full cell identifiers.

Example

array_length(geo_h3_to_children(617700169958293503, 10))
-- → 7

geo_h3_to_geo

Locates an H3 cell’s center as a latitude/longitude tuple in degrees.

geo_h3_to_geo(uint64) -> tuple(float64,float64)

Returns the geographic center of a valid H3 cell as a two-field tuple, with latitude first and longitude second. The coordinates are degrees, so consumers must convert explicitly before using radian-based formulas. SQL NULL returns NULL and an invalid cell index raises INVALID_ARGUMENT.

Example

tuple_element(geo_h3_to_geo(617700169958293503), 1) BETWEEN -90 AND 90
-- → true

geo_h3_to_geo_boundary

Expands a cell identifier into its perimeter coordinates in latitude-first order.

geo_h3_to_geo_boundary(uint64) -> array(tuple(float64,float64))

Returns the H3 cell boundary as an array of latitude/longitude tuples in degrees. Pentagon shape and icosahedron-face crossings can alter the vertex count, so callers should use the complete returned array rather than assume six vertices. NULL stays NULL; invalid cell encodings raise INVALID_ARGUMENT.

Example

array_length(geo_h3_to_geo_boundary(617700169958293503)) >= 5
-- → true

geo_h3_to_parent

Finds an H3 cell’s ancestor at an explicitly coarser hierarchy level.

geo_h3_to_parent(uint64,uint8) -> uint64

Returns the ancestor cell at the supplied lower resolution while preserving the source’s hierarchy branch. The target must be coarser than the input and within zero through 15; invalid cells or resolution choices raise INVALID_ARGUMENT. A NULL operand returns NULL, and the output is a full uint64 index rather than a base-cell number.

Example

geo_h3_get_resolution(geo_h3_to_parent(617700169958293503, 8))
-- → 8

geo_h3_to_string

Formats a validated H3 identifier in its canonical hexadecimal notation.

geo_h3_to_string(uint64) -> string

Serializes a cell index as canonical lowercase hexadecimal H3 text, without an SQL hexadecimal-literal prefix. The resulting text identifies the same cell and does not expose host byte order. SQL NULL produces NULL, while an invalid cell encoding raises INVALID_ARGUMENT.

Example

geo_h3_to_string(617700169958293503)
-- → '8928308280fffff'

geo_h3_unidirectional_edge_is_valid

Checks whether a uint64 encodes a structurally valid directed H3 edge.

geo_h3_unidirectional_edge_is_valid(uint64) -> bool

Returns true for valid directed-edge indexes and false for malformed values or ordinary cell identifiers. Unlike edge accessors, invalid encodings are predicate results and do not raise INVALID_ARGUMENT. SQL NULL stays NULL, and a value of an incompatible SQL type raises TYPE_MISMATCH.

Example

geo_h3_unidirectional_edge_is_valid(617700169958293503)
-- → false

geo_hash_decode

Decodes a geohash into the longitude/latitude center of its encoded region.

geo_hash_decode(string) -> tuple(float64,float64)

Returns the center of a geohash cell as a longitude-first coordinate tuple in degrees. Resolution is determined by the input string length, so decoding does not recover the exact original point within the cell. NULL yields NULL; invalid characters or an incompatible geohash length raise INVALID_ARGUMENT.

Example

geo_hash_decode('s')
-- → (22.5, 22.5)

geo_hash_encode

Encodes longitude and latitude into a geohash with a chosen character precision.

geo_hash_encode(float64,float64) -> string
geo_hash_encode(float64,float64,uint8) -> string

Returns a geohash for longitude and latitude in degrees, using a precision of 12 characters when omitted. An explicit precision must be between one and 12; invalid precision, nonfinite coordinates or coordinates outside the geographic domain raise INVALID_ARGUMENT. NULL in a supplied argument produces NULL.

Example

geo_hash_encode(1.0, 1.0, 1)
-- → 's'

geo_hashes_in_box

Lists geohash cells covering a longitude/latitude bounding rectangle at fixed precision.

geo_hashes_in_box(float64,float64,float64,float64,uint8) -> array(string)

Enumerates geohashes for the box specified by longitude_min, latitude_min, longitude_max, latitude_max and character precision. Invalid geographic bounds or precision outside one through 12 raise INVALID_ARGUMENT; a result exceeding the engine’s output-value budget raises RESOURCE_LIMIT. SQL NULL in any argument returns NULL.

Example

geo_hashes_in_box(1.0, 1.0, 2.0, 2.0, 1)
-- → ['s']

geo_read_wkb_line_string

Parses a WKB LineString into an ordered array of Cartesian coordinate pairs.

geo_read_wkb_line_string(bytes) -> array(tuple(float64,float64))

Decodes a Well-Known Binary LineString into array(tuple(float64,float64)), retaining the encoded x,y point order. The WKB byte-order marker controls numeric decoding; truncated bytes or a geometry tag other than LineString raises INVALID_ARGUMENT. SQL NULL returns NULL, and an oversized coordinate array raises RESOURCE_LIMIT.

Example

geo_read_wkb_line_string(hex_decode('010200000000000000'))
-- → []

geo_read_wkb_multi_line_string

Decodes a WKB MultiLineString into separate ordered coordinate arrays for each component.

geo_read_wkb_multi_line_string(bytes) -> array(array(tuple(float64,float64)))

Parses Well-Known Binary MultiLineString data as an array of line arrays, each containing x,y float64 tuples. This preserves component boundaries even though the nested physical type also represents polygon rings elsewhere. NULL yields NULL; malformed binary data or incorrect geometry tags raise INVALID_ARGUMENT, and excessive decoded output raises RESOURCE_LIMIT.

Example

geo_read_wkb_multi_line_string(hex_decode('010500000000000000'))
-- → []

geo_read_wkb_multi_polygon

Decodes WKB MultiPolygon bytes into nested polygon, ring and coordinate arrays.

geo_read_wkb_multi_polygon(bytes) -> array(array(array(tuple(float64,float64))))

Parses a WKB MultiPolygon and returns an array of polygons, each represented by an exterior ring followed by interior rings of (x,y) tuples. The WKB byte-order marker determines how coordinates are decoded, and an empty multipolygon returns an empty array. SQL NULL propagates; truncated bytes, an invalid marker or a different geometry tag raise INVALID_ARGUMENT.

Example

geo_read_wkb_multi_polygon(hex_decode('010600000000000000'))
-- → []

geo_read_wkb_point

Reads one Cartesian coordinate pair from a binary WKB Point.

geo_read_wkb_point(bytes) -> tuple(float64,float64)

Decodes the WKB Point header and returns its two coordinates as a tuple of float64 values in x,y order. Either WKB byte order is interpreted from the header; this operation does not transform coordinates or infer a geographic reference system. NULL input returns NULL, while malformed payloads or a non-Point tag raise INVALID_ARGUMENT.

Example

geo_read_wkb_point(hex_decode('0101000000000000000000F03F0000000000000040'))
-- → (1, 2)

geo_read_wkb_polygon

Restores a polygon's outer boundary and hole rings from WKB binary geometry.

geo_read_wkb_polygon(bytes) -> array(array(tuple(float64,float64)))

Reads WKB Polygon bytes into an array of rings, with the exterior ring first and each hole represented by another array of (x,y) tuples. Encoded coordinate order is preserved, including any ring-closing coordinate, and an empty polygon has no rings. NULL propagates; malformed binary data or an unexpected geometry type raises INVALID_ARGUMENT.

Example

geo_read_wkb_polygon(hex_decode('010300000000000000'))
-- → []

geo_s2_cap_contains

Tests whether an S2 point lies inside a spherical cap defined by a center and angular radius.

geo_s2_cap_contains(uint64,float64,uint64) -> bool

Uses the first cell ID as the cap center, the second argument as its radius in degrees, and the final ID as the candidate point. The closed cap includes its boundary and a zero-radius cap contains its center. Any NULL argument yields NULL, while invalid S2 IDs or radii outside the spherical range raise INVALID_ARGUMENT.

Example

geo_s2_cap_contains(1152921504606846976, 0, 1152921504606846976)
-- → true

geo_s2_cap_union

Returns the center ID and degree radius of a spherical cap enclosing two input caps.

geo_s2_cap_union(uint64,float64,uint64,float64) -> tuple(uint64,float64)

Accepts two center-ID and angular-radius pairs and constructs an enclosing S2 cap, returning its center ID and radius in degrees. The output is a cap bound rather than an arbitrary two-region geometry, so it can cover points outside both original caps. NULL propagates; invalid cell IDs or radius arguments raise INVALID_ARGUMENT.

Example

geo_s2_cap_union(1152921504606846977, 0, 1152921504606846977, 0)
-- → (1152921504606846977, 0)

geo_s2_cells_intersect

Determines whether two S2 cell regions overlap on the sphere.

geo_s2_cells_intersect(uint64,uint64) -> bool

Compares two valid S2 cells at their encoded levels and reports whether their hierarchical cell regions intersect. Identical IDs and a cell paired with its ancestor intersect; merely being nearby does not imply a match. SQL NULL returns NULL, and malformed cell identifiers raise INVALID_ARGUMENT.

Example

geo_s2_cells_intersect(1152921504606846976, 1152921504606846976)
-- → true

geo_s2_get_neighbors

Lists the edge-adjacent S2 cells at the same subdivision level as an input cell.

geo_s2_get_neighbors(uint64) -> array(uint64)

Returns an array of the cell's same-level edge neighbors, including neighbors across S2 face boundaries. Corner-only adjacency is excluded, and the result contains four neighbors rather than all nearby descendants. NULL input yields NULL; an invalid S2 cell ID raises INVALID_ARGUMENT.

Example

array_length(geo_s2_get_neighbors(1152921504606846976))
-- → 4

geo_s2_rect_add

Expands an S2 latitude–longitude rectangle to include an additional point.

geo_s2_rect_add(uint64,uint64,uint64) -> tuple(uint64,uint64)

Interprets the first two IDs as southwest and northeast corners and enlarges their spherical rectangle to include the third ID's point. Returns the new corner-ID pair, preserving the original rectangle when the point is already contained. Any NULL produces NULL, while invalid IDs or an invalid rectangle specification raise INVALID_ARGUMENT.

Example

geo_s2_rect_add(1152921504606846977, 1152921504606846977, 1152921504606846977)
-- → (1152921504606846977, 1152921504606846977)

geo_s2_rect_contains

Checks a candidate S2 point against southwest and northeast rectangle corners.

geo_s2_rect_contains(uint64,uint64,uint64) -> bool

Tests whether the candidate point represented by the third ID belongs to the closed spherical latitude–longitude rectangle given by the first two IDs. Rectangle edges are included, and longitude intervals follow the S2 rectangle convention across the antimeridian. NULL arguments propagate; malformed IDs or rectangle bounds raise INVALID_ARGUMENT.

Example

geo_s2_rect_contains(
  1152921504606846976,
  1152921504606846976,
  1152921504606846976
)
-- → true

geo_s2_rect_intersection

Finds shared S2 rectangle bounds, using the corner pair (0,0) when no overlap exists.

geo_s2_rect_intersection(uint64,uint64,uint64,uint64) -> tuple(uint64,uint64)

Takes southwest and northeast IDs for each of two spherical rectangles and returns the intersection's corner pair. Disjoint inputs return the explicit empty sentinel (0,0), whose zeros are not valid ordinary cell corners. NULL propagates, while invalid non-sentinel cell IDs or malformed rectangle bounds raise INVALID_ARGUMENT.

Example

geo_s2_rect_intersection(
  1152921504606846977,
  1152921504606846977,
  1152921504606846977,
  1152921504606846977
)
-- → (1152921504606846977, 1152921504606846977)

geo_s2_rect_union

Computes the southwest and northeast corners of a rectangle enclosing two S2 rectangles.

geo_s2_rect_union(uint64,uint64,uint64,uint64) -> tuple(uint64,uint64)

Returns an enclosing spherical latitude–longitude rectangle from the two supplied southwest/northeast corner pairs. This rectangular bound can include locations in the gap between the input rectangles, rather than returning a multipart union. SQL NULL yields NULL, and invalid IDs or inconsistent rectangle specifications raise INVALID_ARGUMENT.

Example

geo_s2_rect_union(
  1152921504606846977,
  1152921504606846977,
  1152921504606846977,
  1152921504606846977
)
-- → (1152921504606846977, 1152921504606846977)

geo_s2_to_geo

Decodes a spherical S2 identifier into the geographic midpoint of its footprint.

geo_s2_to_geo(uint64) -> tuple(float64,float64)

Decodes a valid S2 cell identifier and returns its geographic center as a float64 (longitude, latitude) tuple in degrees. The point is the center at the cell's encoded level, rather than its boundary or the original point used to choose that cell. NULL remains NULL, and an invalid identifier raises INVALID_ARGUMENT.

Example

geo_s2_to_geo(1152921504606846976)
-- → (0, 0)