azureBlobStorage

Fournit une interface de type table pour sélectionner/insérer des fichiers dans Azure Blob Storage. Cette fonction de table est semblable à la fonction s3.

azureBlobStorage(connection_string, container_name, blobpath [, format, compression, partition_strategy, structure])

azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, partition_strategy, structure])

azureBlobStorage(named_collection[, option=value [,..]])

Les arguments peuvent également être transmis à l’aide de collections nommées. Dans ce cas, les clés suivantes sont prises en charge :

Exemple :

CREATE NAMED COLLECTION azure_my_data AS
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'mycontainer',
    blob_path = 'data/*.parquet',
    account_name = 'myaccount',
    account_key = 'mykey...==',
    format = 'Parquet';

SELECT *
FROM azureBlobStorage(azure_my_data)
LIMIT 5;

Vous pouvez également surcharger les valeurs de la collection nommée au moment de l’exécution de la requête :

SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;

Une table ayant la structure spécifiée, permettant de lire ou d’écrire des données dans le fichier spécifié.

SELECT *
FROM azureBlobStorage(
    'https://myaccount.blob.core.windows.net/',
    'mycontainer',
    'data/*.parquet',
    'myaccount',
    'mykey...==',
    'Parquet'
)
LIMIT 5;

SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'data/*.csv',
    'CSVWithNames'
)
LIMIT 5;

Un chemin contenant {_partition_id} implique la stratégie de partitionnement WILDCARD. Un chemin avec un autre glob n'utilise aucune stratégie de partitionnement et ignore PARTITION BY. Un chemin sans glob utilise HIVE lorsque file_like_engine_default_partition_strategy est défini sur HIVE ; sinon, il n'utilise aucune stratégie de partitionnement.

INSERT INTO TABLE FUNCTION azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_{_partition_id}.csv',
    'CSV',
    'auto',
    'wildcard',
    'column1 UInt32, column2 UInt32, column3 UInt32'
) PARTITION BY column3
VALUES (1, 2, 3), (3, 2, 1), (78, 43, 3);

Ensuite, lisez une partition spécifique :

SELECT *
FROM azureBlobStorage(
    'DefaultEndpointsProtocol=https;AccountName=myaccount;AccountKey=mykey...==;EndPointSuffix=core.windows.net',
    'mycontainer',
    'test_1.csv',
    'CSV',
    'auto',
    'column1 UInt32, column2 UInt32, column3 UInt32'
);

┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘

• _path — Chemin du fichier. Type : LowCardinality(String).
• _file — Nom du fichier. Type : LowCardinality(String).
• _size — Taille du fichier en octets. Type : Nullable(UInt64). Si la taille du fichier est inconnue, la valeur est NULL.
• _time — Date de dernière modification du fichier. Type : Nullable(DateTime). Si cette date est inconnue, la valeur est NULL.

Prise en charge uniquement pour les requêtes INSERT.

WILDCARD : remplace le caractère générique {_partition_id} dans le chemin de fichier par la clé de partitionnement réelle. Elle est sélectionnée par défaut lorsque le chemin contient {_partition_id}.

Lorsqu'aucun partition_strategy n'est défini, un chemin avec un autre glob n'utilise aucune stratégie de partitionnement et ignore PARTITION BY. Un chemin sans glob utilise HIVE lorsque file_like_engine_default_partition_strategy est défini sur HIVE ; sinon, il n'utilise aucune stratégie de partitionnement.

HIVE implémente le partitionnement de style Hive pour les lectures et les écritures. Les fichiers sont générés au format suivant : <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>.

Exemple de stratégie de partitionnement HIVE

INSERT INTO TABLE FUNCTION azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root',
    format = 'CSVWithNames',
    compression = 'auto',
    structure = 'year UInt16, country String, id Int32',
    partition_strategy = 'hive'
) PARTITION BY (year, country)
VALUES (2020, 'Russia', 1), (2021, 'Brazil', 2);

SELECT _path, * FROM azureBlobStorage(
    azure_conf2,
    storage_account_url = 'https://myaccount.blob.core.windows.net/',
    container = 'cont',
    blob_path = 'azure_table_root/**.csvwithnames'
)

   ┌─_path───────────────────────────────────────────────────────────────────────────┬─id─┬─year─┬─country─┐
1. │ cont/azure_table_root/year=2021/country=Brazil/7351307847391293440.csvwithnames │  2 │ 2021 │ Brazil  │
2. │ cont/azure_table_root/year=2020/country=Russia/7351307847378710528.csvwithnames │  1 │ 2020 │ Russia  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘

Il s’agit d’une indication permettant à ClickHouse d’analyser les fichiers partitionnés au format Hive au moment de la lecture. Cela n’a aucun effet sur l’écriture. Pour des lectures et écritures symétriques, utilisez l’argument partition_strategy.

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

Exemple

Utiliser une colonne virtuelle créée avec un partitionnement au format Hive

SELECT * FROM azureBlobStorage(config, storage_account_url='...', container='...', blob_path='http://data/path/date=*/country=*/code=*/*.parquet') WHERE date > '2020-01-01' AND country = 'Netherlands' AND code = 42;

Une signature d’accès partagé (SAS) est un URI qui accorde un accès restreint à un conteneur ou à un fichier dans Azure Storage. Utilisez-la pour fournir un accès limité dans le temps aux ressources d’un compte de stockage sans partager la clé de ce compte. Plus de détails ici.

La fonction azureBlobStorage prend en charge les signatures d’accès partagé (SAS).

Un jeton Blob SAS contient toutes les informations nécessaires pour authentifier la requête, y compris le blob cible, les autorisations et la durée de validité. Pour construire une URL de blob, ajoutez le jeton SAS au point de terminaison du service Blob. Par exemple, si le point de terminaison est https://clickhousedocstest.blob.core.windows.net/, la requête devient :

SELECT count()
FROM azureBlobStorage('BlobEndpoint=https://clickhousedocstest.blob.core.windows.net/;SharedAccessSignature=sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌

Autrement, les utilisateurs peuvent utiliser l’URL SAS Blob générée :

SELECT count()
FROM azureBlobStorage('https://clickhousedocstest.blob.core.windows.net/?sp=r&st=2025-01-29T14:58:11Z&se=2025-01-29T22:58:11Z&spr=https&sv=2022-11-02&sr=c&sig=Ac2U0xl4tm%2Fp7m55IilWl1yHwk%2FJG0Uk6rMVuOiD0eE%3D', 'exampledatasets', 'example.csv')

┌

• Moteur de table AzureBlobStorage