功能介紹

目前gpossext支持讀寫TEXT、CSV格式的文件以及GZIP壓縮格式的TEXT、CSV文件。

gpossext架構圖如下。

TEXT和CSV格式說明

下列幾個參數可以在外表DDL參數中指定，用于規定讀寫OSS的文件格式：

• TEXT和CSV行分割符號是\n，也就是換行符。

• DELIMITER用于定義列的分割符：

  • 當用戶數據中包括DELIMITER時，則需要和QUOTE參數一同使用。

  • 推薦的列分割符有,、\t、|或一些不常見的字符。

• QUOTE用于包裹有特殊字符的用戶數據（以列為單位）：

  • 包含有特殊字符的字符串會被QUOTE包裹，用于區分用戶數據和控制字符。

  • 如果不必要，例如整數，基于優化效率的考慮，不必使用QUOTE包裹數據。

  • QUOTE不能和DELIMITER相同，默認QUOTE是雙引號。

  • 當用戶數據中包含了QUOTE字符，則需要使用轉義字符ESCAPE加以區分。

• ESCAPE用于特殊字符轉義：

  • 轉義字符出現在需要轉義的特殊字符前，表示它不是一個特殊字符。

  • ESCAPE默認和QUOTE相同，為雙引號""。

  • 也支持設置成\（MySQL默認的轉義字符）或別的字符。

注意事項

• 創建和使用外部表的語法，除了location相關參數，其余參數和Greenplum的使用方式相同。

• 數據導入導出的性能和AnalyticDB PostgreSQL的資源（CPU、I/O、內存、網絡等）有關，也和OSS相關。為了獲取最優的導入導出性能，建議在創建表時，使用列式存儲加壓縮功能。例如，指定子句"WITH (APPENDONLY=true, ORIENTATION=column, COMPRESSTYPE=zlib, COMPRESSLEVEL=5, BLOCKSIZE=1048576)"，詳細信息，請參見 Greenplum Database創建表官方文檔。

• 為了保證數據導入導出的性能，請保證OSS與AnalyticDB PostgreSQL在同一地域下。

操作步驟

1. 創建OSS外部表插件。

   使用OSS外部表時，需要在AnalyticDB PostgreSQL中先創建OSS外部表插件（每個庫中均需要單獨創建）。創建命令如下：

   CREATE EXTENSION IF NOT EXISTS oss_ext;

2. 在AnalyticDB PostgreSQL中，創建WRITABLE外部表。

   創建OSS外部表語法如下。

   CREATE WRITABLE EXTERNAL TABLE table_name
   ( column_name data_type [, ...] | LIKE other_table )
   LOCATION ('ossprotocol')
   FORMAT 'TEXT'
                  [( [DELIMITER [AS] 'delimiter']
                  [NULL [AS] 'null string']
                  [ESCAPE [AS] 'escape' | 'OFF'] )]
             | 'CSV'
                  [([QUOTE [AS] 'quote']
                  [DELIMITER [AS] 'delimiter']
                  [NULL [AS] 'null string']
                  [FORCE QUOTE column [, ...]] ]
                  [ESCAPE [AS] 'escape'] )]
   [ ENCODING 'encoding' ]
   [ DISTRIBUTED BY (column, [ ... ] ) | DISTRIBUTED RANDOMLY ]
   ossprotocol:
      oss://oss_endpoint [prefix=prefix_name|dir=[folder/[folder/]...]/file_name]
       id=userossid key=userosskey bucket=ossbucket compressiontype=[none|gzip] async=[true|false]

   參數說明如下。

   參數	說明
   WRITABLE	WRITABLE是導出模式外部表的關鍵字，創建外部表時需要明確指明。
   FORMAT	支持文件格式，例如TEXT、CSV。
   ENCODING	文件中數據的編碼格式，例如UTF8。
   DISTRIBUTED BY	DISTRIBUTED BY子句可以讓數據節點（Segment）按指定的分布鍵將數據導出到OSS。
   oss://oss_endpoint	協議和Endpoint，格式為協議名://oss_endpoint，其中協議名為oss，oss_endpoint為OSS對應區域的域名。示例如下： oss://oss-cn-hangzhou.aliyuncs.com 重要 如果是從阿里云的主機訪問數據庫，應該使用內網域名（即帶有internal的域名），避免產生公網流量。
   id	阿里云賬號的AccessKey ID。獲取AccessKey操作，請參見創建AccessKey。
   key	阿里云賬號的AccessKey Secret。獲取AccessKey操作，請參見創建AccessKey。
   bucket	指定數據文件所在的Bucket，需要在OSS上預先創建。
   prefix	指定數據文件對應路徑名的前綴，不支持正則表達式，僅是匹配前綴。 說明 與dir互斥，兩者只能設置其中一個。 WRITABLE外部表在導出數據時，會根據該前綴自動生成一個唯一的文件名來給導出文件命名。 如果指定prefix=osstest/exp/outfromhdb，則表示的導出路徑為osstest/exp/，導出文件的名稱都以outfromhdb開頭。
   dir	OSS中的虛擬文件夾路徑。 說明 與prefix互斥，兩者只能設置其中一個。 文件夾路徑需要以/結尾，如test/mydir/。 在導出數據時，使用此參數創建外部表，所有數據會導出到此目錄下的多個文件中，輸出文件名的形式為filename.x，x為數字，但可能不是連續的。
   compressiontype	導出文件的壓縮格式。 none（默認值）：導入的文件未壓縮。 gzip：導入的文件壓縮格式為GZIP。 說明 目前僅支持GZIP壓縮格式。
   num_parallel_worker	設置導出到OSS的壓縮數據的并行壓縮線程個數，默認值為3。取值范圍為1~8。示例如下： num_parallel_worker=3
   oss_flush_block_size	單次導出數據到OSS的buffer大小，默認為32 MB。取值范圍為1 MB~128 MB。示例如下： oss_flush_block_size=32
   oss_file_max_size	設置導出到OSS的最大文件大小，超出之后會切換到另一個文件繼續寫。默認為1024 MB。取值范圍為8 MB~4000 MB。示例如下： oss_file_max_size=1024
   oss_connect_timeout	設置連接超時。單位為秒，默認為10秒。
   oss_dns_cache_timeout	設置DNS超時。單位為秒，默認為60秒。
   oss_speed_limit	設置觸發超時的最小速率。默認為1024字節，即1 KB。 需要與oss_speed_time參數配合使用。 說明 如果使用默認值且連續15秒的傳輸速率小于1 KB，會觸發超時。具體信息，請參見OSS SDK 錯誤處理。
   oss_speed_time	設置觸發超時的最長時間。默認為15秒。 需要與oss_speed_limit參數配合使用。 說明 如果使用默認值且連續15秒的傳輸速率小于1 KB，會觸發超時。具體信息，請參見OSS SDK 錯誤處理。

