功能介紹

OSS FDW基于PG FDW（PostgreSQL Foreign Data Wrapper）框架進(jìn)行開發(fā)，通過OSS FDW，您可以進(jìn)行如下操作：

• 將OSS數(shù)據(jù)導(dǎo)入本地表（行存表或列存表）進(jìn)行分析加速。

• 直接查詢分析OSS的海量數(shù)據(jù)。

• OSS外表與本地表關(guān)聯(lián)分析。

OSS FDW支持多種格式的數(shù)據(jù)文件，適用不同的業(yè)務(wù)場景，具體文件格式如下：

• 支持訪問CSV、TEXT、JSON、JSONLINE格式的非壓縮文本文件。

• 支持訪問CSV、TEXT格式的GZIP壓縮、標(biāo)準(zhǔn)SNAPPY壓縮文本文件。

• 支持訪問JSON、JSONLINE格式的GZIP壓縮文本文件。

• 支持訪問ORC格式的二進(jìn)制文件。ORC數(shù)據(jù)類型與AnalyticDB PostgreSQL版數(shù)據(jù)類型的映射關(guān)系，請參見ORC文件數(shù)據(jù)類型對照表。

• 支持訪問PARQUET格式的二進(jìn)制文件。PARQUET數(shù)據(jù)類型與AnalyticDB PostgreSQL版數(shù)據(jù)類型的映射關(guān)系，請參見Parquet文件數(shù)據(jù)類型對照表。

• 支持訪問AVRO格式的二進(jìn)制文件。AVRO數(shù)據(jù)類型與AnalyticDB PostgreSQL版數(shù)據(jù)類型的映射關(guān)系，請參見Avro文件數(shù)據(jù)類型對照表。

準(zhǔn)備工作

準(zhǔn)備OSS數(shù)據(jù)

準(zhǔn)備示例文件example.csv。

獲取OSS Bucket信息

以下內(nèi)容將指導(dǎo)您獲取Bucket名稱、文件的路徑、Endpoint（地域節(jié)點(diǎn)）和Bucket域名。

1. 登錄OSS管理控制臺。

2. 在左側(cè)導(dǎo)航欄中，單擊目標(biāo)Bucket列表。

3. 在Bucket列表，單擊目標(biāo)Bucket。

   您可以在Bucket列表頁面，您可以獲取Bucket名稱。

4. 在文件管理頁面，您可以獲取的Bucket中文件的路徑。

5. 單擊左側(cè)概覽。

6. 在概覽頁面的訪問端口區(qū)域，您可以獲取Endpoint（地域節(jié)點(diǎn)）和Bucket域名。

   建議使用ECS的VPC網(wǎng)絡(luò)訪問（內(nèi)網(wǎng)）的訪問域名進(jìn)行訪問。

獲取AccessKey ID和AccessKey Secret

獲取AccessKey ID和AccessKey Secret的具體操作，請參見創(chuàng)建AccessKey。

創(chuàng)建OSS Server

使用CREATE SERVER語句創(chuàng)建OSS Server，指定需要訪問的OSS服務(wù)端。更多關(guān)于CREATE SERVER的介紹，請參見CREATE SERVER。

語法

CREATE SERVER server_name
    FOREIGN DATA WRAPPER fdw_name
    [ OPTIONS ( option 'value' [, ... ] ) ]

參數(shù)選項(xiàng)

OPTIONS參數(shù)選項(xiàng)請參見下表：

示例

CREATE SERVER oss_serv
    FOREIGN DATA WRAPPER oss_fdw
    OPTIONS (
        endpoint 'oss-cn-********.aliyuncs.com',
        bucket 'adb-pg'
  );

您也可以通過ALTER SERVER語句修改OSS Server的配置，使用方法，請參見ALTER SERVER。

修改OSS Server配置示例如下：

• 修改OSS Server中的某個(gè)參數(shù)：

  ALTER SERVER oss_serv OPTIONS(SET endpoint 'oss-cn-********.aliyuncs.com');

• 添加OSS Server中的某個(gè)參數(shù)：

  ALTER SERVER oss_serv OPTIONS(ADD connect_timeout '20');

• 刪除OSS Server中的某個(gè)參數(shù)：

  ALTER SERVER oss_serv OPTIONS(DROP connect_timeout);

您也可以通過DROP SERVER語句刪除該OSS Server，使用方法，請參見DROP SERVER。

創(chuàng)建OSS User Mapping

創(chuàng)建OSS Server后，您還需要?jiǎng)?chuàng)建一個(gè)訪問OSS Server的用戶。您可以使用CREATE USER MAPPING語句創(chuàng)建OSS User Mapping，用于定義AnalyticDB PostgreSQL版數(shù)據(jù)庫用戶與訪問OSS Server用戶的映射關(guān)系。更多介紹，請參見CREATE USER MAPPING。

語法

