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

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, partition_strategy, structure])

Requiere account_name y account_key como argumentos independientes:

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

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 token SAS). 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. Sin una estrategia explícita, una ruta con `{_partition_id}` usa `WILDCARD`. Una ruta con otro glob no usa ninguna estrategia de partición e ignora `PARTITION BY`. Una ruta sin glob usa `HIVE` cuando `file_like_engine_default_partition_strategy` es `HIVE`; de lo contrario, no usa ninguna estrategia de partición.
`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.

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

Una ruta que contiene {_partition_id} implica la estrategia de partición WILDCARD. Una ruta con otro glob no utiliza ninguna estrategia de partición e ignora PARTITION BY. Una ruta sin un glob utiliza HIVE cuando file_like_engine_default_partition_strategy es HIVE; de lo contrario, no utiliza ninguna estrategia de partición.

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

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 cuando la ruta contiene {_partition_id}.

Cuando no se establece partition_strategy, una ruta con otro glob no utiliza ninguna estrategia de partición e ignora PARTITION BY. Una ruta sin glob utiliza HIVE cuando file_like_engine_default_partition_strategy es HIVE; de lo contrario, no utiliza ninguna estrategia de partición.

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

┌

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

┌

Motor de tabla AzureBlobStorage