3. 并行導出數據。

   在AnalyticDB PostgreSQL數據庫中執行如下命令，并行將數據導出到OSS。

   INSERT INTO <外部表> SELECT * FROM <源表>

操作示例

本文以源表example為例，介紹將源表example的數據導出到OSS。

1. 創建OSS外部表插件。

   創建命令如下：

   CREATE EXTENSION IF NOT EXISTS oss_ext;

2. 創建源表，用于裝載待導出的數據。

   源表example的建表語句如下：

   CREATE TABLE example
           (date text, time text, open float,
            high float, low float, volume int)
            DISTRIBUTED BY (date);

3. 創建OSS導出外部表。

   • 創建外部表時，使用prefix參數指定導出路徑。示例如下：

     CREATE WRITABLE EXTERNAL TABLE ossexample_exp
             (date text, time text, open float, high float,
             low float, volume int)
             location('oss://oss-cn-hangzhou.aliyuncs.com
             prefix=osstest/exp/outfromhdb id=XXX
             key=XXX bucket=testbucket') FORMAT 'csv'
             DISTRIBUTED BY (date);

   • 創建外部表時，使用dir參數指定導出路徑。示例如下：

     CREATE WRITABLE EXTERNAL TABLE ossexample_exp
             (date text, time text, open float, high float,
             low float, volume int)
             location('oss://oss-cn-hangzhou.aliyuncs.com
             dir=osstest/exp/ id=XXX
             key=XXX bucket=testbucket') FORMAT 'csv'
             DISTRIBUTED BY (date);

4. 將數據并行地從example表導出到OSS。

   INSERT INTO ossexample_exp SELECT * FROM example;

執行如下查詢計劃，可以看到Segment節點直接將本地數據導出到OSS，沒有進行數據重分布。

EXPLAIN INSERT INTO ossexample_exp SELECT * FROM example;

返回信息如下：

                          QUERY PLAN
---------------------------------------------------------------
 Insert (slice0; segments: 3)  (rows=1 width=92)
   ->  Seq Scan on example  (cost=0.00..0.00 rows=1 width=92)
(2 rows)

SDK錯誤處理

當導入或導出操作出錯時，錯誤日志可能會出現如下信息：

• code：出錯請求的HTTP狀態碼。

• error_code：OSS的錯誤碼。

• error_msg：OSS的錯誤信息。

• req_id：標識該次請求的UUID。當您無法解決問題時，可以憑req_id來請求OSS開發工程師的幫助。

具體信息，請參見OSS API 錯誤響應，超時相關的錯誤可以使用oss_ext相關參數處理。

參考文檔

• OSS Endpoint 信息

• OSS幫助文檔

• OSS SDK錯誤處理

• OSS API錯誤響應

• Greenplum Database創建外部表官方文檔

• Greenplum Database創建表官方文檔