Funções H3 geoespaciais
Aplica-se a: 
Databricks SQL Azure Databricks Runtime
H3 é um sistema global de indexação de grade. Sistemas de grade usam uma forma, como retângulos ou triângulos, para criar mosaico em uma superfície, que neste caso é a superfície da Terra. O sistema H3 foi projetado para usar hexágonos (e alguns pentágonos) e oferece 16 níveis de resoluções dentro de sua hierarquia. Em resoluções mais altas, as formas tesseladas são menores.
As expressões H3 têm suporte somente em clusters habilitados para Photon e warehouses do Databricks SQL nas camadas pro/sem servidor do Databricks SQL.
Leia mais sobre resoluções do H3 e sobre as origens do H3.
Consulte também:
- Início Rápido do H3 (Databricks SQL)
- Exemplo de funções geoespaciais H3
- Lista alfabética de funções H3 geoespaciais
H3 para Análise Geoespacial
O H3 dá suporte a um padrão comum para processar e analisar dados espaciais. Comece indexando dados geoespaciais de formatos padrão (latitude e longitude, WKT (texto conhecido),WKB (binário conhecido) ou GeoJSON para IDs de célula H3. Com um único conjunto de dados, você pode agregar por ID de célula para responder a perguntas controladas por localização. Com vários conjuntos de dados indexados, é possível combiná-los usando as IDs de célula, revelando como conjuntos de dados diferentes se relacionam um com o outro. Essa junção de conjuntos de dados é semanticamente uma junção espacial, mas sem a necessidade de um predicado espacial.
Quais são os benefícios de usar o H3 no Databricks?
Aproveite os recursos do Delta Lake para obter um armazenamento e layout eficientes dos dados indexados do H3. A operação OPTIMIZE do Delta Lake com ordenação Z (em IDs de célula H3) permite que você co-localize dados espacialmente. Além disso, os algoritmos de omissão de dados do Delta Lake usam a co-localidade para reduzir de forma inteligente o volume de dados que precisa ser lido.
Você tem flexibilidade no modo como trabalha com os dados. Você pode optar por trabalhar com IDs de célula H3 armazenadas como grandes inteiros ou cadeias de caracteres. Para obter o melhor desempenho usando IDs de célula H3, use a representação de inteiro grande. Para ver o uso detalhado de expressões H3, confira o guia de referência do SQL.
Observação
Você não precisa instalar a biblioteca H3. Ela está incluída como uma dependência visível no Databricks Runtime, a partir do Databricks Runtime 11.2, usando a versão 3.7.0 da biblioteca Java H3.
Importar funções do Databricks para obter H3 (Databricks Runtime)
Nenhuma importação necessária para o SQL do Databricks e o SQL do Spark.
Para importar funções H3 para Python ou Scala em notebooks, use os comandos a seguir:
Python
from pyspark.databricks.sql import functions as dbf
Scala
import com.databricks.sql.functions._
Lista de funções H3 geoespaciais (Databricks SQL)
Importar
| Função | Descrição |
|---|---|
| h3_coverash3(geographyExpr, resolutionExpr) | Retorna uma ARRAY de IDs de célula H3 (representadas como BIGINT) correspondentes ao conjunto mínimo de hexágonos ou pentágonos, da resolução especificada, que cobrem totalmente a área ou linha geográfica de entrada. |
| h3_coverash3string(geographyExpr, resolutionExpr) | Retorna uma ARRAY de IDs de célula H3 (representadas como STRING) correspondentes ao conjunto mínimo de hexágonos ou pentágonos, da resolução especificada, que cobrem totalmente a área ou linha geográfica de entrada. |
| h3_longlatash3(longitudeExpr, latitudeExpr, resolutionExpr) | Retorna a ID da célula H3 (como um BIGINT) correspondente à longitude e latitude fornecidas na resolução especificada. |
| h3_longlatash3string(longitudeExpr, latitudeExpr, resolutionExpr) | Retorna a ID da célula H3 (como uma série hexadecimal) correspondente à longitude e latitude fornecidas na resolução especificada. |
| h3_pointash3(geographyExpr, resolutionExpr) | Retorna a ID da célula H3 (como um BIGINT) correspondente ao ponto fornecido na resolução especificada. |
| h3_pointash3string(geographyExpr, resolutionExpr) | Retorna a ID da célula H3 (como uma STRING) correspondente ao ponto fornecido na resolução especificada. |
| h3_polyfillash3(geographyExpr, resolutionExpr) | Retorna uma ARRAY de IDs de célula H3 (representadas como BIGINT) correspondentes a hexágonos ou pentágonos, da resolução especificada, que estão contidas na área geográfica de entrada. |
| h3_polyfillash3string(geographyExpr, resolutionExpr) | Retorna uma ARRAY de IDs de célula H3 (representada como STRING) correspondentes a hexágonos ou pentágonos, da resolução especificada, que estão contidas na área geográfica de entrada. |
| h3_tessellateaswkb(geographyExpr, resolutionExpr) | Retorna um mosaico da geografia de entrada usando células H3 na resolução especificada. |
| h3_try_polyfillash3(geographyExpr, resolutionExpr) | Retorna uma ARRAY de IDs de célula H3 (representadas como BIGINT) correspondentes a hexágonos ou pentágonos, da resolução especificada, que estão contidas na área geográfica de entrada. |
| h3_try_polyfillash3string(geographyExpr, resolutionExpr) | Retorna uma ARRAY de IDs de célula H3 (representada como STRING) correspondentes a hexágonos ou pentágonos, da resolução especificada, que estão contidas na área geográfica de entrada. |
Exportação
| Função | Descrição |
|---|---|
| h3_boundaryasgeojson(h3CellIdExpr) | Retorna o limite poligonal da célula de entrada H3 no formato GeoJSON. |
| h3_boundaryaswkb(h3CellIdExpr) | Retorna o limite poligonal da célula de entrada H3 no formato WKB. |
| h3_boundaryaswkt(h3CellIdExpr) | Retorna o limite poligonal da célula de entrada H3 no formato WKT. |
| h3_centerasgeojson(h3CellIdExpr) | Retorna o centro da célula de entrada H3 como um ponto no formato GeoJSON. |
| h3_centeraswkb(h3CellIdExpr) | Retorna o centro da célula de entrada H3 como um ponto no formato WKB. |
| h3_centeraswkt(h3CellIdExpr) | Retorna o centro da célula de entrada H3 como um ponto no formato WKT. |
Conversões
| Função | Descrição |
|---|---|
| h3_h3tostring(h3CellIdExpr) | Converte a ID da célula H3 de entrada em sua representação de cadeia de caracteres hexadecimal equivalente. |
| h3_stringtoh3(h3CellIdStringExpr) | Converte a cadeia de entrada, que deve ser uma cadeia hexadecimal que representa uma ID de célula H3, para a representação BIGINT correspondente da ID da célula H3. |
Predicados
| Função | Descrição |
|---|---|
| h3_ischildof(h3CellId1Expr, h3CellId2Expr) | Retorna verdadeiro se a primeira ID da célula H3 for igual ou um filho da segunda ID da célula H3. |
| h3_ispentagon(h3CellIdExpr) | Retorna verdadeiro se a entrada BIGINT ou CADEIA de caracteres hexadecimal corresponder a uma célula H3 pentagonal ou não. |
Validade
| Função | Descrição |
|---|---|
| h3_isvalid(expr) | Retorna true se a entrada BIGINT ou STRING for uma ID de célula H3 válida. |
| h3_try_validate(h3CellIdExpr) | Retorna o valor de entrada, que é do tipo BIGINT ou STRING, se corresponder a uma ID de célula H3 válida ou, caso contrário, NULL. |
| h3_validate(h3CellIdExpr) | Retorna o valor de entrada, que é do tipo BIGINT ou STRING, se corresponder a uma ID de célula H3 válida ou emite um erro, caso contrário. |
Distância relacionada
| Função | Descrição |
|---|---|
| h3_distance(h3CellId1Expr, h3CellId2Expr) | Retorna a distância da grade das duas IDs de célula H3 de entrada. |
| h3_hexring(h3CellIdExpr, kExpr) | Retorna uma matriz de IDs de célula H3 que formam um anel vazado hexagonal centralizado na célula H3 de origem e que estão a uma distância k da grade da célula H3 de origem. |
| h3_kring(h3CellIdExpr, kExpr) | Retorna as IDs de célula H3 que estão dentro da (grade) k de distância da célula de origem. |
| h3_kringdistances(h3CellIdExpr, kExpr) | Retorna todas as IDs da célula H3 (representadas como inteiros longos ou cadeias) dentro da distância k da grade da ID da célula H3 de origem, juntamente com a distância da ID da célula H3 de origem. |
| h3_try_distance(h3CellId1Expr, h3CellId2Expr) | Retorna a distância da grade das duas IDs de célula H3 de entrada da mesma resolução ou NULL se a distância for indefinida. |
Traversal
| Função | Descrição |
|---|---|
| h3_maxchild(h3CellIdExpr, resolutionExpr) | Retorna o filho do valor máximo da célula H3 de entrada na resolução especificada. |
| h3_minchild(h3CellIdExpr, resolutionExpr) | Retorna o filho do valor mínimo da célula H3 de entrada na resolução especificada. |
| h3_resolution(h3CellIdExpr) | Retorna a resolução da ID de célula H3 de entrada. |
| h3_tochildren(h3CellIdExpr, resolutionExpr) | Retorna uma matriz das IDs de célula H3 filhos da ID de célula H3 de entrada na resolução especificada. |
| h3_toparent(h3CellIdExpr, resolutionExpr) | Retorna a ID de célula H3 pai da ID de célula H3 de entrada na resolução especificada. |
Compactação
| Função | Descrição |
|---|---|
| h3_compact(h3CellIdsExpr) | Compacta o conjunto de entrada de IDs de célula H3 da melhor maneira possível. |
| h3_uncompact(h3CellIdsExpr, resolutionExpr) | Descompacta o conjunto de entrada de IDs de célula H3 para a resolução especificada. |