GET_DATA_FROM_OSS - MaxCompute

GET_DATA_FROM_OSS函數用於讀取一個對象的部分或全部內容，並以二進位形式返回。

使用情境

MaxCompute提供了Object Table功能，支援數倉計算引擎訪問OSS儲存的非結構化資料及其元資訊。詳情請參見OBJECT TABLE定義。

Object Table中儲存了對應路徑下OSS對象的元資訊，對於OSS對象的實際資料內容，可通過GET_DATA_FROM_OSSFunction Compute，實現動態載入指定OSS對象的二進位內容。

命令格式

BINARY GET_DATA_FROM_OSS (
  STRING <full_object_table_name>,
  STRING <key> 
  [, BIGINT <offset>]              
  [, BIGINT <length>] 
  [, STRING <object_not_found_policy>] 
)

參數說明

參數	是否必填	資料類型	說明	預設值
full_object_table_name	是	STRING	三層模型下，完整的OBJECT TABLE路徑，包括Project和Schema名稱，如`project.schema.object_table`。如果在建表時選擇了RoleARN的認證方式，該參數將協助使用者自動產生訪問OSS的STS Token。	無
key	是	STRING	即被訪問對象在該Object Table中的名稱。詳情請參見查看OBJECT TABLE屬性返回結果中的key參數說明。	無
offset	否	BIGINT	表示讀取對象內容的起始位置，取值大於等於0。	預設為0，即從頭開始讀取。
length	否	BIGINT	需要讀取的位元組數。	預設值為-1，即不限制長度。
object_not_found_policy	否	STRING	表示快取資料中存在某個對象的key，但在實際的OSS中該對象已不存在時，MaxCompute返回當前函數調用結果的方式。取值如下： `OUTPUT_NULL`：不拋出異常，輸出為NULL。 `THROW_EXCEPTION`：直接拋出異常，終止當前任務。 `WARN_AND_NULL`：不拋出異常，輸出為NULL。同時在SQL Runtime的輸出日誌中記錄該對象不存在的情況。如果大量對象出現這種不一致的情況，可能會對整體任務的效能造成一定影響。	預設值為OUTPUT_NULL。

傳回值說明

返回BINARY類型。

使用樣本

下述樣本中，需要將project_name參數替換為實際的MaxCompute專案名稱。

資料準備

登入OSS控制台，上傳測試資料signedget.txt至object-table-test/object_table_folder目錄下。具體操作請參見上傳檔案。

使用本地用戶端（odpscmd），或在DataWorks中建立MaxCompute SQL節點，以建立Object Table並重新整理中繼資料資訊緩衝。詳情請參見建立OBJECT TABLE。本例中建立的OBJECT TABLE名稱為ot_demo_day。

-- Object Table在MaxCompute專案中支援Schema功能，開啟三層模型。 
SET odps.namespace.schema=true;

-- 選擇對應MaxCompute專案。 
USE <project_name>;

-- 選擇對應的schema。 
USE SCHEMA <schema_name>;

-- Object Table在MaxCompute專案中支援2.0資料類型系統。 
SET odps.sql.type.system.odps2=true;

-- 建立Object Table。
CREATE OBJECT TABLE ot_demo_day 
WITH serdeproperties ( 
 'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole') 
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/object-table-test/object_table_folder';

-- 重新整理表緩衝。 
ALTER TABLE ot_demo_day REFRESH METADATA;

樣本1

讀取Object Table的全部內容，並以二進位形式返回。預設Object Table的完整路徑為<project_name>.default.ot_demo_day，不同參數組合方式如下。

-- 最完整形式。
SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, -1, 'OUTPUT_NULL') FROM ot_demo_day;

-- 以下寫法均與get_data_from_oss('<project_name>.default.ot_demo_day', key, 0, -1, 'OUTPUT_NULL')等價。
SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key) FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0) FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, -1) FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 'OUTPUT_NULL') FROM ot_demo_day;

SELECT GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, 'OUTPUT_NULL') FROM ot_demo_day;

返回結果如下：

+------+
| _c0  |
+------+
| test=20maxcompute=20download=20files=20by=20url=20 |
+------+

樣本2

如果需要將GET_DATA_FROM_OSS函數的結果輸出為STRING類型，可以嵌套一層STRING函數。

SELECT STRING(
  GET_DATA_FROM_OSS('<project_name>.default.ot_demo_day', key, 0, -1, 'OUTPUT_NULL')
) 
FROM ot_demo_day;