CREATE USER MAPPING FOR { username | USER | CURRENT_USER | PUBLIC }
    SERVER servername
    [ OPTIONS ( option 'value' [, ... ] ) ]

參數(shù)選項(xiàng)

OPTIONS參數(shù)選項(xiàng)請參見下表：

示例

CREATE USER MAPPING FOR PUBLIC
    SERVER oss_serv
    OPTIONS (
        id 'LTAI5t7Ge***************',
        key 'FikziJd2La*******************'
    );

您也可以通過DROP USER MAPPING語句刪除該用戶，使用方法，請參見DROP USER MAPPING。

創(chuàng)建OSS FDW

擁有OSS Server和訪問OSS Server的用戶后，您可以開始創(chuàng)建OSS FDW。您可以使用CREATE FOREIGN TABLE語句創(chuàng)建OSS FDW，更多信息，請參見CREATE FOREIGN TABLE。

語法

CREATE FOREIGN TABLE [ IF NOT EXISTS ] table_name ( [
    column_name data_type [ OPTIONS ( option 'value' [, ... ] ) ] [ COLLATE collation ] [ column_constraint [ ... ] ]
      [, ... ]
] )
    SERVER server_name
  [ OPTIONS ( option 'value' [, ... ] ) ]

參數(shù)選項(xiàng)

OPTIONS參數(shù)選項(xiàng)請參見下表：

示例

CREATE FOREIGN TABLE ossexample (
    date text,
    time text,
    open float,
    high float,
    low float,
    volume int
) SERVER oss_serv OPTIONS (dir 'dir_oss_adb/', format 'csv');

您也可以通過DROP FOREIGN TABLE語句刪除該OSS FDW，使用方法，請參見DROP FOREIGN TABLE。

查詢分析OSS數(shù)據(jù)

查詢OSS FDW外表的數(shù)據(jù)與查詢本地表數(shù)據(jù)方法一樣，常見查詢?nèi)缦拢?/p>

• 鍵值過濾查詢，示例如下：

  SELECT * FROM ossexample WHERE volume = 5;

• 聚合查詢，示例如下：

  SELECT count(*) FROM ossexample WHERE volume = 5;

• 過濾、分組和LIMIT查詢，示例如下：

  SELECT low, sum(volume)
    FROM ossexample
   GROUP BY low
   ORDER BY low
   limit 5;

OSS FDW外表與本地表關(guān)聯(lián)分析

1. 新建用于關(guān)聯(lián)分析的本地表example，并插入測試數(shù)據(jù)，示例如下：

   CREATE TABLE example (id int, volume int);
   INSERT INTO example VALUES(1,1), (2,3), (4,5);

2. 本地表example和OSS FDW外表ossexample執(zhí)行關(guān)聯(lián)查詢，示例如下：

   SELECT example.volume, min(high), max(low)
   FROM
   ossexample,
   example
   WHERE ossexample.volume = example.volume
   GROUP BY(example.volume)
   ORDER BY example.volume;

容錯(cuò)機(jī)制

OSS FDW通過log_errors和segment_reject_limit參數(shù)提供容錯(cuò)功能，原始數(shù)據(jù)中的錯(cuò)誤數(shù)據(jù)不會(huì)導(dǎo)致OSS外表掃描停止。

關(guān)于log_errors和segment_reject_limit參數(shù)的信息，請參見創(chuàng)建OSS FDW。

• 創(chuàng)建支持容錯(cuò)的OSS FDW外表，示例如下：

  CREATE FOREIGN TABLE oss_error_sales (id int, value float8, x text)
      SERVER oss_serv
      OPTIONS (log_errors 'true',         -- 記錄錯(cuò)誤行信息
               segment_reject_limit '10', -- 錯(cuò)誤行數(shù)不得超過10行，否則會(huì)停止掃描。
               dir 'error_sales/',        -- 指定外表匹配的OSS文件目錄
               format 'csv',              -- 指定按csv格式解析文件
               encoding 'utf8');          -- 指定文件編碼 

• 查看錯(cuò)誤行的日志，查看方式如下：

  SELECT * FROM gp_read_error_log('oss_error_sales');

• 刪除錯(cuò)誤行的日志，刪除方式如下：

  SELECT gp_truncate_error_log('oss_error_sales');

常見問題

Q：刪除OSS FDW上的數(shù)據(jù)時(shí)，能否同時(shí)刪除OSS上的數(shù)據(jù)。

A：刪除OSS FDW上的數(shù)據(jù)時(shí)，無法刪除OSS上的數(shù)據(jù)。

相關(guān)文檔

• 使用OSS Foreign Table分區(qū)表

• 使用OSS Foreign Table導(dǎo)入和導(dǎo)出數(shù)據(jù)

• OSS Foreign Table最佳實(shí)踐

• OSS Foreign Table數(shù)據(jù)類型對照表