AnalyticDB for PostgreSQLでは、OSS外部テーブル (gpossext) 機能を使用して、Object Storage Service (OSS) からAnalyticDB for PostgreSQLにデータを並行してインポートできます。
gpossextの概要
gpossextは、ファイルがGZIPパッケージで圧縮されているかどうかに関係なく、TEXTおよびCSVファイルからデータを読み書きできます。
次の図は、gpossextアーキテクチャを示しています。
テキストとCSV形式
次のパラメーターは、OSSから読み書きされるファイルの形式を指定します。 外部テーブルのDDLパラメーターでパラメーターを指定できます。
\n: TEXTまたはCSVファイルの行区切り文字として使用される文字。DELIMITER: 列の区切り文字。
DELIMITERパラメーターを指定する場合は、QUOTEパラメーターも指定する必要があります。
推奨される列区切り文字には、コンマ (
,) 、縦棒 (|) 、および\tなどの特殊文字が含まれます。
QUOTE: 特殊文字を含むユーザーデータの各列を囲みます。
特殊文字を含む文字列は、ユーザーデータとコントロール文字を区別するためにQUOTE文字で囲む必要があります。
効率を向上させるために、整数などのデータをQUOTE文字で囲まないことをお勧めします。
QUOTE文字はDELIMITERで指定した文字と同じにすることはできません。 QUOTEのデフォルト値は、二重引用符 ("") のペアです。
QUOTE文字を含むユーザーデータには、ユーザーデータとマシンコードを区別するためにESCAPE文字も含める必要があります。
ESCAPE: エスケープ文字。
エスケープする必要がある特殊文字の前にエスケープ文字を配置して、特殊文字ではないことを示します。
ESCAPEのデフォルト値はQUOTEのデフォルト値と同じです。
バックスラッシュ (
\) などの他の文字をESCAPE文字として使用することもできます。
表 1 TEXTおよびCSVファイルのデフォルトのコントロール文字
コントロール文字 | テキスト | CSV |
DELIMITER | \t (タブ) | , (コンマ) |
QUOTE | "(二重引用符) | "(二重引用符) |
ESCAPE | 非該当 | "(二重引用符) |
NULL | \N (バックスラッシュn) | 引用符なしの空の文字列 |
制御文字はすべて半角文字でなければなりません。
使用上の注意
外部テーブルの作成と使用に使用される構文は、場所関連のパラメーターの構文を除いて、Greenplum Databaseの構文と同じです。
データのインポートとエクスポートのパフォーマンスは、AnalyticDB for PostgreSQLインスタンスのOSSパフォーマンスとリソース (CPU、I/O、メモリ、ネットワークリソースなど) によって異なります。 インポートとエクスポートのパフォーマンスを最大化するには、テーブルの作成時に列指向のストレージと圧縮を使用することをお勧めします。 たとえば、次の句を指定できます。
"WITH (APPENDONLY=true, ORIENTATION=column, COMPRESSTYPE=zlib, COMPRESSLEVEL=5, BLOCKSIZE=1048576)"詳細については、「CREATE TABLE」をご参照ください。インポートとエクスポートのパフォーマンスを確保するには、OSSバケットとAnalyticDB for PostgreSQLインスタンスが同じリージョンにある必要があります。
手順
OSS外部テーブル拡張機能を作成します。
OSS外部テーブルを使用する前に、まずAnalyticDB for PostgreSQLでOSS外部テーブル拡張機能を作成する必要があります。 アクセスするデータベースごとに拡張機能を作成します。 次のステートメントを実行して、拡張子を作成します。
CREATE EXTENSION IF NOT EXISTS oss_ext;AnalyticDB for PostgreSQLにインポートするデータを、OSSの複数のオブジェクトに均等に配布します。 詳細については、「OSS外部テーブルの概要」をご参照ください。
説明AnalyticDB for PostgreSQLの各データパーティション (計算ノード) は、ポーリングメカニズムを使用してOSSオブジェクトを並列に読み取ります。 読み取り効率を向上させるために、並行して読み取ることができるオブジェクトの数を、計算ノードの数の整数倍に設定することを推奨します。
読み取り可能な外部テーブルを作成します。AnalyticDB for PostgreSQL.
次のステートメントを実行して、OSS外部テーブルを作成します。
CREATE [READABLE] EXTERNAL TABLE tablename ( columnname datatype [, ...] | LIKE othertable ) LOCATION ('ossprotocol') FORMAT 'TEXT' [( [HEADER] [DELIMITER [AS] 'delimiter' | 'OFF'] [NULL [AS] 'null string'] [ESCAPE [AS] 'escape' | 'OFF'] [NEWLINE [ AS ] 'LF' | 'CR' | 'CRLF'] [FILL MISSING FIELDS] )] | 'CSV' [( [HEADER] [QUOTE [AS] 'quote'] [DELIMITER [AS] 'delimiter'] [NULL [AS] 'null string'] [FORCE NOT NULL column [, ...]] [ESCAPE [AS] 'escape'] [NEWLINE [ AS ] 'LF' | 'CR' | 'CRLF'] [FILL MISSING FIELDS] )] [ ENCODING 'encoding' ] [ [LOG ERRORS [INTO error_table]] SEGMENT REJECT LIMIT count [ROWS | PERCENT] ] ossprotocol: oss://oss_endpoint [prefix=prefix_name|dir=[folder/[folder/]...]/file_name|filepath=[folder/[folder/]...]/file_name] id=userossid key=userosskey bucket=ossbucket compressiontype=[none|gzip] async=[true|false]下表に、各パラメーターを説明します。
パラメーター
説明
フォーマット
サポートされているファイル形式 (TEXTやCSVなど) 。
エンコーディング
UTF-8など、オブジェクト内のデータをエンコードするために使用される形式。
ログエラー
インポートに失敗したデータを無視し、error_tableに書き込みます。 countパラメーターを使用して、エラー耐性のしきい値を指定できます。
説明LOG ERRORSステートメントを使用して、内部ファイルへのインポートに失敗した行に関する情報を記録できます。LOG ERRORS SEGMENT REJECT LIMIT 5;gp_read_error_log('external_table_name ')関数を使用して、インポートに失敗した行に関する情報を取得できます。SELECT * FROM gp_read_error_log('external_table_name');外部テーブルを削除すると、内部ファイルも削除されます。
gp_truncate_error_log('external_table_name ')関数を使用して、内部ファイルを削除することもできます。SELECT gp_truncate_error_log('external_table_name');
oss:// oss_endpoint
プロトコル名: // OSS_endpoint形式のossのエンドポイントURL。 ossはプロトコル名、oss_endpointはリージョン内のOSSへのアクセスに使用されるドメイン名です。 例：oss://oss-cn-hangzhou.aliyuncs.com重要Alibaba CloudサーバーからAnalyticDB for PostgreSQLインスタンスにアクセスする場合は、インターネットトラフィックの生成を回避するために内部エンドポイントを使用します。 内部エンドポイントには、
internalキーワードが含まれます。id
Alibaba CloudアカウントのAccessKey ID。 AccessKeyペアの取得方法については、「AccessKeyペアの作成」をご参照ください。
キー
Alibaba CloudアカウントのAccessKeyシークレット。 AccessKeyペアの取得方法については、「AccessKeyペアの作成」をご参照ください。
バケット
オブジェクトが保存されているバケット。 データをインポートする前に、OSSバケットを作成する必要があります。
プレフィックス
OSSオブジェクトパスのプレフィックス。 正規表現はサポートされていません。
説明設定できるパラメーターは、dir、filepath、prefixのいずれかだけです。
読み取り可能な外部テーブルをデータインポートに使用すると、パスにプレフィックスが含まれるすべてのOSSオブジェクトのデータがインポートされます。
prefixパラメーターをtest/filenameに設定すると、次のオブジェクトがインポートされます。
test/filename
test/filenamexxx
test/filename/aa
test/filenameyyy/aa
test/filenameyyy/bb/aa
prefixパラメーターをtest/filename /に設定すると、前述のオブジェクトのうち次のオブジェクトのみがインポートされます。
test/filename/aa
dir
データオブジェクトを格納するOSSディレクトリ。
説明設定できるパラメーターは、prefix、filepath、dirのいずれかだけです。
ディレクトリのパスはスラッシュ (
/) で終わる必要があります。 例:test/mydir/データをインポートする外部テーブルを作成するときにこのパラメーターを設定すると、サブディレクトリとサブディレクトリ内のオブジェクトを除く、ディレクトリ内のすべてのオブジェクトがインポートされます。 dirパラメーターはfilepathパラメーターとは異なり、ディレクトリ内のオブジェクトの名前を指定する必要はありません。
ファイルパス
OSSオブジェクトパスを含むオブジェクト名。
説明設定できるパラメーターは、prefix、dir、filepathのいずれかだけです。
このパラメーターは、読み取り可能な外部テーブルを作成する場合にのみ設定できます。 このパラメーターは、データをインポートするときにのみ使用できます。
compressiontype
インポートしたファイルの圧縮形式。 有効な値：
none (デフォルト): ファイルは圧縮されていません。
gzip: ファイルはGZIP形式で圧縮されています。
説明GZIP形式のみがサポートされています。
compressionlevel
OSSに書き込まれるファイルの圧縮レベル。 有効値: 1～9。 デフォルト値: 6。
compressionlevel=6oss_connect_timeout
接続タイムアウト期間。 デフォルト値は 10 です。 単位は秒です。
oss_dns_cache_timeout
DNS解決のタイムアウト期間。 デフォルト値: 60。 単位は秒です。
oss_speed_limit
1秒あたりに送信されるデータの最小量。 1秒あたりに送信されるデータ量が、特定の期間に指定された値よりも少ない場合、タイムアウトがトリガーされます。 単位はバイトです。 デフォルト値: 1024。 1024バイトは1 KBに等しい。
このパラメーターを設定する場合は、oss_speed_timeパラメーターも設定する必要があります。
説明oss_speed_limitおよびoss_speed_timeパラメーターにデフォルト値が使用されているときに、15秒間連続で伝送速度が1 KB/sより低い場合、タイムアウトが発生します。 詳細については、次をご参照ください： エラー処理
oss_speed_time
最小伝送速度を許容することができる最大期間。 送信レートが指定された期間の間指定された値より低い場合、タイムアウトがトリガーされます。 デフォルト値: 15。 単位は秒です。
このパラメーターを設定する場合は、oss_speed_limitパラメーターも設定する必要があります。
説明oss_speed_limitおよびoss_speed_timeパラメーターにデフォルト値が使用されているときに、15秒間連続で伝送速度が1 KB/sより低い場合、タイムアウトが発生します。 詳細については、次をご参照ください： エラー処理
非同期
非同期データのインポートを有効にするかどうかを指定します。
補助スレッドを有効にして、OSSからのデータインポートを高速化できます。
デフォルトでは、非同期データインポートが有効になっています。 非同期データのインポートを無効にするには、asyncパラメーターを
falseまたはfに設定します。非同期データインポートは、通常のデータインポートよりも多くのハードウェアリソースを消費します。
データを並列にインポートします。
AnalyticDB for PostgreSQLで次のステートメントを実行して、OSSからAnalyticDB for PostgreSQLにデータを並行してインポートします。
INSERT INTO <Destination table> SELECT * FROM <External table>
例
この例では、データはOSSからexampleという名前の宛先テーブルにインポートされます。
次のステートメントを実行して、OSS外部テーブル拡張機能を作成します。
CREATE EXTENSION IF NOT EXISTS oss_ext;次のステートメントを実行して、インポートするデータの格納に使用するexampleという名前のテーブルを作成します。
CREATE TABLE example (date text, time text, open float, high float, low float, volume int) DISTRIBUTED BY (date);ossexampleという名前のOSS外部テーブルを作成して、データをインポートします。
prefixパラメーターを使用して、インポートするオブジェクトのパスを指定する場合は、次のステートメントを実行します。
CREATE READABLE EXTERNAL TABLE ossexample (date text, time text, open float, high float, low float, volume int) location('oss://oss-cn-hangzhou.aliyuncs.com prefix=osstest/example id=XXX key=XXX bucket=testbucket compressiontype=gzip') FORMAT 'csv' (QUOTE '''' DELIMITER E'\t') ENCODING 'utf8' LOG ERRORS SEGMENT REJECT LIMIT 5;dirパラメーターを使用して、インポートするオブジェクトのパスを指定する場合は、次のステートメントを実行します。
CREATE READABLE EXTERNAL TABLE ossexample (date text, time text, open float, high float, low float, volume int) location('oss://oss-cn-hangzhou.aliyuncs.com dir=osstest/ id=XXX key=XXX bucket=testbucket') FORMAT 'csv' LOG ERRORS SEGMENT REJECT LIMIT 5;filepathパラメーターを使用して、インポートするオブジェクトのパスを指定する場合は、次のステートメントを実行します。
CREATE READABLE EXTERNAL TABLE ossexample (date text, time text, open float, high float, low float, volume int) location('oss://oss-cn-hangzhou.aliyuncs.com filepath=osstest/example.csv id=XXX key=XXX bucket=testbucket') FORMAT 'csv' LOG ERRORS SEGMENT REJECT LIMIT 5;
ossexample外部テーブルからサンプルテーブルにデータを並行してインポートします。
INSERT INTO example SELECT * FROM ossexample;
次のクエリプランを実行します。 結果は、コンピューティングノードがOSSからデータを並列にインポートすることを示しています。 再分配運動ノードは、データをハッシュし、データを対応する計算ノードに分配する。 データを受信する計算ノードは、データをデータベースに挿入する。
EXPLAIN INSERT INTO example SELECT * FROM ossexample;
QUERY PLAN
-----------------------------------------------------------------------------------------------
Insert (slice0; segments: 4) (rows=250000 width=92)
-> Redistribute Motion 4:4 (slice1; segments: 4) (cost=0.00..11000.00 rows=250000 width=92)
Hash Key: ossexample.date
-> External Scan on ossexample (cost=0.00..11000.00 rows=250000 width=92)
(4 rows)SDKのトラブルシューティング
インポートまたはエクスポートプロセス中にエラーが発生した場合、エラーログには次の情報が含まれます。
code: 失敗したリクエストの HTTP ステータスコード。
error_code: OSSによって返されるエラーコード。
error_msg: OSSから返されるエラーメッセージ。
req_id: 失敗したリクエストのUUID。 問題が解決しない場合は、技術サポートのためにOSSにリクエストUUIDを提供できます。
詳細については、次をご参照ください： エラー応答 oss_extに関連するパラメーターを使用して、タイムアウトに関連するエラーを修正できます。