motor de tabela URL

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.

O motor URL é um wrapper unificado sobre os outros motores de armazenamento de arquivos e objetos: ele encaminha 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 encaminhados. 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 encaminhamento 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);

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.

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.

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 │
└───────┴───────┘

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

• _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)).

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;

• 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.