Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Funções para trabalhar com coordenadas geográficas

View as MarkdownEdit this pageReport an issueSet up docs MCP

greatCircleDistance

Calcula a distância entre dois pontos na superfície da Terra com base na fórmula do círculo máximo.

greatCircleDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

Parâmetros de entrada

  • lon1Deg — Longitude do primeiro ponto em graus. Intervalo: [-180°, 180°].
  • lat1Deg — Latitude do primeiro ponto em graus. Intervalo: [-90°, 90°].
  • lon2Deg — Longitude do segundo ponto em graus. Intervalo: [-180°, 180°].
  • lat2Deg — Latitude do segundo ponto em graus. Intervalo: [-90°, 90°].

Valores positivos correspondem à latitude norte e à longitude leste, e valores negativos correspondem à latitude sul e à longitude oeste.

Valor retornado

A distância entre dois pontos na superfície da Terra, em metros.

Gera uma exceção quando os valores dos parâmetros de entrada estão fora do intervalo.

Exemplo

SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance
┌─greatCircleDistance─┐
│            14128352 │
└─────────────────────┘

geoDistance

Semelhante a greatCircleDistance, mas calcula a distância no elipsoide WGS-84 em vez de na esfera. Esta é uma aproximação mais precisa do geoide da Terra. O desempenho é o mesmo de greatCircleDistance (sem perda de desempenho). Recomenda-se usar geoDistance para calcular distâncias na Terra.

Nota técnica: para pontos suficientemente próximos, calculamos a distância usando uma aproximação planar com a métrica no plano tangente ao ponto médio das coordenadas.

