コードによる MaxCompute MaxFrame とランタイムフラグの制御 - MaxCompute

このドキュメントでは、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 文によって標準出力に出力されるログの最大長を 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.session.quota_name`	ジョブ実行に使用するクォータを指定します。	str/None	None
`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` を含めることができます。
`options.dpe.settings = {"substep.public_network_whitelist": ["xxxxxx"]}`	DPE エンジンに UDF のパブリックネットワークアクセスホワイトリスト構成を追加します。
`options.dpe.settings = { "substep.internal_network_whitelist": ["xxxxx"]}`	DPE エンジンに UDF の内部ネットワークアクセスホワイトリスト構成を追加します。

重要

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