Usar a extensão TimescaleDB - ApsaraDB RDS: Central de Documentação do Alibaba Cloud

O TimescaleDB amplia o ApsaraDB RDS for PostgreSQL com sharding automático, gravações e recuperação eficientes e agregação de dados de série temporal em tempo quase real — ideal para telemetria IoT, métricas de aplicativos e dados de tick financeiro.

O ApsaraDB RDS for PostgreSQL oferece suporte apenas à extensão TimescaleDB de código aberto (licenciada sob Apache). Os recursos que exigem a licença comercial do Timescale não estão disponíveis. Para obter detalhes, consulte TimescaleDB.

Pré-requisitos

Antes de começar, certifique-se de que você tem:

Uma instância RDS executando o PostgreSQL 10 ou versão posterior
Uma versão secundária de engine 20230330 ou posterior (o PostgreSQL 17 exige a versão 20241030 ou posterior)

Para verificar e atualizar a versão secundária da engine, consulte Atualizar a versão secundária da engine de uma instância do ApsaraDB RDS for PostgreSQL.

Importante

A partir de 17 de abril de 2023, algumas extensões não podem mais ser criadas em instâncias que executam versões secundárias da engine anteriores à 20230330. Para obter detalhes, consulte [Aviso] A partir de 17 de abril de 2023, algumas extensões não podem mais ser criadas em instâncias do ApsaraDB RDS for PostgreSQL que executam versões secundárias da engine anteriores.

PostgreSQL 14 com TimescaleDB 2.5.0 ou anterior: se a versão secundária da engine for anterior à 20230330, execute ALTER EXTENSION timescaledb UPDATE; após atualizar para a versão 20230330 ou posterior.
PostgreSQL 10, 11, 12, 13 e 15: as instalações existentes do TimescaleDB não são afetadas pelo requisito de versão secundária da engine.
Primeira instalação ou reinstalação: atualize a versão secundária da engine para 20230330 ou posterior antes de continuar.

Se o TimescaleDB já estava instalado antes de uma atualização da versão secundária da engine, o seguinte erro pode aparecer em seguida: Execute a instrução a seguir para resolver o problema:

ERROR:  could not access file "$libdir/timescaledb-1.3.0": No such file or directory

ALTER EXTENSION timescaledb UPDATE;

Etapa 1: Instalar a extensão

Instalar pelo console

Acesse a página Instâncias. Selecione a região na barra de navegação superior e clique no ID da instância.
No painel de navegação à esquerda, clique em Plug-ins.
Na aba Extension Marketplace, localize a seção timescaledb e clique em Install.
Na caixa de diálogo, selecione um banco de dados e uma conta privilegiada e clique em Install.

A extensão estará pronta quando o status da instância mudar de Maintaining Instance para Running.

Instalar via SQL

Adicione timescaledb ao parâmetro shared_preload_libraries. Por exemplo, defina o Running Value como 'pg_stat_statements,auto_explain,timescaledb'. Para obter detalhes, consulte Modificar os parâmetros de uma instância do ApsaraDB RDS for PostgreSQL.

Conecte-se ao banco de dados de destino e execute:

CREATE EXTENSION IF NOT EXISTS timescaledb CASCADE;

Para verificar a instalação, execute SELECT * FROM pg_extension; e confirme que timescaledb aparece nos resultados.

Etapa 2: Criar uma hypertable

Uma hypertable é a estrutura de dados central do TimescaleDB para dados de série temporal. Ela é particionada automaticamente por tempo — e opcionalmente por uma dimensão adicional — para que o desempenho das consultas permaneça estável à medida que os dados crescem.

Conecte-se ao banco de dados e crie uma tabela padrão:

CREATE TABLE conditions (
  time        TIMESTAMPTZ       NOT NULL,
  location    TEXT              NOT NULL,
  temperature DOUBLE PRECISION  NULL,
  humidity    DOUBLE PRECISION  NULL
);

Converta a tabela em uma hypertable, particionada pela coluna time:
```
SELECT create_hypertable('conditions', 'time');
```

Para obter mais opções de configuração, consulte Criar hypertables.

Etapa 3: Inserir dados

Use instruções INSERT padrão — o TimescaleDB encaminha cada linha para o chunk correto automaticamente.

