MaxCompute:オブジェクトテーブル

構文

CREATE OBJECT TABLE [IF NOT EXISTS] <objecttable_name> 
WITH SERDEPROPERTIES ('<key>' = '<value>') 
LOCATION '<location>' 
[TBLPROPERTIES ('<key>' = '<value>')] 
[COMMENT '<comment>'] 
;

パラメーター

例

SET odps.namespace.schema=true; 
CREATE OBJECT TABLE ot_demo_day 
WITH serdeproperties ( 
 'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole') 
LOCATION 'oss://oss-cn-hangzhou-internal.aliyuncs.com/odps-external-****/ottest/';

構文

DESC <object_table_name>

パラメーター

object_table_name: 必須。テーブル名。

例

DESC ot_demo_day; 

以下の結果が返されます。

+------------------------------------------------------------------------------------+
| Owner:                    ALIYUN$****@test.aliyunid.com                        |
| Project:                  test_objecttable                                         |
| Schema:                   default                                                  |
| TableComment:                                                                      |
+------------------------------------------------------------------------------------+
| CreateTime:               2024-09-02 20:01:56                                      |
| LastDDLTime:              2024-09-02 20:01:56                                      |
| LastModifiedTime:         2024-09-02 20:01:56                                      |
+------------------------------------------------------------------------------------+
| InternalTable: YES      | Size: 0                                                  |
+------------------------------------------------------------------------------------+
| Native Columns:                                                                    |
+------------------------------------------------------------------------------------+
| Field           | Type       | Label | Comment                                     |
+------------------------------------------------------------------------------------+
| key             | varchar(2048) |       | The name of the object.                     |
| size            | bigint     |       | The size of the returned object in bytes.   |
| type            | varchar(32) |       | The type of the object and valid values: Normal, Multipart, Appendable, and Symlink. |
| last_modified   | timestamp  |       | The last modified time of the object.       |
| storage_class   | varchar(32) |       | The storage class of the object.            |
| etag            | varchar(64) |       | The entity tag (ETag). When an object is created, an ETag is created to identify the content of the object. |
| restore_info    | varchar(256) |       | The restoration status of the object.       |
| owner_id        | bigint     |       | The ID of the bucket owner.                 |
| owner_display_name | varchar(256) |       | The display name of the bucket owner.       |
+------------------------------------------------------------------------------------+

返された結果の一部のカラムについて以下に説明します。

構文

SHOW CREATE TABLE <object_table_name>;

パラメーター

object_table_name: 必須。テーブル名。

例

SHOW CREATE TABLE ot_demo_day; 

以下の結果が返されます。

CREATE OBJECT TABLE IF NOT EXISTS yunqi_object_****.`default`.ot_demo_day 
WITH SERDEPROPERTIES ( 
  'serialization.format'='1', 
  'odps.properties.rolearn'='acs:ram::139699392458****:role/aliyunodpsdefaultrole') 
LOCATION 
  'oss://oss-cn-hangzhou-internal.aliyuncs.com/odps-external-****/ottest/' 
TBLPROPERTIES ( 
  'last_modified_time'='1731478307', 
  'transient_lastDdlTime'='1731478307', 
  'metadata.cache.mode'='manual', 
  'metadata.staleness.seconds'='3600');

手動リフレッシュ

各リフレッシュはメタデータの完全同期です。リフレッシュのタイミングと頻度を制御できます。

• 構文

  ALTER TABLE <objecttable_name> REFRESH METADATA;

• パラメーター

  objecttable_name: 必須。テーブル名。

• 例

  ALTER TABLE ot_demo_day REFRESH METADATA;

定期リフレッシュ

オブジェクトテーブルにマッピングされた OSS ディレクトリ内のファイルが頻繁に変更される場合は、メタデータを定期的にリフレッシュできます。これを行うには、テーブル作成時に関連パラメーターを指定します。これにより、メンテナンスコストを削減できます。

• 構文

  SET odps.namespace.schema=true;
  SET odps.sql.type.system.odps2 = true;
  
  CREATE OBJECT TABLE ot_demo_day 
  WITH serdeproperties (
   'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole'
  )
  location 'oss://oss-cn-hangzhou-internal.aliyuncs.com/odps-external-****/ottest/'
  tblproperties (
    'metadata.cache.mode' = 'periodic',
    'metadata.staleness.seconds' = '3600'
  );
  

• パラメーター

  • metadata.staleness.seconds: リフレッシュ期間。periodic モードでは、このパラメーターを指定する必要があります。値は [1, 604800] (1 秒から 1 週間) の範囲内である必要があります。このパラメーターは厳密な保証ではなく、スケジューラはこのパラメーターに基づいてリフレッシュを実行しようとします。

  • metadata.cache.mode: リフレッシュのトリガー方法を指定します。以下の 3 つのオプションがあります。

    • periodic: 定期トリガー

    • crontab: スケジュールされたリフレッシュ

    • manual: 手動トリガー (デフォルト)。トリガーのタイミングを制御できます。

スケジュールされたリフレッシュ

オブジェクトテーブルにマッピングされた OSS ディレクトリ内のファイルが頻繁に変更される場合は、メタデータを固定時刻にリフレッシュするようにスケジュールできます。これを有効にするには、テーブル作成時に関連パラメーターを指定します。これにより、メンテナンスコストを削減できます。

