Uso do PostGIS no Hologres - Hologres: Central de Documentação do Alibaba Cloud

O PostGIS estende o Hologres com tipos de dados espaciais, funções e operadores. Use-o para armazenar, consultar e analisar dados geográficos — desde filtros de bounding box e buscas por proximidade até verificações de interseção de polígonos e cálculos de distância.

O Hologres oferece suporte ao PostGIS 3.0.0.

Suporte a engines

No Hologres V1.3 e versões posteriores, a maioria das funções do PostGIS executa na Hologres Query Engine (HQE), desenvolvida pela Alibaba Cloud, que proporciona melhor desempenho de consulta em comparação à PQE. Em versões anteriores à V1.3, as funções executam na PostgreSQL Query Engine (PQE), onde o desempenho pode ser inferior. Para verificar qual engine cada função utiliza, consulte Spatial functions: cada tabela de funções indica a engine correspondente ao grupo inteiro ou lista essa informação na coluna Required engine.

Instalar e desinstalar a extensão PostGIS

Execute a instrução abaixo como superusuário para instalar o PostGIS em um banco de dados. A instalação ocorre por banco de dados — repita esta etapa para cada banco que necessite de suporte espacial.

-- Install PostGIS explicitly into the public schema.
CREATE EXTENSION IF NOT EXISTS postgis SCHEMA public;

Não é possível instalar o PostGIS no schema pg_catalog.

Para verificar a instalação, execute:

SELECT public.postgis_full_version();

Uma instalação bem-sucedida retorna uma string de versão como POSTGIS="3.0.0 ...".

Nota

A função postgis_full_version() é uma função PL/pgSQL localizada no schema public. O search_path padrão do Hologres inclui o schema public, permitindo chamar a função sem prefixo de schema. Caso o search_path da sessão atual não inclua o schema public, a chamada falhará com o erro function postgis_full_version() does not exist. Os exemplos neste tópico utilizam o prefixo public. para garantir o funcionamento independentemente do search_path configurado.

Desinstalar o PostGIS

Para remover a extensão:

DROP EXTENSION postgis;

Se o banco de dados ainda contiver objetos dependentes do tipo geometry ou geography — por exemplo, uma tabela criada conforme descrito em Create and query a geometry table — a instrução falhará com a mensagem cannot drop extension postgis because other objects depend on it. Exclua primeiro os objetos dependentes:

Identifique os objetos e colunas que ainda utilizam algum tipo espacial:

SELECT n.nspname AS schema_name, c.relname AS object_name, a.attname AS column_name, t.typname
FROM pg_attribute a
  JOIN pg_class c ON c.oid = a.attrelid
  JOIN pg_type t ON t.oid = a.atttypid
  JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE t.typname IN ('geometry', 'geography')
  AND c.relkind IN ('r', 'p', 'm', 'f')
  AND a.attnum > 0
  AND NOT a.attisdropped
  AND n.nspname NOT LIKE 'pg_%';

Exclua cada tabela retornada pela consulta ou remova apenas suas colunas espaciais:
```
DROP TABLE <TABLE_NAME>;
```
Nota
Caso a lixeira de tabelas esteja ativada — configuração padrão no Hologres V3.1 e versões posteriores — o comando DROP TABLE move a tabela para a lixeira, exigindo também a execução da próxima etapa. Para ignorar a lixeira e pular a etapa seguinte, use DROP TABLE <TABLE_NAME> FORCE;. Para mais informações, consulte Table recycle bin.
Esvazie a lixeira. Tabelas na lixeira ainda dependem dos tipos espaciais, mantendo esses tipos em uso até que a lixeira seja esvaziada:
```
CALL hologres.hg_purge_all_tables();
```
Importante
A função hg_purge_all_tables() exclui permanentemente todas as tabelas presentes na lixeira do banco de dados atual. Essa ação é irreversível. Antes de executá-la, confirme que a lixeira não contém nenhuma tabela ainda necessária. Um superusuário da instância atual deve executar este comando.
Desinstale a extensão:
```
DROP EXTENSION postgis;
```

Importante

