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

> Fornece uma interface semelhante a uma tabela para selecionar/inserir arquivos no Azure Blob Storage. Semelhante à função s3.

# Função de tabela azureBlobStorage

export const CloudNotSupportedBadge = () => {
  return <div className="cloudNotSupportedBadge">
            <div className="cloudNotSupportedIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.5" d="M6.33366 12.6666L12.3739 12.6667C13.6593 12.6667 14.7073 11.6187 14.7073 10.3334C14.7073 9.04804 13.6593 8.00003 12.3739 8.00003C12.3739 8.00003 12.3337 7.66659 12.0003 7.33325M10.667 5.33322C8.00033 2.33325 4.45395 4.78537 4.14195 6.68203C2.55728 6.7627 1.29395 8.06203 1.29395 9.6667C1.29395 11.3234 2.66699 12.6666 4.00033 12.6666" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.5" d="M2.66699 14L12.0003 4.66663" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>

        </div>
            Not supported in ClickHouse Cloud
        </div>;
};

export const ExperimentalBadge = () => {
  return <div className="experimentalBadge">
            <div className="experimentalIcon">
            <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
                <path strokeWidth="1.25" d="M5.5 2H10.5" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M9.50015 2V6.19625L13.4283 12.7425C13.4738 12.8183 13.4985 12.9049 13.4996 12.9934C13.5008 13.0818 13.4785 13.169 13.435 13.246C13.3914 13.323 13.3283 13.3871 13.2519 13.4317C13.1755 13.4764 13.0886 13.4999 13.0002 13.5H3.00015C2.91164 13.5 2.8247 13.4766 2.74822 13.432C2.67174 13.3874 2.60847 13.3233 2.56487 13.2463C2.52126 13.1693 2.49889 13.082 2.50004 12.9935C2.50119 12.905 2.52582 12.8184 2.5714 12.7425L6.50015 6.19625V2" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
                <path strokeWidth="1.25" d="M4.47656 9.56754C5.30344 9.41254 6.47656 9.47942 7.99969 10.25C10.0153 11.2707 11.4216 11.0569 12.2184 10.7282" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" />
            </svg>
        </div>
            Experimental feature. <u><a href="/docs/beta-and-experimental-features#experimental-features">Learn more.</a></u>
        </div>;
};

Fornece uma interface semelhante a uma tabela para selecionar/inserir arquivos no [Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs). Esta função de tabela é semelhante à [função s3](/pt-BR/reference/functions/table-functions/s3).

<div id="syntax">
  ## Sintaxe
</div>

