:oss_fdw を使用した外部データファイルの読み書き

oss_fdw パラメーター

oss_fdw プラグインは、他の外部データラッパー (FDW) インターフェイスと同様の方法を使用して、OSS に格納されている外部データをカプセル化します。 oss_fdw を使用して、OSS に保存されているデータを読み取ることができます。 このプロセスは、データテーブルの読み取りに似ています。 oss_fdw は、OSS でファイルデータに接続して解析するための一意のパラメーターを提供します。

CREATE SERVER パラメーター

• ossendpoint: ホストとも呼ばれる内部ネットワークを介して OSS にアクセスするために使用されるエンドポイント。
• id oss: OSS アカウントの ID。
• key oss: OSS アカウントのキー。
• bucket: OSS バケット。 このパラメーターを指定する前に、OSS アカウントを作成する必要があります。

次のフォールトトレランスパラメーターは、データのインポートとエクスポートに使用します。 ネットワーク接続が不十分な場合は、これらのパラメーターを調整して、インポートとエクスポートを成功させることができます。

• oss_connect_timeout: 接続タイムアウト期間を示します。 デフォルト値: 10。 単位: 秒。
• oss_dns_cache_timeout: DNS タイムアウト期間を示します。 デフォルト値: 60。 単位: 秒。
• oss_speed_limit: 最小データ転送速度を示します。 デフォルト値: 1。 単位: Kbit/s。
• oss_speed_time: データ転送速度が最小値より低い最大期間を示します。 デフォルト値: 15。 単位: 秒。

デフォルトのパラメーター値が使用されている場合に、15 秒間連続して伝送速度が 1 Kbit/秒 より低下すると、タイムアウトエラーが生じます。

CREATE FOREIGN TABLE パラメーター

• filepath: OSS のパスを含むファイル名。

  • ファイル名にパスが含まれますが、バケット名は含まれません。

  • このパラメーターは、OSS の対応するパスにある複数のファイルと一致します。 データベースに複数のファイルをロードすることができます。

  • filepath または filepath.x の形式で名前が付けられたファイルをデータベースにインポートします。 x の値は、1 から始まる連続した数値である必要があります。

    たとえば、filepath、filepath.1、filepath.2、filepath.3、filepath.5 という名前のファイルのうち、最初の 4 つのファイルが一致してインポートされます。 filepath.5 ファイルはインポートされません。

• dir: OSS の仮想ファイルディレクトリ。

  • ディレクトリはスラッシュ (/) で始める必要があります。

  • dir で示される仮想ディレクトリ内のすべてのファイル (サブフォルダとサブフォルダ内のファイルを除く) が照合され、データベースにインポートされます。

• prefix: データファイルに対応するパス名の接頭語。 接頭語は正規表現をサポートしていません。 prefix、filepath、および dir は相互に排他的であるため、一度に指定できるパラメーターは 1 つだけです。

• format: ファイル形式は csv のみが可能です。

• encoding: ファイルデータのエンコード形式。 UTF-8 などの一般的な PostgreSQL エンコーディングフォーマットがサポートされています。

• parse_errors: フォールトトレラントな解析モード。 解析プロセス中にエラーが生じた場合、データの行全体が無視されます。

• delimiter: 列の区切り文字。

• quote: ファイルの引用文字。

• escape: ファイルのエスケープ文字。

• null: 指定された文字列に一致する列を null に設定します。

• force_not_null: 列の値を null 以外の値に設定します。 たとえば、force_not_null 'id' は、'id' 列の値を空の文字列に設定するために使用されます。

• compressiontype: OSS で読み書きするファイルの形式を指定します。

  • none: 圧縮されていないテキストファイル。 これがデフォルト値です。
  • gzip: 読み取るファイルは gzip 圧縮されている必要があります。

• compressionlevel: OSS に書き込まれる圧縮形式の圧縮レベルを指定します。 有効値: 1～9。 デフォルト値: 6。

CREATE FOREIGN TABLE のエクスポートモードパラメーター

• oss_flush_block_size: 一度に OSS に書き込まれたデータのバッファーサイズ。 デフォルト値: 32 MB。 有効な値: 1～128 MB。

• oss_file_max_size: OSS に書き込まれるデータの最大ファイルサイズ (最大ファイルサイズを超えると、後続のデータは別のファイルに書き込まれます)。 デフォルト値 : 1024 MB。 有効な値: 8～4000 MB。

• num_parallel_worker: OSS データが書き込まれる並列圧縮スレッドの数。 有効値: 1～8。 デフォルト値: 3。

補助関数

FUNCTION oss_fdw_list_file (relname text, schema text DEFAULT 'public')

• 外部テーブルが一致する OSS ファイルの名前とサイズを取得します。

• ファイルサイズの単位はバイトです。

select * from oss_fdw_list_file('t_oss');
              name              |   size    
--------------------------------+-----------
 oss_test/test.gz.1  | 739698350
 oss_test/test.gz.2  | 739413041
 oss_test/test.gz.3  | 739562048
