ApsaraDB for ClickHouse:よくある質問

ApsaraDB for ClickHouse は、主にコミュニティバージョンで見つかった安定性のバグを修正し、ユーザーロールレベルでリソース使用の優先順位を設定できるリソースキューを提供します。

以下のいずれかのソリューションを使用できます：

• ネットワーク接続を確認します。ping コマンドを実行してネットワーク接続を確認できます。また、telnet コマンドを実行して、データベースポート 3306 および 8123 が開いているかどうかを確認できます。

• ClickHouse にホワイトリストが設定されているか確認します。詳細については、「ホワイトリストの設定」をご参照ください。

• クライアントの IP アドレスが正しいか確認します。企業ネットワーク内のコンピューターの IP アドレスは頻繁に変更されるため、表示される IP アドレスが正しくない場合があります。専門の IP アドレス検索サービスを使用して、送信元 IP アドレスを特定できます。詳細については、「whatsmyip」をご参照ください。

バージョン 20.3 および 20.8 では、外部テーブルを作成する際に自動的に接続を検証します。テーブルが作成された場合、ネットワークが接続されていることを示します。テーブルが作成できない場合、一般的な原因は次のとおりです：

• 宛先エンドポイントと ClickHouse クラスターが同じ VPC にないため、ネットワークが切断されています。

• MySQL エンドポイントにホワイトリスト設定が構成されています。ClickHouse クラスターの IP アドレスを MySQL エンドポイントのホワイトリストに追加する必要があります。

一般的な原因と解決策は次のとおりです：

• 原因 1：VPC またはパブリックネットワーク環境が正しく設定されていません。プログラムとクラスターが同じ VPC にある場合は、内部ネットワーク接続を使用できます。同じ VPC にない場合は、パブリックエンドポイントを有効にして接続する必要があります。

  ソリューション：パブリックエンドポイントの申請方法の詳細については、「パブリックエンドポイントの申請と解放」をご参照ください。

• 原因 2：クラスターにホワイトリストが設定されていません。

  ソリューション：ホワイトリストの設定方法の詳細については、「ホワイトリストの設定」をご参照ください。

• 原因 3：ECS セキュリティグループで必要なポートが開かれていません。

  ソリューション：セキュリティグループの設定方法の詳細については、「セキュリティグループの操作」をご参照ください。

• 原因 4：企業ネットワークのファイアウォールが接続をブロックしています。

  ソリューション：ファイアウォールのルールを変更します。

• 原因 5：接続文字列のパスワードに !@#$%^&*()_+= などの特殊文字が含まれています。これらの特殊文字は接続時に認識されず、接続が失敗する可能性があります。

  ソリューション：接続文字列内の特殊文字をエスケープする必要があります。エスケープルールは次のとおりです：

  ! : %21
  @ : %40
  # : %23
  $ : %24
  % : %25
  ^ : %5e
  & : %26
  * : %2a
  ( : %28
  ) : %29
  _ : %5f
  + : %2b
  = : %3d

  例：パスワードが ab@#c の場合、接続文字列内の特殊文字をエスケープする必要があります。パスワードは ab%40%23c になります。

• 原因 6：デフォルトでは、ApsaraDB for ClickHouse は SLB インスタンスをマウントします。これは従量課金サービスです。アカウントに支払い遅延がある場合、ApsaraDB for ClickHouse インスタンスにアクセスできなくなる可能性があります。

  ソリューション：Alibaba Cloud アカウントに支払い遅延があるか確認してください。ある場合は、速やかに未払い残高を支払ってください。

以下のいずれかのソリューションを使用できます：

• インポートする前に、OSS 上のファイルをより小さなファイルに分割します。

• インスタンスのメモリをアップグレードします。メモリのアップグレード方法の詳細については、「コミュニティ互換版クラスターの垂直スケーリングと水平スケーリング」をご参照ください。

一般的な原因と解決策は次のとおりです：

• 原因 1：不適切なパラメーター設定が構成されています。ClickHouse は、大きなバッチと少数の同時実行プロセスを使用する書き込み操作に適しています。ほとんどの場合、バッチサイズは数万、あるいは数十万にもなります。バッチサイズは行サイズに依存します。行サイズを 1 行あたり 100 バイトと見積もることができますが、実際のデータ特性に基づいて計算する必要があります。

  ソリューション：同時実行プロセス数は 10 を超えないことを推奨します。さまざまなパラメーターを調整してみてください。

