Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

AzureBlobStorage テーブルエンジン

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

テーブルの作成

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

エンジンパラメータ

  • 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 が含まれます (接続文字列を作成する) 。または、ここに 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 — ファイルのフォーマット。
  • compression — サポートされる値: none, gzip/gz, brotli/br, xz/LZMA, zstd/zst。デフォルトでは、ファイル拡張子から圧縮を自動判別します (auto を設定した場合と同じです) 。
  • partition_strategy – オプション: wildcard または hive。wildcard ではパス内に {_partition_id} が必要で、これはパーティションキーに置き換えられます。hive ではワイルドカードは使用できず、パスをテーブルのルートとみなし、Snowflake IDs をファイル名、ファイルフォーマットを拡張子とする Hive スタイルのパーティションディレクトリを生成します。明示的な方式を指定しない場合、{_partition_id} を含むパスでは wildcard が使用されます。別の glob を含むパスではパーティション方式は使用されず、PARTITION BY は無視されます。glob を含まないパスでは、file_like_engine_default_partition_strategy が hive の場合は hive が使用され、それ以外の場合はパーティション方式は使用されません。
  • partition_columns_in_data_file - hive パーティション方式でのみ使用されます。データファイル内にパーティションカラムが書き込まれているものとして ClickHouse が扱うかどうかを指定します。デフォルトは false です。
  • extra_credentials - 認証には client_id と tenant_id を使用します。extra_credentials が指定されている場合、account_name と account_key より優先されます。

例

ローカルでの Azure Storage 開発には、Azurite エミュレーターを使用できます。詳細はこちらを参照してください。ローカルの Azurite インスタンスを使用する場合、以下のコマンドでは Azurite がホスト azurite1 で利用可能であることを前提としているため、http://azurite1:10000 の代わりに http://localhost:10000 を使用する必要がある場合があります。

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;
┌─key──┬─data──┐
│  1   │   a   │
│  2   │   b   │
│  3   │   c   │
└──────┴───────┘

仮想カラム

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

認証

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

  • Managed Identity - endpoint、connection_string、または storage_account_url を指定して使用できます。
  • SAS Token - endpoint、connection_string、または storage_account_url を指定して使用できます。URL に ? が含まれていることで識別されます。例については、azureBlobStorage を参照してください。
  • Workload Identity - endpoint または storage_account_url を指定して使用できます。config で use_workload_identity パラメータが設定されている場合、認証には (workload identity) が使用されます。

データキャッシュ

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

キャッシュを有効にするには、設定 filesystem_cache_name = '<name>' と enable_filesystem_cache = 1 を使用します。

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の設定ファイルに次のセクションを追加します。
<clickhouse>
    <filesystem_caches>
        <cache_for_azure>
            <path>path to cache directory</path>
            <max_size>10Gi</max_size>
        </cache_for_azure>
    </filesystem_caches>
</clickhouse>
  1. ClickHouse の storage_configuration セクションの cache 構成 (したがって cache ストレージも) を再利用します。詳しくはこちらを参照してください

PARTITION BY

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

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

パーティション方式

wildcard: ファイルパス内の {_partition_id} ワイルドカードを実際のパーティションキーに置き換えます。読み取りはサポートされていません。パスに {_partition_id} が含まれる場合、デフォルトで選択されます。

partition_strategy が設定されていない場合、別の glob を含むパスではパーティション方式は使用されず、PARTITION BY は無視されます。glob を含まないパスでは、file_like_engine_default_partition_strategy が hive の場合は hive が使用され、それ以外の場合はパーティション方式は使用されません。

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

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

hive パーティション方式の例:

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

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

select _path, * from azure_table;
┌─_path──────────────────────────────────────────────────────────────────────┬─year─┬─country─┬─counter─┐
│ cont/hive_partitioned/year=2020/country=Russia/7351305360873664512.parquet │ 2020 │ Russia  │       1 │
│ cont/hive_partitioned/year=2021/country=Brazil/7351305360894636032.parquet │ 2021 │ Brazil  │       2 │
└────────────────────────────────────────────────────────────────────────────┴──────┴─────────┴─────────┘

関連項目

Azure Blob Storageテーブル関数

Navigation