MaxFrame フラグ設定ガイド - MaxCompute - Alibaba Cloud ドキュメントセンター

このドキュメントでは、MaxCompute のフラグ、実行時フラグ、および MaxFrame の実行時パラメーターについて説明します。詳細な設定例を示し、それぞれの意味、デフォルト値、有効値、一般的なシナリオ、推奨設定について解説します。

MaxFrame パラメーターの例

MaxCompute SQL フラグ

MaxFrame では、すべての MaxCompute SQL 関連のフラグは options.sql.settings ディクショナリで管理されます。

from maxframe import options

options.sql.settings = {
  # 例：ジョブの最大実行時間を 72 時間に設定します。
  "odps.sql.job.max.time.hours": 72,
  # 例：ジョブにカスタムイメージを指定します。
  "odps.session.image": "common",
  # 例：すべての入力テーブルの同時実行性を 50000 に設定します。
  "odps.sql.split.dop": '{"*":50000}',
  # 例：データ処理のバッチサイズを 1024 行に設定します。
  "odps.sql.executionengine.batch.rowcount": 1024,
}

MaxFrame オプション

MaxFrame の実行時パラメーターは、options.xxx 形式を使用して直接設定します。次のコードに例を示します。

from maxframe import options

# 例：LogView リンクの保存期間を 24 時間に設定します。
options.session.logview_hours = 24

# 例：リトライ可能なエラーが発生した場合のクライアントのリトライ回数を設定します。
options.retry_times = 3

# 例：MaxCompute の組み込みクエリ最適化機能を有効にします。
options.sql.enable_mcqa = True

MaxCompute フラグ

次の表に、options.sql.settings ディクショナリの一般的なフラグを示します。

パラメーターカテゴリ	パラメーター	目的	有効値の範囲とデフォルト値	推奨事項
同時実行性とチャンキング	`odps.sql.split.dop`	カラムストア統計情報 (CMF) を使用して、テーブルごとにデータ読み取りの並列処理の次数 (DOP) を設定します。このパラメーターは `split.size` よりも優先度が高いです。このパラメーターは、{table_name: value} の形式のディクショナリを使用して設定します。特定のテーブルを対象にするには、その完全修飾名 `project.[schema.]table` を使用します。すべてのテーブルのチャンキングを指定するには、`{"":50000}` のように、マッチングにアスタリスク () を使用します。	範囲：1～99999。デフォルト：なし。	大きなテーブルを処理したり、大規模なタスクを実行したりする場合は、このパラメーターを明示的に有効にして、高い同時実行性を実現します。
同時実行性とチャンキング	`odps.stage.mapper.split.size`	CMF 情報が利用できない場合、システムは入力テーブルのサイズ (MB) に基づいてタスクをチャンキングします。	範囲：≥ 1。デフォルト：256 MB。	デフォルト値を維持します。
リソースとメモリ	`odps.stage.mapper.mem/reducer.mem/joiner.mem`	それぞれマッパー、レデューサー、ジョイナーの各ステージで、単一のワーカーにメモリ (MB) を割り当てます。	範囲：1024 MB～12288 MB。デフォルト：1024 MB。	大量のデータを処理する場合、データホットスポットが発生した場合、または複雑な結合によってメモリ不足 (OOM) エラーが発生した場合は、この値を増やしてください。
リソースとメモリ	`odps.stage.reducer.num / odps.stage.joiner.num`	Reduce ステージと Join ステージの同時実行インスタンス数を手動で設定します。	最大：10000。デフォルト：システムによって動的に計算されます。	ジョブに `GROUP BY` や `JOIN` などの大規模なシャッフルが含まれる場合や、データスキューがある場合は、この値を増やして計算負荷を分散させます。
シャッフルと出力の安全性	`odps.sql.runtime.flag.fuxi_streamline_x_EnableNormalCheckpoint` & `fuxi_ShuffleService_client_CheckpointMaxCopy`	マッパーによって出力される中間データのバックアップを有効にし、レプリカ数を設定します。		大規模なシャッフルを伴う長時間実行ジョブの場合、レプリカ数を 2 に設定します。 `2 ("fuxi_ShuffleService_client_CheckpointMaxCopy": 2)` これにより、フォールトトレランスとデータ読み取りの安定性が大幅に向上します。
シャッフルと出力の安全性	`odps.sql.sys.flag.fuxi_JobMaxInternalFolderSize`	単一のジョブが生成できる中間シャッフルデータの最大合計サイズ (MB) を設定します。		非常に大きなテーブルでシャッフル操作を実行する際に `Internal data size exceeds limit` エラーが発生した場合は、この値を増やしてください。
計算の安定性と監視	`odps.sql.runtime.flag.fuxi_EnableInstanceMonitor` & `fuxi_InstanceMonitorTimeout`	これら 2 つのパラメーターは一緒に使用する必要があります。基盤となる Fuxi スケジューラのハートビート監視を有効にし、タイムアウト期間 (秒) を設定します。これにより、システムが長時間実行されている UDF を応答なしと誤って判断し、終了させてしまうのを防ぎます。		`fuxi_InstanceMonitorTimeout` を変更するには、テクニカルサポートに連絡してホワイトリストへの追加を依頼してください。
	`odps.job.instance.retry.times`	マシンの故障など一時的なエラーで単一のワーカー (インスタンス) が失敗した後、システムが自動的にリトライする最大回数です。	デフォルト：3。推奨最大値：100。	デフォルトより高い値を設定するには、テクニカルサポートに連絡してパラメーターをホワイトリストに追加するよう依頼してください。
	`odps.dag2.compound.config`	基盤となるワーカーの再利用ポリシーを設定します。`fuxi.worker.reuse.policy:NO_REUSE` に設定すると、ワーカーの再利用が無効になります。		UDF にメモリリークや状態汚染のリスクがある場合は、再利用を無効にして、各タスクがクリーンな環境で実行されるようにします。これにより、タスクの起動オーバーヘッドがわずかに増加します。