• 原因 2：DataWorks の専用リソースグループの ECS インスタンスの仕様が低い。たとえば、専用リソースの CPU とメモリが小さすぎると、同時実行プロセス数とアウトバウンド帯域幅が制限されます。バッチサイズが大きすぎてメモリが小さすぎると、DataWorks プロセスで Java ガベージコレクション (GC) がトリガーされる可能性があります。

  ソリューション：DataWorks の出力ログで ECS インスタンスの仕様を確認してください。

• 原因 3：データソースからのデータ読み取りが遅い。

  ソリューション：DataWorks の出力ログで `totalWaitReaderTime` と `totalWaitWriterTime` を検索してください。`totalWaitReaderTime` が `totalWaitWriterTime` より著しく大きい場合、ボトルネックは書き込み側ではなく読み取り側にあります。

• 原因 4：パブリックエンドポイントが使用されています。パブリックエンドポイントの帯域幅は制限されており、パフォーマンス専有型のデータインポートおよびエクスポートをサポートできません。

  ソリューション：パブリックエンドポイントを VPC エンドポイントに置き換えます。

• 原因 5：ダーティデータが存在します。ダーティデータがない場合、データはバッチで書き込まれます。しかし、ダーティデータに遭遇すると、現在のバッチ書き込み操作は失敗し、行ごとの書き込みにフォールバックします。これにより、多くのデータパートが生成され、書き込み速度が大幅に低下します。

  ダーティデータを確認するには、次のいずれかの方法を使用できます：

  • エラーメッセージを確認します。返されたメッセージに Cannot parse が含まれている場合、ダーティデータが存在します。

    コードは次のとおりです：

    SELECT written_rows, written_bytes, query_duration_ms, event_time, exception
    FROM system.query_log
    WHERE event_time BETWEEN '2021-11-22 22:00:00' AND '2021-11-22 23:00:00' AND lowerUTF8(query) LIKE '%insert into <table_name>%' and type != 'QueryStart' and exception_code != 0
    ORDER BY event_time DESC LIMIT 30;

  • バッチ内の行数を確認します。行数が 1 の場合、ダーティデータが存在します。

    コードは次のとおりです：

    SELECT written_rows, written_bytes, query_duration_ms, event_time
    FROM system.query_log
    WHERE event_time BETWEEN '2021-11-22 22:00:00' AND '2021-11-22 23:00:00' AND lowerUTF8(query) LIKE '%insert into <table_name>%' and type != 'QueryStart'
    ORDER BY event_time DESC LIMIT 30;

  ソリューション：データソース内のダーティデータを削除または変更します。

問題をトラブルシューティングするには、次の方法を使用できます：

1. `query_log` システムテーブルをチェックして、インポート中にエラーが発生したかどうかを確認します。エラーが発生した場合、データ損失が発生した可能性があります。

2. テーブルエンジンが重複排除をサポートしているかどうかを判断します。たとえば、ReplacingMergeTree エンジンを使用している場合、ClickHouse の行数は Hive よりも少なくなる可能性があります。

3. Hive の行数の正確性を再確認します。ソースの行数が誤って決定された可能性があります。

問題をトラブルシューティングするには、次の方法を使用できます：

1. `query_log` システムテーブルをチェックして、インポート中にエラーが発生したかどうかを確認します。エラーが発生した場合、データ損失が発生した可能性があります。

2. テーブルエンジンが重複排除をサポートしているかどうかを判断します。たとえば、ReplacingMergeTree エンジンを使用している場合、ClickHouse の行数は Kafka よりも少なくなる可能性があります。

3. Kafka 外部テーブルに `kafka_skip_broken_messages` パラメーターが設定されているかどうかを確認します。このパラメーターが存在する場合、解析に失敗した Kafka メッセージがスキップされる可能性があります。これにより、ClickHouse の総行数が Kafka よりも少なくなります。

以下のいずれかのソリューションを使用できます：

• ClickHouse クライアントを使用してファイルをエクスポートしてデータを移行します。詳細については、「セルフマネージド ClickHouse インスタンスから ApsaraDB for ClickHouse コミュニティ互換版インスタンスへのデータ移行」をご参照ください。

• `remote` 関数を使用してデータを移行します。

  INSERT INTO <destination_table> SELECT * FROM remote('<connection_string>', '<database>', '<table>', '<username>', '<password>');

