Configuration parameters

目次

Configuration parameters#

このリファレンスガイドでは、 Postgres Analytics AcceleratorPGAA拡張機能が提供する構成パラメーターについて説明します。これにより、実行エンジンの調整、リモート接続の管理、およびデータレイク全体のクエリパフォーマンスの最適化ができます。

エグゼキューターエンジン#

pgaa.executor_engine#

分析操作の実行を担当するコンピューティングバックエンドを決定します。

サポートされている値はseafowl 、およびspark_connect です。

デフォルトはseafowl です。

pgaa.spark_connect_url#

Spark Connectサービスの接続エンドポイントを定義します。リモートSpark ConnectサービスのURLを指定します。 pgaa.executor_engine がspark_connect に設定されている場合、この設定は必須です。

値は、特定のSpark Connect URI形式sc://<host>:<port> に従う必要があります。

デフォルトはNULL です。

pgaa.spark_connect_extra_config#

pgaa.executor_engine= 'spark_connect' を使用する場合、詳細な調整パラメーターとランタイム設定をJSONオブジェクトとしてSparkセッションに直接提供します。オプションのリストについては、 Spark Connect configuration を参照してください。

例

SET pgaa.spark_connect_extra_config = {
    "spark.sql.execution.arrow.maxRecordsPerBatch": "65536"
};

デフォルトはNULL です。

クエリー動作#

pgaa.enable_direct_scan#

分析テーブルのクエリ実行戦略を制御します。 PGAAがクエリ全体を最適化されたSeafowlエンジンにオフロードしようとするか、標準のPostgres互換性レイヤーを使用して処理するかどうかを決定します。

デフォルトはon で、これは、PGAAがCompatScanにフェイルオーバーする前に、最初にDirectScanを試行することを意味します。

pgaa.direct_scan_fail_behavior#

ダイレクトスキャンが試行されたが、サポートされていないSQL機能または構文のために完了できなかった場合のシステムの反応を定義します。

サポートされている値は次のとおりです。

  • ignore システムはサイレントにCompatScanにフォールバックします。

  • warn デフォルト クエリは互換性フォールバックを使用して実行されますが、PostgresはDirectScanが失敗したことを示す警告通知を発行します。

  • error DirectScanを使用できない場合、クエリの実行は完全に中止されます。

DirectScanが要求されたが失敗した場合の動作、 ignore 、warn 、error のいずれか。デフォルトはwarn です。

pgaa.enable_join_pushdown#

CompatScanでは、分析テーブル間の結合操作の最適化戦略を制御します。結合をPostgres内でローカルに処理するか、リモート実行エンジンSeafowlまたはSparkにオフロードするかどうかを決定します。

デフォルトはon です。

pgaa.enable_groupby_pushdown#

CompatScanでは、集計操作SUM 、COUNT 、AVG 、GROUP BY などをリモート実行エンジンSeafowlまたはSparkにオフロードしようとします。

デフォルトはon です。

pgaa.ctas_intermediate_flush_size#

PGAA管理テーブルへの大規模なINSERT またはCREATE TABLE AS (CTAS) オペレーション中のバッチ動作を制御します。

デフォルト8192です。

pgaa.flush_task_interval_s#

PGAAバックグラウンドプロセスが永続ストレージへの分析データの保留中のフラッシュをチェックして実行する頻度を秒単位で指定します。

デフォルト5です。

pgaa.max_in_memory_mb#

ストレージへの強制的なフラッシュがトリガーされる前に、ライタがデータのバッファーに利用できるメモリの最大量をメガバイト単位で設定します。

デフォルトは3072MBです。

pgaa.scan_aggregation_cost_factor#

ローカルのPostgres実行と比較して、リモートバックエンドSparkまたはSeafowlで集計を実行するコストを重み付けるためにPostgresクエリプランナーが使用する乗数。

デフォルトは0.005です。

pgaa.scan_per_tuple_cost#

ローカルのPostgres実行と比較して、リモートバックエンドSparkまたはSeafowlで単一行タプルをスキャンするコストを重み付けるためにPostgresクエリプランナーが使用する乗数。

デフォルト0.02です。

pgaa.scan_startup_cost#

ローカルのPostgres実行と比較して、リモートバックエンドSparkまたはSeafowlでスキャンを開始する固定「スタートアップ」コストを重み付けるためにPostgresクエリプランナーが使用する乗数。

デフォルト25です。

pgaa.use_seafowl_cost_estimates#

Postgresクエリプランナーが、 Postgresによって内部収集された統計に依存するのではなく、Seafowlエンジンから直接リアルタイムのコスト推定を要求するかどうかを決定します。

