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

System variables

システム変数

StarRocksは、要件に合わせて設定および変更できる多くのシステム変数を提供します。このセクションでは、StarRocksでサポートされている変数について説明します。MySQLクライアントでSHOW VARIABLESコマンドを実行することでこれらの変数の設定を表示することができます。また、SETコマンドを使用して変数を動的に設定または変更することもできます。これらの変数をシステム全体で効果を発揮させるか、現在のセッションのみで効果を発揮させるか、または単一のクエリステートメントのみで効果を発揮させるかのいずれかにすることができます。

StarRocksの変数はMySQLの変数セットを参照していますが、一部の変数はMySQLクライアントプロトコルとの互換性があり、MySQLデータベースでは機能しません。

注意

任意のユーザはSHOW VARIABLESを実行し、変数をセッションレベルで有効にする権限があります。ただし、SYSTEMレベルのOPERATE権限を持つユーザのみが、変数をグローバルに有効にすることができます。グローバルに有効な変数は、将来のすべてのセッション（現在のセッションを除く）に影響を与えます。

現在のセッションに設定変更を適用し、その設定変更をすべての将来のセッションにも適用するには、変更を2回行います。1回目はGLOBAL修飾子なしで、2回目はGLOBAL修飾子付きで行います。例:

SET query_mem_limit = 137438953472; -- 現在のセッションに適用する
SET GLOBAL query_mem_limit = 137438953472; -- 将来のすべてのセッションに適用する

ビュー変数​

SHOW VARIABLES [LIKE 'xxx']を使用して、すべての変数または一部の変数を表示することができます。例:

-- システムのすべての変数を表示する
SHOW VARIABLES;

-- 特定のパターンに一致する変数を表示する
SHOW VARIABLES LIKE '%time_zone%';

変数の設定​

グローバルにまたは単一のセッションに変数を設定する​

変数をグローバルにまたは現在のセッションのみに有効にすることができます。グローバルに設定した場合、新しい値はすべての将来のセッションで使用されますが、現在のセッションでは元の値が使用されます。現在のセッションのみに設定する場合は、変数は現在のセッションのみで有効になります。

SET <var_name> = xxx;で設定された変数は現在のセッションにのみ適用されます。例:

SET query_mem_limit = 137438953472;

SET forward_to_master = true;

SET time_zone = "Asia/Shanghai";

SET GLOBAL <var_name> = xxx;で設定された変数はグローバルに適用されます。例:

SET GLOBAL query_mem_limit = 137438953472;

次の変数はグローバルにのみ適用されます。これらの変数は単一のセッションに対して有効にすることはできず、これらの変数に対して単一のセッションで設定しようとすると（SET <var_name> = xxx;）、エラーが返されます。

  • activate_all_roles_on_login
  • character_set_database
  • default_rowset_type
  • enable_query_queue_select
  • enable_query_queue_statistic
  • enable_query_queue_load
  • init_connect
  • lower_case_table_names
  • license
  • language
  • query_cache_size
  • query_queue_fresh_resource_usage_interval_ms
  • query_queue_concurrency_limit
  • query_queue_mem_used_pct_limit
  • query_queue_cpu_used_permille_limit
  • query_queue_pending_timeout_second
  • query_queue_max_queued_queries
  • system_time_zone
  • version_comment
  • version

また、変数の設定は定数式もサポートしています。例:

SET query_mem_limit = 10 * 1024 * 1024 * 1024;
SET forward_to_master = concat('tr', 'u', 'e');

単一のクエリステートメントで変数を設定する​

一部のシナリオでは、特定のクエリに対して変数を設定する必要があります。SET_VARヒントを使用することで、単一のステートメント内でのみ有効なセッション変数を設定することができます。例:

SELECT /*+ SET_VAR(query_mem_limit = 8589934592) */ name FROM people ORDER BY name;

SELECT /*+ SET_VAR(query_timeout = 1) */ sleep(3);

注意

SET_VARは、SELECTキーワードの後に配置し、/*+...*/で囲む必要があります。

また、単一のステートメントで複数の変数を設定することもできます。例:

SELECT /*+ SET_VAR
  (
  exec_mem_limit = 515396075520,
  query_timeout=10000000,
  batch_size=4096,
  parallel_fragment_exec_instance_num=32
  )
  */ * FROM TABLE;

変数の説明​