(3 rows)

補助機能

oss_fdw.rds_read_one_file: 読み取りモードでは、外部テーブルと一致するファイルを指定します。 ファイルが指定されている場合、外部テーブルは、データのインポート時にこのファイルとのみ一致します。

例: set oss_fdw.rds_read_one_file = 'oss_test/example16.csv.1';

set oss_fdw.rds_read_one_file = 'oss_test/test.gz.2';
select * from oss_fdw_list_file('t_oss');
              name              |   size    
--------------------------------+-----------
  oss_test/test.gz.2  | 739413041
(1 rows)

oss_fdw の例

# Create a plug-in
create extension oss_fdw; 
# Create a server 
CREATE SERVER ossserver FOREIGN DATA WRAPPER oss_fdw OPTIONS 
     (host 'oss-cn-hangzhou.aliyuncs.com', id 'xxx', key 'xxx', bucket 'mybucket');
# Create an OSS external table
CREATE FOREIGN TABLE ossexample 
    (date text, time text, open float,
     high float, low float, volume int) 
     SERVER ossserver 
     OPTIONS ( filepath 'osstest/example.csv', delimiter ',' ,
         format 'csv', encoding 'utf8', PARSE_ERRORS '100');
# Create a table to load data to
create table example
        (date text, time text, open float,
         high float, low float, volume int)
# Load data from ossexample to example.
insert into example select * from ossexample;
# Result
# oss_fdw estimates the file size in OSS and formulates a query plan correctly.
explain insert into example select * from ossexample;
                             QUERY PLAN                              
---------------------------------------------------------------------
 Insert on example (cost=0.00..1.60 rows=6 width=92)
   ->  Foreign Scan on ossexample (cost=0.00..1.60 rows=6 width=92)
         Foreign OssFile: osstest/example.csv.0
         Foreign OssFile Size: 728
(4 rows)
# Write the data in the example table to OSS.
insert into ossexample select * from example;
explain insert into ossexample select * from example;
                           QUERY PLAN
-----------------------------------------------------------------
 Insert on ossexample (cost=0.00..16.60 rows=660 width=92)
   ->  Seq Scan on example (cost=0.00..16.60 rows=660 width=92)
(2 rows)

oss_fdw の使用に関する考慮事項

• oss_fdw は、PostgreSQL の FOREIGN TABLE フレームワークに基づいて開発された外部テーブルプラグインです。

• データのインポート効率は、Oracle クラスターリソース (CPU、I/O、メモリ、MET) および OSS と互換性のある POLARDB の影響を受けます。

• データインポートのパフォーマンスを保証するには、Oracle と互換性のある POLARDB が OSS と同じリージョンにあることをご確認ください。 詳細については、「」「エンドポイント (Endpoints)」をご参照ください。

• 外部テーブルの SQL 文の読み取り中に "oss endpoint userendpoint not in aliyun white list" というエラーが報告された場合は、「」「リージョンとエンドポイント (Regions and endpoints)」にリストされているエンドポイントを使用してください。 問題が解決しない場合は、チケットを起票し、サポートセンターへお問い合わせください。

エラー処理

インポートまたはエクスポートエラーが生じた場合には、エラーログには次の情報が含まれています。

• code: 失敗したリクエストの HTTP ステータスコード。

• error_code: OSS から返されたエラーコード。

• error_msg: OSS から返されたエラーメッセージ。

• req_id: リクエストを識別する UUID。 問題を解決できない場合は、req_id を提供することで OSS 開発エンジニアに助けを求めることができます。

ログフィールドの詳細は、次の図をご参照ください。 タイムアウトエラーは oss_ext パラメーターを使用して処理します。

• OSS ヘルプ

• OSSエラー処理

• OSS エラー応答

ID とキーの暗号化

CREATE SERVER の id および key パラメーターが暗号化されていない場合は、select * from pg_foreign_server 文を実行すると、情報がプレーンテキストで表示されます。 ID とキーが公開されます。 対称暗号化を使用して、ID とキーを非表示にすることができます。 インスタンスごとに異なるキーを使用して、情報をさらに保護します。 ただし、以前のバージョンとの非互換性を回避するために、Greenplum で行うようにデータ型を追加しないでください。

暗号化された情報

postgres=# select * from pg_foreign_server ;
  srvname  | srvowner | srvfdw | srvtype | srvversion | srvacl |                                                                              srvoptions
-----------+----------+--------+---------+------------+--------+------------------------------------------------------------------------------------------------------------------------------------
----------------------------------
 ossserver |       10 |  16390 |         |            |        | {host=oss-cn-hangzhou-zmf.aliyuncs.com,id=MD5xxxxxxxx,key=MD5xxxxxxxx,bucket=067862}

暗号化された情報の前には、MD5 ハッシュ値が付きます。 全長を 8 で割った余りは 3 です。 そのため、エクスポートされたデータがインポートされるとき再び暗号化されません。 しかし、ユーザーは MD5 で始まるキーと ID を作成することはできません。