Skip to main content

Sinopse

Descrição

O módulo chdb_hook se integra ao comando COPY do PostgreSQL para usar o chDB e copiar dados TO ou FROM qualquer um dos formatos de dados fornecidos pelo chDB em arquivos locais, buckets do AWS S3, Google Cloud Storage, entre outros. Ele também se integra ao CREATE TABLE, permitindo que uma tabela derive suas colunas e carregue suas linhas a partir de qualquer um desses mesmos destinos.

Carregamento

Carregue o chdb_hook de uma das seguintes maneiras como super user. Use a que fizer mais sentido para o seu caso de uso:
  • Explicitamente, via comando LOAD; permanece ativo pelo tempo de duração de uma session:
    O SQL Console do ClickHouse Cloud ainda não oferece suporte ao comando LOAD 'chdb_hook', mas ele pode ser executado via psql ou qualquer outra database connection. Caso contrário, entre em contato com seu representante de Support para adicioná-lo à configuration do seu service Postgres, e depois disso ele poderá ser usado no SQL Console.
  • Para todas as sessions, pela configuração [session_preload_libraries], no postgresql.conf:
    Ou via ALTER SYSTEM:
    Essa configuração também pode ser definida individualmente por database, via ALTER DATABASE:
    Ou para usuários e grupos específicos, via ALTER ROLE:
  • Na inicialização do servidor, pela configuração [shared_preload_libraries], de modo que fique sempre disponível para todas as sessions e databases:
Atenção: carregar o chdb_hook permite que usuários nas roles pg_read_server_files ou pg_write_server_files executem COPY de dados de e para arquivos no servidor Postgres, bem como para cloud storage.

Sobrecarga do COPY

Durante o carregamento, o chdb_hook se integra ao comando COPY do Postgres para copiar dados TO ou FROM qualquer um dos formatos de dados suportados pelo chDB em arquivos locais, buckets do AWS S3, Google Cloud Storage e outros. Para carregar uma tabela a partir de um arquivo CSV no S3, por exemplo, crie a tabela e depois chame COPY com uma URL s3://:

Privilégios

Um COPY do chdb_hook exige os mesmos privilégios do COPY que ele substitui: SELECT na relação ou em cada coluna copiada, no caso do COPY TO, e INSERT no caso do COPY FROM. Uma URL file:// lê ou grava um arquivo no servidor, portanto também exige participação em pg_read_server_files ou pg_write_server_files. O COPY FROM exige uma transação de leitura e gravação.

Esquemas de URL

O chdb_hook só é executado para destinos de COPY do tipo URL que usam um dos esquemas a seguir:

Formatos de URL

O formato das URLs varia conforme o target.

File

Deve ser um caminho absoluto no servidor Postgres. Um caminho relativo resulta em erro. O usuário do Postgres deve ser membro da role pg_read_server_files ou pg_write_server_files, conforme apropriado. O usuário de sistema do Postgres deve ter acesso de leitura ou escrita ao arquivo, conforme apropriado. No caso de COPY TO, se o caminho não existir, o chdb_hook criará os diretórios pais que estiverem ausentes; para isso, ele precisa ter permissão no sistema de arquivos. Exemplo:

HTTP

Qualquer URL HTTP comum, inclusive em armazenamento em nuvem público. Para COPY TO, o chdb_hook tentará fazer um POST dos dados para a URL. Exemplo:

S3

URLs do S3 podem assumir o formato de um URI do S3
Ou de uma URL de object:

GCS

As URLs do GCS têm o formato de uma URL pública:
Ou uma URI do Cloud Storage, que o chdb_hook converte em uma URL pública:

Azure Blob Storage

Use uma URL blob.windows.net com o nome da account como subdomínio:
Ou use algum outro host name:

Azure ABFS

URLs ABFS devem usar este formato:

URLs HDFS

URLs HDFS podem usar URLs típicas no estilo HTTP, com uma porta opcional:

Wildcards em paths