変数はアルファベット順で説明されます。globalのラベルが付いている変数はグローバルにのみ有効です。その他の変数はグローバルに有効にすることもセッションごとに有効にすることもできます。

activate_all_roles_on_login (global)​

ユーザがStarRocksクラスタに接続する際に、StarRocksユーザのすべてのロール（デフォルトのロールと付与されたロールを含む）を有効にするかどうかを指定します。この変数はv3.0以降でサポートされています。

  • インエーブル（true）の場合、ユーザのすべてのロールがログイン時に有効になります。これはSET DEFAULT ROLEで設定されたロールよりも優先されます。
  • ディスエーブル（false）の場合、SET DEFAULT ROLEで設定されたロールが有効になります。

デフォルト値: false.

セッションで割り当てられたロールをアクティブにする場合は、SET ROLEコマンドを使用します。

auto_increment_increment​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

autocommit​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

batch_size​

クエリの実行中に各ノードが送信する単一のパケットの行数を指定するために使用されます。デフォルトは1024です。つまり、ソースノードが生成するデータの1024行ごとにパッケージ化して宛先ノードに送信されます。行数を増やすと、大量のデータのシナリオでクエリのスループットが向上しますが、少量のデータのシナリオではクエリのレイテンシが増加する可能性があります。また、クエリのメモリオーバーヘッドも増加する可能性があります。batch_sizeは1024から4096の間に設定することをおすすめします。

cbo_enable_low_cardinality_optimize​

低基数最適化を有効にするかどうかを指定します。この機能を有効にすると、STRING列をクエリするパフォーマンスが約3倍向上します。デフォルト値: true.

character_set_database (global)​

StarRocksでサポートされている文字セットです。UTF8（utf8）のみがサポートされています。

connector_io_tasks_per_scan_operator (2.5以降)​

外部テーブルクエリ中のスキャン演算子によって発行される最大の同時I/Oタスク数です。値は整数です。デフォルト値: 16.

現在、StarRocksは外部テーブルをクエリする際に、同時I/Oタスクの数を自動的に調整することができます。この機能はデフォルトで有効になっており、変数enable_connector_adaptive_io_tasksで制御されます。

count_distinct_column_buckets (2.5以降)​

GROUP BY COUNT DISTINCTクエリのCOUNT DISTINCT列のバケット数です。この変数はenable_distinct_column_bucketizationがtrueに設定されている場合のみ効果があります。デフォルト値: 1024.

default_rowset_type (global)​

グローバル変数。計算ノードのストレージエンジンで使用されるデフォルトのストレージ形式を設定するために使用されます。現在サポートされているストレージ形式はalphaとbetaです。

default_table_compression (3.0以降)​

テーブルストレージのデフォルトの圧縮アルゴリズムを設定するために使用されます。サポートされている圧縮アルゴリズムはsnappy、lz4、zlib、zstdです。デフォルト値: lz4_frame。

CREATE TABLEステートメントでcompressionプロパティを指定した場合は、compressionで指定された圧縮アルゴリズムが適用されます。

disable_colocate_join​

コロケーションジョインを有効にするかどうかを制御するために使用されます。デフォルト値はfalseで、機能が有効になっています。この機能が無効になっている場合、クエリプランではコロケーションジョインを実行しません。

disable_streaming_preaggregations​

ストリーミングプリアグリゲーションを有効にします。デフォルト値はfalseで、有効になっています。

div_precision_increment​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

enable_connector_adaptive_io_tasks (2.5以降)​

外部テーブルをクエリする際に、同時I/Oタスクの数を自動的に調整するかどうかを指定します。デフォルト値: true.

この機能が無効になっている場合、変数connector_io_tasks_per_scan_operatorを使用して同時I/Oタスクの数を手動で設定することができます。

enable_distinct_column_bucketization (2.5以降)​

GROUP BY COUNT DISTINCTクエリのCOUNT DISTINCT列にバケット化を有効にするかどうかを指定します。これにより、GROUP BY列aが低基数列であり、COUNT DISTINCT列bがデータの偏りがある高基数列である場合に、パフォーマンスボトルネックが発生しません。このような状況では、COUNT DISTINCT列のデータを複数のバケットに分割してデータをバランスさせ、データの偏りを防ぐことができます。

デフォルト値: falseで、この機能は無効になっています。この変数は変数count_distinct_column_bucketsとともに使用する必要があります。

