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

> このエンジンは、Azure Blob Storage エコシステム向けのインテグレーションを提供します。

# AzureBlobStorage テーブルエンジン

このエンジンは、[Azure Blob Storage](https://azure.microsoft.com/en-us/products/storage/blobs) エコシステム向けのインテグレーションを提供します。

<div id="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">
  ### エンジンパラメータ
</div>

* `endpoint` — コンテナーとプレフィックスを含む AzureBlobStorage のエンドポイント URL。使用する認証方式で必要な場合は、任意で account\_name を含めることもできます。(`http://azurite1:{port}/[account_name]{container_name}/{data_prefix}`)。または、storage\_account\_url、account\_name、container を使ってこれらのパラメータを個別に指定することもできます。プレフィックスを指定する場合は、endpoint を使用する必要があります。
* `endpoint_contains_account_name` - endpoint に account\_name が含まれるかどうかを指定するフラグです。これは一部の認証方式でのみ必要です。(デフォルト: true)
* `connection_string|storage_account_url` — connection\_string には account name と key が含まれます ([接続文字列を作成する](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 を指定し、account name と account key を個別のパラメータとして指定することもできます (account\_name と account\_key パラメータを参照) 。
* `container_name` - コンテナー名
* `blobpath` - ファイルパス。readonly モードでは、次のワイルドカードをサポートします: `*`, `**`, `?`, `{abc,def}` および `{N..M}`。ここで、`N`, `M` — 数値、`'abc'`, `'def'` — 文字列です。
* `account_name` - storage\_account\_url を使用する場合は、ここで account name を指定できます
* `account_key` - storage\_account\_url を使用する場合は、ここで account key を指定できます
* `format` — ファイルの[フォーマット](/ja/reference/formats/index)。
* `compression` — サポートされる値: `none`, `gzip/gz`, `brotli/br`, `xz/LZMA`, `zstd/zst`。デフォルトでは、ファイル拡張子から圧縮を自動判別します (`auto` を設定した場合と同じです) 。
* `partition_strategy` – オプション: `wildcard` または `hive`。`wildcard` ではパス内に `{_partition_id}` が必要で、これはパーティションキーに置き換えられます。`hive` ではワイルドカードは使用できず、パスをテーブルのルートとみなし、Snowflake IDs をファイル名、ファイルフォーマットを拡張子とする Hive スタイルのパーティションディレクトリを生成します。デフォルトは `file_like_engine_default_partition_strategy` 設定です (`26.6` より古い `compatibility` 設定では `wildcard`、それ以外では `hive`) 。
* `partition_columns_in_data_file` - `hive` パーティション方式でのみ使用されます。データファイル内にパーティションカラムが書き込まれているものとして ClickHouse が扱うかどうかを指定します。デフォルトは `false` です。
* `extra_credentials` - 認証には `client_id` と `tenant_id` を使用します。extra\_credentials が指定されている場合、`account_name` と `account_key` より優先されます。

**例**

ローカルでの Azure Storage 開発には、Azurite エミュレーターを使用できます。詳細は[こちら](https://learn.microsoft.com/en-us/azure/storage/common/storage-use-azurite?tabs=docker-hub%2Cblob-storage)を参照してください。ローカルの Azurite インスタンスを使用する場合、以下のコマンドでは Azurite がホスト `azurite1` で利用可能であることを前提としているため、`http://azurite1:10000` の代わりに `http://localhost:10000` を使用する必要がある場合があります。

```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">
  ## 仮想カラム
</div>

* `_path` — ファイルのパス。型: `LowCardinality(String)`.
* `_file` — ファイル名。型: `LowCardinality(String)`.
* `_size` — ファイルのサイズ (バイト単位) 。型: `Nullable(UInt64)`。サイズが不明な場合、値は `NULL` です。
* `_time` — ファイルの最終更新時刻。型: `Nullable(DateTime)`。時刻が不明な場合、値は `NULL` です。

<div id="authentication">
  ## 認証
</div>

現在、認証方式は 3 つあります。

* `Managed Identity` - `endpoint`、`connection_string`、または `storage_account_url` を指定して使用できます。
* `SAS Token` - `endpoint`、`connection_string`、または `storage_account_url` を指定して使用できます。URL に `?` が含まれていることで識別されます。例については、[azureBlobStorage](/ja/reference/functions/table-functions/azureBlobStorage#using-shared-access-signatures-sas-sas-tokens) を参照してください。
* `Workload Identity` - `endpoint` または `storage_account_url` を指定して使用できます。config で `use_workload_identity` パラメータが設定されている場合、認証には ([workload identity](https://github.com/Azure/azure-sdk-for-cpp/tree/main/sdk/identity/azure-identity#authenticate-azure-hosted-applications)) が使用されます。

<div id="data-cache">
  ### データキャッシュ
</div>

`Azure` テーブルエンジンは、ローカルディスク上でのデータキャッシュをサポートしています。
ファイルシステムキャッシュの設定オプションと使用方法については、この[セクション](/ja/concepts/features/configuration/server-config/storing-data#using-local-cache)を参照してください。
キャッシュはストレージオブジェクトのパスと ETag に基づいて行われるため、ClickHouse が古い cache バージョンを読み取ることはありません。

キャッシュを有効にするには、設定 `filesystem_cache_name = '<name>'` と `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. 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. ClickHouse の `storage_configuration` セクションの cache 構成 (したがって cache ストレージも) を再利用します。詳しくは[こちら](/ja/concepts/features/configuration/server-config/storing-data#using-local-cache)を参照してください

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

`PARTITION BY` — 任意です。ほとんどの場合、パーティションキーは不要です。必要な場合でも、通常は月単位より細かいパーティションキーは必要ありません。パーティション化してもクエリは高速化されません (`ORDER BY` 式とは対照的です) 。細かすぎるパーティション化は決して行わないでください。クライアント識別子や名前でデータをパーティション化しないでください (代わりに、クライアント識別子または名前を `ORDER BY` 式の最初のカラムにしてください) 。

月単位でパーティション化するには、`toYYYYMM(date_column)` 式を使用します。ここで、`date_column` は [Date](/ja/reference/data-types/date) 型の日付を持つカラムです。この場合、パーティション名は `"YYYYMM"` フォーマットになります。

<div id="partition-strategy">
  #### パーティション方式
</div>

`wildcard`: ファイルパス内の `{_partition_id}` ワイルドカードを実際のパーティションキーに置き換えます。読み取りはサポートされていません。デフォルトで選択されるのは、`compatibility` 設定が `26.6` より前の場合のみです。それ以外では、デフォルトは `hive` です (`file_like_engine_default_partition_strategy` 設定を参照) 。

`hive` は、読み取りと書き込みに Hive スタイルのパーティション化を実装します。読み取りは再帰的な glob パターンを使用して行われます。書き込みでは、次のフォーマットでファイルが生成されます: `<prefix>/<key1=val1/key2=val2...>/<snowflakeid>.<toLower(file_format)>`。

注: `hive` パーティション方式を使用する場合、`use_hive_partitioning` 設定は効果がありません。

`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">
  ## 関連項目
</div>

[Azure Blob Storageテーブル関数](/ja/reference/functions/table-functions/azureBlobStorage)