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

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

​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