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

oss_fdw パラメーター

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

注

oss_fdw は、OSS で次のタイプのファイルを読み書きすることができます。TEXT ファイルと CSV ファイル、および gzip 圧縮された TEXT ファイルと CSV ファイルです。
各パラメーターの値は二重引用符 (")で囲む必要があり、不要なスペースを含めることはできません。

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。

注

OPTIONS パラメーターでファイルパスとディレクトリを指定する必要があります。
filepath または dir を指定する必要があります。
現在、エクスポートモードは仮想フォルダ、つまり、dir のみがサポートされています。

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 パラメーターを使用して処理します。

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 を作成することはできません。