Exclua os objetos dependentes conforme descrito acima em vez de usar DROP EXTENSION postgis CASCADE, mesmo que a mensagem de erro do PostgreSQL sugira o uso de CASCADE. A opção CASCADE remove os dados da extensão (PostGIS, RoaringBitmap, Proxima, Binlog e dados BSI) juntamente com todos os objetos dependentes, incluindo metadados, tabelas, views e dados do servidor. Essa ação é irreversível.

Resolver o conflito da tabela `spatial_ref_sys`

Se o comando CREATE EXTENSION postgis falhar com o erro relation spatial_ref_sys already exists, significa que o banco de dados contém uma tabela de sistema spatial_ref_sys residual de uma instalação anterior. Um comando DROP EXTENSION postgis normal não deixa resíduos, portanto esse erro geralmente ocorre após uma migração de outro banco de dados ou quando uma tabela com o mesmo nome foi criada manualmente. Resolva o conflito da seguinte forma:

Remova a extensão parcialmente instalada:
```
DROP EXTENSION IF EXISTS postgis;
```
Remova a tabela de sistema residual. Antes de executar esta instrução, confirme que a tabela é realmente um resíduo de instalação anterior e não uma tabela de negócios:
```
DROP TABLE IF EXISTS spatial_ref_sys CASCADE;
```

Reinstale a extensão PostGIS:

CREATE EXTENSION IF NOT EXISTS postgis SCHEMA public;

Verifique a instalação:
```
SELECT public.postgis_full_version();
```

Criar e consultar uma tabela geometry

O PostGIS oferece suporte a dois tipos de dados espaciais no Hologres: geometry (coordenadas planares/cartesianas) e geography (coordenadas esféricas de longitude/latitude). Para detalhes sobre o tipo geography, consulte a documentação de geography do PostGIS.

O tipo geometry é o mais utilizado. As etapas a seguir demonstram como criar uma tabela geometry e executar consultas espaciais.

1. Criar uma tabela geometry

Ao criar uma tabela, especifique um subtipo geometry se necessário. Subtipos suportados: Point, MultiPoint, LineString, MultiLineString, Polygon, MultiPolygon.

Sem subtipo:

CREATE TABLE holo_gis_1 (
  id   INT,
  geom geometry,
  PRIMARY KEY (id)
);

Com subtipo e identificador de sistema de referência espacial (SRID):

CREATE TABLE holo_gis_2 (
  id   INT,
  geom geometry(point, 4326),
  PRIMARY KEY (id)
);

Neste exemplo, o subtipo é Point e o SRID é 4326 (WGS 84). Se nenhum SRID for especificado, o valor padrão será 0. O SRID das geometrias inseridas ou utilizadas em predicados de consulta deve corresponder ao SRID da coluna. Caso contrário, a instrução falhará com erros como Geometry SRID (0) does not match column SRID (4326) ou Operation on mixed SRID geometries. Para mais informações sobre SRIDs, consulte a documentação do PostGIS.

2. Inserir dados espaciais

-- Without SRID
INSERT INTO holo_gis_1 VALUES (1, ST_GeomFromText('point(116 39)'));

-- With SRID 4326
INSERT INTO holo_gis_2 VALUES (1, ST_GeomFromText('point(116 39)', 4326));

Para mais informações sobre funções espaciais, consulte Spatial functions.

3. Consultar dados espaciais

Após inserir os dados, execute os seguintes tipos de consulta.

Consulta por intervalo retangular

Retorna todos os pontos dentro de um bounding box.

Sem SRID:

SELECT st_astext(geom)
FROM holo_gis_1
WHERE ST_Covers(
  ST_MakeBox2D(ST_Point(116, 39), ST_Point(117, 40)),
  geom
);

Com SRID:

SELECT st_astext(geom)
FROM holo_gis_2
WHERE ST_Covers(
  ST_SetSRID(ST_MakeBox2D(ST_Point(116, 39), ST_Point(117, 40)), 4326),
  geom
);

Ambas as consultas retornam:

st_astext
-------------
POINT(116 39)

Nota

