Functions#

リファレンスセクションは、Analytics Acceleratorで使用可能な機能のリストです。

PGAAの保存場所を作成する方法の詳細については、

テーブルファンクション#

pgaa.list_analytics_tables()#

PGAAによって管理されているすべての分析テーブルのリストを返します。構成、ストレージ統計、現在のレプリケーションステータスを含みます。

概要

SELECT * FROM pgaa.list_analytics_tables();

パラメーター

なし。

Return

Column	Type	Description
nspoid	OID	テーブルを含む名前空間スキーマのOID。
reloid	OID	テーブルリレーションのOID。
schema_name	TEXT	Postgresスキーマの名前。
table_name	TEXT	分析テーブルの名前。
format	pgaa.table_format	保存形式`delta`、iceberg、または`parquet`。
object_storage_snapshot_size_bytes	BIGINT	オブジェクトストレージ内の最新のテーブルスナップショットのバイト単位のサイズ。
object_storage_total_size_bytes	BIGINT	オブジェクトストレージ内のこのテーブルのすべてのバージョン/ファイルのバイト単位の合計サイズ。
replication_status	pgaa.replication_status	データ移動の現在の状態 enabled、disabled、または`initial_offload` 。 PGD統合が必要です。
storage_location_name	TEXT	テーブルに関連付けられているPGFS格納場所の名前。
storage_location_path	TEXT	データが存在するストレージ場所内のパス。
catalog_name	TEXT	外部カタログの名前該当する場合。
catalog_namespace	TEXT	外部カタログ内の名前空間。
catalog_table	TEXT	外部カタログで定義されたテーブル名。

テーブルには、格納場所またはカタログを持つことができます。両方を持つことはできません。

カタログの詳細は、オブジェクトストレージへのカタログ管理オフロードまたはレプリケーションを実行する場合はレプリケーションターゲット、または Integrating with Iceberg catalogs の場合はソースカタログの場所を参照します。

pgaa.lakehouse_table_stats()#

特定の分析テーブルのストレージ統計を返します。最新のアクティブなスナップショットのサイズ、オブジェクトストレージに保存されているすべてのデータバージョン履歴データとログの合計累積サイズを含みます。

概要

SELECT * FROM pgaa.lakehouse_table_stats(table_name::regclass);

パラメーター

Parameter	Type	Description
relation	REGCLASS	調査する分析テーブルの名前またはOID。

Return

Column	Type	Description
latest_snapshot_size	BIGINT	テーブルの最新のアクティブなスナップショットのバイト単位のサイズ。
total_size	BIGINT	メタデータ、トランザクションログ、履歴スナップショットを含む、オブジェクトストレージのテーブルに関連付けられているすべてのファイルのバイト単位の合計サイズ。

pgaa.test_storage_location()#

定義された保存場所の接続と構成をテストし、読み取りまたは書き込み権限を確認します。

概要

SELECT pgaa.test_storage_location(location_name, test_writes);

パラメーター

Parameter	Type	Description
name	TEXT	テストする保存場所の名前。
test_writes	BOOLEAN	`true`の場合、ファンクションは書き込み操作を試行して権限を確認します。 `false`の場合、読み取りのみがテストされます。

Return

テストが成功した場合はNULL を返します。テストが失敗した場合、説明的なエラーメッセージを返します。

pgaa.pgaa_version()#

特定のビルドバージョン、ビルド日、Gitコミットハッシュを含むEDB Postgres Analytics Acceleratorのバージョン情報を返します。

pgaa.add_catalog#

SELECT pgaa.pgaa_version();

パラメーター

なし。

Return

現在のインストールの一意のGit識別子、セマンティックバージョン、ビルドタイムスタンプ、および一意のGit識別子を含む文字列。

カタログファンクション#

pgaa.add_catalog()#

新しいIcebergカタログをPGAAに登録します。この機能は、カタログがシステムに登録される前に、自動接続チェックを実行して、資格情報とアクセス可能性を検証します。

概要

SELECT pgaa.add_catalog(catalog_name, catalog_type, catalog_options::json);

パラメーター

Parameter	Type	Description
catalog_name	VARCHAR	PGAA内のカタログの一意の名前。
catalog_type	pgaa.catalog_type	カタログタイプ。サポートされている値は、iceberg-rest Iceberg RESTカタログ、および`iceberg-s3tables`AWS S3テーブルです。
catalog_options	JSON	接続パラメーターと認証パラメーターを含むJSONオブジェクト。

