Esta sección recoge el conocimiento operativo que los consumidores necesitan además de la referencia de funciones: cuándo th3index es el tipo adecuado, las convenciones que asume la implementación y los peligros específicos de H3 que las cargas de trabajo reales deben tener en cuenta. La cuadrícula hexagonal jerárquica de H3 tiene algunas propiedades no evidentes que la codificación binaria int64 oculta; esta sección las expone para que no sorprendan a los consumidores.
Use th3index cuando el identificador natural de una ubicación discreta a una resolución dada sea una celda H3 — viajes de vehículos agrupados a la resolución H3 9, lecturas de sensores ambientales agrupadas por celda H3, eventos geo-cercados identificados por su celda contenedora. El tipo almacena una celda H3 por instante; la resolución puede variar entre los instantes de una misma trayectoria, pero la mayoría de las cargas de trabajo fijan una resolución por columna.
Elija tgeompoint / tgeogpoint en lugar de th3index cuando el valor de interés sea la posición geográfica real (precisión subcelular). Elija tbigint en lugar de th3index cuando los valores resulten ser enteros de 64 bits pero no tengan semántica H3 — las representaciones binarias son idénticas (se convierten sin pérdida mediante th3index :: tbigint y viceversa) pero el sistema de tipos SQL usa la distinción para rechazar funciones agnósticas a H3 sobre trayectorias específicas de H3.
Cinco peligros afectan de forma fiable a las cargas de trabajo que usan celdas H3. Cada uno es una propiedad de la cuadrícula H3 en sí más que una decisión de implementación de MobilityDB; las mitigaciones siguientes explican cómo trabajar con ellos.
El orden int64 es arbitrario respecto a la geometría de la cuadrícula. Los identificadores de celda H3 son enteros sin signo de 64 bits cuyo patrón de bits codifica resolución, celda base y posición jerárquica. El orden binario de dos celdas no tiene significado geográfico — dos celdas adyacentes en bits pueden estar en lados opuestos del planeta, y dos celdas espacialmente adyacentes pueden tener patrones de bits muy distintos.
Mitigación: th3index deliberadamente no tiene tipos compañeros h3span / h3spanset (precedente: geometry no tiene geometryspan), y los índices de caja envolvente capturan la extensión espaciotemporal de las celdas (stbox), no el valor del identificador de celda. El filtrado por rango de valores debe pasar por funciones de inspección h3_* (resolución, celda base, comprobaciones de jerarquía) o la enumeración explícita de conjuntos mediante h3indexset. El código que asume que cell_a < cell_b refleja proximidad espacial producirá resultados silenciosamente erróneos.
Mezcla de resoluciones en las operaciones. Las celdas H3 a distintas resoluciones (0–15) representan áreas de cobertura diferentes. Mezclar resoluciones en una misma trayectoria es válido pero semánticamente requiere justificación explícita — th3CellToParent(cell, coarser_res) engrosa, h3CellToChildren(parent, finer_res) refina, y h3CompactCells / h3UncompactCells realizan el ciclo de ida y vuelta correctamente solo cuando las resoluciones de entrada son compatibles.
Mitigación: los consumidores deberían documentar el invariante de resolución por trayectoria (p. ej. "todas las celdas son de resolución 9") y validar las entradas en el límite de ingesta. El accesor th3GetResolution permite que una restricción CHECK lo imponga.
Celdas pentagonales. La cuadrícula H3 tiene 12 celdas pentagonales (en lugar de hexagonales) por resolución — los duales de Eisenstein de los 12 vértices del icosaedro. h3GridRing puede fallar cerca de estos pentágonos; h3GridPathCells falla si el camino cruza uno. El error es explícito (libh3 lanza un fallo explícito), pero las cargas de trabajo que esperan que las operaciones de anillo / camino siempre tengan éxito necesitan una protección.
Mitigación: el código defensivo debería envolver las llamadas sensibles a pentágonos y comprobar h3_is_pentagon_cell en las entradas y salidas clave. Para trayectorias que pasan cerca de un pentágono, recurra a h3GridDisk (que es seguro ante pentágonos) o calcule los segmentos del camino por partes alrededor del pentágono.
Ciclo de compactación / descompactación. h3CompactCells produce la representación mixta de resoluciones más compacta de un conjunto de celdas; h3UncompactCells la expande de nuevo. El ciclo es sin pérdida en extensión espacial, pero el orden de las celdas no se preserva — libh3 no garantiza una salida ordenada. Las consultas que consumen la salida como si su orden fuera estable devolverán resultados distintos antes y después de la compactación aunque el conjunto espacial subyacente sea idéntico.
Mitigación: reordene tras la compactación si el orden importa (p. ej. ORDER BY cell en SQL o ARRAY_AGG ... ORDER BY 1 al materializar). Para conjuntos temporales, prefiera la semántica de igualdad de conjuntos de h3indexset sobre la de igualdad de arreglos.
Comportamiento en el antimeridiano y los polos. Las celdas base de H3 se posicionan sobre un icosaedro; a altas resoluciones algunas celdas cerca del antimeridiano o los polos pueden tener una geometría poco intuitiva. th3CellToLatlng / h3_latlng_to_cell realizan el ciclo de ida y vuelta correctamente, pero las coordenadas cerca de ±180° de longitud o cerca de los polos pueden resolverse a celdas en grupos de celdas base inesperados.
Mitigación: las cargas de trabajo en latitudes polares o que cruzan el antimeridiano deberían validar celdas representativas contra la implementación de referencia de libh3 directamente y añadir fixtures para los casos límite específicos que la carga de trabajo encuentre.
La representación en disco de th3index es byte a byte idéntica a la de tbigint (cada instante lleva un ID de celda H3 de 64 bits más una marca de tiempo). Consecuencias para la planificación del almacenamiento:
WKT mediante th3_in y th3_out. Las celdas se representan como cadenas hexadecimales canónicas (p. ej. '8928308280fffff'); se aceptan tanto decimal como hexadecimal en la entrada. El ciclo de ida y vuelta es estable a nivel de bits.
WKB / EWKB / HexWKB mediante el patrón estándar de PostGIS de bandera de endianidad seguida de la carga útil. Estable entre versiones mayores de PostgreSQL.
MFJSON mediante asMFJSON(th3index) y th3indexFromMFJSON(text). La carga útil de la celda se representa como el identificador int64 de la celda en el arreglo values, la misma representación que utiliza tbigint; los consumidores que necesiten la forma hexadecimal canónica aplican h3_cell_to_string.
pg_dump usa WKT en modo plano y WKB bajo --binary-upgrade; ambos realizan el ciclo de ida y vuelta limpiamente.
Conversión cruzada con tbigint: las conversiones bidireccionales th3index :: tbigint son reinterpretaciones binarias sin coste. Úselas al trabajar con vistas tanto seguras por tipo (th3index) como aptas para aritmética (tbigint) de la misma trayectoria en una sola consulta.