> ## Documentation Index > Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt > Use this file to discover all available pages before exploring further. > Documentação sobre coordenadas # Funções para trabalhar com coordenadas geográficas
## greatCircleDistance
Calcula a distância entre dois pontos na superfície da Terra com base na [fórmula do círculo máximo](https://en.wikipedia.org/wiki/Great-circle_distance). ```sql theme={null} 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** ```sql theme={null} SELECT greatCircleDistance(55.755831, 37.617673, -55.755831, -37.617673) AS greatCircleDistance ``` ```text theme={null} ┌─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. ```sql theme={null} 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** ```sql theme={null} SELECT geoDistance(38.8976, -77.0366, 39.9496, -75.1503) AS geoDistance ``` ```text theme={null} ┌─geoDistance─┐ │ 212458.73 │ └─────────────┘ ```
## greatCircleAngle
Calcula o ângulo central entre dois pontos na superfície terrestre usando [a fórmula do círculo máximo](https://en.wikipedia.org/wiki/Great-circle_distance). ```sql theme={null} 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** ```sql theme={null} SELECT greatCircleAngle(0, 0, 45, 0) AS arc ``` ```text theme={null} ┌─arc─┐ │ 45 │ └─────┘ ```
## geoToUTM
Converte coordenadas geográficas WGS84 `(longitude, latitude)` em coordenadas [Universal Transverse Mercator (UTM)](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system). 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. ```sql theme={null} geoToUTM(longitude, latitude[, zone]) ``` **Argumentos** * `longitude` — Longitude em graus. Intervalo: `[-180°, 180°]`. [`Float32`](/docs/pt-BR/reference/data-types/float)/[`Float64`](/docs/pt-BR/reference/data-types/float). * `latitude` — Latitude em graus. Intervalo: `[-80°, 84°]`. [`Float32`](/docs/pt-BR/reference/data-types/float)/[`Float64`](/docs/pt-BR/reference/data-types/float). * `zone` — Opcional. Força o uso desta zona UTM na projeção, em vez de selecioná-la automaticamente. Intervalo: `[1, 60]`. [`(U)Int*`](/docs/pt-BR/reference/data-types/int-uint). **Valor retornado** Uma tupla nomeada `(easting, northing, zone, band)`: `easting` e `northing` em metros ([`Float64`](/docs/pt-BR/reference/data-types/float)), o número da `zone` UTM ([`UInt8`](/docs/pt-BR/reference/data-types/int-uint)) e a letra da `band` de latitude MGRS ([`FixedString(1)`](/docs/pt-BR/reference/data-types/fixedstring)). 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** ```sql theme={null} SELECT geoToUTM(2.294497, 48.858222) AS utm; -- Eiffel Tower ``` ```text theme={null} (448251.5978370684,5411935.125629659,31,'U') ```
## UTMToGeo
Converte coordenadas [UTM](https://en.wikipedia.org/wiki/Universal_Transverse_Mercator_coordinate_system) em coordenadas geográficas WGS84 `(longitude, latitude)`. Esta é a função inversa de [`geoToUTM`](#geotoutm). ```sql theme={null} UTMToGeo(easting, northing, zone, is_north) ``` **Argumentos** * `easting` — Coordenada leste em metros (inclui o false easting de 500000 m). [`(U)Int*`](/docs/pt-BR/reference/data-types/int-uint)/[`Float*`](/docs/pt-BR/reference/data-types/float). * `northing` — Coordenada norte em metros (inclui o false northing de 10000000 m no hemisfério sul). [`(U)Int*`](/docs/pt-BR/reference/data-types/int-uint)/[`Float*`](/docs/pt-BR/reference/data-types/float). * `zone` — Número da zona UTM. Intervalo: `[1, 60]`. [`(U)Int*`](/docs/pt-BR/reference/data-types/int-uint). * `is_north` — Hemisfério: `1` para o hemisfério norte, `0` para o hemisfério sul. [`(U)Int*`](/docs/pt-BR/reference/data-types/int-uint). **Valor retornado** Uma tupla nomeada `(longitude, latitude)` em graus. [`Tuple(Float64, Float64)`](/docs/pt-BR/reference/data-types/tuple). **Exemplo** ```sql theme={null} SELECT UTMToGeo(448251.6, 5411935.13, 31, 1) AS coord; ``` ```text theme={null} (2.2944970289079203,48.85822204127082) ```
## geoToMGRS
Codifica coordenadas geográficas WGS84 `(longitude, latitude)` como uma string do [Military Grid Reference System (MGRS)](https://en.wikipedia.org/wiki/Military_Grid_Reference_System). A string tem o formato `<100km square>`, 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°]`. ```sql theme={null} geoToMGRS(longitude, latitude[, precision]) ``` **Argumentos** * `longitude` — Longitude em graus. Intervalo: `[-180°, 180°]`. [`Float32`](/docs/pt-BR/reference/data-types/float)/[`Float64`](/docs/pt-BR/reference/data-types/float). * `latitude` — Latitude em graus. Intervalo: `[-80°, 84°]`. [`Float32`](/docs/pt-BR/reference/data-types/float)/[`Float64`](/docs/pt-BR/reference/data-types/float). * `precision` — Opcional. Número de dígitos para cada coordenada leste e norte. Padrão: `5`. Intervalo: `[0, 5]`. [`(U)Int*`](/docs/pt-BR/reference/data-types/int-uint). **Valor retornado** A cadeia de referência MGRS. [`String`](/docs/pt-BR/reference/data-types/string). **Exemplo** ```sql theme={null} SELECT geoToMGRS(2.294497, 48.858222) AS mgrs, geoToMGRS(2.294497, 48.858222, 3) AS mgrs_100m; ``` ```text theme={null} ┌─mgrs────────────┬─mgrs_100m───┐ │ 31UDQ4825111935 │ 31UDQ482119 │ └─────────────────┴─────────────┘ ```
## MGRSToGeo
Decodifica uma string [MGRS](https://en.wikipedia.org/wiki/Military_Grid_Reference_System) em coordenadas geográficas WGS84 `(longitude, latitude)`. Esta é a operação inversa de [`geoToMGRS`](#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. ```sql theme={null} MGRSToGeo(mgrs) ``` **Argumentos** * `mgrs` — string de referência MGRS a ser decodificada. [`String`](/docs/pt-BR/reference/data-types/string)/[`FixedString`](/docs/pt-BR/reference/data-types/fixedstring). **Valor retornado** Uma tupla nomeada `(longitude, latitude)` em graus. [`Tuple(Float64, Float64)`](/docs/pt-BR/reference/data-types/tuple). **Exemplo** ```sql theme={null} SELECT MGRSToGeo('31UDQ4825111935') AS coord; ``` ```text theme={null} (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. ```sql theme={null} pointInEllipses(x, y, x₀, y₀, a₀, b₀,...,xₙ, yₙ, aₙ, bₙ) ``` **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** ```sql theme={null} SELECT pointInEllipses(10., 10., 10., 9.1, 1., 0.9999) ``` ```text theme={null} ┌─pointInEllipses(10., 10., 10., 9.1, 1., 0.9999)─┐ │ 1 │ └─────────────────────────────────────────────────┘ ```
## pointInPolygon
Verifica se o ponto está contido no polígono no plano. ```sql theme={null} pointInPolygon((x, y), [(a, b), (c, d) ...], ...) ``` **Valores de entrada** * `(x, y)` — Coordenadas de um ponto no plano. Tipo de dado — [Tuple](/docs/pt-BR/reference/data-types/tuple) — uma tupla de dois números, ou um [Point](/docs/pt-BR/reference/data-types/geo#point). * `[(a, b), (c, d) ...]` — Vértices do polígono. Tipo de dado — [Array](/docs/pt-BR/reference/data-types/array) ou [Ring](/docs/pt-BR/reference/data-types/geo#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](/docs/pt-BR/reference/data-types/geo#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](/docs/pt-BR/reference/data-types/geo#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](/docs/pt-BR/reference/data-types/geo#geometry) que contenha valores em formato de polígono (`Ring`, `Polygon` ou `MultiPolygon`). Os tipos em formato de polígono ([Ring](/docs/pt-BR/reference/data-types/geo#ring), [Polygon](/docs/pt-BR/reference/data-types/geo#polygon), [MultiPolygon](/docs/pt-BR/reference/data-types/geo#multipolygon) e [Geometry](/docs/pt-BR/reference/data-types/geo#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** ```sql theme={null} SELECT pointInPolygon((3., 3.), [(6, 0), (8, 4), (5, 8), (0, 2)]) AS res ``` ```text theme={null} ┌─res─┐ │ 1 │ └─────┘ ``` O polígono também pode ser fornecido usando os tipos de dados geométricos nomeados, inclusive como coluna de uma tabela: ```sql theme={null} 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; ``` ```text theme={null} ┌─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.