o que é pg_sphere, como usar pg_sphere - PolarDB: Central de Documentação do Alibaba Cloud

O pg_sphere é uma extensão open-source do PostgreSQL que adiciona tipos de dados esféricos, operadores e funções ao PolarDB for PostgreSQL. Utilize essa extensão para armazenar e consultar objetos em uma esfera — como coordenadas geográficas, posições de estrelas e polígonos na Terra — além de calcular distâncias e áreas entre eles.

Pré-requisitos

Antes de começar, verifique se você possui:

Um cluster do PolarDB for PostgreSQL executando uma das seguintes versões:
- PostgreSQL 16 (versão secundária do mecanismo 2.0.16.9.6.0 ou posterior)
- PostgreSQL 14 (versão secundária do mecanismo 2.0.14.5.1.0 ou posterior)
- PostgreSQL 11 (versão secundária do mecanismo 2.0.11.9.27.0 ou posterior)

Para verificar a versão secundária do seu mecanismo, execute SHOW polardb_version; ou consulte o console. Caso sua versão não atenda aos requisitos, atualize a versão secundária do mecanismo.

Instalar ou desinstalar a extensão

Instale a extensão:

CREATE EXTENSION pg_sphere;

Desinstale a extensão:

DROP EXTENSION pg_sphere;

Tipos de dados

O pg_sphere oferece os seguintes tipos de objetos esféricos:

Tipo	Descrição
Point	Posição em uma esfera definida por longitude e latitude. Ideal para localizações geográficas, posições estelares ou qualquer ponto em uma superfície esférica.
Euler transformation	Rotação no espaço 3D definida por três ângulos de Euler. Utilizada para transformar ou rotacionar coordenadas esféricas.
Circle	Calota esférica definida por um ponto central e um raio.
Line	Arco de círculo máximo na esfera.
Ellipses	Região elíptica na esfera.
Path	Sequência ordenada de pontos que formam um arco aberto na esfera.
Polygon	Região fechada delimitada por arcos de círculos máximos. Adequado para fronteiras geográficas, como contornos de países ou áreas de cobertura.

Representar um ponto

Especifique um ponto (spoint) em um dos três formatos abaixo:

Radianos — especifique a longitude e a latitude em radianos:

SELECT spoint '(0.1,-0.2)';

Saída:

spoint
--------------
 (0.1 , -0.2)
(1 row)

Graus — adicione o sufixo d a cada valor:

SELECT spoint '( 10.1d, -90d)';

Saída:

spoint
----------------------------------------
 (0.176278254451427 , -1.5707963267949)
(1 row)

Graus, minutos e segundos (DMS) — utilize os sufixos d, m e s:

SELECT spoint '( 10d 12m 11.3s, -13d 14m)';

Saída:

spoint
------------------------------------------
 (0.178078367649387 , -0.230965237680583)
(1 row)

Um círculo é dividido em 360 graus. Cada grau divide-se em 60 minutos, e cada minuto, em 60 segundos.

Construtores

Os construtores criam objetos esféricos a partir de valores escalares. O exemplo a seguir constrói um ponto com longitude de 270 graus e latitude de -30 graus, convertendo de graus para radianos:

SELECT spoint (270.0 * pi() / 180.0, -30.0 * pi() / 180.0) AS spoint;

Saída:

                 spoint
-----------------------------------------
 (4.71238898038469 , -0.523598775598299)
(1 row)

Operadores

O pg_sphere suporta os seguintes operadores:

Categoria	Operadores	Descrição
Conversão de tipo	`::`	Projeta um objeto esférico para um tipo compatível
Igualdade	`=`, `<>`	Verifica se dois objetos são iguais ou diferentes
Contenção e sobreposição	`<@`, `@>`, `!<@`, `!@>`, `&&`, `!&&`	Testa contenção e sobreposição entre objetos
Interseção de linhas	`#`	Verifica se duas linhas se cruzam
Distância	`<->`	Calcula a distância angular entre dois objetos
Comprimento e circunferência		Calcula o comprimento de um caminho ou a circunferência de um círculo
Centro	`@@`	Retorna o ponto central de um objeto

O exemplo abaixo usa o operador de distância (<->) para calcular a distância angular entre dois círculos centrados nas latitudes de 20 e 40 graus, cada um com raio de 2 graus. O resultado é retornado em graus:

SELECT 180 * ( scircle '<(0d,20d),2d>' <-> scircle '<(0d,40d),2d>' ) / pi() AS dist;

Saída:

 dist
------
   16
(1 row)

Funções

O pg_sphere disponibiliza três categorias de funções de cálculo:

Funções de área — calculam a área de um objeto esférico em radianos quadrados. Tipos suportados: scircle, spolygon, sbox.
Funções de caminho — calculam propriedades de caminhos esféricos.
Funções de distância — calculam a distância angular entre objetos esféricos.

Área de um círculo

Calcule a área de um círculo esférico com centro no polo norte (90 graus) e raio de 60 graus, expressa como um múltiplo de pi:

SELECT area( scircle '<(0d,90d),60d>' ) / pi() AS area;

Saída:

area
------
    1
(1 row)

Longitude e latitude de um ponto

Na extensão pg_sphere para PolarDB, a função long(spoint) foi renomeada para long_sphere(spoint) . Atualize todas as consultas existentes que utilizem long(spoint) .

Obtenha a longitude de um ponto em graus:

SELECT long_sphere ( spoint '(10d,20d)' ) * 180.0 / pi() AS longitude;

Saída:

longitude
------------
10
(1 row)

Obtenha a latitude de um ponto em graus:

SELECT lat ( spoint '(10d,20d)' ) * 180.0 / pi() AS latitude;

Saída:

latitude
----------
20
(1 row)

Referências

Para obter a lista completa de tipos de dados, operadores e funções, consulte a documentação oficial do pg_sphere.