Para grandes conjuntos de dados, use o operador de bounding box && como filtro preliminar antes de aplicar um predicado espacial exato. Isso reduz o número de linhas processadas no cálculo exato. O operador && executa na HQE, tendo custo menor que funções topológicas como ST_Intersects e ST_Covers, delegadas à PQE. Por exemplo:

SELECT st_astext(geom)
FROM holo_gis_1
WHERE geom && ST_MakeBox2D(ST_Point(116, 39), ST_Point(117, 40))
  AND ST_Intersects(ST_GeomFromText('POLYGON((116 39,117 39,117 40,116 40,116 39))'), geom);

Se precisar apenas de um filtro por intervalo retangular, sem semântica topológica exata, use geom && ST_MakeBox2D(...) isoladamente. Caso a coluna possua SRID, envolva o box com ST_SetSRID usando o mesmo SRID. Caso contrário, a instrução falhará com Operation on mixed SRID geometries.

Verificação de interseção de polígono

Para encontrar pontos dentro de um polígono arbitrário ou em sua fronteira, use ST_Intersects com o polígono. Diferentemente do bounding box criado por ST_MakeBox2D, o polígono pode ter qualquer forma, e ST_Intersects considera o contato na fronteira como uma correspondência válida.

Sem SRID:

SELECT st_astext(geom)
FROM holo_gis_1
WHERE ST_Intersects(
  ST_GeomFromText('POLYGON((116 39,117 39,117 40,116 40,116 39))'),
  geom
);

Com SRID:

SELECT st_astext(geom)
FROM holo_gis_2
WHERE ST_Intersects(
  ST_SetSRID(ST_GeomFromText('POLYGON((116 39,117 39,117 40,116 40,116 39))'), 4326),
  geom
);

Ambas as consultas retornam:

st_astext
-------------
POINT(116 39)

Funções espaciais

O PostGIS fornece funções espaciais para converter e analisar valores geometry. A sintaxe das funções utiliza os seguintes parâmetros:

geom: um valor geometry ou uma expressão que resulte em geometry
precision: um INTEGER que controla a precisão de saída das coordenadas. O nome do parâmetro, sua semântica e o valor padrão variam conforme a função:
- ST_AsText(geom [, precision]): número de dígitos significativos. O padrão é 15.
- ST_AsGeoJSON(geom [, maxdecimaldigits]): número máximo de casas decimais. O padrão é 9. Especifique este parâmetro explicitamente caso precise manter maior precisão; caso contrário, as coordenadas exportadas perderão precisão.
Recomendamos especificar um valor entre 1 e 20. Valores fora desse intervalo são aceitos, mas não produzem dígitos adicionais significativos, pois um float de dupla precisão comporta aproximadamente 15 a 17 dígitos significativos.
index: INTEGER; índice base 1, salvo indicação em contrário
srid: INTEGER; identificador do sistema de referência espacial

Cada função executa em uma das seguintes engines de consulta:

Engine	Quando se aplica	Desempenho
HQE (Hologres Query Engine)	Hologres V1.3 e posterior	Superior — otimizada para cargas analíticas
PQE (PostgreSQL Query Engine)	Todas as versões; obrigatória para certas funções	Inferior — modo de compatibilidade

Para a especificação completa das funções do PostGIS, consulte a documentação de referência do PostGIS.

Nota

As atribuições de engine nas tabelas a seguir refletem o comportamento medido no Hologres V4.2 e indicam apenas a engine atual (HQE ou PQE). A engine utilizada por uma função pode mudar entre versões. Para confirmar a engine da sua instância, verifique se a saída do EXPLAIN contém um nó PQE. Para visão geral do suporte a engines por versão, consulte Engine support.
As tabelas a seguir listam a assinatura mais comum de cada função. Algumas funções aceitam sobrecargas adicionais — por exemplo, ST_MakeLine também aceita um array de geometrias, e ST_AddPoint também aceita uma posição de inserção. Consulte a documentação de referência do PostGIS para obter a lista completa de sobrecargas, bem como funções que aparecem nos exemplos mas não estão listadas nestas tabelas, como ST_MakeBox2D.

