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

> Consulta dados de e para um servidor HTTP/HTTPS remoto. Este motor é semelhante ao motor File.

# motor de tabela URL

Consulta dados de e para um servidor HTTP/HTTPS remoto. Este motor é semelhante ao motor [File](/docs/pt-BR/reference/engines/table-engines/special/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](#scheme-dispatch) 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](#scheme-dispatch) 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](/docs/pt-BR/reference/formats/index#formats-overview).

  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.

<div id="scheme-dispatch">
  ## Despacho por esquema de URL
</div>

O motor `URL` é um wrapper unificado sobre os outros motores de armazenamento de arquivos e objetos: ele direciona 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](/docs/pt-BR/reference/engines/table-engines/special/file); `s3://`, `gs://`, `gcs://`, `oss://` pelo motor [S3](/docs/pt-BR/reference/engines/table-engines/integrations/s3); `az://`, `azure://`, `abfss://`, `abfs://` pelo motor [AzureBlobStorage](/docs/pt-BR/reference/engines/table-engines/integrations/azureBlobStorage); e `hdfs://` pelo motor [HDFS](/docs/pt-BR/reference/engines/table-engines/integrations/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 despachados. 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](/docs/pt-BR/reference/engines/table-engines/integrations/s3) (com `url_scheme_mappers` configurado).

A configuração [url\_base](/docs/pt-BR/reference/settings/session-settings#url_base) é aplicada antes do despacho por esquema, portanto uma referência relativa é primeiro resolvida em relação à base e depois encaminhada ao motor correspondente.

```sql theme={null}
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);
```

<div id="using-the-engine-in-the-clickhouse-server">
  ## Uso
</div>

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](https://en.wikipedia.org/wiki/Chunked_transfer_encoding).

Você pode limitar o número máximo de redirecionamentos HTTP GET usando a configuração [max\_http\_get\_redirects](/docs/pt-BR/reference/settings/session-settings#max_http_get_redirects).

<div id="wildcards-with-http-index-pages">
  ## Curingas com páginas de índice HTTP
</div>

Quando [allow\_experimental\_url\_wildcard\_from\_index\_pages](/docs/pt-BR/reference/settings/session-settings#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`](/docs/pt-BR/reference/functions/table-functions/url#wildcards-with-http-index-pages).

A expansão é limitada por [max\_http\_index\_page\_size](/docs/pt-BR/reference/settings/server-settings/settings#max_http_index_page_size) para cada página de índice obtida e por [url\_wildcard\_max\_directories\_to\_read](/docs/pt-BR/reference/settings/session-settings#url_wildcard_max_directories_to_read) ao percorrer diretórios recursivamente.

<div id="example">
  ## Exemplo
</div>

**1.** Crie uma tabela `url_engine_table` no servidor:

```sql theme={null}
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:

```python3 theme={null}
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()
```

```bash theme={null}
$ python3 server.py
```

**3.** Solicitar dados:

```sql theme={null}
SELECT * FROM url_engine_table
```

```text theme={null}
┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘
```

<div id="details-of-implementation">
  ## Detalhes da implementação
</div>

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

<div id="virtual-columns">
  ## Colunas virtuais
</div>

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

<div id="resolving-relative-urls">
  ## Resolução de URLs relativas
</div>

A configuração [url\_base](/docs/pt-BR/reference/settings/session-settings#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](https://datatracker.ietf.org/doc/html/rfc3986). Para ver uma descrição completa das regras de resolução, consulte a [documentação da função de tabela url](/docs/pt-BR/reference/functions/table-functions/url#resolving-relative-urls).

**Exemplo**

```sql theme={null}
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;
```

<div id="storage-settings">
  ## Configurações de armazenamento
</div>

* [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 na URI. Ativado por padrão.
* [url\_base](/docs/pt-BR/reference/settings/session-settings#url_base) - URL base para a resolução de URLs relativas passadas ao motor.