使用するストレージに応じて、catalog_options のJSONファイルは別のオプションを指定する必要があります。

RESTカタログの場合

{
"url": "https://your-catalog-endpoint.com",
"warehouse_name": "your_warehouse_name",
"warehouse": "your_warehouse_id",
"token": "your_secret_auth_token"
"danger_accept_invalid_certs": "false"
}

そこで

url RESTカタログサービスのベースHTTP(S)エンドポイント。 - warehouse_name ウェアハウスIDに代わる人間が判読可能な代替。構成を簡単にするために一部のRESTプロバイダーでサポートされています。 - warehouse カタログサービス内の特定のウェアハウスの一意の識別子。 - danger_accept_invalid_certs true に設定されている場合、PostgresはSSL証明書の検証をスキップします。これは、内部テストまたは自己署名証明書を使用する場合にのみ使用します。機密のパブリック接続には決して使用しないでください。

Snowflake Open Catalogのような一部のIceberg RESTカタログプロバイダーは、別のパラメーターを想定する場合があります。次のOAuthオプションを指定します。

{
"oauth2.grant_type": "client_credentials",
"oauth2.client_id": "oauth-client-id",
"oauth2.client_secret": "oauth-client-secret",
"oauth2.token_uri": "https://EXAMPLE-polaristest.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens",
"oauth2.scope": "PRINCIPAL_ROLE:read_only"
}

そこで

oauth2.grant_type OAuth2フローを指定します。サービス間通信の最も一般的な値はclient_credentials です。 - oauth2.client_id IDプロバイダーに登録されたアプリケーションの一意の識別子。 - oauth2.client_secret クライアントIDの認証に使用される秘密キー。 - oauth2.token_uri PGAAが資格情報を送信してアクセストークンを要求する完全なHTTP(S)エンドポイント。 - oauth2.scope オプショナルクライアントがアクセスを要求している権限またはリソースのスペース区切りリスト。
AWS S3テーブルの場合

{
"arn": "arn:aws:s3tables:us-east-1:1234567890:bucket/my-bucket",
"region": "us-east-1"
}

そこで

arn S3テーブルバケットの一意の識別子であるAmazonリソースネームARNを指定します。 - region S3テーブルバケットが存在するAWSデータセンターの物理的な場所を指定します。

Return

成功するとカタログの名前を返します。

pgaa.update_catalog()#

既存のIcebergカタログの構成オプションJSONオブジェクトを更新します。 pgaa.add_catalog() と同様に、このファンクションは検証チェックを実行して、変更を適用する前に新しい接続パラメーターが機能していることを確認します。

概要

SELECT * FROM pgaa.update_catalog(catalog_name, new_options::json);

パラメーター

Parameter	Type	Description
catalog_name	VARCHAR	PGAA内のカタログの一意の名前。
new_options	JSON	更新された接続パラメーターと認証パラメーターを含むJSONオブジェクト。

各カタログタイプに必要なJSONフィールドの詳細については、 pgaa.add_catalog() を参照してください。

Return

更新が成功すると、カタログの名前を返します。

例

OAuth2トークンをローテーションします。

SELECT * FROM pgaa.lakehouse.update_catalog(
    marketing_lakehouse,
    {
        "url": "https://iceberg.example.com",
        "oauth2.client_id": "pgaa_service_user",
        "oauth2.client_secret": "new_secure_secret_2026",
        "oauth2.token_uri": "https://auth.example.com/token"
    }::json
);

pgaa.delete_catalog()#

登録されたカタログをデータベースから削除します。偶発的なデータの損失を防ぐため、カタログで管理されているテーブルがまだ存在する場合、このファンクションではカスケードパラメーターを明示的にtrueに設定する必要があります。

概要

SELECT * FROM pgaa.delete_catalog(catalog_name, cascade := true);

パラメーター

Parameter	Type	Description
catalog_name	VARCHAR	削除するカタログの名前。
cascade	BOOLEAN	`true`の場合、PGAAは、カタログエントリを削除する前に、このカタログで管理されているすべてのローカルテーブル定義を自動的に削除します。デフォルトは`false`です。

Return

正常に完了すると、削除されたカタログの名前を返します。

pgaa.list_catalogs()#

システム内に登録されているすべてのカタログのリストを返します。接続構成、メタデータ同期タイムスタンプ、現在の動作ステータスを含みます。