ソリューション：MySQL データを再同期します。そのためには、次の手順を実行します：

1. 同期が停止したテーブルを削除します。

   DROP TABLE <table_name> ON cluster default;

   説明

   table_name は同期が停止したテーブルの名前です。テーブルに分散テーブルがある場合は、ローカルテーブルと分散テーブルの両方を削除する必要があります。

2. 同期プロセスを再開します。

   ALTER database <database_name> ON cluster default MODIFY SETTING skip_unsupported_tables = 1;

   説明

   <database_name> は同期中の ApsaraDB for ClickHouse のデータベースです。

一般的な原因と解決策は次のとおりです：

• 原因 1：高いメモリ使用量。

  ソリューション：`max_insert_threads` パラメーターを調整して、潜在的なメモリ使用量を削減します。

• 原因 2：INSERT INTO SELECT 文を使用して、ある ClickHouse クラスターから別のクラスターにデータをインポートしています。

  ソリューション：ファイルをインポートしてデータを移行します。詳細については、「セルフマネージド ClickHouse インスタンスから ApsaraDB for ClickHouse コミュニティ互換版インスタンスへのデータ移行」をご参照ください。

ClickHouse サーバーには、各クエリスレッド用のメモリトラッカーがあります。同じクエリ内のすべてのスレッドのトラッカーは、「クエリ用メモリトラッカー」に報告します。その上には、「合計用メモリトラッカー」があります。状況に応じて、以下のいずれかのソリューションを使用できます：

• Memory limit (for query) エラーが発生した場合、クエリが使用しているメモリが多すぎる (インスタンスの総メモリの 70%) ため、失敗しています。この場合、垂直アップグレードを実行してインスタンスのメモリを増やすことができます。

• Memory limit (for total) エラーが発生した場合、インスタンスの総メモリ使用量が制限 (インスタンスの総メモリの 90%) を超えています。この場合、クエリの同時実行数を減らしてみてください。問題が解決しない場合は、バックグラウンドの非同期タスクが大量のメモリを使用している可能性があります。これは、書き込み後のプライマリキーマージタスクでよく見られます。垂直アップグレードを実行してインスタンスのメモリを増やす必要があります。

サーバーのデフォルトの最大クエリ同時実行数は 100 です。これはコンソールで変更できます。実行中のパラメーター値を変更するには、次の手順を実行します：

1. ApsaraDB for ClickHouse コンソールにログインします。

2. [クラスターリスト] ページで、[コミュニティ版インスタンスのリスト] を選択し、ターゲットクラスター ID をクリックします。

3. 左側のナビゲーションウィンドウで、[パラメーター設定] をクリックします。

4. [パラメーター設定] ページで、max_concurrent_queries パラメーターの [実行パラメーター値] の横にある編集ボタンをクリックします。

5. ポップアップボックスにターゲット値を入力し、[確認] をクリックします。

6. [パラメーターの送信] をクリックします。

7. [パラメーターの送信] をクリックします。

以下のいずれかのソリューションを使用できます：

• マルチノードクラスターであるかどうかを確認します。マルチノードクラスターの場合、一貫した結果を得るには、分散テーブルを作成し、そこにデータを書き込み、クエリを実行する必要があります。そうしないと、各クエリが異なるシャードのデータにアクセスするため、結果が一致しなくなります。分散テーブルの作成方法の詳細については、「分散テーブルの作成」をご参照ください。

• マスターレプリカクラスターであるかどうかを確認します。マスターレプリカクラスターでは、レプリカ間でデータを同期するために Replicated 系テーブルエンジンを持つテーブルが必要です。そうしないと、各クエリが異なるレプリカにアクセスするため、結果が一致しなくなります。Replicated 系テーブルエンジンを持つテーブルの作成方法の詳細については、「テーブルエンジン」をご参照ください。

一般的な原因と解決策は次のとおりです：

• 原因 1：テーブル作成プロセスの問題。分散 ClickHouse クラスターにはネイティブな分散 DDL セマンティクスがありません。セルフマネージド ClickHouse クラスターで create table を使用してテーブルを作成すると、クエリは成功メッセージを返すかもしれませんが、テーブルは現在接続しているサーバーにのみ作成されます。別のサーバーに再接続すると、このテーブルは表示されません。

  ソリューション：

  1. テーブルを作成する際、create table <table_name> on cluster default 文を使用します。on cluster default 宣言は、この文をデフォルトクラスター内のすべてのノードにブロードキャストして実行します。以下のコードは例です：

     CREATE TABLE test ON cluster default (a UInt64) Engine = MergeTree() ORDER BY tuple();

  2. `test` テーブルに分散テーブルエンジンを作成します。テーブル作成文は次のとおりです：

     CREATE TABLE test_dis ON cluster default AS test Engine = Distributed(default, default, test, cityHash64(a));

