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

> Crée une table à partir de l’`URL` avec le `format` et la `structure` spécifiés

# url

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Non pris en charge par ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Fonctionnalité expérimentale. <u><a href="/docs/docs/beta-and-experimental-features#experimental-features">En savoir plus.</a></u>
        </div>;
};

La fonction `url` crée une table à partir de l’`URL` avec le `format` et la `structure` spécifiés.

La fonction `url` peut être utilisée dans des requêtes `SELECT` et `INSERT` sur des données stockées dans des tables [URL](/docs/fr/reference/engines/table-engines/special/url).

<div id="syntax">
  ## Syntaxe
</div>

```sql theme={null}
url(URL [,format] [,structure] [,headers])
```

<div id="parameters">
  ## Paramètres
</div>

| Paramètre   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `URL`       | URL entre guillemets simples dont le schéma sélectionne le backend. Une URL `http`/`https` (ou non reconnue) est une adresse de serveur acceptant les requêtes `GET` ou `POST` (pour les requêtes `SELECT` ou `INSERT`, respectivement) ; un schéma non HTTP reconnu (`file://`, `s3://`, `az://`, `hdfs://`, …) est redirigé vers la fonction de table correspondante — voir [routage selon le schéma d’URL](#scheme-dispatch). Type : [String](/docs/fr/reference/data-types/string). |
| `format`    | [Format](/docs/fr/reference/formats/index) des données. Type : [String](/docs/fr/reference/data-types/string).                                                                                                                                                                                                                                                                                                                                                                               |
| `structure` | Structure de la table au format `'UserID UInt64, Name String'`. Détermine les noms et les types des colonnes. Type : [String](/docs/fr/reference/data-types/string).                                                                                                                                                                                                                                                                                                                    |
| `headers`   | En-têtes au format `'headers('key1'='value1', 'key2'='value2')'`. Vous pouvez définir des en-têtes pour l’appel HTTP.                                                                                                                                                                                                                                                                                                                                                              |

<div id="returned_value">
  ## Valeur renvoyée
</div>

Une table au format et à la structure spécifiés, contenant les données de l'`URL` définie.

<div id="examples">
  ## Exemples
</div>

Récupération des 3 premières lignes d’une table contenant des colonnes de type `String` et [UInt32](/docs/fr/reference/data-types/int-uint) depuis un serveur HTTP qui renvoie les données au format [CSV](/docs/fr/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;
```

Insertion de données à partir d’une `URL` dans une table :

```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;
```

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

La fonction `url` sert de wrapper unifié au-dessus des autres fonctions de table pour les fichiers et le stockage d’objets : elle distribue les requêtes vers le bon backend selon le schéma d’URL. Cela permet de lire depuis n’importe quel emplacement pris en charge avec une syntaxe unique et uniforme.

| Schéma                                       | Distribué vers                                                                             |
| -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `http`, `https` (et tout schéma non reconnu) | le moteur `URL` lui-même (HTTP `GET`/`POST`)                                               |
| `file`                                       | la fonction [`file`](/docs/fr/reference/functions/table-functions/file)                         |
| `s3`, `gs`, `gcs`, `oss`                     | la fonction [`s3`](/docs/fr/reference/functions/table-functions/s3)                             |
| `az`, `azure`, `abfss`, `abfs`               | la fonction [`azureBlobStorage`](/docs/fr/reference/functions/table-functions/azureBlobStorage) |
| `hdfs`                                       | la fonction [`hdfs`](/docs/fr/reference/functions/table-functions/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 distribués. Les autres schémas de fournisseurs compatibles S3 (`cos`, `obs`, `eos`, …) sont spécifiques à une région et n’ont pas de mappage d’endpoint par défaut. Une URL `cos://…` est donc traitée comme un schéma non reconnu et signalée comme une erreur ; pour ces backends, utilisez directement la fonction [`s3`](/docs/fr/reference/functions/table-functions/s3) (avec `url_scheme_mappers` configuré).

Pour `file://`, un chemin relatif (`file://data.csv`) est résolu dans le répertoire [user\_files](/docs/fr/reference/settings/server-settings/settings#user_files_path), et un chemin absolu (`file:///home/user/data.csv`) doit, comme d’habitude, pointer à l’intérieur de celui-ci.

Les arguments `format`, `structure` et `compression_method`, ainsi que le paramètre [url\_base](#resolving-relative-urls), fonctionnent de la même manière quelle que soit la cible de distribution.

```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');
```

La répartition selon le schéma d’URL n’est pas encore prise en charge par [`urlCluster`](/docs/fr/reference/functions/table-functions/urlCluster) : tout schéma autre que `http(s)` transmis à `urlCluster` est rejeté avec une erreur. Utilisez plutôt la fonction de cluster correspondante (`s3Cluster`, `azureBlobStorageCluster`, `hdfsCluster`, …) pour ces backends.

<div id="globs-in-url">
  ## Globs dans l’URL
</div>

Les motifs dans `{ }` sont utilisés pour générer un ensemble de shards ou pour spécifier des adresses de basculement. Pour connaître les types de motifs pris en charge et voir des exemples, consultez la description de la fonction [remote](/docs/fr/reference/functions/table-functions/remote#globs-in-addresses).
Le caractère `|` à l’intérieur des motifs sert à spécifier des adresses de basculement. Elles sont parcourues dans le même ordre que celui indiqué dans le motif. Le nombre d’adresses générées est limité par le paramètre [glob\_expansion\_max\_elements](/docs/fr/reference/settings/session-settings#glob_expansion_max_elements).
Pour la syntaxe des globs dans le chemin de l’URL (comme `*`, `{a,b}`, `{N..M}` et `**`), voir [Globs dans le chemin](/docs/fr/reference/functions/table-functions/file#globs-in-path). Notez que `?` marque le début de la chaîne de requête dans une URL et ne peut pas être utilisé comme caractère générique dans le composant de chemin.

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

Pour `url` et le moteur de table `URL`, ClickHouse peut étendre les caractères génériques en récupérant des pages d’index HTTP (HTML ou texte brut) et en extrayant les URL du corps de la réponse. Cela permet d’utiliser des motifs comme `/**/` lorsque le serveur expose des listes de répertoires.

Remarques :

* Les URL relatives sont résolues par rapport à l’URL de la page d’index.
* Les modèles `URL` sont étendus avant la récupération des pages d’index, y compris l’expansion des segments par virgules et par plages numériques, ainsi que les options de basculement `|` en dehors du composant de chemin.
* Les motifs de basculement `|` à l’intérieur du composant de chemin ne sont pas pris en charge pour l’expansion des pages d’index HTTP.
* La correspondance des caractères génériques est appliquée au composant de chemin de l’URL.
* Si une URL listée contient déjà une query string ou un fragment, celle-ci prévaut sur ceux de l’URL source. Sinon, la query string et le fragment de l’URL source sont utilisés.
* Une liste vide est autorisée ; les erreurs HTTP (par ex. 404) sur les pages d’index génèrent des exceptions.
* La taille maximale d’une page d’index est limitée par [max\_http\_index\_page\_size](/docs/fr/reference/settings/server-settings/settings#max_http_index_page_size).
* Le nombre maximal de répertoires lus lors de l’expansion récursive est limité par [url\_wildcard\_max\_directories\_to\_read](/docs/fr/reference/settings/session-settings#url_wildcard_max_directories_to_read).

Exemple :

```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;
```

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

* `_path` — Chemin de l’`URL`. Type : `LowCardinality(String)`.
* `_file` — Nom de la ressource pointée par 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` — Horodatage de la dernière modification du fichier. Type : `Nullable(DateTime)`. Si l’horodatage est inconnu, la valeur est `NULL`.
* `_headers` - En-têtes de réponse HTTP. Type : `Map(LowCardinality(String), LowCardinality(String))`.

<div id="hive-style-partitioning">
  ## paramètre use\_hive\_partitioning
</div>

Lorsque le paramètre `use_hive_partitioning` est défini sur 1, ClickHouse détecte le partitionnement de type Hive dans le chemin (`/name=value/`) et permet d’utiliser les colonnes de partition comme colonnes virtuelles dans une requête. Ces colonnes virtuelles porteront les mêmes noms que dans le chemin partitionné.

**Exemple**

Utilisation de colonnes virtuelles créées avec le partitionnement de type 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;
```

<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 de passer une URL relative à la fonction `url`. Lorsque `url_base` est défini et que l’argument de la fonction est une référence relative, celle-ci est résolue par rapport à l’URL de base, conformément à la [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986).

Les règles de résolution sont les suivantes :

* **Relative au chemin** (par ex. `data.csv`) : fusionnée avec le chemin de l’URL de base — tout ce qui suit le dernier `/` du chemin de base est remplacé. La barre oblique finale est importante : `https://example.com/dir/` + `data.csv` donne `https://example.com/dir/data.csv`, mais `https://example.com/dir` + `data.csv` donne `https://example.com/data.csv`. Les segments de point (`./` et `../`) sont normalisés.
* **Relative à l’hôte** (par ex. `/test/data.csv`) : résolue à l’aide du schéma et de l’hôte de l’URL de base.
* **Relative au schéma** (par ex. `//other.com/test/data.csv`) : résolue à l’aide du schéma de l’URL de base.
* **Requête uniquement** (par ex. `?x=1`) : ajoutée au chemin de base complet, en remplaçant toute requête ou tout fragment existant.
* **Fragment uniquement** (par ex. `#frag`) : ajouté à l’URL de base, en conservant la requête et en remplaçant tout fragment existant.
* **Vide** : renvoie l’URL de base sans fragment.
* **URL absolue** : transmise telle quelle ; `url_base` est ignoré.

**Exemple**

```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;
```

<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 passées à la fonction `url`.

<div id="permissions">
  ## Autorisations
</div>

La fonction `url` nécessite l’autorisation `CREATE TEMPORARY TABLE`. Par conséquent, elle ne fonctionnera pas pour les utilisateurs dont le paramètre [readonly](/docs/fr/concepts/features/configuration/settings/permissions-for-queries#readonly) est défini sur 1. Au minimum, readonly = 2 est requis.

<div id="related">
  ## Voir aussi
</div>

* [Colonnes virtuelles](/docs/fr/reference/engines/table-engines/index#table_engines-virtual_columns)