概要

SELECT * FROM pgaa.list_catalogs();

パラメーター

なし。

Return

Column	Type	Description
name	TEXT	カタログの名前。
type	pgaa.catalog_type	カタログタイプ。サポートされている値は、iceberg-rest Iceberg RESTカタログ、および`iceberg-s3tables`AWS S3テーブルです。
options	JSON	このカタログに使用される接続パラメーターURL、ARNなど。
status	pgaa.catalog_status	カタログの現在のヘルス detached、attached、refresh_retry、または`refresh_failed` 。
created_at	TIMESTAMPTZ	カタログが最初に登録されたときのタイムスタンプ。
last_refreshed_at	TIMESTAMPTZ	PGAAが最後にこのカタログからメタデータを正常に同期した時間。

pgaa.import_catalog()#

ワンタイムスキャンを実行し、登録済みのIcebergカタログからPostgresにテーブル定義のインポートを実行します。このファンクションは、PGAAがリモートテーブルを照会するために必要なローカルメタデータを作成します。これは手動で1回限りのインポートであり、自動で継続的な同期は有効になりません。

概要

SELECT pgaa.import_catalog(catalog_name, namespace_filter);

パラメーター

Parameter	Type	Description
catalog_name	VARCHAR	インポートする以前に登録したカタログの名前。
namespace_filter	VARCHAR	指定した場合、この特定のIceberg名前空間内のテーブルのみがインポートされます。省略または`NULL`の場合、すべての名前空間のすべてのテーブルがインポートされます。デフォルトは`NULL`です。

Return

なし。

pgaa.attach_catalog()#

以前に登録したIcebergカタログの継続的なメタデータの同期を有効にします pgaa.add_catalog() を使用接続されると、PGAAはリモートカタログの変更を自動的に監視し、それに応じてローカルPostgresメタデータを更新します。ポーリングレート構成については、カタログの同期を参照してください。

概要

SELECT pgaa.attach_catalog(catalog_name);

パラメーター

Parameter	Type	Description
catalog_name	VARCHAR	同期を開始する登録済みカタログの名前。

Return

なし。

pgaa.detach_catalog()#

登録されたIcebergカタログの継続的なメタデータの同期を停止し、detached 状態に移動します。 cascade がtrue の場合、デタッチする前にカタログによって管理されているすべてのテーブルを削除します。 cascade がfalse の場合、テーブルはデータベースに残りますが、同期は停止します。

概要

SELECT * FROM pgaa.detach_catalog(catalog_name, cascade := true);

パラメーター

Parameter	Type	Description
catalog_name	VARCHAR	切り離す登録済みカタログの名前。
cascade	BOOLEAN	オプショナル。 `true`の場合、PGAAは、デタッチする前に、このカタログに関連付けられているすべてのローカルテーブル定義を自動的に削除します。デフォルトは`false`です。

Return

ファンクションは、デタッチされるカタログのpgaa.catalog システムテーブルから行を結果ます。

Column	Type	Description
name	TEXT	分離されたカタログの名前。
type	pgaa.catalog_type	カタログタイプ。
status	pgaa.catalog_status	新しいステータスは`detached`になります。

pgaa.test_catalog()#

登録されたIcebergカタログの接続と構成をテストします。このファンクションは、 Postgresインスタンスがリモートカタログエンドポイントと通信できることを確認し、オプションで提供された資格情報に書き込み権限があることを検証します。

概要

SELECT pgaa.test_catalog(catalog_name, test_writes:=true);

パラメーター

Parameter	Type	Description
name	TEXT	テストする登録済みカタログの名前。
text_writes	BOOLEAN	`true`の場合、ファンクションはカタログメタデータサービスへの書き込み操作を試行して、権限を確認します。 `false`の場合、読み取り権限のみがテストされます。

Return

テストが成功した場合はNULL を返します。テストが失敗した場合、説明的なエラーメッセージを返します。

pgaa.list_catalog_tables()#

登録されたIcebergカタログで使用可能なすべてのテーブルとビューのリストを返します。この機能を使用すると、最初にテーブルをローカルデータベースにインポートまたは接続することなく、リモートカタログのコンテンツを探索できます。

概要

SELECT * FROM pgaa.list_catalog_tables(catalog_name, namespace_filter);

パラメーター