デフォルトはon です。

pgaa.write_lock_timeout_s#

タイムアウトして操作を中止する前に、プロセスが書き込みロックの取得を待機する最大時間を秒単位で指定します。

デフォルト3です。

Seafowl#

pgaa.autostart_seafowl#

バックグラウンドワーカーによって管理されるSeafowlプロセスの自動開始を制御します。

デフォルトはon です。

pgaa.autostart_seafowl_max_memory_mb#

組み込みSeafowlエンジンが消費できるRAMの量の上限をメガバイト単位で設定し、分析エンジンがメインのPostgresプロセスのリソースを枯渇させないようにします。

デフォルトは2147483647です。

pgaa.autostart_seafowl_enable_metrics#

標準の可観測性スタックを使用して分析エンジンの状態、クエリスループット、およびリソース使用率をモニタするリアルタイムパフォーマンスメトリックを提供する専用のHTTPエンドポイントを開くことにより、SeafowlプロセスでPrometheusメトリックを有効にします。

デフォルト値はon です。

pgaa.autostart_seafowl_metrics_host#

メトリックエンドポイントのバインドホスト。

pgaa.autostart_seafowl_enable_metrics= on の場合、Prometheusメトリックサービスが到達可能なホスト名またはIPアドレスを指定します。

デフォルトは127.0.0.1 で、これはセキュリティのためのローカルループバックをポイントし、メトリックがデフォルトで公開されないことを保証します。

pgaa.autostart_seafowl_metrics_port#

pgaa.autostart_seafowl_enable_metrics= on のときにPrometheusメトリックサービスに使用される特定のネットワークポートを定義します。

サポートされている値の範囲は1024〜65535です。デフォルトは9090 です。

pgaa.autostart_seafowl_enable_object_store_cache#

S3、Azure、またはGCPの外部ストレージの場所のSeafowlオブジェクトストアキャッシュを有効にするかどうかを決定します。

デフォルトはon です。

pgaa.autostart_seafowl_log_level#

バックグラウンドSeafowlプロセスのロギングの詳細度を指定します。

サポートされている値には、error 、warn 、info 、debug 、およびtrace が含まれます。

デフォルトはinfo です。

pgaa.autostart_seafowl_path#

Seafowl実行可能ファイルへの絶対ファイルパスを指定します。これにより、バックグラウンド分析エンジンを起動するときにどのバイナリを起動するかをPGAAスーパーバイザに正確に指示します。このパラメーターの変更は、別のマシンまたはコンテナーでSeafowlサービスを実行しているカスタム構成の場合にのみ必要です。

デフォルトは空の文字列です。

pgaa.autostart_seafowl_port#

バックグラウンドSeafowlプロセスがリッスンするTCPポートを指定します。 PGAA拡張機能はこのポートを使用して、ローカル実行エンジンと通信します。

デフォルトは47470です。

pgaa.autostart_seafowl_tmp_dir#

クエリの実行中にバックグラウンドのSeafowlプロセスが一時ファイルを保存するディレクトリを指定します。

デフォルトは空の文字列です。

pgaa.enable_maintenance_worker#

PGAAバックグラウンドスーパーバイザが専用のメンテナンスワーカープロセスを起動および管理するかどうかを制御します。

デフォルトはoff です。

pgaa.maintenance_worker_sleep_interval#

現在実行する保留中の作業がない場合に、新しいタスクをチェックする前にメンテナンスワーカープロセスが待機する時間を秒単位で定義します。

デフォルトは30秒です。

pgaa.seafowl_client_retry_base_ms#

Seafowlプロセスへの失敗した要求を再試行する前にPostgresクライアントが待機する初期遅延をミリ秒単位で指定します。後続の障害が発生するたびに、待機時間は2倍になります。

デフォルト100です。

pgaa.seafowl_url#

PGAA拡張機能がSeafowlサービスと通信するために使用するエンドポイントURLを指定します。デフォルトでは、PGAAはデータベースと同じホストでSeafowlプロセスを自動的に管理します。このパラメーターの変更は、別のマシンまたはコンテナーでSeafowlサービスを実行しているカスタム構成の場合にのみ必要です。

デフォルトはhttp://localhost:47470 です。

カタログの同期#

pgaa.metastore_sync_poll_rate_s#

現在接続されているカタログの状態をポーリングする間隔を秒単位で設定します。これを0に設定すると、自動バックグラウンド同期が完全に無効になります。

デフォルトは60秒です。

pgaa.metastore_sync_stale_duration_s#