また、COUNT DISTINCT列のバケット化を有効にするには、クエリにskewヒントを追加することもできます。例えば、select a,count(distinct [skew] b) from t group by a;です。

enable_insert_strict​

INSERTステートメントを使用してデータをロードする際に、厳密モードを有効にするかどうかを指定します。デフォルト値はtrueで、厳密モードがデフォルトで有効になっています。詳細については、厳密モードを参照してください。

enable_materialized_view_union_rewrite (2.5以降)​

マテリアライズドビューのUNIONクエリのリライトを有効にするかどうかを制御するブール値です。デフォルト: true。

enable_rule_based_materialized_view_rewrite (2.5以降)​

ルールベースのマテリアライズドビュークエリリライトを有効にするかどうかを制御するブール値です。この変数は主にシングルテーブルクエリリライトで使用されます。デフォルト: true。

enable_spill (3.0以降)​

中間結果のスピリングを有効にするかどうかを指定します。デフォルト: false。trueに設定すると、StarRocksはクエリの集計、ソート、または結合演算子の処理時にメモリ使用量を削減するために中間結果をディスクにスピルします。

enable_profile​

クエリのプロファイルを分析するためにプロファイルを送信するかどうかを指定します。デフォルト値はfalseで、プロファイルは必要ありません。

デフォルトでは、プロファイルは、BEでクエリエラーが発生した場合にのみFEに送信されます。プロファイルの送信にはネットワークオーバーヘッドが発生し、高い同時性に影響を与えるため、注意が必要です。

クエリのプロファイルを分析する必要がある場合は、この変数をtrueに設定します。クエリが完了すると、プロファイルを現在接続されているFEのWebページ（アドレス: fe_host:fe_http_port/query）で表示することができます。このページには、enable_profileが有効になっている最新の100のクエリのプロファイルが表示されます。

enable_query_queue_load (global)​

ロードタスクのためのクエリキューを有効にするブール値です。デフォルト値: false。

enable_query_queue_select (global)​

SELECTクエリのためのクエリキューを有効にするブール値です。デフォルト値: false。

enable_query_queue_statistic (global)​

統計クエリのためのクエリキューを有効にするブール値です。

enable_scan_block_cache (2.5以降)​

データキャッシュ機能を有効にするかどうかを指定します。この機能が有効になると、StarRocksは外部ストレージシステムから読み込んだホットデータをブロックごとにキャッシュし、クエリと分析を高速化します。詳細については、データキャッシュを参照してください。

enable_populate_block_cache (2.5以降)​

StarRocksで外部ストレージシステムから読み込まれたデータブロックをキャッシュするかどうかを指定します。外部ストレージシステムから読み込まれたデータブロックをキャッシュしたくない場合は、この変数をfalseに設定します。デフォルト値: true. この変数は2.5からサポートされています。

enable_tablet_internal_parallel (2.3以降)​

タブレットの自動並列スキャンを有効にするかどうかを指定します。この機能を有効にすると、セグメントごとに複数のスレッドを使用してタブレットをスキャンすることができ、スキャンの並列性が高まります。デフォルト値: true。

enable_query_cache (2.5以降)​

クエリキャッシュ機能を有効にするかどうかを指定します。有効な値はtrueとfalseです。この機能を有効にした場合、クエリキャッシュのアプリケーションシナリオで指定された条件を満たすクエリのみに適用されます。

enable_adaptive_sink_dop (2.5以降)​

データのロードに対する適応的な並列処理を有効にするかどうかを指定します。この機能を有効にすると、INSERT INTOとBroker Loadジョブのロード並列処理をシステムが自動的に設定します。これはpipeline_dopのメカニズムと同等です。v2.5以降の新しく展開されたStarRocksクラスタの場合、デフォルトでtrueに設定されます。v2.4からアップグレードされたv2.5クラスタの場合、デフォルトはfalseになります。

enable_pipeline_engine​

パイプライン実行エンジンを有効にするかどうかを指定します。trueは有効、falseは無効を示します。デフォルト値: true。

enable_sort_aggregate (2.5以降)​

ソート済みストリーミングを有効にするかどうかを指定します。trueはソート済みストリーミングが有効になり、データストリーム内のデータをソートします。

enable_global_runtime_filter​