Construtores de geometry

Todas as funções deste grupo executam na HQE.

Função	Sintaxe	Retorno	Descrição
`ST_LineFromMultiPoint`	`ST_LineFromMultiPoint(geom)`	`GEOMETRY`	Cria uma linestring a partir de uma geometria multipoint, preservando a ordem dos pontos. A geometria retornada possui o mesmo SRID da entrada.
`ST_MakeEnvelope`	`ST_MakeEnvelope(xmin, ymin, xmax, ymax [, srid])`	`GEOMETRY` (POLYGON)	Gera o polígono retangular definido pelas coordenadas dos cantos fornecidos, onde as coordenadas especificam os cantos inferior esquerdo e superior direito. O resultado é sempre um POLYGON, mesmo quando as coordenadas formam uma linha ou um único ponto. Se um SRID for fornecido, a geometria retornada usará esse SRID; caso contrário, o SRID será 0.
`ST_MakeLine`	`ST_MakeLine(geom1, geom2)`	`GEOMETRY` (LINESTRING)	Constrói uma linestring a partir de duas geometrias de entrada.
`ST_MakePoint`	`ST_MakePoint(x, y)`	`GEOMETRY` (POINT)	Cria um ponto a partir de valores de coordenadas.
`ST_Point`	`ST_Point(x, y)`	`GEOMETRY` (POINT)	Gera um ponto com base em valores de coordenadas.
`ST_Polygon`	`ST_Polygon(linestring, srid)`	`GEOMETRY` (POLYGON)	Cria um polígono cujo anel externo é a linestring de entrada, com o SRID especificado.

Acessadores de geometry

Todas as funções deste grupo executam na HQE, exceto ST_IsPolygonCCW, que executa na PQE. Elas não são complementares: quando o anel externo e os anéis internos possuem a mesma orientação, ambas retornam false. Não negue ST_IsPolygonCW para testar orientação anti-horária. Ao filtrar uma tabela grande por orientação de anel, observe também que essas duas funções executam em engines diferentes.

