S3Queue テーブルエンジン
このエンジンは Amazon S3 エコシステムと統合されており、ストリーミングインポートを可能にします。このエンジンは Kafka や RabbitMQ エンジンに似ていますが、S3固有の機能を提供します。
テーブルの作成
24.7
未満では、mode
、after_processing
、keeper_path
を除くすべての設定にs3queue_
プレフィックスを使用する必要があります。
エンジンパラメータ
S3Queue
のパラメータは、S3
テーブルエンジンがサポートするものと同じです。パラメータセクションの詳細はこちらを参照してください。
例
名前付きコレクションを使用する場合:
設定
テーブルに設定された設定のリストを取得するには、system.s3_queue_settings
テーブルを使用します。24.10
から利用可能です。
mode
可能な値:
- unordered — 順序が保証されないモードでは、すべての処理済みファイルの集合がZooKeeper内の永続ノードで追跡されます。
- ordered — 順序付きモードでは、ファイルは字典順序で処理されます。つまり、ファイル名が'BBB'のファイルがある時、それに後から追加されたファイル名'AA'は無視されます。成功裏に消費されたファイルの最大名(字典順に意味する)と、処理に失敗し再試行されるファイルの名前のみがZooKeeperに保存されます。
デフォルト値: ordered
は24.6未満のバージョンでは。24.6以降ではデフォルト値はなく、手動で指定する必要があります。以前のバージョンで作成されたテーブルのデフォルト値は互換性のためOrdered
のままです。
after_processing
成功裏に処理した後にファイルを削除するか保持するか。 可能な値:
- keep.
- delete.
デフォルト値: keep
.
keeper_path
ZooKeeper内のパスは、テーブルエンジンの設定として指定するか、グローバル設定から提供されたパスとテーブルのUUIDから形成されたデフォルトパスを使用できます。 可能な値:
- String.
デフォルト値: /
.
s3queue_loading_retries
指定した回数までファイルの読み込みを再試行します。デフォルトでは、リトライはありません。 可能な値:
- 正の整数。
デフォルト値: 0
.
s3queue_processing_threads_num
処理を行うスレッドの数。Unordered
モードのみに適用されます。
デフォルト値: CPUの数または16。
s3queue_parallel_inserts
デフォルトではprocessing_threads_num
は1つのINSERT
を生成しますので、ファイルをダウンロードし、複数のスレッドで解析することしかしません。
しかし、これにより並列性が制限されるので、より良いスループットのためにはparallel_inserts=true
を使用すると、データを並行して挿入できるようになります(ただし、これによりMergeTreeファミリーの生成されるデータパーツの数が増えることに注意してください)。
INSERT
はmax_process*_before_commit
設定に従って生成されます。
デフォルト値: false
.
s3queue_enable_logging_to_s3queue_log
system.s3queue_log
へのログ記録を有効にします。
デフォルト値: 0
.
s3queue_polling_min_timeout_ms
ClickHouseが次のポーリング試行を行う前に待機する最小時間(ミリ秒)を指定します。
可能な値:
- 正の整数。
デフォルト値: 1000
.
s3queue_polling_max_timeout_ms
ClickHouseが次のポーリング試行を開始する前に待機する最大時間(ミリ秒)を定義します。
可能な値:
- 正の整数。
デフォルト値: 10000
.
s3queue_polling_backoff_ms
新しいファイルが見つからないときに、前回のポーリング間隔に追加される待機時間を決定します。次のポーリングは、前回の間隔とこのバックオフ値の合計、または最大間隔のうち、いずれか低い方の後に発生します。
可能な値:
- 正の整数。
デフォルト値: 0
.
s3queue_tracked_files_limit
'unordered'モードの場合、ZooKeeperノードの数を制限できます。'ordered'モードでは何もしません。 制限に達した場合、最も古い処理済みファイルがZooKeeperノードから削除され、再処理されます。
可能な値:
- 正の整数。
デフォルト値: 1000
.
s3queue_tracked_file_ttl_sec
'unordered'モードの場合、ZooKeeperノード内で処理済みファイルを保存する最大秒数(デフォルトでは無限)で、'ordered'モードでは何もしません。 指定した秒数が経過した後、ファイルは再インポートされます。
可能な値:
- 正の整数。
デフォルト値: 0
.
s3queue_cleanup_interval_min_ms
'Ordered'モードの場合。バックグラウンドタスクの再スケジュール間隔の最小境界を定義します。このタスクは、追跡されたファイルのTTLと最大追跡ファイルセットを維持する役割を果たします。
デフォルト値: 10000
.
s3queue_cleanup_interval_max_ms
'Ordered'モードの場合。バックグラウンドタスクの再スケジュール間隔の最大境界を定義します。このタスクは、追跡されたファイルのTTLと最大追跡ファイルセットを維持する役割を果たします。
デフォルト値: 30000
.
s3queue_buckets
'Ordered'モードの場合。24.6
以降から利用可能です。S3Queueテーブルの複数のレプリカがあり、いずれも同じメタデータディレクトリを保持している場合、s3queue_buckets
の値は少なくともレプリカの数と同じである必要があります。s3queue_processing_threads
設定も使用する場合は、s3queue_buckets
の設定値をさらに増加させることが合理的です。これは、S3Queue
の処理の実際の並行性を定義します。
S3関連の設定
エンジンはすべてのS3関連の設定をサポートしています。S3設定の詳細についてはこちらを参照してください。
S3 ロールベースアクセス
S3 Role-Based Access is available in the Scale and Enterprise plans. To upgrade, visit the Plans page in the cloud console.
s3Queueテーブルエンジンはロールベースのアクセスをサポートしています。 バケットにアクセスするためのロールを設定する手順については、こちらのドキュメントを参照してください。
ロールが設定されると、roleARN
を下記のようにextra_credentials
パラメータを介して渡すことができます:
S3Queue オーダーモード
S3Queue
処理モードは、ZooKeeper内のメタデータをより少なく保存することを可能にしますが、時間的に後から追加されたファイルがアルファベット順に大きい名前を持つ必要があるという制限があります。
S3Queue
のordered
モードは、unordered
モードと同様に(s3queue_)processing_threads_num
設定をサポートしています(s3queue_
プレフィックスはオプショナルです)。この設定により、サーバー上でS3
ファイルの処理を行うスレッドの数を制御できます。
さらに、ordered
モードは(s3queue_)buckets
と呼ばれる別の設定も導入しています。これは「論理スレッド」を意味します。これは分散シナリオでのことで、S3Queue
テーブルのレプリカが複数のサーバー上に存在し、この設定が処理ユニットの数を定義します。例として、各S3Queue
レプリカの各処理スレッドが特定のファイル処理のために特定のbucket
をロックしようとします。各bucket
はファイル名のハッシュによって特定のファイルに割り当てられます。したがって、分散シナリオにおいては、(s3queue_)buckets
設定がレプリカの数と同じ、またはそれ以上であることが強く推奨されます。この設定はレプリカの数よりも多くても問題ありません。最も最適なシナリオは、(s3queue_)buckets
設定がnumber_of_replicas
と(s3queue_)processing_threads_num
の掛け算に等しいことです。
(s3queue_)processing_threads_num
設定はバージョン24.6
以前では使用が推奨されていません。
(s3queue_)buckets
設定はバージョン24.6
以降から利用可能です。
説明
SELECT
はストリーミングインポートにはそれほど有用ではありません(デバッグを除く)、なぜなら各ファイルは一度だけインポートできるからです。したがって、指定されたS3のパスからデータストリームとして消費するためのテーブルを作成するのがより実用的です。
- エンジンを使用してS3内の指定パスから消費するためのテーブルを作成し、それをデータストリームと見なします。
- 必要な構造でテーブルを作成します。
- エンジンからデータを変換し、事前に作成されたテーブルに格納するマテリアライズドビューを作成します。
MATERIALIZED VIEW
がエンジンと接続すると、バックグラウンドでデータを収集し始めます。
例:
仮想カラム
_path
— ファイルへのパス。_file
— ファイル名。
仮想カラムに関する詳細はこちらを参照してください。
パス内のワイルドカード
path
引数は、bash風のワイルドカードを使用して複数のファイルを指定できます。処理されるファイルは存在し、全体のパスパターンと一致している必要があります。ファイルのリストはSELECT
の際に決定され(CREATE
時ではありません)。
*
—/
を除く任意の文字の数を表し、空文字列も含まれます。**
—/
を含む任意の字符の数を表し、空文字列も含まれます。?
— 任意の単一文字を表します。{some_string,another_string,yet_another_one}
— 任意の文字列'some_string', 'another_string', 'yet_another_one'
を表します。{N..M}
— NからMまでの範囲内の任意の数を表し、両端を含みます。NおよびMには先頭ゼロを含めることができます(例:000..078
)。
{}
を使用した構文は、remoteテーブル関数に似ています。
制限事項
- 重複行が発生する可能性がある理由:
-
ファイル処理の途中で解析中に例外が発生し、リトライが
s3queue_loading_retries
で有効になっている場合。 -
S3Queue
が複数のサーバーで設定されており、同じパスのZooKeeperを指している場合、処理されたファイルのコミットが完了する前にキーパーセッションが期限切れになり、別のサーバーがファイル処理を引き継ぐことにより、最初のサーバーによって部分的または完全に処理されたファイルの処理が行われる可能性があります。 -
サーバーの異常終了。
S3Queue
が複数のサーバーで設定され、同じパスのZooKeeperを指している場合、Ordered
モードが使用されると、s3queue_loading_retries
は機能しません。これはすぐに修正される予定です。
内部構造の把握
内部構造を把握するには、system.s3queue
のステートレステーブルとsystem.s3queue_log
の永続テーブルを使用します。
system.s3queue
。このテーブルは永続的でなく、現在処理中のS3Queue
のメモリ内状態を表示します:現在どのファイルが処理中か、どのファイルが処理済みまたは失敗したか。
例:
system.s3queue_log
。永続テーブル。system.s3queue
と同じ情報を持ちますが、processed
およびfailed
ファイルについてです。
テーブルは以下の構造を持っています:
system.s3queue_log
を使用するためには、その設定をサーバーの設定ファイルに定義する必要があります:
例: