Sinopse
Descrição
O módulo chdb_hook se integra ao comando COPY do PostgreSQL para usar o chDB e copiar dadosTO 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:
Sobrecarga do COPY
Durante o carregamento, o chdb_hook se integra ao comando COPY do Postgres para copiar dadosTO 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
UmCOPY 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 deCOPY 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 rolepg_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. ParaCOPY 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 S3GCS
As URLs do GCS têm o formato de uma URL pública:Azure Blob Storage
Use uma URLblob.windows.net com o nome da account como subdomínio:
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 comandosCOPY 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>= Ne<= M.**: Corresponde recursivamente a todos os arquivos de um directory.
- https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_1.csv
- https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_2.csv
- https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_3.csv
- https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_1.csv
- https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_2.csv
- https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_3.csv
{some,another}_prefix para corresponder aos dois nomes de directory e
some_file_{1..3}.csv' para corresponder aos arquivos, assim:
Opções
O comandoCOPY 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_IDeAWS_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)nonegzipougzbrotlioubrxzouLZMAzstdouzstlz4bz2snappy
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 comandoCOPY do chdb_hook inclui no contexto do erro a consulta chDB que ele tentou
executar:
{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:
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çãostructure_from e deixe a lista de colunas vazia:
copy_from para carregar as linhas, além das colunas:
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:
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:
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
COPYem relações com policies de row-level security aplicáveis à role que faz a cópia. O Postgres aplica essas policies reescrevendo oCOPY TOcomo uma consulta, o que o chdb_hook não suporta. - O ClickHouse não possui array NULL, portanto o
COPY TOarmazena um array vazio ([]) no lugar de umNULL. - O ClickHouse representa os equivalentes de
lseg,pathoupolygoncomo arrays; assim, valores NULL desses tipos também são gravados peloCOPY TOcomo 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
pathaberto 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
StringdejsonejsonbporJSONsomente 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ãoStringdejsonejsonbporJSONsomente se os valores do objeto não foremnullou 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 FROMlê um campoNullabledo Protobuf que contenha uma string vazia ou zero comoNULL. (chdb-io/chdb-core#152) - O
COPY TOem Parquet descarta osNULLs 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
timedo Postgres nem aoTime64do chDB. Configure as colunastimecomoStrings 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
timecomoStrings em uma structure explícita para preservar seus valores. (ClickHouse/ClickHouse#111860) - Os formatos CSVWithNames e CSVWithNamesAndTypes atualmente não conseguem importar
valores
NULLde 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 hookCOPY 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 peloDESCRIBE 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:
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
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)
0, que não impõe limite de memória.
chdb_hook.max_threads
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
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
pg_get_loaded_modules() do Postgres 18.