• 原因 2：ReplicatedMergeTree ストレージテーブルの設定の問題。ReplicatedMergeTree テーブルエンジンは、マスターレプリカ同期機能を備えた MergeTree テーブルエンジンの拡張版です。シングルレプリカインスタンスは MergeTree テーブルのみを作成できます。マスターレプリカインスタンスは ReplicatedMergeTree テーブルのみを作成できます。

  ソリューション：マスターレプリカインスタンスでテーブルを作成する際、ReplicatedMergeTree('/clickhouse/tables/{database}/{table}/{shard}', '{replica}') または ReplicatedMergeTree() を使用して ReplicatedMergeTree テーブルエンジンを設定します。ReplicatedMergeTree('/clickhouse/tables/{database}/{table}/{shard}', '{replica}') の設定は固定であり、変更する必要はありません。

データがプライマリキーで正しくマージされることを保証するには、次の 2 つの前提条件を満たす必要があります：

• ストレージテーブルで定義された `PARTITION BY` フィールドは、ORDER BY 句に含まれている必要があります。異なるパーティションのデータはプライマリキーでマージされません。

• 分散テーブルで定義されたハッシュアルゴリズムフィールドは、ORDER BY 句に含まれている必要があります。異なるノードのデータはプライマリキーでマージされません。

一般的な OPTIMIZE コマンドとその説明は次のとおりです：

一般的な原因と解決策は次のとおりです：

• 原因 1：データの TTL 期限切れは、プライマリキーのマージフェーズで処理されます。データパートが長期間プライマリキーでマージされない場合、期限切れのデータは削除できません。

  ソリューション：

  • OPTIMIZE FINAL または OPTIMIZE PARTITION を使用して手動でマージタスクをトリガーします。

  • テーブル作成時に `merge_with_ttl_timeout` や `ttl_only_drop_parts` などのパラメーターを設定して、期限切れデータを含むデータパートのマージ頻度を増やします。

• 原因 2：テーブルの TTL が変更または追加され、既存のデータパートに TTL 情報がないか、情報が正しくない。これも期限切れデータが削除されない原因となる可能性があります。

  ソリューション：

  • ALTER TABLE ... MATERIALIZE TTL コマンドを使用して TTL 情報を再生成します。

  • OPTIMIZE PARTITION を使用して TTL 情報を更新します。

ローカルテーブルの変更は直接実行できます。分散テーブルを変更するには、状況に応じて手順が異なります：

• データ書き込みがない場合は、まずローカルテーブルを変更し、次に分散テーブルを変更できます。

• データ書き込みがある場合は、操作の種類によって異なる処理が必要です：

  タイプ	手順
  `Nullable` 列の追加	ローカルテーブルを変更します。 分散テーブルを変更します。
  列のデータ型を変更 (型が変換可能な場合)
  `Nullable` 列の削除	分散テーブルを変更します。 ローカルテーブルを変更します。
  非 `Nullable` 列の追加	データ書き込みを停止します。 分散テーブルで `SYSTEM FLUSH DISTRIBUTED` を実行します。 ローカルテーブルを変更します。 分散テーブルを変更します。 データ書き込みを再開します。
  非 `Nullable` 列の削除
  列名の変更

以下のいずれかのソリューションを使用できます：

• 操作が完了するのを待ちます。

• コンソールでクエリを終了してみてください。

一般的な原因と解決策は次のとおりです：

• 原因 1：ClickHouse クライアントが構文を解析し、set global on cluster default はサーバーによって追加された構文です。クライアントがサーバーと整合性のあるバージョンに更新されていない場合、この構文はクライアントによってブロックされます。

  ソリューション：

  • クライアント側で構文を解析しないツール (JDBC ドライバー、DataGrip、DBeaver など) を使用します。

  • JDBC プログラムを記述して文を実行します。

• 原因 2：set global on cluster default key = value; で、`value` が文字列であるにもかかわらず、引用符がありません。

  ソリューション：文字列型の値の両側に引用符を追加します。

