azureBlobStorage

Proporciona una interfaz de tipo tabla para seleccionar/insertar archivos en Azure Blob Storage. Similar a la función s3.

​

Función de tabla azureBlobStorage

Proporciona una interfaz de tipo tabla para seleccionar/insertar archivos en Azure Blob Storage. Esta función de tabla es similar a la función s3.

​

Sintaxis

Cadena de conexión

Las credenciales están integradas en la cadena de conexión, por lo que no se requiere account_name/account_key por separado:

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

URL de la cuenta de almacenamiento

Requiere account_name y account_key como argumentos independientes:

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

Colección con nombre

Consulta Colecciones con nombre a continuación para ver la lista completa de claves compatibles:

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

​

Argumentos

Argumento	Descripción
connection_string	Una cadena de conexión que incluye credenciales integradas (nombre de la cuenta + clave de la cuenta o SAS token). Al usar esta forma, account_name y account_key no deben pasarse por separado. Consulta Configurar una cadena de conexión.
storage_account_url	La URL del endpoint de la cuenta de almacenamiento, por ejemplo https://myaccount.blob.core.windows.net/. Al usar esta forma, debes pasar también account_name y account_key.
container_name	Nombre del contenedor.
blobpath	Ruta del archivo. Admite los siguientes comodines en modo de solo lectura: *, **, ?, {abc,def} y {N..M}, donde N y M son números, y 'abc' y 'def' son cadenas.
account_name	Nombre de la cuenta de almacenamiento. Obligatorio al usar storage_account_url sin SAS; no debe pasarse al usar connection_string.
account_key	Clave de la cuenta de almacenamiento. Obligatoria al usar storage_account_url sin SAS; no debe pasarse al usar connection_string.
format	El formato del archivo.
compression	Valores admitidos: none, gzip/gz, brotli/br, xz/LZMA, zstd/zst. De forma predeterminada, detectará automáticamente la compresión por la extensión del archivo (igual que si se establece auto).
structure	Estructura de la tabla. Formato: 'column1_name column1_type, column2_name column2_type, ...'.
partition_strategy	Opcional. Valores admitidos: WILDCARD o HIVE. WILDCARD requiere {_partition_id} en la ruta, que se reemplaza con la clave de partición. HIVE no permite comodines, asume que la ruta es la raíz de la tabla y genera directorios particionados con estilo Hive, con Snowflake IDs como nombres de archivo y el formato de archivo como extensión. El valor predeterminado es la configuración file_like_engine_default_partition_strategy (WILDCARD en configuraciones compatibility anteriores a 26.6; HIVE en caso contrario).
partition_columns_in_data_file	Opcional. Solo se usa con la estrategia de partición HIVE. Indica a ClickHouse si debe esperar que las columnas de partición estén escritas en el archivo de datos. El valor predeterminado es false.
extra_credentials	Usa client_id y tenant_id para la autenticación. Si se proporcionan extra_credentials, tienen prioridad sobre account_name y account_key.

​

Colecciones con nombre

Los argumentos también pueden pasarse mediante colecciones con nombre. En este caso, se admiten las siguientes claves:

Key	Required	Description
container	Yes	Nombre del contenedor. Corresponde al argumento posicional container_name.
blob_path	Yes	Ruta del archivo (con comodines opcionales). Corresponde al argumento posicional blobpath.
connection_string	No*	Cadena de conexión con credenciales incorporadas. *Debe proporcionarse connection_string o storage_account_url.
storage_account_url	No*	URL del endpoint de la cuenta de almacenamiento. *Debe proporcionarse connection_string o storage_account_url.
account_name	No	Obligatorio cuando se usa storage_account_url
account_key	No	Obligatorio cuando se usa storage_account_url
format	No	Formato de archivo.
compression	No	Tipo de compresión.
structure	No	Estructura de la tabla.
client_id	No	ID de cliente para la autenticación.
tenant_id	No	ID del tenant para la autenticación.

Los nombres de las claves de las colecciones con nombre son distintos de los nombres de los argumentos posicionales de la función: container (no container_name) y blob_path (no blobpath).

Ejemplo:

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;

También puede sobrescribir los valores de la colección con nombre durante la consulta:

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

​

Valor devuelto

Una tabla con la estructura especificada para leer o escribir datos en el archivo indicado.

​

Ejemplos

​

Lectura con el formato storage_account_url

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

​

Lectura con la forma connection_string

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

​

Escritura por particiones

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

Luego, vuelva a leer una partición específica:

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 │
└─────────┴─────────┴─────────┘

​

Columnas virtuales

• _path — Ruta del archivo. Tipo: LowCardinality(String).
• _file — Nombre del archivo. Tipo: LowCardinality(String).
• _size — Tamaño del archivo en bytes. Tipo: Nullable(UInt64). Si se desconoce el tamaño del archivo, el valor es NULL.
• _time — Fecha y hora de la última modificación del archivo. Tipo: Nullable(DateTime). Si se desconoce la hora, el valor es NULL.

​

Escritura particionada

​

Estrategia de partición

Solo se admite para consultas INSERT.

WILDCARD: reemplaza el comodín {_partition_id} en la ruta del archivo por la clave de partición correspondiente. Se selecciona de forma predeterminada solo con configuraciones de compatibility anteriores a 26.6; de lo contrario, el valor predeterminado es HIVE (consulte la configuración file_like_engine_default_partition_strategy).

HIVE implementa el particionamiento de estilo Hive para lecturas & escrituras. Genera archivos con el siguiente formato: <prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>.

Ejemplo de estrategia de partición 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  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘

​

ajuste use_hive_partitioning

Esta es una indicación para que ClickHouse analice archivos particionados con estilo Hive en el momento de la lectura. No tiene efecto al escribir. Para que la lectura y la escritura sean simétricas, use el argumento partition_strategy.

Cuando use_hive_partitioning se establece en 1, ClickHouse detecta el particionamiento de estilo Hive en la ruta (/name=value/) y permite usar las columnas de partición como columnas virtuales en la consulta. Estas columnas virtuales tendrán los mismos nombres que en la ruta particionada.

Ejemplo

Use una columna virtual creada con particionamiento de estilo 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;

​

Uso de firmas de acceso compartido (SAS)

Una firma de acceso compartido (SAS) es un URI que concede acceso restringido a un contenedor o archivo de Azure Storage. Úsela para proporcionar acceso temporal a los recursos de una cuenta de almacenamiento sin compartir la clave de la cuenta. Más información aquí.

La función azureBlobStorage admite firmas de acceso compartido (SAS).

Un token SAS de blob contiene toda la información necesaria para autenticar la solicitud, incluido el blob de destino, los permisos y el período de validez. Para construir una URL de blob, agregue el token SAS al endpoint del servicio Blob. Por ejemplo, si el endpoint es https://clickhousedocstest.blob.core.windows.net/, la solicitud pasa a ser:

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

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.425 sec.

Como alternativa, los usuarios pueden usar la URL SAS del blob:

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

┌─count()─┐
│      10 │
└─────────┘

1 row in set. Elapsed: 0.153 sec.

​

Relacionado

• Motor de tabla AzureBlobStorage