接続されたカタログのローカルメタデータが古いと考えられるしきい値を定義します。ローカルキャッシュのメタデータがこの期間よりも古い場合、システムは更新を優先してデータレイクとの一貫性を保証します。

デフォルトは60秒です。

pgaa.enable_metastore_sync_worker#

PGAAが専用のバックグラウンドワーカーを生成して、Iceberg RESTカタログなどのリモートプロバイダーからのメタデータを継続的に同期するかどうかを決定します。

デフォルトはoff です。

キャッシング#

pgaa.lakehouse_table_stats_cache_ttl_s#

pgaa.lakehouse_table_stats() ファンクションをサポートするために物理テーブルのサイズがキャッシュされる期間秒単位を制御します。これにより、メタデータのオブジェクトストアへの頻繁な要求が防止されます。これを0に設定すると、統計キャッシュが無効になり、ファンクションはストレージプロバイダーから直接データを取得します。

デフォルトは300秒です。

pgaa.autostart_seafowl_object_store_cache_capacity_mb#

Seafowlプロセスが保存場所からデータをキャッシュするために使用できるローカルディスク領域の最大量をメガバイト単位で指定します。

デフォルト1024です。

pgaa.autostart_seafowl_object_store_cache_min_fetch_size_kb#

pgaa.autostart_seafowl_enable_object_store_cache が有効になっているときにオブジェクトストアに送信されるアウトバウンド要求の最小サイズを定義します。

デフォルト1024です。

pgaa.autostart_seafowl_object_store_cache_ttl_s#

Seafowlオブジェクトストアキャッシュに保存されているオブジェクトのTime To LiveTTLを指定します。このパラメーターは、キャッシュされたデータチャンクがエビクションの対象となるまでに有効な時間を決定します。

デフォルト3600です。

Postgres DistributedPGD統合#

pgaa.max_replication_lag_s#

フラッシュが強制されるまでの最大許容遅延秒。

デフォルト5です。

pgaa.flush_task_interval_s#

システムがフラッシュ要件をチェックする頻度秒。

デフォルト5です。

DataFusionから継承された構成#

PGAAはSeafowlクエリエンジンの基になる実行エンジンとしてApache DataFusionを使用するため、 PGAAはクエリ実行エンジンを調整できる複数のpgaa.datafusion.* 構成パラメーターを提供します。

これらの設定は、メモリ管理、実行並列処理、オプティマイザールールなどの低レベルの動作を制御します。

次を実行して、PGAAが組み込むDataFusion構成パラメーターの完全なリストを確認できます。

SELECT name, setting, short_desc, context FROM pg_settings WHERE name LIKE %pgaa.data%;

キー、デフォルト値、およびパフォーマンスへの影響の包括的なリストについては、 DataFusion documentation を参照してください。 DataFusionドキュメントを参照する場合、pgaa. を接頭辞として付けることにより、ドキュメントキーをPGAA構成パラメーターに変換できます。

エグゼキューターエンジン#

pgaa.executor_engine#

分析操作の実行を担当するコンピューティングバックエンドを決定します。

サポートされている値はseafowl 、およびspark_connect です。

デフォルトはseafowl です。

pgaa.spark_connect_url#

Spark Connectサービスの接続エンドポイントを定義します。リモートSpark ConnectサービスのURLを指定します。 pgaa.executor_engine がspark_connect に設定されている場合、この設定は必須です。

値は、特定のSpark Connect URI形式sc://<host>:<port> に従う必要があります。

デフォルト値はNULL です。

pgaa.spark_connect_extra_config#

pgaa.executor_engine= 'spark_connect' を使用する場合、詳細な調整パラメーターとランタイム設定をJSONオブジェクトとしてSparkセッションに直接提供します。オプションのリストについては、 Spark Connect configuration を参照してください。

例

SET pgaa.spark_connect_extra_config = {
    "spark.sql.execution.arrow.maxRecordsPerBatch": "65536"
};

デフォルト値はNULL です。

クエリー動作#

pgaa.enable_direct_scan#

分析テーブルのクエリ実行戦略を制御します。 PGAAがクエリ全体を最適化されたSeafowlエンジンにオフロードしようとするか、標準のPostgreSQL互換性レイヤーを使用して処理するかどうかを決定します。

デフォルト値はon で、これは、PGAAがCompatScanにフェイルオーバーする前に、最初にDirectScanを試行することを意味します。

pgaa.direct_scan_fail_behavior#

ダイレクトスキャンが試行されたが、サポートされていないSQL機能または構文のために完了できなかった場合のシステムの反応を定義します。