Os paths de URL podem conter globs em comandos COPY FROM. Os arquivos devem corresponder ao padrão completo do path, não apenas ao suffix ou ao prefix. Há uma única exceção: quando o path se refere a um directory existente e não usa globs, um * é adicionado implicitamente ao path para selecionar todos os arquivos do directory. Os wildcards suportados:
  • *: Corresponde a uma quantidade arbitrária de characters, exceto /, incluindo a empty string.
  • ?: Corresponde a um único character arbitrário.
  • {groucho,harpo,chico}: Substitui qualquer uma das strings “groucho”, “harpo” e “chico”. As strings podem conter /.
  • {N..M}: Corresponde a qualquer número >= N e <= M.
  • **: Corresponde recursivamente a todos os arquivos de um directory.
Por exemplo, para carregar dados destes arquivos em um único comando: Use {some,another}_prefix para corresponder aos dois nomes de directory e some_file_{1..3}.csv' para corresponder aos arquivos, assim:

Opções

O comando COPY do chdb_hook oferece suporte às seguintes opções:

format:

O formato de leitura ou escrita. Deve ser um dos formats fornecidos pelo chDB, que incluem TSV, CSV, Parquet, Iceberg, JSON, entre outros. Omita ou defina como auto para que o chDB determine o formato a partir da extensão do nome do arquivo ao final da URL.

structure

A estrutura de dados do chDB para uma linha. Consiste em uma lista de nomes de colunas, [tipos de dados do ClickHouse] e modificadores. Se omitido, o chdb_hook mapeia os tipos de dados do Postgres para tipos do ClickHouse geralmente apropriados; consulte Postgres para chDB para mais detalhes. Se definido como auto, o chDB tenta inferir os tipos. Exemplo:

access_key e access_secret

Credenciais de longo prazo do usuário da AWS account para autenticar requisições.
  • S3: Um [access key ID e access secret] da AWS, geralmente definidos pelas variáveis de ambiente AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY
  • GCS: Uma HMAC key and secret do GCP
  • Azure: Um nome de Azure storage account e access key

session_token

Token de sessão da AWS a ser usado com access_key e access_secret, geralmente definido pela variável de ambiente AWS_SESSION_TOKEN. Usado apenas para URLs do S3.

compression

Formato de compressão do arquivo. Use quando a compressão não puder ser inferida pelo nome do arquivo. Valores suportados:
  • auto (padrão)
  • none
  • gzip ou gz
  • brotli ou br
  • xz ou LZMA
  • zstd ou zst
  • lz4
  • bz2
  • snappy

timeout

Tempo limite da requisição em milissegundos. Aplica-se a URLs HTTP, S3, GCS e Azure. O padrão é 30000 (30s).

Depuração

Em caso de erro, o comando COPY do chdb_hook inclui no contexto do erro a consulta chDB que ele tentou executar:
O chdb_hook usa placeholders no estilo {name:Type} para query parameters, a fim de proteger contra vulnerabilidades de injection de SQL e minimizar o risco de registrar dados sensíveis em log, como credenciais. Se, no entanto, você precisar ver o conteúdo desses parameters para depurar um issue, defina temporariamente o GUC [log_min_messages] do Postgres como DEBUG1 ou superior, para que o chdb_hook envie a consulta e os parameters ao log do Postgres (nunca ao client), onde aparecerão assim:
Não mantenha [log_min_messages] em um nível de depuração por mais tempo do que uma única sessão de depuração, para evitar o registro de informações sensíveis como credenciais, e porque o próprio PostgreSQL também registra informações de depuração e pode encher o log rapidamente.

Sobrecarga de CREATE TABLE

O chdb_hook também faz hook em CREATE TABLE, de modo que uma tabela possa derivar suas colunas e carregar suas linhas a partir de uma URL. Para criar uma tabela com a estrutura derivada de uma URL, passe a URL na opção structure_from e deixe a lista de colunas vazia:
Use copy_from para carregar as linhas, além das colunas:
O copy_from infere as colunas apenas quando a instrução não define nenhuma coluna própria. Uma lista de colunas, uma cláusula INHERITS, um tipo OF ou uma partição definem colunas e, nesse caso, o copy_from copia apenas:
Ambas as opções suportam os mesmos esquemas de URL e options que COPY; credentials, format, compression, timeout e até mesmo uma structure explícita se aplicam. O Postgres mantém os parâmetros de armazenamento que restarem:
Nem structure_from nem copy_from funcionam com IF NOT EXISTS. Use COPY para carregar uma relação existente.