グローバルなランタイムフィルタ（RF）を有効にするかどうかを指定します。RFはランタイムでデータをフィルタリングします。データフィルタリングはJoinステージでよく行われます。複数のテーブルが結合される際には、プッシュダウンなどの最適化技術を使用してデータをフィルタリングし、Joinのスキャン行数とシャッフルステージのI/Oを減らしてクエリの処理を高速化します。

StarRocksでは2つのタイプのRFを提供しています。ローカルRFとグローバルRFです。ローカルRFはBroadcast Hash Joinに適しており、グローバルRFはShuffle Joinに適しています。

デフォルト値: trueで、これはグローバルRFが有効になっていることを意味します。この機能が無効になっている場合、グローバルRFは効果を発揮しません。ローカルRFは引き続き機能します。

enable_multicolumn_global_runtime_filter​

マルチカラムのグローバルランタイムフィルタを有効にするかどうかを指定します。デフォルト値: falseで、マルチカラムのグローバルRFは無効です。

Join（Broadcast JoinとReplicated Joinを除く）に複数の等値結合条件がある場合:

  • この機能が無効になっている場合、ローカルRFのみが動作します。
  • この機能が有効になっている場合、マルチカラムグローバルRFが実行され、multi-columnがパーティション化clauseで使用されます。

event_scheduler​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

enable_strict_type (v3.1以降)​

すべての複合述語およびWHERE句内のすべての式に対して暗黙の型変換を許可するかどうかを指定します。デフォルト値: false。

force_streaming_aggregate​

集計ノードが計算のためにストリーミング集計を有効にするかどうかを制御するために使用されます。デフォルト値はfalseで、機能が無効になっています。

forward_to_master​

特定のコマンドをリーダーFEに転送して実行するかどうかを指定します。デフォルト値はfalseで、リーダーFEに転送しないことを意味します。StarRocksクラスタには複数のFEがあり、そのうち1つがリーダーFEです。通常、ユーザは完全な機能を備えた操作のためにいずれかのFEに接続することができます。ただし、リーダーFEのみで利用できる情報があります。

例えば、SHOW BACKENDSコマンドをリーダーFEに転送しない場合、ノードがアクティブであるかどうかなどの基本情報のみを表示することができます。リーダーFEに転送することで、ノードの開始時間や最後のハートビート時間などの詳細情報を含むより詳細な情報を取得できます。

この変数に影響を受けるコマンドは次のとおりです：

  • SHOW FRONTENDS: リーダーFEに転送することで、最新のハートビートメッセージを表示することができます。
  • SHOW BACKENDS: リーダーFEに転送することで、ブート時間、最後のハートビート情報、ディスク容量情報などの詳細情報を表示することができます。
  • SHOW BROKER: リーダーFEに転送することで、ブート時間および最後のハートビート情報を表示することができます。
  • SHOW TABLET
  • ADMIN SHOW REPLICA DISTRIBUTION
  • ADMIN SHOW REPLICA STATUS: リーダーFEに転送することで、リーダーFEのメタデータに格納されているタブレット情報を表示することができます。通常、異なるFEのメタデータは同じである必要があります。エラーが発生した場合、現在のFEとリーダーFEのメタデータを比較するためにこの方法を使用できます。
  • SHOW PROC: リーダーFEに転送することで、メタデータに格納されたPROC情報を表示することができます。これは主にメタデータの比較に使用されます。

group_concat_max_len​

group_concat関数で返される文字列の最大長さです。デフォルト値: 1024。最小値: 4。単位: 文字数。

hash_join_push_down_right_table​

Joinクエリで右側のテーブルのフィルタ条件を使用して左側のテーブルのデータをフィルタリングできるかどうかを制御するために使用されます。フィルタリングが可能なデータ量を減らすことができ、クエリの処理に必要なデータ量を削減できます。

trueは操作が許可され、システムは左側のテーブルをフィルタリングできるかどうかを決定します。falseは操作が無効を示します。デフォルト値はtrueです。

init_connect (global)​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

interactive_timeout​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

io_tasks_per_scan_operator (2.5以降)​

スキャン演算子が発行できる、同時に発行できるI/Oタスクの最大数です。レイテンシが高いHDFSやS3などのリモートストレージシステムにアクセスするための設定です。ただし、大きな値はより多くのメモリを消費します。

値は整数です。デフォルト値: 4。

