> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Este motor oferece integração com o ecossistema do Azure Blob Storage.

# Motor de tabela AzureBlobStorage

Este motor oferece integração com o ecossistema do [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs).

<div id="create-table">
  ## CREATE TABLE
</div>

```sql theme={null}
CREATE TABLE azure_blob_storage_table (name String, value UInt32)
    ENGINE = AzureBlobStorage(connection_string|storage_account_url, container_name, blobpath, [account_name, account_key, format, compression, partition_strategy, partition_columns_in_data_file, extra_credentials(client_id=, tenant_id=)])
    [PARTITION BY expr]
    [SETTINGS ...]
```

<div id="engine-parameters">
  ### Parâmetros do mecanismo
</div>

* `endpoint` — URL do endpoint do AzureBlobStorage com contêiner e prefixo. Opcionalmente, pode conter `account&#95;name` se o método de autenticação usado exigir isso. (`http://azurite1:{port}/[account_name]{container_name}/{data_prefix}`) ou esses parâmetros podem ser fornecidos separadamente usando `storage&#95;account&#95;url`, `account&#95;name` e `container`. Para especificar o prefixo, `endpoint` deve ser usado.
* `endpoint_contains_account_name` - Este sinalizador é usado para especificar se `endpoint` contém `account&#95;name`, já que isso só é necessário para determinados métodos de autenticação. (Padrão: true)
* `connection_string|storage_account_url` — `connection&#95;string` inclui nome da conta e chave ([Criar string de conexão](https://learn.microsoft.com/en-us/azure/storage/common/storage-configure-connection-string?toc=%2Fazure%2Fstorage%2Fblobs%2Ftoc.json\&bc=%2Fazure%2Fstorage%2Fblobs%2Fbreadcrumb%2Ftoc.json#configure-a-connection-string-for-an-azure-storage-account)) ou você também pode fornecer aqui a URL da conta de armazenamento e o nome da conta e a chave da conta como parâmetros separados (consulte os parâmetros `account&#95;name` e `account&#95;key`)
* `container_name` - Nome do contêiner
* `blobpath` - caminho do arquivo. Suporta os seguintes curingas no modo `readonly`: `*`, `**`, `?`, `{abc,def}` e `{N..M}`, em que `N`, `M` — números, `'abc'`, `'def'` — strings.
* `account_name` - se `storage&#95;account&#95;url` for usado, o nome da conta pode ser especificado aqui
* `account_key` - se `storage&#95;account&#95;url` for usado, a chave da conta pode ser especificada aqui
* `format` — O [formato](/pt-BR/reference/formats) do arquivo.
* `compression` — Valores compatíveis: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`. Por padrão, a compressão será detectada automaticamente pela extensão do arquivo. (equivale a definir como `auto`).
* `partition_strategy` – Opções: `WILDCARD` ou `HIVE`. `WILDCARD` exige um `{_partition_id}` no caminho, que é substituído pela chave de partição. `HIVE` não permite curingas, pressupõe que o caminho seja a raiz da tabela e gera diretórios particionados no estilo Hive com Snowflake IDs como nomes de arquivo e o formato do arquivo como extensão. O padrão é `WILDCARD`
* `partition_columns_in_data_file` - Usado apenas com a estratégia de particionamento `HIVE`. Informa ao ClickHouse se deve esperar que as colunas de partição sejam gravadas no arquivo de dados. O padrão é `false`.
* `extra_credentials` - Use `client_id` e `tenant_id` para autenticação. Se `extra&#95;credentials` forem fornecidas, elas terão prioridade sobre `account_name` e `account_key`.

**Exemplo**

Os usuários podem usar o emulador Azurite para desenvolvimento local do Azure Storage. Mais detalhes [aqui](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite?tabs=docker-hub%2Cblob-storage). Se estiver usando uma instância local do Azurite, talvez seja necessário substituir `http://localhost:10000` por `http://azurite1:10000` nos comandos abaixo, em que assumimos que o Azurite está disponível no host `azurite1`.

```sql theme={null}
CREATE TABLE test_table (key UInt64, data String)
    ENGINE = AzureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV');

INSERT INTO test_table VALUES (1, 'a'), (2, 'b'), (3, 'c');

SELECT * FROM test_table;
```

```text theme={null}
┌─key──┬─data──┐
│  1   │   a   │
│  2   │   b   │
│  3   │   c   │
└──────┴───────┘
```

<div id="virtual-columns">
  ## Colunas virtuais
</div>

* `_path` — Caminho do arquivo. Tipo: `LowCardinality(String)`.
* `_file` — Nome do arquivo. Tipo: `LowCardinality(String)`.
* `_size` — Tamanho do arquivo em bytes. Tipo: `Nullable(UInt64)`. Se o tamanho for desconhecido, o valor é `NULL`.
* `_time` — Data e hora da última modificação do arquivo. Tipo: `Nullable(DateTime)`. Se a data e hora forem desconhecidas, o valor é `NULL`.

<div id="authentication">
  ## Autenticação
</div>

Atualmente, há 3 formas de autenticação:

* `Managed Identity` - Pode ser usada ao fornecer um `endpoint`, `connection_string` ou `storage_account_url`.
* `SAS Token` - Pode ser usado ao fornecer um `endpoint`, `connection_string` ou `storage_account_url`. Ele é identificado pela presença de `?` na URL. Consulte [azureBlobStorage](/pt-BR/reference/functions/table-functions/azureBlobStorage#using-shared-access-signatures-sas-sas-tokens) para ver exemplos.
* `Workload Identity` - Pode ser usada ao fornecer um `endpoint` ou `storage_account_url`. Se o parâmetro `use_workload_identity` estiver definido na configuração, a [Workload Identity](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/identity/azure-identity#authenticate-azure-hosted-applications) será usada para autenticação.

<div id="data-cache">
  ### Cache de dados
</div>

O mecanismo de tabela `Azure` oferece suporte ao cache de dados em disco local.
Consulte as opções de configuração e o uso do cache do sistema de arquivos nesta [seção](/pt-BR/concepts/features/configuration/server-config/storing-data#using-local-cache).
O cache é feito com base no caminho e no ETag do objeto de armazenamento, portanto o ClickHouse não lerá uma versão desatualizada do cache.

Para habilitar o cache, use a configuração `filesystem_cache_name = '<name>'` e `enable_filesystem_cache = 1`.

```sql theme={null}
SELECT *
FROM azureBlobStorage('DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://azurite1:10000/devstoreaccount1/;', 'testcontainer', 'test_table', 'CSV')
SETTINGS filesystem_cache_name = 'cache_for_azure', enable_filesystem_cache = 1;
```

1. adicione a seção a seguir ao arquivo de configuração do ClickHouse:

```xml theme={null}
<clickhouse>
    <filesystem_caches>
        <cache_for_azure>
            <path>path to cache directory</path>
            <max_size>10Gi</max_size>
        </cache_for_azure>
    </filesystem_caches>
</clickhouse>
```

2. reutilize a configuração de cache (e, portanto, o armazenamento em cache) da seção `storage_configuration` do ClickHouse, [descrita aqui](/pt-BR/concepts/features/configuration/server-config/storing-data#using-local-cache)

<div id="partition-by">
  ### PARTITION BY
</div>

`PARTITION BY` — Opcional. Na maioria dos casos, você não precisa de uma chave de partição e, quando ela é necessária, em geral não precisa ser mais granular do que mensal. O particionamento não acelera consultas (ao contrário da expressão ORDER BY). Você nunca deve usar um particionamento granular demais. Não particione seus dados por identificadores ou nomes de clientes (em vez disso, use o identificador ou o nome do cliente como a primeira coluna na expressão ORDER BY).

Para particionar por mês, use a expressão `toYYYYMM(date_column)`, em que `date_column` é uma coluna com uma data do tipo [Date](/pt-BR/reference/data-types/date). Os nomes das partições aqui têm o formato `"YYYYMM"`.

<div id="partition-strategy">
  #### Estratégia de particionamento
</div>

`WILDCARD` (padrão): substitui o caractere curinga `{_partition_id}` no caminho do arquivo pela chave de partição real. A leitura não é suportada.

`HIVE` implementa o particionamento no estilo Hive para leituras & gravações. A leitura é implementada com um padrão glob recursivo. A gravação gera arquivos no seguinte formato: `<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>`.

Observação: ao usar a estratégia de particionamento `HIVE`, a configuração `use_hive_partitioning` não tem efeito.

Exemplo de estratégia de particionamento `HIVE`:

```sql theme={null}
arthur :) create table azure_table (year UInt16, country String, counter UInt8) ENGINE=AzureBlobStorage(account_name='devstoreaccount1', account_key='Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==', storage_account_url = 'http://localhost:30000/devstoreaccount1', container='cont', blob_path='hive_partitioned', format='Parquet', compression='auto', partition_strategy='hive') PARTITION BY (year, country);

arthur :) insert into azure_table values (2020, 'Russia', 1), (2021, 'Brazil', 2);

arthur :) select _path, * from azure_table;

   ┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
1. │ cont/hive_partitioned/year=2020/country=Russia/7351305360873664512.parquet │ 2020 │ Russia  │       1 │
2. │ cont/hive_partitioned/year=2021/country=Brazil/7351305360894636032.parquet │ 2021 │ Brazil  │       2 │
   └────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘
```

<div id="see-also">
  ## Veja também
</div>

[Função de tabela do Azure Blob Storage](/pt-BR/reference/functions/table-functions/azureBlobStorage)