Moteur de table URL

Interroge des données depuis/vers un serveur HTTP/HTTPS distant. Ce moteur est similaire au moteur 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 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 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.

  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.

Le moteur URL est une surcouche unifiée des autres moteurs de stockage de fichiers et d’objets : il route 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 ; s3://, gs://, gcs://, oss:// par le moteur S3 ; az://, azure://, abfss://, abfs:// par le moteur AzureBlobStorage ; et hdfs:// par le moteur 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 routé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 (avec url_scheme_mappers configuré) pour ces backends.

Le paramètre 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 routée vers le moteur correspondant.

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

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.

Vous pouvez limiter le nombre maximal de redirections HTTP GET à suivre à l’aide du paramètre max_http_get_redirects.

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

Cette expansion est limitée par max_http_index_page_size pour chaque page d’index récupérée, et par url_wildcard_max_directories_to_read pour le parcours récursif des répertoires.

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

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 :

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()

$ python3 server.py

3. Demandez les données :

SELECT * FROM url_engine_table

┌─word──┬─value─┐
│ Hello │     1 │
│ World │     2 │
└───────┴───────┘

• 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

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

Le paramètre 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. Pour une description complète des règles de résolution, consultez la documentation de la fonction de table url.

Exemple

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;

• 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 transmises au moteur.