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

> Interroge des données depuis/vers un serveur HTTP/HTTPS distant. Ce moteur est similaire au moteur File.

# Moteur de table URL

Interroge des données depuis/vers un serveur HTTP/HTTPS distant. Ce moteur est similaire au moteur [File](/docs/fr/reference/engines/table-engines/special/file).

Le moteur `URL` est également un wrapper unifié qui route vers le bon backend en fonction du schéma d’URL, de sorte qu’un schéma non HTTP reconnu est délégué au moteur correspondant — voir [routage selon le schéma d’URL](#scheme-dispatch) ci-dessous.

Syntaxe : `URL(URL [,Format] [,CompressionMethod])`

* Le paramètre `URL` doit respecter la structure d’un Uniform Resource Locator. Pour une URL `http`/`https` (le backend par défaut), elle doit pointer vers un serveur utilisant HTTP ou HTTPS, et aucun en-tête supplémentaire n’est nécessaire pour obtenir une réponse du serveur. Une URL avec un schéma non HTTP reconnu (`file://`, `s3://`, `az://`, `hdfs://`, …) est à la place déléguée au moteur correspondant — voir [routage selon le schéma d’URL](#scheme-dispatch) ci-dessous.

* Le `Format` doit être un format que ClickHouse peut utiliser dans les requêtes `SELECT` et, si nécessaire, dans les `INSERTs`. Pour obtenir la liste complète des formats pris en charge, voir [Formats](/docs/fr/reference/formats/index#formats-overview).

  Si cet argument n’est pas spécifié, ClickHouse détecte automatiquement le format à partir du suffixe du paramètre `URL`. Si le suffixe du paramètre `URL` ne correspond à aucun format pris en charge, la création de la table échoue. Par exemple, pour l’expression de moteur `URL('http://localhost/test.json')`, le format `JSON` est appliqué.

* `CompressionMethod` indique si le body HTTP doit être compressé. Si la compression est activée, les paquets HTTP envoyés par le moteur URL contiennent l’en-tête 'Content-Encoding' pour indiquer la méthode de compression utilisée.

Pour activer la compression, assurez-vous d’abord que l’endpoint HTTP distant indiqué par le paramètre `URL` prend en charge l’algorithme de compression correspondant.

Le `CompressionMethod` pris en charge doit être l’un des suivants :

* gzip or gz
* deflate
* brotli or br
* lzma or xz
* zstd or zst
* lz4
* bz2
* snappy
* none
* auto

Si `CompressionMethod` n’est pas spécifié, la valeur par défaut est `auto`. Cela signifie que ClickHouse détecte automatiquement la méthode de compression à partir du suffixe du paramètre `URL`. Si le suffixe correspond à l’une des méthodes de compression listées ci-dessus, la compression correspondante est appliquée ; sinon, aucune compression n’est activée.

Par exemple, pour l’expression de moteur `URL('http://localhost/test.gzip')`, la méthode de compression `gzip` est appliquée, mais pour `URL('http://localhost/test.fr')`, aucune compression n’est activée, car le suffixe `fr` ne correspond à aucune des méthodes de compression ci-dessus.

<div id="scheme-dispatch">
  ## Routage selon le schéma d’URL
</div>

Le moteur `URL` est une surcouche unifiée des autres moteurs de stockage de fichiers et d’objets : il redirige vers le backend approprié en fonction du schéma de l’URL. `http`/`https` (ainsi que tout schéma non reconnu) sont pris en charge par le moteur `URL` lui-même ; `file://` est pris en charge par le moteur [File](/docs/fr/reference/engines/table-engines/special/file) ; `s3://`, `gs://`, `gcs://`, `oss://` par le moteur [S3](/docs/fr/reference/engines/table-engines/integrations/s3) ; `az://`, `azure://`, `abfss://`, `abfs://` par le moteur [AzureBlobStorage](/docs/fr/reference/engines/table-engines/integrations/azureBlobStorage) ; et `hdfs://` par le moteur [HDFS](/docs/fr/reference/engines/table-engines/integrations/hdfs).

Seuls les schémas S3 que le mappeur d’URI S3 résout en un endpoint concret sans configuration supplémentaire (`s3`, ainsi que `gs`/`gcs`/`oss`) sont redirigés. Les autres schémas de fournisseurs compatibles S3 (`cos`, `obs`, `eos`, …) sont spécifiques à une région et ne disposent d’aucun mapping d’endpoint par défaut. Par conséquent, transmettre une telle URL au moteur `URL` est considéré comme un schéma non reconnu et signalé comme une erreur ; utilisez directement le moteur [S3](/docs/fr/reference/engines/table-engines/integrations/s3) (avec `url_scheme_mappers` configuré) pour ces backends.

Le paramètre [url\_base](/docs/fr/reference/settings/session-settings#url_base) est appliqué avant le routage du schéma ; une référence relative est donc d’abord résolue par rapport à la base, puis redirigée vers le moteur correspondant.

```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">
  ## Utilisation
</div>

Les requêtes `INSERT` et `SELECT` sont transformées en requêtes `POST` et `GET`,
respectivement. Pour le traitement des requêtes `POST`, le serveur distant doit prendre en charge
l’[encodage de transfert par blocs](https://en.wikipedia.org/wiki/Chunked_transfer_encoding).

Vous pouvez limiter le nombre maximal de redirections HTTP GET à suivre à l’aide du paramètre [max\_http\_get\_redirects](/docs/fr/reference/settings/session-settings#max_http_get_redirects).

<div id="wildcards-with-http-index-pages">
  ## Caractères génériques avec les pages d’index HTTP
</div>

Lorsque [allow\_experimental\_url\_wildcard\_from\_index\_pages](/docs/fr/reference/settings/session-settings#allow_experimental_url_wildcard_from_index_pages) est activé, le moteur de table `URL` peut étendre les caractères génériques en récupérant des pages d’index HTTP et en en extrayant les liens.
Il s’agit du même mécanisme que pour la fonction de table [`url`](/docs/fr/reference/functions/table-functions/url#wildcards-with-http-index-pages).

Cette expansion est limitée par [max\_http\_index\_page\_size](/docs/fr/reference/settings/server-settings/settings#max_http_index_page_size) pour chaque page d’index récupérée, et par [url\_wildcard\_max\_directories\_to\_read](/docs/fr/reference/settings/session-settings#url_wildcard_max_directories_to_read) pour le parcours récursif des répertoires.

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

**1.** Créez une table `url_engine_table` sur le serveur :

```sql theme={null}
CREATE TABLE url_engine_table (word String, value UInt64)
ENGINE=URL('http://127.0.0.1:12345/', CSV)
```

**2.** Créez un serveur HTTP simple à l’aide des outils standard de Python 3 et
démarrez-le :

```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.** Demandez les données :

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

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

<div id="details-of-implementation">
  ## Détails de l’implémentation
</div>

* Les lectures et les écritures peuvent être effectuées en parallèle
* Non pris en charge :
  * les opérations `ALTER` et `SELECT...SAMPLE`
  * les index
  * la réplication

<div id="virtual-columns">
  ## Colonnes virtuelles
</div>

* `_path` — Chemin de l'`URL`. Type: `LowCardinality(String)`.
* `_file` — Nom de la ressource de l'`URL`. Type: `LowCardinality(String)`.
* `_size` — Taille de la ressource en octets. Type: `Nullable(UInt64)`. Si la taille est inconnue, la valeur est `NULL`.
* `_time` — Date et heure de la dernière modification du fichier. Type: `Nullable(DateTime)`. Si cette information est inconnue, la valeur est `NULL`.
* `_headers` - En-têtes de réponse HTTP. Type: `Map(LowCardinality(String), LowCardinality(String))`.

<div id="resolving-relative-urls">
  ## Résolution des URL relatives
</div>

Le paramètre [url\_base](/docs/fr/reference/settings/session-settings#url_base) permet d'utiliser une URL relative avec le moteur `URL`. Lorsque `url_base` est défini, l'URL transmise au moteur est résolue par rapport à cette base, conformément à la [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986). Pour une description complète des règles de résolution, consultez la [documentation de la fonction de table url](/docs/fr/reference/functions/table-functions/url#resolving-relative-urls).

**Exemple**

```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">
  ## Paramètres de stockage
</div>

* [engine\_url\_skip\_empty\_files](/docs/fr/reference/settings/session-settings#engine_url_skip_empty_files) - permet d'ignorer les fichiers vides lors de la lecture. Désactivé par défaut.
* [enable\_url\_encoding](/docs/fr/reference/settings/session-settings#enable_url_encoding) - permet d'activer ou de désactiver le décodage/l'encodage du chemin dans l'URI. Activé par défaut.
* [url\_base](/docs/fr/reference/settings/session-settings#url_base) - URL de base pour résoudre les URL relatives transmises au moteur.