Função	Sintaxe	Retorno	Descrição
`GeometryType`	`GeometryType(geom)`	`TEXT`	Retorna o nome do subtipo da geometria de entrada como string, sem prefixo e em maiúsculas, como POINT ou POLYGON.
`ST_Boundary`	`ST_Boundary(geom)`	`GEOMETRY`	Devolve a fronteira da geometria de entrada. Uma geometria vazia retorna a entrada inalterada; um ponto ou multipoint não vazio retorna uma coleção de geometrias vazia; uma linestring retorna um multipoint de seus pontos de fronteira; um polígono sem anéis internos retorna uma linestring fechada; um polígono com anéis internos ou um multipolígono retorna uma multilinestring de todos os anéis de fronteira.
`ST_Dimension`	`ST_Dimension(geom)`	`INTEGER`	Indica a dimensão intrínseca do subtipo da geometria.
`ST_Envelope`	`ST_Envelope(geom)`	`GEOMETRY`	Retorna o bounding box mínimo da geometria de entrada. Devolve um ponto se o box degenerar para um ponto, uma linestring de dois pontos se for unidimensional, ou um polígono orientado no sentido horário nos demais casos. A geometria retornada mantém o mesmo SRID da entrada.
`ST_ExteriorRing`	`ST_ExteriorRing(geom)`	`GEOMETRY` (LINESTRING)	Extrai o anel externo de um polígono como uma linestring fechada.
`ST_GeometryN`	`ST_GeometryN(geom, index)`	`GEOMETRY`	Obtém a geometria no índice base 1 especificado. Para geometrias simples (ponto, linestring, polígono) com índice 1, retorna a própria geometria; caso contrário, retorna null. Para coleções, devolve o elemento no índice indicado.
`ST_GeometryType`	`ST_GeometryType(geom)`	`TEXT`	Fornece o nome do subtipo da geometria de entrada como string, prefixado com ST_, como ST_Point ou ST_Polygon. Esse prefixo é a única diferença em relação a GeometryType, portanto considere o formato ao escrever condições de igualdade.
`ST_InteriorRingN`	`ST_InteriorRingN(geom, index)`	`GEOMETRY` (LINESTRING)	Recupera o anel interno de um polígono na posição de índice dada, como uma linestring fechada.
`ST_IsClosed`	`ST_IsClosed(geom)`	`BOOLEAN`	Retorna `true` se a geometria for fechada. Um ponto ou multipoint é sempre fechado. Uma linestring é fechada quando seus pontos inicial e final coincidem. Um polígono é fechado quando todos os anéis são não vazios e seus pontos inicial e final coincidem.
`ST_IsCollection`	`ST_IsCollection(geom)`	`BOOLEAN`	Devolve `true` se a geometria for uma `GEOMETRYCOLLECTION`, `MULTIPOINT`, `MULTILINESTRING` ou `MULTIPOLYGON`.
`ST_IsEmpty`	`ST_IsEmpty(geom)`	`BOOLEAN`	Indica `true` se a geometria não contiver pontos.
`ST_IsPolygonCCW`	`ST_IsPolygonCCW(geom)`	`BOOLEAN`	Retorna `true` se o anel externo do polígono de entrada tiver orientação anti-horária e todos os anéis internos tiverem orientação horária. Devolve `false` se o anel externo e os anéis internos tiverem a mesma orientação. Também retorna `true` para pontos, linestrings, multipoints e multilinestrings, para coleções de geometrias cujos elementos poligonais atendam à condição anterior e para um polígono vazio (`POLYGON EMPTY`).
`ST_IsPolygonCW`	`ST_IsPolygonCW(geom)`	`BOOLEAN`	Retorna `true` se o anel externo do polígono de entrada tiver orientação horária e todos os anéis internos tiverem orientação anti-horária. Devolve `false` se o anel externo e os anéis internos tiverem a mesma orientação. Também retorna `true` para pontos, linestrings, multipoints e multilinestrings, para coleções de geometrias cujos elementos poligonais atendam à condição anterior e para um polígono vazio (`POLYGON EMPTY`).
`ST_IsSimple`	`ST_IsSimple(geom)`	`BOOLEAN`	Indica `true` se a geometria não apresentar pontos geométricos anômalos, como auto-interseções.
`ST_NPoints`	`ST_NPoints(geom)`	`INTEGER`	Conta o número de pontos na geometria.
`ST_NRings`	`ST_NRings(geom)`	`INTEGER`	Informa a quantidade de anéis na geometria.
`ST_NumGeometries`	`ST_NumGeometries(geom)`	`INTEGER`	Retorna o total de elementos em uma coleção de geometrias.
`ST_NumInteriorRings`	`ST_NumInteriorRings(geom)`	`INTEGER`	Devolve o número de anéis internos em um polígono.
`ST_NumPoints`	`ST_NumPoints(geom)`	`INTEGER`	Fornece a contagem de pontos na geometria.
`ST_PointN`	`ST_PointN(geom, index)`	`GEOMETRY` (POINT)	Extrai o ponto no índice especificado de uma linestring. Índices negativos contam a partir do final: `-1` retorna o último ponto.
`ST_Points`	`ST_Points(geom)`	`GEOMETRY` (MULTIPOINT)	Coleta todos os pontos não vazios da geometria como um multipoint. Pontos duplicados, incluindo pontos iniciais e finais de anéis, são preservados.
`ST_StartPoint`	`ST_StartPoint(geom)`	`GEOMETRY`	Obtém o primeiro ponto de uma linestring. A geometria retornada mantém o mesmo SRID da entrada.
`ST_X`	`ST_X(point)`	`DOUBLE PRECISION`	Recupera a coordenada X de um ponto.
`ST_Y`	`ST_Y(point)`	`DOUBLE PRECISION`	Recupera a coordenada Y de um ponto.

Editores de geometry

Todas as funções deste grupo executam na HQE.

