メインコンテンツまでスキップ
メインコンテンツまでスキップ

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 に保存されます。

デフォルト値: 24.6 より前は ordered。24.6 以降では、デフォルト値は存在せず、設定は手動で指定する必要があります。以前のバージョンで作成されたテーブルのデフォルト値は互換性のために Ordered のままです。

after_processing​

成功裏に処理された後にファイルを削除するか保持するかを指定します。 可能な値:

  • keep.
  • delete.

デフォルト値: keep.

keeper_path​

ZooKeeper のパスはテーブルエンジンの設定として指定することができ、デフォルトのパスはグローバル設定提供のパスとテーブル UUID から構成されます。 可能な値:

  • String.

デフォルト値: /.

s3queue_loading_retries​

指定された回数までファイルの読み込みを再試行します。デフォルトでは、再試行はありません。 可能な値:

  • 正の整数。

デフォルト値: 0.

s3queue_processing_threads_num​

処理を行うスレッド数。Unordered モードのみ適用されます。

デフォルト値: 1.

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​

処理済みファイルを ZooKeeper ノードに保存する最大秒数（デフォルトでは永遠に保存）で、'unordered' モードで機能し、'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 ロールベースアクセス​

Scale plan feature

S3 Role-Based Access is available in the Scale and Enterprise plans. To upgrade, visit the Plans page in the cloud console.

S3Queue テーブルエンジンはロールベースのアクセスをサポートしています。 バケットにアクセスするためのロールを構成する手順については こちら を参照してください。

ロールが構成されたら、以下のように extra_credentials パラメータを介して roleARN を渡すことができます:

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 はストリーミングインポートには特に便利ではありません（デバッグを除く）、なぜなら各ファイルは一度だけインポートされるからです。リアルタイムスレッドを作成するためには、マテリアライズドビュを作成することがより実用的です。これを行うには：

  1. エンジンを使用して、S3 の指定されたパスからデータを取り出すためのテーブルを作成し、それをデータストリームと見なします。
  2. 希望する構造を持つテーブルを作成します。
  3. エンジンからデータを変換し、前に作成したテーブルに挿入するマテリアライズドビューを作成します。

MATERIALIZED VIEW がエンジンに参加すると、バックグラウンドでデータを収集し始めます。

例：

仮想カラム​

  • _path — ファイルへのパス。
  • _file — ファイル名。

仮想カラムに関する詳細は こちら を参照してください。

パスのワイルドカード​

path 引数は、bashのようなワイルドカードを使用して複数のファイルを指定できます。処理されるファイルは存在し、全体のパスパターンに一致する必要があります。ファイルのリストは SELECT の際に決定されます（CREATE の時点ではありません）。

  • * — '/' を除く任意の数の任意の文字を置き換え、空文字列を含めます。
  • ** — '/' を含む任意の数の任意の文字を置き換え、空文字列を含めます。
  • ? — 1 つの文字を置き換えます。
  • {some_string,another_string,yet_another_one} — 'some_string', 'another_string', 'yet_another_one' のいずれかの文字列を置き換えます。
  • {N..M} — N から M までの範囲の任意の数字を両端を含めて置き換えます。N と M には先頭ゼロを含んでいてもかまいません（例: 000..078）。

{} を用いた構文は remote テーブル関数に似ています。

制限事項​

  1. 重複行が発生する原因：
  • ファイル処理の途中でパース中に例外が発生し、s3queue_loading_retries によって再試行が有効化される場合；
  • S3Queue が複数のサーバーに設定され、ZooKeeper 内の同じパスを指摘し、1 台のサーバーが処理されたファイルをコミットする前にセッションが切れると、別のサーバーがファイルの処理を引き継ぐ可能性があるため、ファイルは最初のサーバーで部分的または完全に処理されている可能性があります；
  • 異常なサーバー終了。
  1. S3Queue が複数のサーバーに設定され、ZooKeeper 内の同じパスを指摘し、Ordered モードが使用されると、s3queue_loading_retries は機能しません。これはすぐに修正される予定です。

インストロスペクション​

インストロスペクションには system.s3queue ステートレステーブルおよび system.s3queue_log 永続テーブルを使用します。

  1. system.s3queue。このテーブルは永続的ではなく、S3Queue のメモリ内状態を表示します: 現在処理中のファイル、処理済みまたは失敗したファイル。

例：

  1. system.s3queue_log。永続テーブル。処理されたファイルおよび失敗したファイルに関する情報が system.s3queue と同様です。

テーブルの構造は次のようになります：

system.s3queue_log を使用するには、サーバー設定ファイルにその設定を定義します：

例：