geoDistance(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

Parâmetros de entrada

  • lon1Deg — Longitude do primeiro ponto em graus. Intervalo: [-180°, 180°].
  • lat1Deg — Latitude do primeiro ponto em graus. Intervalo: [-90°, 90°].
  • lon2Deg — Longitude do segundo ponto em graus. Intervalo: [-180°, 180°].
  • lat2Deg — Latitude do segundo ponto em graus. Intervalo: [-90°, 90°].

Valores positivos correspondem à latitude norte e à longitude leste, e valores negativos correspondem à latitude sul e à longitude oeste.

Valor retornado

A distância entre dois pontos na superfície da Terra, em metros.

Gera uma exceção quando os valores dos parâmetros de entrada estão fora do intervalo.

Exemplo

SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance
┌─geoDistance─┐
│   212458.73 │
└─────────────┘

greatCircleAngle

Calcula o ângulo central entre dois pontos na superfície terrestre usando a fórmula do círculo máximo.

greatCircleAngle(lon1Deg, lat1Deg, lon2Deg, lat2Deg)

Parâmetros de entrada

  • lon1Deg — Longitude do primeiro ponto em graus.
  • lat1Deg — Latitude do primeiro ponto em graus.
  • lon2Deg — Longitude do segundo ponto em graus.
  • lat2Deg — Latitude do segundo ponto em graus.

Valor retornado

O ângulo central entre dois pontos, em graus.

Exemplo

SELECT greatCircleAngle(0, 0, 45, 0) AS arc
┌─arc─┐
│  45 │
└─────┘

geoToUTM

Converte coordenadas geográficas WGS84 (longitude, latitude) em coordenadas Universal Transverse Mercator (UTM).

UTM é um conjunto de 60 projeções transversas de Mercator, cada uma cobrindo uma zona longitudinal de 6°, que mapeia coordenadas geográficas para uma grade plana em metros. A zona é selecionada automaticamente com base na longitude, aplicando as exceções padrão para a Noruega e Svalbard, a menos que uma zone explícita seja informada. UTM só é definido para latitudes no intervalo [-80°, 84°]; as calotas polares usam o sistema UPS separado.

geoToUTM(longitude, latitude[, zone])

Argumentos

  • longitude — Longitude em graus. Intervalo: [-180°, 180°]. Float32/Float64.
  • latitude — Latitude em graus. Intervalo: [-80°, 84°]. Float32/Float64.
  • zone — Opcional. Força o uso desta zona UTM na projeção, em vez de selecioná-la automaticamente. Intervalo: [1, 60]. (U)Int*.

Valor retornado

Uma tupla nomeada (easting, northing, zone, band): easting e northing em metros (Float64), o número da zone UTM (UInt8) e a letra da band de latitude MGRS (FixedString(1)). Uma band igual a 'N' ou superior indica o hemisfério norte.

Gera uma exceção quando a latitude está fora de [-80°, 84°] ou a longitude está fora de [-180°, 180°].

Exemplo

SELECT geoToUTM(2.294497, 48.858222) AS utm; -- Eiffel Tower
(448251.5978370684,5411935.125629659,31,'U')

UTMToGeo

Converte coordenadas UTM em coordenadas geográficas WGS84 (longitude, latitude). Esta é a função inversa de geoToUTM.

UTMToGeo(easting, northing, zone, is_north)

Argumentos

  • easting — Coordenada leste em metros (inclui o false easting de 500000 m). (U)Int*/Float*.
  • northing — Coordenada norte em metros (inclui o false northing de 10000000 m no hemisfério sul). (U)Int*/Float*.
  • zone — Número da zona UTM. Intervalo: [1, 60]. (U)Int*.
  • is_north — Hemisfério: 1 para o hemisfério norte, 0 para o hemisfério sul. (U)Int*.

Valor retornado

Uma tupla nomeada (longitude, latitude) em graus. Tuple(Float64, Float64).

Exemplo

SELECT UTMToGeo(448251.6, 5411935.13, 31, 1) AS coord;
(2.2944970289079203,48.85822204127082)

geoToMGRS

Codifica coordenadas geográficas WGS84 (longitude, latitude) como uma string do Military Grid Reference System (MGRS).

A string tem o formato <zone><band><100km square><easting><northing>, por exemplo 31UDQ4825111935. O argumento precision controla o número de dígitos usados para cada um de easting e northing: 5 (padrão) para 1 m, 4 para 10 m, 3 para 100 m, 2 para 1 km, 1 para 10 km e 0 somente para o quadrado da grade de 100 km. O MGRS é definido apenas para latitudes no intervalo [-80°, 84°].

geoToMGRS(longitude, latitude[, precision])

Argumentos

  • longitude — Longitude em graus. Intervalo: [-180°, 180°]. Float32/Float64.
  • latitude — Latitude em graus. Intervalo: [-80°, 84°]. Float32/Float64.
  • precision — Opcional. Número de dígitos para cada coordenada leste e norte. Padrão: 5. Intervalo: [0, 5]. (U)Int*.

Valor retornado

A cadeia de referência MGRS. String.

Exemplo

SELECT geoToMGRS(2.294497, 48.858222) AS mgrs, geoToMGRS(2.294497, 48.858222, 3) AS mgrs_100m;
┌─mgrs────────────┬─mgrs_100m───┐
│ 31UDQ4825111935 │ 31UDQ482119 │
└─────────────────┴─────────────┘

MGRSToGeo

Decodifica uma string MGRS em coordenadas geográficas WGS84 (longitude, latitude). Esta é a operação inversa de geoToMGRS.

O ponto retornado é o centro do quadrado da grade referenciado, portanto a precisão do resultado corresponde à precisão codificada na string. Os espaços em branco na entrada são ignorados, e as letras não diferenciam maiúsculas de minúsculas.

MGRSToGeo(mgrs)

Argumentos

Valor retornado

Uma tupla nomeada (longitude, latitude) em graus. Tuple(Float64, Float64).

Exemplo

SELECT MGRSToGeo('31UDQ4825111935') AS coord;
(2.294495618908297,48.85822536113692)

pointInEllipses

Verifica se o ponto pertence a pelo menos uma das elipses. As coordenadas são geométricas no sistema de coordenadas cartesiano.

pointInEllipses(x, y, x₀

Parâmetros de entrada

  • x, y — Coordenadas de um ponto no plano.
  • xᵢ, yᵢ — Coordenadas do centro da i-ésima elipse.
  • aᵢ, bᵢ — Eixos da i-ésima elipse nas unidades das coordenadas x e y.

O número de parâmetros de entrada deve ser 2+4⋅n, em que n é o número de elipses.

Valores retornados

1 se o ponto estiver dentro de pelo menos uma das elipses; 0 se não estiver.

Exemplo

SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)
┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐
│                                               1 │
└─────────────────────────────────────────────────┘

pointInPolygon

Verifica se o ponto está contido no polígono no plano.

pointInPolygon((x, y), [(a, b), (c, d) ...], ...)

Valores de entrada

  • (x, y) — Coordenadas de um ponto no plano. Tipo de dado — Tuple — uma tupla de dois números, ou um Point.
  • [(a, b), (c, d) ...] — Vértices do polígono. Tipo de dado — Array ou Ring. Cada vértice é representado por um par de coordenadas (a, b). Os vértices devem ser especificados em sentido horário ou anti-horário. O número mínimo de vértices é 3.
  • A função oferece suporte a polígonos com furos (áreas vazadas). Tipo de dado — Polygon. Passe o Polygon inteiro como segundo argumento ou passe primeiro o anel externo e, em seguida, cada furo como argumento adicional separado.
  • A função também oferece suporte a multipolígonos. Tipo de dado — MultiPolygon. Passe o MultiPolygon inteiro como segundo argumento ou liste cada polígono componente como um argumento separado.
  • O argumento do polígono também pode ser uma coluna Geometry que contenha valores em formato de polígono (Ring, Polygon ou MultiPolygon).

Os tipos em formato de polígono (Ring, Polygon, MultiPolygon e Geometry) podem ser passados tanto como constantes quanto como colunas regulares (não constantes) da tabela. Quando o polígono é fornecido em vários argumentos separados (um anel externo seguido por furos, ou vários polígonos de um multipolígono), todos esses argumentos devem ser constantes.

Valores retornados

1 se o ponto estiver dentro do polígono, 0 se não estiver. Se o ponto estiver na borda do polígono, a função poderá retornar 0 ou 1.

Exemplo

SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res
┌─res─┐
│   1 │
└─────┘

O polígono também pode ser fornecido usando os tipos de dados geométricos nomeados, inclusive como coluna de uma tabela:

CREATE TABLE poly (id UInt32, shape Polygon) ENGINE = Memory;
INSERT INTO poly VALUES (1, [[(0, 0), (10, 0), (10, 10), (0, 10)], [(4, 4), (6, 4), (6, 6), (4, 6)]]);
SELECT id, pointInPolygon((2., 2.), shape) AS res FROM poly;
┌─id─┬─res─┐
│  1 │   1 │
└────┴─────┘

Nota • Você pode definir validate_polygons = 0 para ignorar a validação da geometria. • pointInPolygon pressupõe que todo polígono esteja bem formado. Se a entrada tiver auto-interseções, anéis em ordem incorreta ou arestas sobrepostas, os resultados se tornam pouco confiáveis — especialmente para pontos que ficam exatamente sobre uma aresta, um vértice ou dentro de uma auto-interseção, onde a noção de "dentro" vs. "fora" é indefinida. • Quando o argumento do polígono é constante e o ponto é expresso usando colunas-chave indexadas (por exemplo, pointInPolygon((x, y), constant_polygon) em uma tabela em que x, y fazem parte da PRIMARY KEY ou são cobertos por um índice minmax), o ClickHouse pode usar tanto a chave primária quanto os índices de data-skipping minmax para descartar grânulos irrelevantes.

Navigation