url - ClickHouse Documentation

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.

Syntaxe

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

Paramètres

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. Type : String.
`format`	Format des données. Type : String.
`structure`	Structure de la table au format `'UserID UInt64, Name String'`. Détermine les noms et les types des colonnes. Type : String.
`headers`	En-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;

Routage selon le schéma d’URL

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`
`s3`, `gs`, `gcs`, `oss`	la fonction `s3`
`az`, `azure`, `abfss`, `abfs`	la fonction `azureBlobStorage`
`hdfs`	la fonction `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 (avec url_scheme_mappers configuré). Pour file://, un chemin relatif (file://data.csv) est résolu dans le répertoire user_files, 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, fonctionnent de la même manière quelle que soit la cible de distribution.

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

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. Pour la syntaxe des globs dans le chemin de l’URL (comme *, {a,b}, {N..M} et **), voir Globs dans le chemin. 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.

Caractères génériques avec les pages d’index HTTP

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.
Le nombre maximal de répertoires lus lors de l’expansion récursive est limité par url_wildcard_max_directories_to_read.

Exemple :

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;

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.

Colonnes virtuelles

​Syntaxe

​Paramètres

​Valeur renvoyée

​Exemples

​Routage selon le schéma d’URL

​Globs dans l’URL

​Caractères génériques avec les pages d’index HTTP

​Colonnes virtuelles

​paramètre use_hive_partitioning

​Résolution des URL relatives

​Paramètres de stockage

​Autorisations

​Voir aussi