Função	Sintaxe	Retorno	Descrição
`ST_AddPoint`	`ST_AddPoint(geom1, geom2)`	`GEOMETRY`	Adiciona um ponto a uma linestring e retorna o resultado.
`ST_Multi`	`ST_Multi(geom)`	`GEOMETRY` (MULTIPOINT, MULTILINESTRING, MULTIPOLYGON ou GEOMETRYCOLLECTION)	Converte uma geometria para seu multi-tipo correspondente. Se a entrada já for um multi-tipo ou coleção, retorna uma cópia.
`ST_RemovePoint`	`ST_RemovePoint(geom, index)`	`GEOMETRY`	Remove o ponto no índice base zero especificado de uma linestring. A geometria retornada mantém o mesmo SRID da entrada.
`ST_Reverse`	`ST_Reverse(geom)`	`GEOMETRY`	Inverte a ordem dos vértices de uma geometria linear ou areal. Para ponto ou multipoint, retorna uma cópia. Para coleções, inverte os vértices de cada elemento.
`ST_SetPoint`	`ST_SetPoint(geom1, index, geom2)`	`GEOMETRY`	Substitui o ponto no índice especificado pelas coordenadas do ponto de entrada em uma linestring.

Validação de geometry

Função	Sintaxe	Retorno	Engine necessária	Descrição
`ST_IsValid`	`ST_IsValid(geom)`	`BOOLEAN`	PQE	Verifica se a geometria é válida conforme a especificação OGC, retornando `true` em caso positivo.

Funções de sistema de referência espacial

Todas as funções deste grupo executam na HQE.

Função	Sintaxe	Retorno	Descrição
`ST_SetSRID`	`ST_SetSRID(geom, srid)`	`GEOMETRY`	Atualiza o SRID da geometria de entrada para o valor especificado, sem reprojetar as coordenadas.
`ST_SRID`	`ST_SRID(geom)`	`INTEGER`	Obtém o SRID da geometria de entrada.

Entrada de geometry

Função	Sintaxe	Retorno	Engine necessária	Descrição
`ST_GeomFromText`	`ST_GeomFromText(wkt_string [, srid])`	`GEOMETRY`	PQE	Constrói uma geometria a partir de sua representação WKT (well-known text).

Saída de geometry

Todas as funções deste grupo executam na HQE.

Função	Sintaxe	Retorno	Descrição
`ST_AsBinary`	`ST_AsBinary(geom)`	`BYTEA`	Converte a geometria para sua representação WKB (well-known binary), codificada como string hexadecimal usando caracteres ASCII `0`–`9` e `A`–`F`.
`ST_AsEWKB`	`ST_AsEWKB(geom)`	`BYTEA`	Exporta a geometria em formato EWKB (extended well-known binary).
`ST_AsEWKT`	`ST_AsEWKT(geom)`	`TEXT`	Exporta a geometria em formato EWKT (extended well-known text).
`ST_AsGeoJSON`	`ST_AsGeoJSON(geom [, maxdecimaldigits])`	`TEXT`	Serializa a geometria como GeoJSON.
`ST_AsText`	`ST_AsText(geom [, precision])`	`TEXT`	Converte a geometria para sua representação WKT.

Predicados de relacionamento espacial

A engine varia conforme a função neste grupo. Consulte a coluna Required engine.