• 構文

  SET odps.namespace.schema=true;
  SET odps.sql.type.system.odps2 = true;
  
  CREATE OBJECT TABLE ot_demo_day 
  WITH SERDEPROPERTIES (
   'odps.properties.rolearn'='acs:ram::xxxxxx:role/aliyunodpsdefaultrole'
  )
  LOCATION 'oss://oss-cn-region-internal.aliyuncs.com/odps-external-****/ottest/'
  TBLPROPERTIES (
    'metadata.cache.mode' = 'crontab',
    'metadata.crontab.expression' = 'your_timed_expression'
  );

• パラメーター

  • metadata.crontab.expression: スケジュールタスクの cron 式。たとえば、毎日午後 2 時にタスクをトリガーする場合、式は 0 0 14 * * ? です。この式は、秒に 0、分に 0、時 (午後 2 時) に 14、月の日に *、月に * を指定します。曜日には ? を使用し、月の日と相互排他になるようにして競合を防ぎます。

  • metadata.cache.mode: リフレッシュをトリガーする方法。以下の 3 つのオプションがあります。

    • crontab: スケジュールされたリフレッシュ

    • periodic: 定期的にトリガー

    • manual: 手動トリガー (デフォルト)。トリガーのタイミングを制御できます。

リフレッシュタスクの表示

次のコマンドを使用して、過去のリフレッシュタスクのステータスを表示できます。

SHOW refresh task history FOR object TABLE <object_table_name>;

• パラメーター

  • <object_table_name> はオブジェクトテーブルである必要があります。

  • 戻り値: このコマンドは、各リフレッシュタスクのインスタンス ID (InstanceId)、開始時刻 (CreateTime)、終了時刻 (EndTime)、ステータス (Status) を返します。

  • ステータスが Failed の場合、wait InstanceId; を実行してからログビューを出力し、エラーの詳細を確認できます。

• 例

  -- オブジェクトテーブルの過去のリフレッシュタスクを表示します。
  SHOW refresh task history for object table ot_demo_day04;
  
  -- 以下の結果が返されます。
  ID = 20260105*******f
  +---------------------------------------------------------------------------------------------------+
  | Project:                  test_project                                                                              |
  | Schema:                   default                                                                                           |
  | Task:                     ***                        |
  +---------------------------------------------------------------------------------------------------+
  | History:                                                                                          |
  +---------------------------------------------------------------------------------------------------+
  | InstanceId                       | CreateTime             | EndTime                | Status       |
  +---------------------------------------------------------------------------------------------------+
  | 20260105******************ks     | 2026-01-05 14:12:00    | 2026-01-05 14:12:04    | Terminated   |
  | 20260105******************y3     | 2026-01-05 14:10:00    | 2026-01-05 14:10:03    | Terminated   |
  +---------------------------------------------------------------------------------------------------+
  
  OK

構文

SELECT * FROM <object_table_name>;

パラメーター

object_table_name: 必須。テーブル名。

例

-- 指定された OSS ディレクトリにアップロードされたデータをクエリできます。データ量が多い場合は、5 件のレコードを表示します。
SELECT * FROM  ot_demo_day [limit 5];

GET_DATA_FROM_OSS 関数の構文

GET_DATA_FROM_OSS 関数は、オブジェクトのコンテンツの一部またはすべてを読み取り、バイナリ形式で返します。

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

パラメーター

例 1

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;

例 2

オブジェクトテーブルのすべてのコンテンツを読み取り、バイナリ値として返します。オブジェクトテーブルの完全なパスは <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;

構文

TRUNCATE TABLE <object_table_name>;

パラメーター

object_table_name: 必須。テーブル名。

例

TRUNCATE TABLE ot_demo_day;

構文

ALTER TABLE <object_table_name> RENAME TO <new_object_table_name>;

パラメーター

• object_table_name: 必須。元のテーブル名。

• new_object_table_name: 必須。新しいテーブル名。

例

ALTER TABLE ot_demo_day RENAME TO new_ot_demo_day;

構文

DROP TABLE [IF EXISTS] <object_table_name>; 

パラメーター

object_table_name: 必須。テーブル名。

例

DROP TABLE IF EXISTS ot_demo_day;

ODPS-0010000:System internal error

• 症状

  以下のエラーメッセージが返されます。

  ODPS-0010000:System internal error - 
  ActionHandler job failed with failinfo	storage service worker error occured: 
  common/io/oss/oss_file_system_cppsdk.cpp(919): 
  OSSRequestException: Status: -50, RequestId: , 
  ErrorCode: ClientError:-50, Message: E_HTTP_ERROR_CONN_REFUSED

• 原因

  オブジェクトテーブル作成時に OSS のパブリックエンドポイントが使用されました。

• 解決策

  オブジェクトテーブルを作成する際、location パラメーター内の oss_endpoint は内部ネットワークアドレスである必要があります。アドレスの取得方法の詳細については、「パラメーター」をご参照ください。

定期リフレッシュが失敗する

• 症状

オブジェクトテーブル作成時に定期リフレッシュのパラメーターを設定しましたが、リフレッシュ期間に達してもリフレッシュが実行されません。

• 解決策

オブジェクトテーブルに設定された location パラメーターの値が OSS の内部ネットワークドメイン名であるかどうかを確認してください。オブジェクトテーブルの作成方法の詳細については、「パラメーター」をご参照ください。

定期リフレッシュタスクでエラーが発生する

• エラーメッセージ

  FAILED: ODPS-0010000:System internal error - ActionHandler job failed with failinfo storage service worker error occured: common/io/oss/oss_file_system_cppsdk.cpp(877): OSSRequestException: Status: -50, RequestId: , ErrorCode: ClientError:-50, Message:

• 解決策

  これは内部エラーです。チケットを送信して MaxCompute テクニカルサポートチームにお問い合わせください。