Linha única:

INSERT INTO conditions(time, location, temperature, humidity)
  VALUES (NOW(), 'office', 70.0, 50.0);

Múltiplas linhas (recomendado para maior throughput):

INSERT INTO conditions
  VALUES
    (NOW(), 'office', 70.0, 50.0),
    (NOW(), 'basement', 66.5, 60.0),
    (NOW(), 'garage', 77.0, 65.2);

Agrupar linhas em um único INSERT é mais eficiente porque o TimescaleDB as agrupa por chunk e grava cada chunk em uma única transação.

Etapa 4: Consultar dados

O TimescaleDB estende o PostgreSQL padrão com funções SQL específicas para tempo. Os exemplos a seguir usam a tabela conditions criada na Etapa 2.

Agrupar dados em buckets de tempo

A função time_bucket() arredonda timestamps para um intervalo fixo, facilitando o cálculo de agregados por período.

-- Aggregate data into 15-minute buckets over the last 3 hours.
SELECT time_bucket('15 minutes', time) AS fifteen_min,
    location,
    COUNT(*),
    MAX(temperature) AS max_temp,
    MAX(humidity) AS max_hum
  FROM conditions
  WHERE time > NOW() - INTERVAL '3 hours'
  GROUP BY fifteen_min, location
  ORDER BY fifteen_min DESC, max_temp DESC;

Resultado de exemplo:

      fifteen_min       | location | count | max_temp | max_hum
------------------------+----------+-------+----------+---------
 2024-12-20 16:00:00+08 | garage   |     1 |       77 |    65.2
 2024-12-20 16:00:00+08 | office   |     2 |       70 |      50
 2024-12-20 16:00:00+08 | basement |     1 |     66.5 |      60

Calcular uma média móvel

Use uma função de janela SQL padrão para suavizar dados ruidosos de sensores:

-- 10-reading moving average for garage temperature over the last day.
SELECT time,
    AVG(temperature) OVER(
      ORDER BY time
      ROWS BETWEEN 9 PRECEDING AND CURRENT ROW
    ) AS smooth_temp
  FROM conditions
  WHERE location = 'garage'
    AND time > NOW() - INTERVAL '1 day'
  ORDER BY time DESC;

Resultado de exemplo:

            time              | smooth_temp
------------------------------+-------------
 2024-12-20 16:11:14.691822+08 |          77

Calcular a mediana

Use a função padrão do PostgreSQL percentile_cont para encontrar a mediana ou qualquer outro percentil:

-- Median temperature across all records.
SELECT percentile_cont(0.5)
    WITHIN GROUP (ORDER BY temperature)
  FROM conditions;

Resultado de exemplo:

 percentile_cont
-----------------
              70

Solução de problemas

Erro de licença

Erro:

ERROR:  functionality not supported under the current license "ApacheOnly", license
HINT:  Upgrade to a Timescale-licensed binary to access this free community feature

O ApsaraDB RDS for PostgreSQL inclui a versão de código aberto (licenciada sob Apache) do TimescaleDB. Os recursos que exigem a licença comercial do Timescale não estão disponíveis porque essa licença proíbe o uso em ofertas de banco de dados como serviço ou software como serviço. Para obter detalhes, consulte a Seção 2.2 do Contrato de Licença do TimescaleDB.

Erro de criação de índice simultânea

Erro:

hypertables do not support concurrent index creation.

O TimescaleDB não oferece suporte a CREATE INDEX CONCURRENTLY em hypertables. Use a alternativa a seguir, que reduz o tempo de retenção de bloqueio criando o índice um chunk por vez:

CREATE INDEX ON conditions (location, time)
  WITH (timescaledb.transaction_per_chunk);

Para obter detalhes, consulte a documentação do Timescale.

ApsaraDB RDS:Usar a extensão TimescaleDB

Pré-requisitos

Etapa 1: Instalar a extensão

Instalar pelo console

Instalar via SQL

Etapa 2: Criar uma hypertable

Etapa 3: Inserir dados

Etapa 4: Consultar dados

Agrupar dados em buckets de tempo

Calcular uma média móvel

Calcular a mediana

Solução de problemas

Erro de licença

Erro de criação de índice simultânea

Próximas etapas