url

Cria uma tabela a partir de uma URL, com format e structure especificados

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

Parâmetro	Descrição
URL	Endereço de servidor HTTP ou HTTPS entre aspas simples, que pode aceitar requisições GET ou POST (para consultas SELECT ou INSERT, respectivamente). 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;

​

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.

​

Relacionados

• Colunas virtuais