Função	Sintaxe	Retorno	Engine necessária	Descrição
`ST_Contains`	`ST_Contains(geom1, geom2)`	`BOOLEAN`	PQE	Retorna `true` se todos os pontos de `geom2` estiverem em `geom1` e seus interiores se interceptarem. Equivalente a `ST_Within(geom2, geom1)`.
`ST_ContainsProperly`	`ST_ContainsProperly(geom1, geom2)`	`BOOLEAN`	PQE	Devolve `true` se ambas as geometrias forem não vazias e todos os pontos de `geom2` estiverem no interior (não na fronteira) de `geom1`.
`ST_CoveredBy`	`ST_CoveredBy(geom1, geom2)`	`BOOLEAN`	HQE	Indica `true` se cada ponto de `geom1` estiver em `geom2`. Equivalente a `ST_Covers(geom2, geom1)`.
`ST_Covers`	`ST_Covers(geom1, geom2)`	`BOOLEAN`	PQE	Retorna `true` se cada ponto de `geom2` estiver em `geom1`. Equivalente a `ST_CoveredBy(geom2, geom1)`.
`ST_Crosses`	`ST_Crosses(geom1, geom2)`	`BOOLEAN`	HQE	Verifica se as duas geometrias se cruzam, retornando `true` em caso afirmativo.
`ST_Disjoint`	`ST_Disjoint(geom1, geom2)`	`BOOLEAN`	HQE	Retorna `true` se as duas geometrias não compartilharem nenhum ponto.
`ST_DWithin`	`ST_DWithin(geom1, geom2, threshold)`	`BOOLEAN`	PQE	Avalia se a distância euclidiana entre as duas geometrias não excede o limiar, retornando `true` nesse caso.
`ST_DWithin_S2`	`ST_DWithin_S2(x1, y1, x2, y2, threshold)`	`BOOLEAN`	HQE	Retorna `true` se a distância esférica entre duas localizações geográficas for menor ou igual a `threshold` (unidade: metros). Parâmetros em ordem: longitude da Localização 1, latitude da Localização 1, longitude da Localização 2, latitude da Localização 2, limiar de distância. Oferece suporte no Hologres V2.0.8 e posterior. Entradas constantes não têm suporte na versão atual.
`ST_Equals`	`ST_Equals(geom1, geom2)`	`BOOLEAN`	HQE	Confirma se as duas geometrias possuem conjuntos de pontos iguais e seus interiores se interceptam, retornando `true`.
`ST_Intersects`	`ST_Intersects(geom1, geom2)`	`BOOLEAN`	PQE	Retorna `true` se as duas geometrias compartilharem pelo menos um ponto.
`ST_Touches`	`ST_Touches(geom1, geom2)`	`BOOLEAN`	HQE	Indica `true` se as duas geometrias se tocarem — elas se interceptam mas não compartilham pontos internos.
`ST_Within`	`ST_Within(geom1, geom2)`	`BOOLEAN`	PQE	Retorna `true` se cada ponto de `geom1` estiver em `geom2` e seus interiores se interceptarem. Equivalente a `ST_Contains(geom2, geom1)`.

Funções de medição

Função	Sintaxe	Retorno	Engine necessária	Descrição
`ST_Angle`	`ST_Angle(geom1, geom2, geom3 [, geom4])`	`DOUBLE PRECISION`	HQE	Calcula o ângulo horário em radianos no intervalo [0, 2π). Com três pontos, mede a rotação de P1 a P3 em torno de P2. Com quatro pontos, mede o ângulo entre as linhas direcionadas P1–P2 e P3–P4; retorna null se P1 for igual a P2 ou P3 for igual a P4.
`ST_Area`	`ST_Area(geom)`	`DOUBLE PRECISION`	HQE	Retorna a área cartesiana da geometria nas mesmas unidades do sistema de coordenadas. Devolve `0` para pontos, linestrings e seus multi-tipos. Para coleções, soma as áreas de todos os elementos.
`ST_Azimuth`	`ST_Azimuth(point1, point2)`	`DOUBLE PRECISION`	HQE	Calcula o azimute cartesiano baseado no norte, definido por dois pontos.
`ST_Distance`	`ST_Distance(geom1, geom2)`	`DOUBLE PRECISION`	HQE	Mede a distância cartesiana entre duas geometrias, expressa nas mesmas unidades das coordenadas de entrada. Para calcular a distância esférica em metros, use `ST_Distance_Sphere_S2`, que recebe valores de longitude e latitude em vez de geometrias.
`ST_Distance_Sphere_S2`	`ST_Distance_Sphere_S2(x1, y1, x2, y2)`	`DOUBLE PRECISION`	HQE	Calcula a distância esférica entre duas localizações geográficas em metros. Parâmetros em ordem: longitude da Localização 1, latitude da Localização 1, longitude da Localização 2, latitude da Localização 2. Faixa válida de latitude: [-90, +90]. Faixa válida de longitude: [-180, +180]. Oferece suporte no Hologres V2.0.8 e posterior. Entradas constantes não têm suporte na versão atual.
`ST_Length`	`ST_Length(geom)`	`DOUBLE PRECISION`	HQE	Retorna o comprimento cartesiano de uma geometria linear nas mesmas unidades do sistema de coordenadas. Devolve `0` para pontos, multipoints e geometrias areais. Para coleções, retorna o comprimento total.
`ST_Perimeter`	`ST_Perimeter(geom)`	`DOUBLE PRECISION`	HQE	Calcula o perímetro cartesiano (comprimento da fronteira) de uma geometria areal nas mesmas unidades do sistema de coordenadas. Retorna `0` para pontos, multipoints e geometrias lineares. Para coleções, soma os perímetros de todos os elementos.