<Tabs>
  <Tab title="String de conexão">
    As credenciais estão embutidas na string de conexão, portanto `account_name`/`account_key` não são necessários separadamente:

    ```sql theme={null}
    azureBlobStorage(connection_string, container_name, blobpath [, format, compression, structure])
    ```
  </Tab>

  <Tab title="URL da conta de armazenamento">
    Requer `account_name` e `account_key` como argumentos separados:

    ```sql theme={null}
    azureBlobStorage(storage_account_url, container_name, blobpath, account_name, account_key [, format, compression, structure])
    ```
  </Tab>

  <Tab title="Coleção nomeada">
    Veja [Coleções nomeadas](#named-collections) abaixo para a lista completa de chaves aceitas:

    ```sql theme={null}
    azureBlobStorage(named_collection[, option=value [,..]])
    ```
  </Tab>
</Tabs>

<div id="arguments">
  ## Argumentos
</div>

| Argumento                        | Descrição                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `connection_string`              | Uma string de conexão que inclui credenciais embutidas (nome da conta + chave da conta ou SAS token). Ao usar esse formato, `account_name` e `account_key` **não** devem ser passados separadamente. Consulte [Configurar uma 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). |
| `storage_account_url`            | A URL do endpoint da conta de armazenamento, por exemplo, `https://myaccount.blob.core.windows.net/`. Ao usar esse formato, você **deve** também passar `account_name` e `account_key`.                                                                                                                                                                                                                                                                                                                   |
| `container_name`                 | Nome do contêiner.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `blobpath`                       | Caminho do arquivo. Oferece suporte aos seguintes caracteres curinga no modo somente leitura: `*`, `**`, `?`, `{abc,def}` e `{N..M}`, em que `N`, `M` — números, `'abc'`, `'def'` — strings.                                                                                                                                                                                                                                                                                                              |
| `account_name`                   | Nome da conta de armazenamento. **Obrigatório** ao usar `storage_account_url` sem SAS; **não** deve ser passado ao usar `connection_string`.                                                                                                                                                                                                                                                                                                                                                              |
| `account_key`                    | Chave da conta de armazenamento. **Obrigatória** ao usar `storage_account_url` sem SAS; **não** deve ser passada ao usar `connection_string`.                                                                                                                                                                                                                                                                                                                                                             |
| `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 (o mesmo que definir como `auto`).                                                                                                                                                                                                                                                                                                           |
| `structure`                      | Estrutura da tabela. Formato: `'column1_name column1_type, column2_name column2_type, ...'`.                                                                                                                                                                                                                                                                                                                                                                                                              |
| `partition_strategy`             | Opcional. Valores compatíveis: `WILDCARD` ou `HIVE`. `WILDCARD` exige um `{_partition_id}` no caminho, que é substituído pela chave de partição. `HIVE` não permite caracteres curinga, pressupõe que o caminho é 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` | Opcional. Usado apenas com a estratégia de partição `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_credentials` forem fornecidas, elas terão prioridade sobre `account_name` e `account_key`.                                                                                                                                                                                                                                                                                                                                                     |

<div id="named-collections">
  ## Coleções nomeadas
</div>

Os argumentos também podem ser passados usando [coleções nomeadas](/pt-BR/concepts/features/configuration/server-config/named-collections). Nesse caso, as seguintes chaves são aceitas:

| Chave                 | Obrigatório | Descrição                                                                                                          |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `container`           | Sim         | Nome do contêiner. Corresponde ao argumento posicional `container_name`.                                           |
| `blob_path`           | Sim         | Caminho do arquivo (com wildcards opcionais). Corresponde ao argumento posicional `blobpath`.                      |
| `connection_string`   | Não\*       | String de conexão com credenciais embutidas. \*É necessário fornecer `connection_string` ou `storage_account_url`. |
| `storage_account_url` | Não\*       | URL do endpoint da conta de armazenamento. \*É necessário fornecer `connection_string` ou `storage_account_url`.   |
| `account_name`        | Não         | Obrigatório ao usar `storage_account_url`                                                                          |
| `account_key`         | Não         | Obrigatório ao usar `storage_account_url`                                                                          |
| `format`              | Não         | Formato do arquivo.                                                                                                |
| `compression`         | Não         | Tipo de compressão.                                                                                                |
| `structure`           | Não         | Estrutura da tabela.                                                                                               |
| `client_id`           | Não         | ID do cliente para autenticação.                                                                                   |
| `tenant_id`           | Não         | ID do tenant para autenticação.                                                                                    |

<Note>
  Os nomes das chaves da coleção nomeada diferem dos nomes dos argumentos posicionais da função: `container` (não `container_name`) e `blob_path` (não `blobpath`).
</Note>

**Exemplo:**

```sql theme={null}
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;
```

Você também pode sobrescrever os valores da coleção nomeada no momento da consulta:

```sql theme={null}
SELECT *
FROM azureBlobStorage(azure_my_data, blob_path = 'other_data/*.csv', format = 'CSVWithNames')
LIMIT 5;
```

<div id="returned_value">
  ## Valor retornado
</div>

Uma tabela com a estrutura especificada para leitura ou gravação de dados no arquivo especificado.

<div id="examples">
  ## Exemplos
</div>

<div id="reading-with-storage-account-url">
  ### Leitura usando o formato `storage_account_url`
</div>

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

<div id="reading-with-connection-string">
  ### Leitura no formato `connection_string`
</div>

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

<div id="writing-with-partitions">
  ### Gravação usando partições
</div>

```sql theme={null}
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);
```

Em seguida, leia uma partição específica:

```sql theme={null}
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'
);
```

```response theme={null}
┌─column1─┬─column2─┬─column3─┐
│       3 │       2 │       1 │
└─────────┴─────────┴─────────┘
```

<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 do arquivo for desconhecido, o valor será `NULL`.
* `_time` — Horário da última modificação do arquivo. Tipo: `Nullable(DateTime)`. Se o horário for desconhecido, o valor será `NULL`.

<div id="partitioned-write">
  ## Gravação particionada
</div>

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

Compatível apenas com consultas INSERT.

`WILDCARD` (padrão): substitui o curinga `{_partition_id}` no caminho do arquivo pela chave de particionamento real.

`HIVE` implementa o particionamento no estilo Hive para leituras & gravações. Gera arquivos usando o seguinte formato: `<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>`.

**Exemplo da estratégia de particionamento `HIVE`**

```sql theme={null}
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);
```

```result theme={null}
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  │
   └─────────────────────────────────────────────────────────────────────────────────┴────┴──────┴─────────┘
```

<div id="hive-style-partitioning">
  ## configuração use\_hive\_partitioning
</div>

Esta é uma instrução para o ClickHouse interpretar arquivos particionados no estilo Hive no momento da leitura. Isso não afeta a gravação. Para manter simetria entre leituras e gravações, use o argumento `partition_strategy`.

Quando a configuração `use_hive_partitioning` é definida como 1, o ClickHouse detecta o particionamento no estilo Hive no caminho (`/name=value/`) e permite usar colunas de partição como colunas virtuais na consulta. Essas colunas virtuais terão os mesmos nomes do caminho particionado.

**Exemplo**

Use a coluna virtual criada com particionamento no estilo Hive

```sql theme={null}
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;
```

<div id="using-shared-access-signatures-sas-sas-tokens">
  ## Usando Shared Access Signatures (SAS)
</div>

Uma Shared Access Signature (SAS) é um URI que concede acesso restrito a um contêiner ou arquivo no Azure Storage. Use-a para fornecer acesso por tempo limitado aos recursos da conta de armazenamento sem compartilhar a chave da conta de armazenamento. Mais detalhes [aqui](https://learn.microsoft.com/en-us/rest/api/storageservices/delegate-access-with-shared-access-signature).

A função `azureBlobStorage` oferece suporte a Shared Access Signatures (SAS).

Um [Blob SAS token](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers) contém todas as informações necessárias para autenticar a solicitação, incluindo o blob de destino, as permissões e o período de validade. Para montar uma URL de blob, acrescente o SAS token ao endpoint do serviço Blob. Por exemplo, se o endpoint for `https://clickhousedocstest.blob.core.windows.net/`, a solicitação será:

```sql theme={null}
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, os usuários podem usar a [URL SAS gerada do Blob](https://learn.microsoft.com/en-us/azure/ai-services/translator/document-translation/how-to-guides/create-sas-tokens?tabs=Containers):

```sql theme={null}
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.
```

<div id="related">
  ## Relacionados
</div>

* [Mecanismo de tabela AzureBlobStorage](/pt-BR/reference/engines/table-engines/integrations/azureBlobStorage)