実行効率と最適化	`odps.sql.executionengine.batch.rowcount`	MaxCompute の内部データ処理の基本単位であるバッチのサイズを行数で設定します。	1024	この値は、メモリとパフォーマンスのバランスを取ります。単一の行に大量のデータが含まれており、OOM エラーが発生する場合は、この値を減らしてください。計算が単純な場合は、この値を増やしてスループットを向上させることができます。
	`odps.sql.runtime.flag.executionengine_EnableVectorizedExpr`	式のベクトル化実行エンジンを有効にします。これにより、計算集約型の操作のパフォーマンスが大幅に向上する可能性があります。		rand() 関数を使用する場合や、多くの算術演算を実行する場合は、このパラメーターを有効にしてください。
	`odps.optimizer.enable.conditional.mapjoin` & `odps.optimizer.cbo.rule.filter.black`	これら 2 つのパラメーターを一緒に使用して、HashJoin を無効にします。		cbo.rule.filter.black を "hj" に設定します。これはエキスパート向けのオプションです。実行計画への影響を完全に理解していない限り、設定しないでください。
	`odps.sql.split.cluster.parallel_explore`	タスク分割ステージ中に CMF 情報を同時に読み取ります。		ジョブの分割ステージに時間がかかりすぎる場合は、このオプションを有効にしてください。
	`odps.sql.jobmaster.memory`	ジョブの Master ノードのメモリサイズを設定します。		非常に大きなテーブルを含むシャッフルジョブを実行する場合は、この値を増やしてください。たとえば、30000 MB に設定します。
UDF と関数の安全性	`odps.sql.udf.timeout` & `odps.function.timeout`	UDF または関数でデータバッチが実行されるタイムアウト期間 (秒) を制御します。	範囲：1～3600 秒。デフォルト：1800 秒。0 に設定しても効果はありません。
UDF と関数の安全性	`odps.sql.runtime.flag.executionengine_PythonStdoutMaxsize`	Python UDF の print 文によって stdout に出力されるログの最大長 (MB) を制限します。	最大：100 MB。デフォルト：20 MB。	この値を変更するには、テクニカルサポートに連絡してホワイトリストへの追加を依頼してください。
リソースと環境の依存関係	`odps.session.image`	ジョブの実行環境を指定します。値は、現在のテナントの MaxCompute プロジェクトに存在するカスタムイメージの名前である必要があります。
	`odps.task.major.version`	機能と動作の安定性を確保するために、ジョブを MaxCompute の特定のメジャーバージョンにロックします。		これはエキスパート向けのオプションです。その影響を理解していない限り、設定しないでください。
	`odps.storage.orc.row.group.stride` & `odps.storage.meta.file.version`	それぞれ ORC ファイルの行グループサイズと CMF メタデータファイルのバージョンを制御します。		これらはエキスパート向けのオプションです。基盤となるメカニズムを理解していない限り、設定しないでください。