各テーブルが占有するディスク領域は、次のコードで確認できます：

SELECT table, formatReadableSize(sum(bytes)) as size, min(min_date) as min_date, max(max_date) as max_date FROM system.parts WHERE active GROUP BY table; 

以下にサンプルコードを示します：

SELECT * FROM system.disks;

以下はサンプルコードです。

SELECT * FROM system.parts WHERE disk_name = 'cold_disk';

以下にサンプルコードを示します。

ALTER TABLE table_name MOVE PARTITION partition_expr TO DISK 'cold_disk';

主な原因は以下のとおりです：

• クエリによる OOM エラーの発生

• 構成変更による再起動

• スペックアップまたはスペックダウンに伴うインスタンスの再起動

一般的なシステムテーブルとその機能は次のとおりです：

ユーザーレベルのパラメーターは、users.xml ファイル内の一部の設定項目に対応します。次のサンプル文を実行します。

SET global ON cluster default ${key}=${value};

文を実行する際に設定を追加します。以下にサンプルコードを示します。

settings max_memory_usage = XXX;

ご利用のクラスターがマスターレプリカクラスターまたはシングルレプリカマルチノードクラスターの場合、多くの書き込み操作を実行すると、書き込みノードの CPU とメモリの使用率は他のノードよりも高くなります。データが他のノードに同期されると、CPU とメモリの使用率は均等になります。

• 問題の説明：

  エラーのトラブルシューティングや潜在的な問題を特定するための、詳細なシステムログ情報の表示方法。

• 解決策：

  1. クラスターの `text_log.level` パラメーターを確認し、次の操作を実行します。

     1. `text_log.level` が空の場合、`text_log` は有効になっていません。`text_log.level` を設定して `text_log` を有効にすることができます。

     2. `text_log.level` が空でない場合は、`text_log` のレベルが現在の要件を満たしているか確認してください。満たしていない場合は、このパラメーターを変更して `text_log` のレベルを設定することができます。

     `text_log.level` パラメーターの表示および変更方法の詳細については、「config.xml パラメーターの設定」をご参照ください。

  2. ターゲットデータベースにログインします。詳細については、「データベースへの接続」をご参照ください。

  3. 分析のために次の文を実行します。

     SELECT * FROM system.text_log;

ターゲットクラスターとデータソースが同じ VPC を使用し、同じリージョンにある場合は、お互いの IP アドレスをホワイトリストに追加しているかどうかを確認します。追加していない場合は、IP アドレスをホワイトリストに追加してください。

• ClickHouse で IP アドレスをホワイトリストに追加する方法の詳細については、「ホワイトリストの設定」をご参照ください。

• 他のデータソースで IP アドレスをホワイトリストに追加する方法の詳細については、各プロダクトのドキュメントをご参照ください。

ターゲットクラスターとデータソースが前述の条件を満たさない場合は、適切なネットワークソリューションを選択してネットワーク問題を解決できます。その後、お互いの IP アドレスをホワイトリストに追加します。

はい、ApsaraDB for ClickHouse Community-Compatible Edition クラスターを Enterprise Edition クラスターに移行できます。

Enterprise Edition クラスターと Community-Compatible Edition クラスター間でデータを移行するための主なメソッドとして、`remote` 関数を使用する方法と、ファイルのエクスポートとインポートを使用する方法の 2 つがあります。 詳細については、セルフマネージド ClickHouse インスタンスから ApsaraDB for ClickHouse Community-Compatible Edition インスタンスへのデータ移行をご参照ください。

バージョン 24.5 以降の新規 Enterprise Edition インスタンスでは、デフォルトのクエリエンジンとして新しいアナライザが使用されます。新しいアナライザは、クエリパフォーマンスが向上する一方で、一部の古い SQL 構文との互換性がなく、解析エラーが発生する可能性があります。このエラーが発生した場合は、次の文を実行して、古いアナライザに戻すことができます。新しいアナライザの詳細については、「New analyzer enabled by default」をご参照ください。

SET allow_experimental_analyzer = 0;

一時停止機能は ClickHouse Community Edition クラスターではサポートされていませんが、Enterprise Edition クラスターでは利用できます。Enterprise Edition クラスターを一時停止するには、Enterprise Edition クラスターリスト ページに移動します。左上隅で、ターゲットリージョンを選択し、ターゲットクラスターを見つけ、ターゲットクラスターの [操作] 列で >一時停止をクリックします。