motor de tabela URL - ClickHouse Documentation

Consulta dados de e para um servidor HTTP/HTTPS remoto. Este motor é semelhante ao motor File. O motor URL também é um wrapper unificado que faz o encaminhamento para o backend correto com base no esquema da URL, de modo que um esquema não HTTP reconhecido é delegado ao motor correspondente — consulte Despacho por esquema de URL abaixo. Sintaxe: URL(URL [,Format] [,CompressionMethod])

O parâmetro URL deve estar em conformidade com a estrutura de um Uniform Resource Locator. Para uma URL http/https (o backend padrão), ela deve apontar para um servidor que use HTTP ou HTTPS, e obter uma resposta do servidor não requer cabeçalhos adicionais. Já uma URL com um esquema não HTTP reconhecido (file://, s3://, az://, hdfs://, …) é delegada ao motor correspondente — consulte Despacho por esquema de URL abaixo.
O Format deve ser um formato que o ClickHouse possa usar em consultas SELECT e, se necessário, em INSERT. Para a lista completa de formatos compatíveis, consulte Formats. Se esse argumento não for especificado, o ClickHouse detectará o formato automaticamente pelo sufixo do parâmetro URL. Se o sufixo do parâmetro URL não corresponder a nenhum dos formatos compatíveis, a criação da tabela falhará. Por exemplo, para a expressão de motor URL('http://localhost/test.json'), o formato JSON é aplicado.
CompressionMethod indica se o corpo HTTP deve ser comprimido. Se a compressão estiver habilitada, os pacotes HTTP enviados pelo motor URL conterão o cabeçalho ‘Content-Encoding’ para indicar qual método de compressão está sendo usado.

Para habilitar a compressão, primeiro certifique-se de que o endpoint HTTP remoto indicado pelo parâmetro URL oferece suporte ao algoritmo de compressão correspondente. O CompressionMethod compatível deve ser um dos seguintes:

gzip or gz
deflate
brotli or br
lzma or xz
zstd or zst
lz4
bz2
snappy
none
auto

Se CompressionMethod não for especificado, o padrão será auto. Isso significa que o ClickHouse detecta automaticamente o método de compressão pelo sufixo do parâmetro URL. Se o sufixo corresponder a qualquer um dos métodos de compressão listados acima, a compressão correspondente será aplicada; caso contrário, nenhuma compressão será habilitada. Por exemplo, para a expressão de motor URL('http://localhost/test.gzip'), o método de compressão gzip é aplicado, mas para URL('http://localhost/test.fr'), nenhuma compressão é habilitada porque o sufixo fr não corresponde a nenhum dos métodos de compressão acima.

Despacho por esquema de URL

O motor URL é um wrapper unificado sobre os outros motores de armazenamento de arquivos e objetos: ele direciona para o backend correto com base no esquema da URL. http/https (e qualquer esquema não reconhecido) são atendidos pelo próprio motor URL; file:// é atendido pelo motor File; s3://, gs://, gcs://, oss:// pelo motor S3; az://, azure://, abfss://, abfs:// pelo motor AzureBlobStorage; e hdfs:// pelo motor HDFS. Somente os esquemas S3 que o mapeador de URI do S3 resolve para um endpoint concreto sem configuração adicional (s3, além de gs/gcs/oss) são despachados. Outros esquemas de provedores compatíveis com S3 (cos, obs, eos, …) são específicos de região e não têm mapeamento de endpoint padrão; portanto, passar uma URL desse tipo para o motor URL faz com que ela seja tratada como um esquema não reconhecido e reportada como erro. Para esses backends, use diretamente o motor S3 (com url_scheme_mappers configurado). A configuração url_base é aplicada antes do despacho por esquema, portanto uma referência relativa é primeiro resolvida em relação à base e depois encaminhada ao motor correspondente.

CREATE TABLE file_via_url (a UInt32, b String) ENGINE = URL('file://data.csv', CSV);
CREATE TABLE s3_via_url (a UInt32, b String) ENGINE = URL('s3://bucket/key.csv', CSV);

Uso

As consultas INSERT e SELECT são transformadas em requisições POST e GET, respectivamente. Para processar requisições POST, o servidor remoto deve oferecer suporte a Chunked transfer encoding. Você pode limitar o número máximo de redirecionamentos HTTP GET usando a configuração max_http_get_redirects.

Curingas com páginas de índice HTTP

Quando allow_experimental_url_wildcard_from_index_pages está habilitada, o motor de tabela URL pode expandir curingas ao buscar páginas de índice HTTP e extrair links delas. Esse é o mesmo mecanismo da função de tabela url. A expansão é limitada por max_http_index_page_size para cada página de índice obtida e por url_wildcard_max_directories_to_read ao percorrer diretórios recursivamente.

Exemplo

1. Crie uma tabela url_engine_table no servidor:

CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)

2. Crie um servidor HTTP básico usando as ferramentas padrão do Python 3 e inicie-o:

from http.server import BaseHTTPRequestHandler, HTTPServer

class CSVHTTPServer(BaseHTTPRequestHandler):
    def do_GET(self):
        self.send_response(200)
        self.send_header('Content-type', 'text/csv')
        self.end_headers()

        self.wfile.write(bytes('Hello,1\nWorld,2\n', "utf-8"))

if __name__ == "__main__":
    server_address = ('127.0.0.1', 12345)
    HTTPServer(server_address, CSVHTTPServer).serve_forever()

$ python3 server.py

3. Solicitar dados:

SELECT * FROM url_engine_table

┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘

Detalhes da implementação

Leituras e gravações podem ocorrer em paralelo
Não há suporte a:
- Operações ALTER e SELECT...SAMPLE.
- Índices.
- Replicação.

Colunas virtuais

_path — Caminho da URL. Tipo: LowCardinality(String).
_file — Nome do recurso da URL. Tipo: LowCardinality(String).
_size — Tamanho do recurso em bytes. Tipo: Nullable(UInt64). Se o tamanho for desconhecido, o valor será NULL.
_time — Hora da última modificação do arquivo. Tipo: Nullable(DateTime). Se a hora for desconhecida, o valor será NULL.
_headers - Cabeçalhos da resposta HTTP. Tipo: Map(LowCardinality(String), LowCardinality(String)).

Resolução de URLs relativas

A configuração url_base permite usar uma URL relativa no motor URL. Quando url_base está definido, a URL passada para o motor é resolvida com base nele, de acordo com a RFC 3986. Para ver uma descrição completa das regras de resolução, consulte a documentação da função de tabela url. Exemplo

SET url_base = 'http://127.0.0.1:12345/';
CREATE TABLE url_engine_table (word String, value UInt64) ENGINE = URL('hello.csv', CSV);
SELECT * FROM url_engine_table;

Configurações de armazenamento

engine_url_skip_empty_files - permite ignorar arquivos vazios durante a leitura. Desativado por padrão.
enable_url_encoding - permite ativar/desativar a decodificação/codificação do caminho na URI. Ativado por padrão.
url_base - URL base para a resolução de URLs relativas passadas ao motor.

​Despacho por esquema de URL

​Uso

​Curingas com páginas de índice HTTP

​Exemplo

​Detalhes da implementação

​Colunas virtuais

​Resolução de URLs relativas

​Configurações de armazenamento