サポートされている値は次のとおりです。

  • ignore デフォルト システムはサイレントにCompatScanにフォールバックします。

  • warn クエリーは互換性フォールバックを使用して実行されますが、PostgreSQLは、DirectScanが失敗したことを示す警告通知を発行します。

  • error DirectScanを使用できない場合、クエリの実行は完全に中止されます。

DirectScanが要求されたが失敗した場合の動作、 ignore 、warn 、error のいずれか。デフォルトはwarn です。

pgaa.enable_join_pushdown#

CompatScanでは、分析テーブル間の結合操作の最適化戦略を制御します。ジョインがPostgreSQL内でローカルに処理されるか、リモート実行エンジンSeafowlまたはSparkにオフロードされるかどうかを決定します。

デフォルト値はon です。

pgaa.enable_groupby_pushdown#

CompatScanでは、集計操作SUM 、COUNT 、AVG 、GROUP BY などをリモート実行エンジンSeafowlまたはSparkにオフロードしようとします。

デフォルト値はon です。

Seafowl#

pgaa.autostart_seafowl#

バックグラウンドワーカーによって管理されるSeafowlプロセスの自動開始を制御します。

デフォルト値はon です。

pgaa.autostart_seafowl_max_memory_mb#

組み込みSeafowlエンジンが消費できるRAMの量の上限をメガバイト単位で設定し、分析エンジンがメインのPostgreSQLプロセスのリソースを枯渇させないようにします。

デフォルト値は2147483647です。

pgaa.autostart_seafowl_enable_metrics#

標準の可観測性スタックを使用して分析エンジンの状態、クエリスループット、およびリソース使用率をモニタするリアルタイムパフォーマンスメトリックを提供する専用のHTTPエンドポイントを開くことにより、SeafowlプロセスでPrometheusメトリックを有効にします。

デフォルト値はon です。

pgaa.autostart_seafowl_metrics_host#

メトリックエンドポイントのバインドホスト。

pgaa.autostart_seafowl_enable_metrics= on の場合、Prometheusメトリックサービスが到達可能なホスト名またはIPアドレスを指定します。

デフォルト値は127.0.0.1 で、これはセキュリティのためのローカルループバックをポイントし、メトリックがデフォルトで公開されないことを保証します。

pgaa.autostart_seafowl_metrics_port#

pgaa.autostart_seafowl_enable_metrics= on のときにPrometheusメトリックサービスに使用される特定のネットワークポートを定義します。

サポートされている値の範囲は1024 〜65535 です。デフォルト値は9090 です。

カタログの同期#

pgaa.metastore_sync_poll_rate_s#

カタログの更新のために接続されている現在の状態をポーリングする間隔を秒単位で決定します。

接続されたカタログの状態をポーリングする間隔を秒単位で設定します。これを0に設定すると、自動バックグラウンド同期が完全に無効になります。

デフォルト値は60秒です。

pgaa.metastore_sync_stale_duration_s#

接続されたカタログのローカルメタデータが古いと考えられるしきい値を定義します。ローカルキャッシュのメタデータがこの期間よりも古い場合、システムは更新を優先してデータレイクとの一貫性を保証します。

デフォルト値は60秒です。

キャッシング#

pgaa.lakehouse_table_stats_cache_ttl_s#

テーブル統計ルックアップの結果がメモリに保持される時間を秒単位で制御します。クエリが計画されている場合、PostgreSQLはこれらの統計を必要にして、最も効率の高い実行パスを選択します。それらをキャッシュすることにより、システムは、すべてのクエリーに対してオブジェクトストアへの高遅延ネットワーク要求を行うことを回避します。これを0に設定すると、キャッシュ統計が完全に無効になります。

デフォルト値は300秒です。

DataFusionから継承された構成#

PGAAはSeafowlクエリエンジンの基になる実行エンジンとしてApache DataFusionを使用するため、 PGAAはクエリ実行エンジンを調整できる複数のpgaa.datafusion.* 構成パラメーターを提供します。

これらの設定は、メモリ管理、実行並列処理、オプティマイザールールなどの低レベルの動作を制御します。

次を実行して、PGAAが組み込むDataFusion構成パラメーターの完全なリストを確認できます。

SELECT name, setting, short_desc, context FROM pg_settings WHERE name LIKE %pgaa.data%;

キー、デフォルト値、およびパフォーマンスへの影響の包括的なリストについては、 DataFusion documentation を参照してください。 DataFusionドキュメントを参照する場合、pgaa. を接頭辞として付けることにより、ドキュメントキーをPGAA構成パラメーターに変換できます。

目次