> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> Cria uma tabela a partir de uma `URL`, com `format` e `structure` especificados
# url
export const CloudNotSupportedBadge = () => {
return
Sem suporte no ClickHouse Cloud
;
};
export const ExperimentalBadge = () => {
return ;
};
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](/docs/pt-BR/reference/engines/table-engines/special/url).
## Sintaxe
```sql theme={null}
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](#scheme-dispatch). Tipo: [String](/docs/pt-BR/reference/data-types/string). |
| `format` | [Format](/docs/pt-BR/reference/formats/index) dos dados. Tipo: [String](/docs/pt-BR/reference/data-types/string). |
| `structure` | Estrutura da tabela no formato `'UserID UInt64, Name String'`. Determina os nomes e os tipos das colunas. Tipo: [String](/docs/pt-BR/reference/data-types/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](/docs/pt-BR/reference/data-types/int-uint) a partir de um servidor HTTP que responde no formato [CSV](/docs/pt-BR/reference/formats/CSV/CSV).
```sql theme={null}
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:
```sql theme={null}
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`](/docs/pt-BR/reference/functions/table-functions/file) |
| `s3`, `gs`, `gcs`, `oss` | a função [`s3`](/docs/pt-BR/reference/functions/table-functions/s3) |
| `az`, `azure`, `abfss`, `abfs` | a função [`azureBlobStorage`](/docs/pt-BR/reference/functions/table-functions/azureBlobStorage) |
| `hdfs` | a função [`hdfs`](/docs/pt-BR/reference/functions/table-functions/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`](/docs/pt-BR/reference/functions/table-functions/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](/docs/pt-BR/reference/settings/server-settings/settings#user_files_path), 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](#resolving-relative-urls) funcionam da mesma forma, independentemente do destino do encaminhamento.
```sql theme={null}
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`](/docs/pt-BR/reference/functions/table-functions/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](/docs/pt-BR/reference/functions/table-functions/remote#globs-in-addresses).
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](/docs/pt-BR/reference/settings/session-settings#glob_expansion_max_elements).
Para a sintaxe de globs no caminho da URL (como `*`, `{a,b}`, `{N..M}` e `**`), consulte [Globs no caminho](/docs/pt-BR/reference/functions/table-functions/file#globs-in-path). 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](/docs/pt-BR/reference/settings/server-settings/settings#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](/docs/pt-BR/reference/settings/session-settings#url_wildcard_max_directories_to_read).
Exemplo:
```sql theme={null}
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
```sql theme={null}
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](/docs/pt-BR/reference/settings/session-settings#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](https://datatracker.ietf.org/doc/html/rfc3986).
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**
```sql theme={null}
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](/docs/pt-BR/reference/settings/session-settings#engine_url_skip_empty_files) - permite ignorar arquivos vazios durante a leitura. Desativado por padrão.
* [enable\_url\_encoding](/docs/pt-BR/reference/settings/session-settings#enable_url_encoding) - permite ativar/desativar a decodificação/codificação do caminho no URI. Ativado por padrão.
* [url\_base](/docs/pt-BR/reference/settings/session-settings#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](/docs/pt-BR/concepts/features/configuration/settings/permissions-for-queries#readonly) = 1. No mínimo, é necessário readonly = 2.
## Relacionados
* [Colunas virtuais](/docs/pt-BR/reference/engines/table-engines/index#table_engines-virtual_columns)