language (global)​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

license (global)​

StarRocksのライセンス情報を表示します。

load_mem_limit​

インポート操作のメモリ制限を指定します。デフォルト値は0で、この変数は使用されず、query_mem_limitが使用されます。

この変数はクエリとインポートの両方を含むINSERT操作にのみ使用されます。ユーザがこの変数を設定しない場合、クエリとインポートのメモリ制限はどちらもexec_mem_limitとなります。それ以外の場合、クエリのメモリ制限はexec_mem_limitとなり、インポートのメモリ制限はload_mem_limitとなります。

B/K/KB/M/MB/G/GB/T/TB/P/PBのような単位をサポートしています。

log_rejected_record_num (v3.1以降)​

ログに記録されることができる不適格なデータ行の最大数を指定します。有効な値は0、-1、および0以外の正の整数です。デフォルト値: 0。

  • 0は、フィルタリングされたデータ行はログに記録されません。
  • -1は、フィルタリングされたすべてのデータ行がログに記録されます。
  • nなどの0以外の正の整数は、各BEで最大n個のフィルタリングされたデータ行がログに記録されることを意味します。

lower_case_table_names (global)​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。StarRocksではテーブル名は大文字と小文字を区別します。

max_allowed_packet​

JDBC接続プールC3P0との互換性のために使用されます。この変数は、クライアントとサーバー間で転送できるパケットの最大サイズを指定します。デフォルト値: 32 MB。単位: バイト。クライアントが「PacketTooBigException」を報告する場合は、この値を増やすことができます。

max_scan_key_num​

1つのクエリでセグメント化されたスキャンキーの最大数です。デフォルト値: -1で、be.confファイルの値が使用されます。この変数を0より大きい値に設定すると、be.confの値は無視されます。

max_pushdown_conditions_per_column​

列ごとにプッシュダウンできる述語の最大数です。デフォルト値: -1で、be.confファイルの値が使用されます。この変数を0より大きい値に設定すると、be.confの値は無視されます。

nested_mv_rewrite_max_level​

クエリリライトに使用できるネストされたマテリアライズドビューの最大レベルです。タイプ: INT。範囲: [1, +∞)。値が1の場合、ベーステーブルで作成されたマテリアライズドビューのみがクエリリライトに使用されます。デフォルト: 3。

net_buffer_length​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

net_read_timeout​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

net_write_timeout​

MySQLクライアントの互換性のために使用されます。実用的な使用方法はありません。

new_planner_optimize_timeout​

クエリオプティマイザのタイムアウト時間です。オプティマイザがタイムアウトすると、エラーが返され、クエリが停止し、クエリのパフォーマンスに影響します。特定のクエリに対してこの変数を大きな値に設定するか、トラブルシューティングのためにStarRocksの技術サポートに連絡することができます。タイムアウトは、クエリに結合が多すぎる場合によく発生します。

デフォルト値: 3000。単位: ミリ秒。

parallel_exchange_instance_num​

実行計画で上位ノードが下位ノードからデータを受け取るために使用するエクスチェンジノードの数を設定するために使用されます。デフォルト値は-1で、エクスチェンジノードの数は下位ノードの実行インスタンスの数と同じになります。この変数を0より大きくして下位ノードの実行インスタンスの数よりも小さい値に設定すると、エクスチェンジノードの数は設定値になります。

分散クエリの実行計画では、上位ノードは通常、異なるBEの実行インスタンスからのデータを受け取るために、1つ以上のエクスチェンジノードを持ちます。通常、エクスチェンジノードの数は下位ノードの実行インスタンスの数と同じです。

データが集計後に急激に減少する集計クエリのシナリオでは、リソースオーバーヘッドを削減するために、この変数を小さな値に変更してエクスチェンジノードの数を減らすことを試すことができます。Duplicate Keyテーブルを使用して集計クエリを実行する例があります。

parallel_fragment_exec_instance_num​

各BEでスキャンノードをスキャンするために使用するインスタンスの数を設定するために使用されます。デフォルト値は1です。

クエリプランは通常、複数のスキャンレンジを生成します。これらのデータは複数のBEノードに分散されます。各BEノードには1つ以上のスキャンレンジがあり、デフォルトでは、各BEノードのスキャンレンジのセットは1つの実行インスタンスによって処理されます。マシンリソースが十分な場合、