url - ClickHouse Documentation

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.

Sintaxe

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

Parâmetros

Parameter	Description
`URL`	Uma URL entre aspas simples cujo esquema seleciona o backend. Uma URL `http`/`https` (ou não reconhecida) é um endereço do servidor que aceita requisições `GET` ou `POST` (para consultas `SELECT` ou `INSERT`, respectivamente); um esquema não HTTP reconhecido (`file://`, `s3://`, `az://`, `hdfs://`, …) é encaminhado para a função de tabela correspondente — consulte Encaminhamento por esquema de URL. Tipo: String.
`format`	Format dos dados. Tipo: String.
`structure`	Estrutura da tabela no formato `'UserID UInt64, Name String'`. Determina os nomes e os tipos das colunas. Tipo: String.
`headers`	Cabeçalhos no formato `'headers('key1'='value1', 'key2'='value2')'`. Você pode definir cabeçalhos para a chamada HTTP.

Valor retornado

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

Exemplos

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;

Encaminhamento por esquema de URL

A função url atua como um wrapper unificado sobre as outras table functions 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.

Esquema	Encaminha para
`http`, `https` (e qualquer esquema não reconhecido)	o próprio engine `URL` (HTTP `GET`/`POST`)
`file`	a função `file`
`s3`, `gs`, `gcs`, `oss`	a função `s3`
`az`, `azure`, `abfss`, `abfs`	a função `azureBlobStorage`
`hdfs`	a função `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 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.

Globs na URL

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.

Curingas com páginas de índice HTTP

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;

Colunas Virtuais

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

configuração use_hive_partitioning

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;

Resolução de URLs relativas

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.

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;

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

Permissões

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

​Sintaxe

​Parâmetros

​Valor retornado

​Exemplos

​Encaminhamento por esquema de URL

​Globs na URL

​Curingas com páginas de índice HTTP

​Colunas Virtuais

​configuração use_hive_partitioning

​Resolução de URLs relativas

​Configurações de armazenamento

​Permissões

​Relacionados