Limitações

Devido a alguns problemas conhecidos e a variações no comportamento dos tipos de dados entre o Postgres e o chDB, o chdb_hook apresenta as seguintes limitações:
  • Não é possível executar COPY em relações com policies de row-level security aplicáveis à role que faz a cópia. O Postgres aplica essas policies reescrevendo o COPY TO como uma consulta, o que o chdb_hook não suporta.
  • O ClickHouse não possui array NULL, portanto o COPY TO armazena um array vazio ([]) no lugar de um NULL.
  • O ClickHouse representa os equivalentes de lseg, path ou polygon como arrays; assim, valores NULL desses tipos também são gravados pelo COPY TO como um array vazio ([]).
  • Valores NULL emitidos para uma structure especificada que não defina a coluna como Nullable serão emitidos como seus valores default. Defina sempre explicitamente as colunas nullable na structure para evitar essa conversão.
  • Um path aberto cujo último ponto é igual ao primeiro é emitido como um path fechado.
  • O Protobuf não possui null em campos repetidos, portanto valores NULL em arrays são omitidos.
  • O JSON type do chDB suporta apenas JSON objects; substitua o mapeamento padrão String de json e jsonb por JSON somente se todos os valores forem JSON object. (ClickHouse/ClickHouse#68428)
  • O JSON type do chDB ignora nulls; chaves de objeto com valores NULL serão omitidas na saída. Substitua o mapeamento padrão String de json e jsonb por JSON somente se os valores do objeto não forem null ou se sua perda for aceitável. (ClickHouse/ClickHouse#68428)
  • Os formatos JSON, JSONCompact e JSONColumnsWithMetadata sempre validam UTF-8, portanto emitem valores bytea com caracteres de substituição.
  • O COPY FROM lê um campo Nullable do Protobuf que contenha uma string vazia ou zero como NULL. (chdb-io/chdb-core#152)
  • O COPY TO em Parquet descarta os NULLs do null map próprio de um Tuple Nullable. (ClickHouse/ClickHouse#112427)
  • Os formatos Parquet, Arrow, ArrowStream, ORC, Avro, Protobuf, ProtobufList, MsgPack e BSONEachRow não possuem tipo correspondente ao time do Postgres nem ao Time64 do chDB. Configure as colunas time como Strings em uma structure explícita para preservar seus valores.
  • A saída em Protobuf trunca os valores de timestamp para o segundo.
  • A saída em Protobuf não suporta datas anteriores a 1970-01-01. Configure as colunas time como Strings em uma structure explícita para preservar seus valores. (ClickHouse/ClickHouse#111860)
  • Os formatos CSVWithNames e CSVWithNamesAndTypes atualmente não conseguem importar valores NULL de box ou circle. (ClickHouse/ClickHouse#115523)

Tipos de dados

O COPY mapeia os tipos do Postgres de uma relação para tipos do chDB, enquanto o CREATE TABLE mapeia os tipos do chDB de uma URL para tipos do Postgres.

Postgres para chDB

Na ausência de uma opção structure explícita, o chdb_hook mapeia tipos do Postgres para equivalentes razoáveis no chDB. Quando eles não atenderem ao seu caso de uso, especifique a structure para substituir os tipos gerados pelos que você precisa. Tipos de array são mapeados para Arrays do element type correspondente. O ClickHouse restringe a nulidade por coluna, enquanto o Postgres a restringe por array; por isso, os elements são sempre Nullable. Nenhum tipo do Postgres é mapeado para Map ou Tuple, mas structure pode indicar um. Um Map pode ser convertido em um array de pares key value, e um Tuple é convertido em um array. Use text[] para suporte a dados heterogêneos.

Conversão de timestamp

Em formatos de texto simples (TSV, CSV, etc.), o hook COPY emite valores DateTime e DateTime64 no formato ISO-8601, YYYY-MM-DDThh:mm:ssZ, independentemente da configuração datestyle atual. Isso garante que os valores timestamptz permaneçam consistentes, mesmo que a origem que importa os valores use um fuso horário diferente. Usar um tipo diferente na saída de structure, como Datetime64(3, 'America/Los_Angeles'), não altera o deslocamento da saída, mas altera a precisão. Exemplos de Timestamp TZ: O hook COPY também converte valores de timestamp do fuso horário da sessão para UTC, garantindo assim que a saída seja relativa a esse fuso horário. Ao serem carregados em um novo sistema, este deve convertê-los para o seu fuso horário local. Portanto, os valores serão diferentes se o fuso horário for diferente, mas equivalentes considerando a diferença entre os fusos. Exemplo do efeito da configuração timezone sobre o timestamp 2026-08-28T12:00:00:

chDB para Postgres

O chdb_hook mapeia os tipos do ClickHouse informados pelo DESCRIBE para estes tipos do Postgres: Todo tipo do chDB omitido desta tabela gera um erro, entre eles Nested, Variant e Dynamic. Use uma structure que os mapeie para String para lê-los como texto. O Postgres admite um intervalo mais restrito que o chDB em alguns desses tipos; por isso, a cópia gera um erro em um Time ou Time64 superior a 24 horas, e em um Date32 fora do intervalo de datas do Postgres.

Codificação de texto

O chDB lê String, FixedString, Enum e JSON como bytes, sem qualquer garantia de codificação. Ao copiar uma coluna desse tipo para text, ou para qualquer outro tipo não binário, os bytes são verificados contra a codificação do banco de dados e é gerado um erro para os dados que não podem ser representados:
Todas as codificações rejeitam NULs, que o Postgres não consegue armazenar em text. Copie para bytea para manter os bytes exatamente como o chDB os escreveu. Nomeie-os dessa forma, pois o CREATE TABLE deriva text para esses tipos:
FixedString(N) preenche valores mais curtos com bytes NUL. Ao copiar para text, os NULs finais são descartados, enquanto bytea mantém todos os N bytes.

Configurações

chdb_hook.max_memory

Define a quantidade máxima de memória para uma consulta chDB, usada para definir a configuração max_memory_usage do chDB. Requer privilégios de superusuário. Use um número inteiro para indicar a quantidade de megabytes ou uma das seguintes unidades de memória:
  • B (bytes)
  • kB (kilobytes)
  • MB (megabytes)
  • GB (gigabytes)
  • TB (terabytes)
O padrão é 0, que não impõe limite de memória.

chdb_hook.max_threads

O número máximo de threads de processamento de consultas para uma consulta chDB, usado para definir a configuração max_threads do chDB. Requer privilégios de superusuário. O padrão é 0, que deixa o próprio chDB determinar o valor. Recomendamos fortemente definir chdb_hook.max_threads antes de executar um COPY de grande porte, para evitar que o chDB consuma toda a CPU em detrimento do PostgreSQL.

chdb_hook.max_parsing_threads

O número máximo de threads que o chDB pode usar para fazer o parsing de dados em input formats que suportam parallel parsing, utilizado para definir a configuração max_parsing_threads do chDB. Requer privilégios de superusuário. O padrão é 0, o que deixa o próprio chDB determinar o valor. Recomendamos definir chdb_hook.max_parsing_threads antes de executar COPY com grandes volumes de dados, para evitar que o chDB consuma todo o uso de CPU em detrimento do PostgreSQL.

Política de versionamento

O chdb_hook segue o Semantic Versioning em seus lançamentos públicos.
  • A major version é incrementada em mudanças de API
  • A minor version é incrementada em mudanças de SQL compatíveis com versões anteriores
  • A versão de patch é incrementada em mudanças apenas no binary
Uma vez instalado, o PostgreSQL a versão por meio da função pg_get_loaded_modules() do Postgres 18.

Autores

Copyright (c) 2026, ClickHouse
Última modificação em 26 de setembro de 2026