その他の一般的なパラメーター	`odps.sql.allow.fullscan`	パーティションフィルター条件なしでパーティションテーブルの全表スキャンを許可するかどうかを指定します。		予期せぬ高コストや長時間の実行を防ぐため、このオプションは注意して有効にしてください。
	`odps.sql.cfile2.field.maxsize`	単一のフィールド (列) に許容される最大ストレージサイズ (バイト単位) を定義します。	デフォルト：8388608 (8 MB)。最大：268435456 (256 MB)。	長いテキスト、HTML、Base64 エンコードデータなど、非常に大きなコンテンツを含むフィールドを処理する場合は、この値を増やしてください。
	`odps.sql.job.max.time.hours`	SQL ジョブ全体の最大実行時間を時間単位で設定します。	最大：72 時間。デフォルト：24 時間。
	`odps.sql.always.commit.result` & `odps.sql.runtime.flag.executionengine_EnableWorkerCommit`	これら 2 つのパラメーターを一緒に使用して、部分的コミット機能を有効にします。一部のデータ処理が失敗してジョブが失敗した場合でも、成功した結果はコミットされます。		これは、部分的な成功が許容される抽出、変換、ロード (ETL) シナリオに適しています。
テーブル書き込みと CMF (固定の組み合わせ)	`{ "odps.task.merge.enabled": "false", "odps.sql.reshuffle.dynamicpt": "false", "odps.sql.enable.dynaparts.stats.collection": "true", "odps.optimizer.dynamic.partition.is.first.nth.value.split.enable": "false", "odps.sql.stats.collection.aggressive": "true", }`			これはフラグの固定の組み合わせです。動的パーティションテーブルにデータを書き込む際に、カラムストア統計情報 (CMF) が迅速かつ正確に生成されることを保証します。これは、後続のジョブが odps.sql.split.dop を使用してデータを正確に分割するために不可欠です。

MaxFrame オプション

次の表に、MaxFrame の主な組み込みオプションを示します。これらのオプションは、options.xxx 形式を使用して直接設定できます。

パラメーター名	目的	タイプ	デフォルト値
`options.local_timezone`	ローカルタイムゾーンを設定します。これは、日時関数のデフォルトの動作に影響します。	STR/None	None
`options.session.logview_hours`	生成された LogView リンクの保存期間を時間単位で設定します。	INT	24
`options.sql.enable_mcqa`	MaxCompute の組み込みのインテリジェントなクエリ最適化および高速化機能を有効にするかどうかを指定します。	BOOL	TRUE
`options.sql.generate_comments`	トレーサビリティのために、生成された SQL 文にコメントを自動的に追加するかどうかを指定します。	BOOL	TRUE
`options.sql.auto_use_common_image`	システムが追加の依存関係を持つライブラリをコードが使用していることを検出した場合に、共通のパブリックイメージを自動的に設定するかどうかを指定します。	BOOL	TRUE
`options.session.max_alive_seconds` `options.session.max_idle_seconds`	セッションのライフサイクルを制御します。 `max_alive_seconds` はセッションの最大生存時間です。 `max_idle_seconds` はセッションに許容される最大アイドル時間です。このアイドル時間を超えると、セッションは取り消されます。 `max_idle_seconds` の値は `max_alive_seconds` の値以下である必要があります。
`options.session.temp_table_lifecycle`	MaxFrame を使用して作成された一時テーブルのデフォルトのライフサイクル (日数) を設定します。	INT	1
`options.session.auto_purge_temp_tables`	セッション終了時に、現在のセッションで作成されたすべての一時テーブルを自動的にクリーンアップするかどうかを指定します。	BOOL	FALSE
`options.function.default_running_options`	`@remote` デコレーターで登録された関数のデフォルトのリソース構成を設定します。	dict。キーには `cpu`、`memory`、`gpu` を含めることができます。

重要

多くの特殊なフラグの使用には、ホワイトリストへのリクエスト、カスタムイメージの管理、CMF 統計情報への依存など、前提条件があります。これらの高度なオプションを設定する前に、MaxCompute のテクニカルサポートチームに連絡し、設定が正しく効果的であることを確認してください。