Passer au contenu principal

​
Fonction de table url

La fonction url crée une table à partir d’une 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 les données des tables URL.

​
Syntaxe

url(URL [,format] [,structure] [,headers])

​
Paramètres

ParamètreDescription
URLAdresse du serveur HTTP ou HTTPS entre guillemets simples, acceptant les requêtes GET ou POST (pour les requêtes SELECT ou INSERT, respectivement). Type : String.
formatFormat des données. Type : String.
structureStructure de la table au format 'UserID UInt64, Name String'. Détermine les noms et les types des colonnes. Type : String.
headersEn-têtes au format 'headers('key1'='value1', 'key2'='value2')'. Vous pouvez définir des en-têtes pour l’appel HTTP.

​
Valeur renvoyée

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

​
Exemples

Récupération des 3 premières lignes d’une table contenant des colonnes de type String et UInt32 depuis un serveur HTTP qui renvoie les données au format CSV. 
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 : 
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 dans l’URL

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

​
Colonnes virtuelles

  • _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)).

​
paramètre use_hive_partitioning

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 
SELECT * FROM url('http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

​
Résolution des URL relatives

Le paramètre 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. 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 
SET url_base = 'https://raw.githubusercontent.com/ClickHouse/ClickHouse/master/';
SELECT * FROM url('tests/queries/0_stateless/data_csv/data.csv', CSV) LIMIT 3;

​
Paramètres de stockage

  • engine_url_skip_empty_files - permet d’ignorer les fichiers vides lors de la lecture. Désactivé par défaut.
  • 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 - URL de base pour résoudre les URL relatives passées à la fonction url.

​
Autorisations

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 est défini sur 1. Au minimum, readonly = 2 est requis.
Dernière modification le 25 juin 2026