Parameter	Type	Description
catalog_name	TEXT	探索する登録済みカタログの名前。
namespace_filter	TEXT	提供する場合、フィルターするIceberg名前空間スキーマを指定します。省略または`NULL`の場合、カタログ内のすべてのテーブルが返されます。デフォルトは`NULL`です。

Return

Column	Type	Description
schema_name	TEXT	リモートのIceberg名前空間/スキーマ。
table_name	TEXT	テーブルまたはビューの名前。

pgaa.drop_catalog_tables()#

特定のIcebergカタログによって管理されているすべてのローカルPostgresテーブルとビュー定義を削除します。cascade がtrue の場合、依存オブジェクトを含みます。リモートのIcebergカタログのテーブルには影響しません。

概要

SELECT * FROM pgaa.drop_catalog_tables(catalog_name, cascade := true);

パラメーター

Parameter	Type	Description
catalog_name	VARCHAR	管理テーブルが削除される登録済みカタログの名前。
cascade	BOOLEAN	`true`の場合、ファンクションはこれらのテーブルに依存するオブジェクトを自動的に削除します。デフォルトは`false`です。

Return

Column	Type	Description
schema_name	TEXT	テーブルが存在したローカルPostgresスキーマ。
table_name	TEXT	削除されたローカルテーブルの名前。

Sparkファンクション#

pgaa.spark_sql()#

構成済みのSpark Connectエンドポイントを介してPostgresクラスターでSpark SQLクエリーを直接実行します。これにより、Postgresで使用できないIceberg圧縮ルーチンまたはSparkファンクションを実行できます。

使用可能なプロシージャーのリストについては、 Spark procedures を参照してください。

このファンクションを実行するには、構成パラメーターpgaa.spark_connect_url を設定して、使用可能なSpark Connectサービスをポイントする必要があります。

概要

単一のカタログの場合

SELECT pgaa.spark_sql(query, catalog_name);

複数のカタログの場合

SELECT pgaa.spark_sql(query, ARRAY[catalog1, catalog2]);

パラメーター

Parameter	Type	Description
query	TEXT	実行するSpark SQLステートメント。
catalog	TEXT or TEXT[]	クエリーに使用する単一のカタログ名、またはカタログ名の配列。

Return

JSONオブジェクトとしてフォーマットされたSparkクエリの結果セット。

例

rewrite_data_files Sparkタスクを介してメタデータのオーバーヘッドを削減します。

SELECT pgaa.spark_sql($$
            CALL preexisting.system.rewrite_data_files(
              table => "preexisting"."ns-1"."table-1",
              strategy => sort,
              sort_order => value DESC,
              options => map(rewrite-all, true)
            )
        $$);

pgaa.execute_compaction()#

圧縮を実行して、分析Icebergテーブルのパフォーマンスとストレージ効率を向上させます。 pgaa.spark_connect_url 構成パラメーターを介してSpark Connectを構成する必要があります。

概要

SELECT pgaa.execute_compaction(table_name::regclass, settings::json);

パラメーター

Parameter	Type	Description
relation	REGCLASS	圧縮する分析テーブルの名前またはOID。
settings	JSON	現在サポートされていません。圧縮動作を定義するオプションのJSONオブジェクト。

注釈

パラメーター`settings` は現在サポートされていません。代わりに、 pgaa.spark_sql() を使用し、クラスターでSparkクエリを直接実行します。

Return

なし。

例

SELECT pgaa.execute_compaction(lakehouse.inventory_iceberg::regclass);

バックグラウンドタスクファンクション#

pgaa.launch_task()#

分析デルタテーブルのバックグラウンドメンテナンスタスクをスケジュールします。

概要

SELECT pgaa.launch_task(
    table_name::regclass,
    task_type,
    task_options::jsonb,
    scheduled_at::timestamp
);

パラメーター

Parameter	Type	Description
table_name	REGCLASS	タスクを実行する分析テーブルの名前またはOID。
task_type	TEXT	メンテナンスオペレーション compaction、zorder、vacuum、または`purge`。
task_options	JSONB	タスクタイプに固有の構成以下を参照してください。
scheduled_at	TIMESTAMP	指定された場合、タスクはこの時間まで待機して実行されます。デフォルトは`NULL`です。

JSONB task_options の値は、各task_type によって異なります。 columns を必要とするzorder と、 storage_location とpath の両方を必要とするpurge を除き、すべてのオプションはオプショナル。

