url

A função url cria uma tabela a partir de uma URL, com format e structure especificados.

A função url pode ser usada em consultas SELECT e INSERT com dados em tabelas URL.

url(URL [,format] [,structure] [,headers])

Uma tabela com o formato e a estrutura especificados, contendo dados da URL definida.

Obtendo as 3 primeiras linhas de uma tabela com colunas dos tipos String e UInt32 a partir de um servidor HTTP que responde no formato CSV.

SELECT * FROM url('http://127.0.0.1:12345/', CSV, 'column1 String, column2 UInt32', headers('Accept'='text/csv; charset=utf-8')) LIMIT 3;

Inserindo dados de uma URL em uma tabela:

CREATE TABLE test_table (column1 String, column2 UInt32) ENGINE=Memory;
INSERT INTO FUNCTION url('http://127.0.0.1:8123/?query=INSERT+INTO+test_table+FORMAT+CSV', 'CSV', 'column1 String, column2 UInt32') VALUES ('http interface', 42);
SELECT * FROM test_table;

A função url atua como um wrapper unificado sobre as outras funções de tabela de arquivo e armazenamento de objetos: ela encaminha para o backend correto com base no esquema da URL. Isso permite ler de qualquer local compatível com uma única sintaxe uniforme.

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 fornecedores compatíveis com S3 (cos, obs, eos, …) são específicos da região e não têm mapeamento de endpoint padrão, portanto uma URL cos://… é tratada como um esquema não reconhecido e reportada como erro; use a função s3 diretamente (com url_scheme_mappers configurado) para esses backends.

Para file://, um caminho relativo (file://data.csv) é resolvido dentro do diretório user_files, e um caminho absoluto (file:///home/user/data.csv) deve apontar para dentro dele, como de costume.

Os argumentos format, structure e compression_method e a configuração url_base funcionam da mesma forma, independentemente do destino do encaminhamento.

SELECT * FROM url('file://data.csv', CSV, 'a UInt32, b String');
SELECT * FROM url('s3://clickhouse-public-datasets/hits_compatible/hits.csv');

O encaminhamento por esquema ainda não é suportado em urlCluster: um esquema diferente de http(s) fornecido a urlCluster é rejeitado com erro. Em vez disso, use a função de cluster correspondente (s3Cluster, azureBlobStorageCluster, hdfsCluster, …) para esses backends.

Padrões em { } são usados para gerar um conjunto de shards ou para especificar endereços de failover. Para ver os tipos de padrões compatíveis e exemplos, consulte a descrição da função remote. O caractere | dentro dos padrões é usado para especificar endereços de failover. Eles são percorridos na mesma ordem em que aparecem no padrão. O número de endereços gerados é limitado pela configuração glob_expansion_max_elements. Para a sintaxe de globs no caminho da URL (como *, {a,b}, {N..M} e **), consulte Globs no caminho. Observe que ? inicia a string de consulta em uma URL e não pode ser usado como caractere curinga no componente de caminho.

Para url e o mecanismo de tabela URL, o ClickHouse pode expandir curingas ao buscar páginas de índice HTTP (HTML ou texto simples) e extrair URLs do corpo da resposta. Isso permite padrões como /**/ quando o servidor expõe listagens de diretórios.

Notas:

• URLs relativas são resolvidas em relação à URL da página de índice.
• Os templates de URL são expandidos antes da busca das páginas de índice, incluindo a expansão de shard por vírgulas e intervalos numéricos, além de opções de failover com | fora do componente de caminho.
• Não há suporte a padrões de failover com | dentro do componente de caminho na expansão de páginas de índice HTTP.
• A correspondência de curingas é aplicada ao componente de caminho da URL.
• Se uma URL listada já contiver uma string de consulta ou fragmento, ela terá precedência sobre os da URL de origem. Caso contrário, a string de consulta e o fragmento da URL de origem serão usados.
• Uma listagem vazia é permitida; erros HTTP (por exemplo, 404) em páginas de índice geram exceções.
• O tamanho máximo da página de índice é limitado por max_http_index_page_size.
• O número máximo de diretórios lidos durante a expansão recursiva é limitado por url_wildcard_max_directories_to_read.

Exemplo:

SELECT count()
FROM url('https://ftp.gnu.org/gnu/wget/wget-1.21*.tar.gz', 'RawBLOB')
SETTINGS max_threads = 1, allow_experimental_url_wildcard_from_index_pages = 1;

• _path — Caminho até a 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 é NULL.
• _time — Data e hora da última modificação do arquivo. Tipo: Nullable(DateTime). Se esse horário for desconhecido, o valor é NULL.
• _headers - Cabeçalhos da resposta HTTP. Tipo: Map(LowCardinality(String), LowCardinality(String)).

Quando a configuração use_hive_partitioning é definida como 1, o ClickHouse detecta o particionamento no estilo Hive no caminho (/name=value/) e permite usar colunas de partição como colunas virtuais na consulta. Essas colunas virtuais terão os mesmos nomes do caminho particionado.

Exemplo

Use a coluna virtual criada com o particionamento no estilo Hive

SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

A configuração url_base permite passar uma URL relativa para a função url. Quando url_base está definida e o argumento da função é uma referência relativa, ela é resolvida com base na URL base, de acordo com a RFC 3986.

As regras de resolução são:

• Relativa ao caminho (por exemplo, data.csv): combinada com o caminho da URL base — tudo após a última / no caminho base é substituído. A barra no final faz diferença: https://example.com/dir/ + data.csv resulta em https://example.com/dir/data.csv, mas https://example.com/dir + data.csv resulta em https://example.com/data.csv. Os segmentos de ponto (./ e ../) são normalizados.
• Relativa ao host (por exemplo, /test/data.csv): resolvida usando o esquema e o host da URL base.
• Relativa ao esquema (por exemplo, //other.com/test/data.csv): resolvida usando o esquema da URL base.
• Apenas consulta (por exemplo, ?x=1): anexada ao caminho base completo, substituindo qualquer consulta ou fragmento existente.
• Apenas fragmento (por exemplo, #frag): anexado à URL base, preservando a consulta e substituindo qualquer fragmento existente.
• Vazia: retorna a URL base sem fragmento.
• URL absoluta: é passada sem alterações; url_base é ignorada. Uma URL é considerada absoluta apenas quando começa com scheme://: um nome cujo primeiro segmento de caminho contém dois-pontos (por exemplo, report:2026.csv), que a RFC 3986 analisaria como uma URI absoluta com o esquema report, é resolvido como uma referência relativa ao caminho, pois esse nome não é uma URL utilizável.
• Base apenas com esquema (por exemplo, file://): uma URL relativa ao caminho é anexada diretamente à base: file:// + data.csv = file://data.csv, o que, para o esquema file://, significa um caminho relativo ao diretório user_files (o diretório atual para clickhouse-local). Os segmentos de ponto são mantidos como estão nesse caso.

Exemplo

SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;

• 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 no URI. Ativado por padrão.
• url_base - URL base para resolver URLs relativas passadas para a função url.

A função url requer a permissão CREATE TEMPORARY TABLE. Portanto, ela não funciona para usuários com a configuração readonly = 1. No mínimo, é necessário readonly = 2.

• Colunas virtuais