Função de sobreposição

Função	Sintaxe	Retorno	Engine necessária	Descrição
`ST_Intersection`	`ST_Intersection(geom1, geom2)`	`GEOMETRY`	HQE	Produz a interseção geométrica de duas geometrias.

Funções de processamento de geometry

Função	Sintaxe	Retorno	Engine necessária	Descrição
`ST_Buffer`	`ST_Buffer(geom, radius)`	Mesmo tipo da entrada: `GEOMETRY` para entrada geometry, `GEOGRAPHY` para entrada geography	PQE	Gera a geometria que representa todos os pontos dentro do raio especificado em relação à geometria de entrada.
`ST_ConvexHull`	`ST_ConvexHull(geom)`	`GEOMETRY`	HQE	Calcula o casco convexo (convex hull) de todos os pontos não vazios na geometria de entrada.
`ST_Simplify`	`ST_Simplify(geom, tolerance)`	`GEOMETRY`	HQE	Retorna uma cópia simplificada da geometria usando o algoritmo Ramer-Douglas-Peucker com a tolerância especificada. A topologia pode não ser preservada.

Funções de bounding box

Todas as funções deste grupo executam na PQE.

Função	Sintaxe	Retorno	Descrição
`ST_XMax`	`ST_XMax(geom)`	`DOUBLE PRECISION`	Obtém a coordenada X máxima do bounding box da geometria. O tipo do parâmetro é box3d; uma entrada geometry é convertida implicitamente.
`ST_XMin`	`ST_XMin(geom)`	`DOUBLE PRECISION`	Obtém a coordenada X mínima do bounding box da geometria. O tipo do parâmetro é box3d; uma entrada geometry é convertida implicitamente.
`ST_YMax`	`ST_YMax(geom)`	`DOUBLE PRECISION`	Obtém a coordenada Y máxima do bounding box da geometria. O tipo do parâmetro é box3d; uma entrada geometry é convertida implicitamente.
`ST_YMin`	`ST_YMin(geom)`	`DOUBLE PRECISION`	Obtém a coordenada Y mínima do bounding box da geometria. O tipo do parâmetro é box3d; uma entrada geometry é convertida implicitamente.

Função de referência linear

Função	Sintaxe	Retorno	Engine necessária	Descrição
`ST_LineInterpolatePoint`	`ST_LineInterpolatePoint(geom, fraction)`	`GEOMETRY` (POINT)	HQE	Interpola um ponto a uma distância fracionária ao longo da linha, medida a partir do início. Por exemplo, `fraction=0.5` retorna o ponto médio.

Melhores práticas para uso de funções espaciais

Para exemplos completos de padrões comuns de análise geográfica, consulte Use spatial functions to query data.

Suporte a engines

Instalar e desinstalar a extensão PostGIS

Desinstalar o PostGIS

Resolver o conflito da tabela spatial_ref_sys

Criar e consultar uma tabela geometry

1. Criar uma tabela geometry

2. Inserir dados espaciais

3. Consultar dados espaciais

Funções espaciais

Construtores de geometry

Acessadores de geometry

Editores de geometry

Validação de geometry

Funções de sistema de referência espacial

Entrada de geometry

Saída de geometry

Predicados de relacionamento espacial

Funções de medição

Função de sobreposição

Funções de processamento de geometry

Funções de bounding box

Função de referência linear

Melhores práticas para uso de funções espaciais

Resolver o conflito da tabela `spatial_ref_sys`