compaction 小さなファイルを大きなファイルにマージして、分析スキャンを高速化します。使用可能なtask_options は次のとおりです。

{
"target_size": 536870912,
"preserve_insertion_order": true,
"max_concurrent_tasks": 10,
"max_spill_size": 2147483648,
"min_commit_interval": 60
}

そこで

target_size 出力ファイルのサイズをバイト単位で指定します。 - preserve_insertion_order 行の既存のソート順を維持するかどうか。 - max_concurrent_tasks エグゼキューターが実行できる並列タスクの数を制限します。 - max_spill_size プロセス中にディスクに流出できる最大データサイズをバイト単位で設定します。 - min_commit_interval デルタログの更新をコミットするまでの最小待機時間を秒単位で設定します。
zorder 複数の列にわたってデータを再編成して、これらの列にフィルターを使用したクエリの「データスキップ」を向上させるクラスタリング手法。使用可能なtask_options は次のとおりです。

{
"columns": ["customer_id", "transaction_date"],
"target_size": 1073741824,
"preserve_insertion_order": false,
"max_concurrent_tasks": 4,
"max_spill_size": 2147483648,
"min_commit_interval": 30
}

そこで

columns 必須 Zオーダーに使用される列を表す文字列の配列。 - target_size 出力ファイルのサイズをバイト単位で指定します。 - preserve_insertion_order 行の既存のソート順を維持するかどうか。 - max_concurrent_tasks エグゼキューターが実行できる並列タスクの数を制限します。 - max_spill_size プロセス中にディスクに流出できる最大データサイズをバイト単位で設定します。 - min_commit_interval デルタログの更新をコミットするまでの最小待機時間を秒単位で設定します。
vacuum デルタトランザクションログによって参照されなくなった古いデータファイルを削除し、オブジェクトストレージの領域を解放します。使用可能なtask_options は次のとおりです。

{
"retention_period": "168 hours",
"dry_run": false,
"enforce_retention_duration": true
}

そこで

retention_period 参照されていないファイルが削除の対象となる年齢を定義します。 - dry_run true の場合、削除されるファイルを計算およびログに記録しますが、削除は実行しません。 - enforce_retention_duration true の場合、タスクはシステムのグローバル最小安全制限に対してretention_period を検証します。
purge 特定のストレージパスからデータを明示的に削除します。使用可能なtask_options は次のとおりです。

{
"storage_location": "s3_main",
"path": "archive/2023/temp/"
}

そこで

storage_location 必須。保存場所の名前。 - path 完全に削除する必要がある保存場所内の相対ディレクトリパスまたはファイル接頭辞。

Return

タスクの一意のタスクID。

pgaa.background_task テーブルと提供されたタスクIDを照会することにより、タスクのステータスを確認できます。

例

過去7日間より前の古いデータファイルを削除します。

SELECT pgaa.launch_task(
    sales.transactions,
    vacuum,
    {"retention_period": "7 days", "dry_run": false}::jsonb
);

圧縮を実行します

SELECT pgaa.launch_task(
    telemetry.logs,
    compaction,
    {
        "target_size": 536870912,
        "max_concurrent_tasks": 2
    }::jsonb
);

列region およびcustomer_id でクラスタリングすることによりデータ行を再編成します。

SELECT pgaa.launch_task(
    crm.customers,
    zorder,
    {
        "columns": ["region", "customer_id"],
        "target_size": 1073741824
    }::jsonb
);

pgaa.execute_compaction()#

圧縮を実行して、分析Icebergテーブルのパフォーマンスとストレージ効率を向上させます。詳細は、 Sparkファンクションを参照してください。

Functions

目次

Functions#

テーブルファンクション#

pgaa.list_analytics_tables()#

pgaa.lakehouse_table_stats()#

pgaa.test_storage_location()#

pgaa.pgaa_version()#

pgaa.add_catalog#

カタログファンクション#

pgaa.add_catalog()#

pgaa.update_catalog()#

pgaa.delete_catalog()#

pgaa.list_catalogs()#

pgaa.import_catalog()#

pgaa.attach_catalog()#

pgaa.detach_catalog()#

pgaa.test_catalog()#

pgaa.list_catalog_tables()#

pgaa.drop_catalog_tables()#

Sparkファンクション#

pgaa.spark_sql()#

pgaa.execute_compaction()#

バックグラウンドタスクファンクション#

pgaa.launch_task()#

pgaa.execute_compaction()#