This section captures the operational knowledge consumers need on top of the function reference: when tquadbin is the right type, the conventions the implementation assumes, and the QUADBIN-specific hazards real workloads need to be aware of. The QUADBIN hierarchical square grid has a few non-obvious properties that the bitwise int64 encoding hides; this section surfaces them so they don't surprise consumers.
Use tquadbin when the natural identifier for a discrete location at a given resolution is a QUADBIN tile — vehicle trips bucketed at a fixed zoom level, sensor readings binned by tile, or events keyed by their containing cell, especially in pipelines that already speak the slippy-map / web-mercator tiling scheme. The type stores one QUADBIN cell per instant; resolution may vary across instants in a single trajectory but most workloads pin one resolution per column.
Choose tgeompoint / tgeogpoint over tquadbin when the actual geographic position (sub-cell precision) is the value of interest. Choose tbigint over tquadbin when the values happen to be 64-bit integers but carry no QUADBIN semantics — the binary representations are identical (they cast losslessly via tquadbin :: tbigint and back) but the SQL type system uses the distinction to reject quadbin-agnostic functions on quadbin-specific trajectories.
A few hazards reliably bite workloads using QUADBIN cells. Each is a property of the QUADBIN grid itself rather than a MobilityDB implementation choice; the mitigations below explain how to work with them.
Int64 ordering is arbitrary with respect to grid geometry. QUADBIN cell identifiers are 64-bit integers whose bitpattern encodes a header tag, resolution, and tile coordinates. The bitwise ordering of two cells carries no spatial-proximity meaning — two cells that are bit-adjacent may be far apart, and two cells that are spatially adjacent may have different bitpatterns.
Mitigation: tquadbin deliberately has no quadbinspan / quadbinspanset companion types (precedent: geometry has no geometryspan). Value-range filtering must go through the quadbin_* inspection functions (resolution, validity, hierarchy) or explicit set enumeration via quadbinset. Code that assumes cell_a < cell_b reflects spatial proximity will silently produce wrong results.
Resolution mixing in operations. QUADBIN cells at different resolutions (0–26) represent different coverage areas. Mixing resolutions in a single trajectory is valid but semantically requires explicit justification — quadbinCellToParent(cell, coarser_res) coarsens and quadbinCellToChildren(parent, finer_res) refines.
Mitigation: consumers should document the resolution invariant per trajectory (e.g. "all cells are resolution 10") and validate inputs at the ingestion boundary. The quadbinGetResolution accessor lets a CHECK constraint enforce this.
Web-mercator latitude limit. QUADBIN inherits the web-mercator projection, which is defined only between approximately ±85.05° latitude. Points outside this band have no QUADBIN cell, and cell area shrinks toward the poles — quadbinCellArea returns progressively smaller values at higher latitudes for cells of the same resolution.
Mitigation: workloads near the poles should clamp or reject latitudes outside the web-mercator band at the ingestion boundary; do not rely on QUADBIN cells for polar coverage.
Antimeridian behaviour. Tile columns wrap at the antimeridian (±180° longitude). A trajectory crossing the antimeridian moves between cells whose tile x coordinates differ by the full width of the grid at that zoom, even though they are spatially adjacent.
Mitigation: workloads that cross the antimeridian should validate representative cells against the QUADBIN reference implementation and add fixtures for the specific edge cases the workload encounters.
The on-disk representation of tquadbin is byte-identical to tbigint (each instant carries one 64-bit QUADBIN cell ID plus a timestamp). Consequences for storage planning:
WKT via tquadbin_in and the temporal output function. Cells render as canonical hex strings (e.g. '480fffffffffffff'); both decimal and hex are accepted on input. Round-trip is bit-stable.
WKB / EWKB / HexWKB via the standard PostGIS endian-flag-then-payload pattern. Stable across PostgreSQL major versions.
pg_dump uses WKT in plain mode and WKB under --binary-upgrade; both round-trip cleanly.
Cross-cast with tbigint: the bidirectional tquadbin :: tbigint casts are zero-cost bitwise reinterpretations. Use them when working with both type-safe (tquadbin) and arithmetic-friendly (tbigint) views of the same trajectory in a single query.