OceanBase URL外部テーブル|V4.3.5|OceanBaseデータベース|OceanBaseデータベースドキュメント|分散データベース

OceanBase URL外部テーブル

最終更新日：2026-04-09 08:28:49 更新

OceanBaseは4.3.5 BP1バージョン以降、CSV、Parquet、ORC形式のファイルまたはODPSテーブルデータをSELECTステートメントを使用して直接読み取ることをサポートしており、外部テーブルを手動で作成する必要はありません。この機能は、以下の典型的なAPシナリオに適用されます：

一時的なデータ探索
迅速なデータロード

URL外部テーブルは、OceanBaseが提供するメタデータ登録不要の外部データアクセス機能です。ユーザーはSELECTまたはLOAD DATAステートメントを使用して、データファイルのパスと形式を直接指定します。システムは動的に解析し、結果を返します。事前に外部テーブルを作成する必要はありません。

サポートされるデータソースと形式

データソースの種類	アクセス方法	サポートされる形式	説明
ローカル / オブジェクトストレージファイル	`FILES()`	CSV / Parquet / ORC	HDFS、OSS、S3、およびS3プロトコルに互換性のあるオブジェクトストレージ、ローカルファイルをサポートします
MaxCompute (ODPS)	`SOURCE()`	ODPSテーブル	ODPS Tunnelに直接接続し、エクスポートは不要です

注意

CSVクエリ結果は、デフォルトで VARCHAR 型です（後続の CAST で変換可能です）。

Parquet / ORCはスキーマ（ネスト構造を含む）を自動的に推測します。

一度のファイル読み取りの上限はありません。

ODPSは FILES() をサポートしていないため、SOURCE() を使用する必要があります。

外部データのクエリ

概要

方法1：Location URL形式（シンプル）

SELECT * FROM 'outfiles/'
(
    FORMAT (TYPE = 'format_type', FIELD_DELIMITER = ','),
    PATTERN = 'regex'
);

方法2：Table Function形式（柔軟で推奨）

SELECT * FROM FILES(
    LOCATION = 'outfiles/',
    FORMAT (TYPE = 'format_type', FIELD_DELIMITER = ','),
    PATTERN = 'regex'
);

'outfiles/'：外部テーブルファイルの保存パスを指定します。サブディレクトリへの再帰スキャンがサポートされています。
FORMAT：外部ファイルの形式と解析オプションを指定するために使用されます。
PATTERN：正規表現パターン文字列を指定して、LOCATION ディレクトリ内のファイルをフィルタリングします。指定しない場合、デフォルトですべてのファイルが読み取られます。

各形式のクエリ例

CSVファイル

基本構文

URL外部テーブルでCSVファイルを読み込む場合、2つの同等な構文を利用できます。その際、TYPE = 'CSV'を指定する必要があります。

Location URL形式（シンプル）

SELECT * FROM 'outfiles/'
(
    FORMAT (
        TYPE = 'CSV',
        FIELD_DELIMITER = ','
    ),
    PATTERN = 'data$'
);

Table Function形式（柔軟で推奨）

SELECT * FROM FILES(
    LOCATION = 'outfiles/',
    FORMAT (
        TYPE = 'CSV',
        FIELD_DELIMITER = ','
    ),
    PATTERN = 'data$'
);

説明

outfiles/ は外部テーブルファイルの保存パスを指定します。サブディレクトリの再帰スキャンもサポートしています。

FORMAT は外部ファイルの形式をCSVおよび関連する解析オプションとして指定するために使用されます。

PATTERN は正規表現パターン文字列を指定し、LOCATION ディレクトリ内のファイルをフィルタリングするために使用されます。指定しない場合は、すべてのファイルが読み込まれます。

重要：URL外部テーブルを使用してCSVファイルを読み取る場合、すべての列のデータ型はデフォルトでVARCHARです（後続のCASTにより他の型に変換可能です）。

LOCATION パラメータは、文字列形式のパス（例えば、'oss://bucket/path/'、'outfiles/'）を指定することも、作成済みのLocationオブジェクト名（クォートなし）を指定することもできます。

例1：永続外部テーブルを作成し、Locationオブジェクトを参照する

長期間使用する外部テーブルのシナリオに適しており、テーブルメタデータはデータベースに保存されます。

-- まず、my_hdfs_locという名前のLocationオブジェクトを定義します
CREATE LOCATION my_hdfs_loc URL = 'hdfs://namenode:8020/data/'

-- 外部テーブル作成時にこのLocationを参照
CREATE EXTERNAL TABLE ex_t1 (
    c1 INT,
    c2 INT,
    c3 INT
)
LOCATION = @my_hdfs_loc
FORMAT (
    TYPE = 'csv',
    FIELD_DELIMITER = ',',
    LINE_DELIMITER = '\n'
);

例2：一時的なクエリでFILES()を使用してLocationオブジェクトを参照する

一度限りの外部ファイルの分析に適しており、永続的なテーブルを作成する必要はありません。

-- Locationオブジェクトmy_hdfs_locが既に存在すると仮定します
CREATE LOCATION my_hdfs_loc URL = 'hdfs://namenode:8020/data/'

-- 直接FILESテーブル関数で参照
SELECT * FROM FILES(
    LOCATION = @my_hdfs_loc,      -- @プレフィックスを使用して定義済みのLocationを参照
    FORMAT (TYPE = 'PARQUET'),
    PATTERN = '.*\\.parquet$'     -- すべての.parquetファイルにマッチ
);

例3：Locationオブジェクトを使用せず、直接パスを指定する

パスを再利用する必要がない単純または一時的なシナリオに適しており、クエリ内にURLまたはパスを直接記述できます。2種類の同等な構文がサポートされています。

-- 方法1：パスをテーブル名として使用する（シンプルな書き方）
SELECT * FROM '/data/'
(
    FORMAT (TYPE = 'CSV', FIELD_DELIMITER = ',', SKIP_BLANK_LINES = TRUE),
    PATTERN = '^datafiles.*\\.csv$'  -- 注意：PATTERNは正規表現です
);

-- 方法2：FILESテーブル関数を使用する（明示的で、複雑な設定に推奨）
SELECT * FROM FILES(
    LOCATION = '/data/',
    FORMAT (TYPE = 'CSV', FIELD_DELIMITER = ',', SKIP_BLANK_LINES = TRUE),
    PATTERN = '^datafiles.*\\.csv$'
);

ヘッダー解析のサポート

FILES()関数を使用してCSVファイルにアクセスする場合、テーブル構造（列名と列数）を明示的に定義しない場合、システムは自動的にテーブル構造を推測します。

列数：指定されたディレクトリ内のCSVファイルの最初の行をサンプリングします。
列名：デフォルトでは、順番に従って'c1', 'c2', ...と命名されます。

多くのCSVファイルの最初の行は列名（ヘッダー）であり、その後の行がデータであるため、OceanBaseはPARSE_HEADER構成パラメータを提供しており、最初の行を列名として解析するかどうかを制御します。

CSVファイルの最初の行が列名の場合：PARSE_HEADER = TRUEを設定する必要があります。
CSVファイルの最初の行が実際のデータの場合：PARSE_HEADER = FALSE（デフォルト）のままにします。

-- 基本クエリ、CSVの最初の行はデータ（ヘッダーなし）、デフォルトの列名c1、c2を使用...
SELECT * FROM FILES(
    LOCATION = 'oss://my-bucket/logs/',
    FORMAT (
        TYPE = 'CSV',
        FIELD_DELIMITER = ',',
        SKIP_BLANK_LINES = TRUE
    ),
    PATTERN = 'user_log_202504.*\\.csv$'
);

-- CSVの最初の行が列名（例：name,age,city）の場合、PARSE_HEADERを有効にする
SELECT * FROM FILES(
    LOCATION = '/data/sales.csv',
    FORMAT (
        TYPE = 'CSV',
        FIELD_DELIMITER = ',',
        PARSE_HEADER = TRUE  -- 最初の行を列名として扱う
    )
);

使用制限：PARSE_HEADER と SKIP_HEADER は排他的であり、同時に使用することはできません。

Parquetファイル（スキーマの自動推測）

-- Location URL形式
SELECT * FROM 'outfiles/'
(
    FORMAT (TYPE = 'PARQUET'),
    PATTERN = 'data$'
);

-- Table Function形式
SELECT * FROM FILES(
    LOCATION = 'outfiles/',
    FORMAT (TYPE = 'PARQUET'),
    PATTERN = 'data$'
);

'outfiles/'外部テーブルファイルの保存パスを指定します。サブディレクトリへの再帰的スキャンがサポートされています。
FORMATファイル形式をPARQUETと指定します。
PATTERNファイルフィルタリング（正規表現マッチング）に使用されます。

-- 実際の例：S3上のParquetパーティションファイルを読み取る
SELECT * FROM FILES(
    LOCATION = 's3://analytics-bucket/events/',
    FORMAT (TYPE = 'PARQUET'),
    PATTERN = 'part-.*\\.parquet$'
);

-- `/data/` パス以下のすべての「datafiles」で始まるParquetファイルを読み取る
SELECT * FROM '/data/' (
    FORMAT = (TYPE = 'PARQUET'),
    PATTERN = 'datafiles$'
);

SELECT * FROM FILES(
    LOCATION = '/data/',
    FORMAT = (TYPE = 'PARQUET'),
    PATTERN = 'datafiles$'
);

ORCファイル

-- URL Location形式
SELECT * FROM 'outfiles/'
(
    FORMAT (TYPE = 'ORC'),
    PATTERN = 'data$'
);

-- Table Function形式
SELECT * FROM FILES(
    LOCATION = 'outfiles/',
    FORMAT (TYPE = 'ORC'),
    PATTERN = 'data$'
);

'outfiles/' パスを指定します。サブディレクトリをサポートしています。
FORMAT 書式を ORC と指定します。
PATTERN ファイルのフィルタリングに使用されます。

-- 例：HDFS上のORCファイルを読み取る
SELECT * FROM 'hdfs://mycluster/data/orc/'
(
    FORMAT (TYPE = 'ORC'),
    PATTERN = 'clicks_202504.*'
);

ODPSテーブル（MaxComputeへの直接接続）

ODPSデータソースはファイル形式ではないため、FILES() はサポートされず、SOURCE() のみがサポートされています：

SELECT * FROM SOURCE(
    TYPE = 'ODPS',
    ACCESSID = 'LTAI5tXXXXXX',
    ACCESSKEY = 'xxxxxxxxxxxxxx',
    ENDPOINT = 'http://service.cn-hangzhou.maxcompute.aliyun.com/api',
    TUNNEL_ENDPOINT = 'http://dt.cn-hangzhou.maxcompute.aliyun.com',
    PROJECT_NAME = 'sales_analytics',
    TABLE_NAME = 'user_behavior'
);

外部データのインポート（LOAD DATA）

外部データをOceanBase内部テーブルに効率的にインポートでき、並列処理や直接書き込みなどの最適化がサポートされています。

構文

LOAD DATA
    [/*+ INSERT HINT */]
    [REPLACE | IGNORE]
    FROM {
        <url_table_function_expr> |
        ( SELECT expression_list FROM <url_table_function_expr> )
    }
    INTO TABLE table_name
    [PARTITION (partition_name1, [partition_name2 ...])]
    [(column_name_var [, column_name_var] ...)]

ここで、<url_table_function_expr> は次のとおりです：

FILES (
    LOCATION = '<string>',
    {
        FORMAT = (
            TYPE = 'CSV',
            LINE_DELIMITER = '<string>' | <expr>,
            FIELD_DELIMITER = '<string>' | <expr>,
            ESCAPE = '<character>' | <expr>,
            FIELD_OPTIONALLY_ENCLOSED_BY = '<character>' | <expr>,
            ENCODING = 'charset',
            NULL_IF = ('<string>' | <expr>, '<string>' | <expr> ...),
            SKIP_HEADER = <int>,
            SKIP_BLANK_LINES = { TRUE | FALSE },
            TRIM_SPACE = { TRUE | FALSE },
            EMPTY_FIELD_AS_NULL = { TRUE | FALSE }
        )
        | FORMAT = ( TYPE = 'PARQUET' | 'ORC' )
    },
    [PATTERN = '<regex_pattern>']
)
| SOURCE (
    TYPE = 'ODPS',
    ACCESSID = '<string>',
    ACCESSKEY = '<string>',
    ENDPOINT = '<string>',
    TUNNEL_ENDPOINT = '<string>',
    PROJECT_NAME = '<string>',
    SCHEMA_NAME = '<string>',
    TABLE_NAME = '<string>',
    QUOTA_NAME = '<string>',
    COMPRESSION_CODE = '<string>'
)

LOCATION ファイルパスを指定します。サブディレクトリの再帰スキャンに対応しています。
ローカルパス：形式は file://path/ または /path/ であり、secure_file_priv 設定パスのサブディレクトリである必要があります。
リモートパス：例えば oss://bucket/path/ のように、機密情報（AccessKeyなど）はOceanBaseによって暗号化され、システムテーブルに保存されます。

説明

機密情報（AKなど）はOceanBaseによって暗号化され、システムテーブルに保存されるため、SQLでは省略可能です（事前に設定されたLOCATIONオブジェクトを再利用することで実現できます）。

インポート例

CSVのインポート (すべての列または指定された列)

-- data1.csvのすべての列をインポート
LOAD DATA /*+ DIRECT(TRUE) PARALLEL(2) */
FROM FILES(
    LOCATION = 'data/csv',
    FORMAT = (
        TYPE = 'CSV',
        FIELD_DELIMITER = ',',
        SKIP_BLANK_LINES = TRUE
    ),
    PATTERN = 'data1.csv'
)
INTO TABLE csv_ex_t1;

-- ターゲットテーブルのcol1とcol2に、c1とc2の列のみをインポート
LOAD DATA /*+ DIRECT(TRUE) PARALLEL(2) */
FROM (
    SELECT c1, c2 FROM FILES(
        LOCATION = 'data/csv',
        FORMAT = (
            TYPE = 'CSV',
            FIELD_DELIMITER = ',',
            SKIP_BLANK_LINES = TRUE
        ),
        PATTERN = 'data1.csv'
    )
)
INTO TABLE csv_ex_t1 (col1, col2);

Parquetのインポート

LOAD DATA /*+ DIRECT(TRUE) PARALLEL(2) */
FROM FILES(
    LOCATION = 'data/parquet',
    FORMAT = (TYPE = 'PARQUET'),
    PATTERN = 'data1.parquet'
)
INTO TABLE parquet_ex_t1;

ORCのインポート

LOAD DATA /*+ DIRECT(TRUE) PARALLEL(2) */
FROM FILES(
    LOCATION = 'data/orc',
    FORMAT = (TYPE = 'ORC'),
    PATTERN = 'data1.orc'
)
INTO TABLE orc_ex_t1;

ODPSからのインポート

LOAD DATA
FROM SOURCE (
    TYPE = 'ODPS',
    ACCESSID = '$ODPS_ACCESSID',
    ACCESSKEY = '$ODPS_ACCESSKEY',
    ENDPOINT = '$ODPS_ENDPOINT',
    PROJECT_NAME = 'example_project',
    SCHEMA_NAME = '',
    TABLE_NAME = 'example_table',
    QUOTA_NAME = '',
    COMPRESSION_CODE = ''
)
INTO TABLE odps_ex_t1;

パラメータの説明

LOCATIONパス形式

タイプ	フォーマット例	説明
ローカルファイル	`file://data/`または`/data/`	`secure_file_priv`を設定する必要があり、パスはそのサブディレクトリである
OSS	`oss://bucket/path/`	OBServerにAccessKeyを設定する必要があります
S3	`s3://bucket/path/`	IAMロール/AccessKeyをサポートします
HDFS	`hdfs://namenode:8020/path/`	Java SDKとKerberos（有効な場合）のデプロイが必要です

CSV形式オプション（よく使用される）

パラメータ	デフォルト値	説明
`FIELD_DELIMITER`	`,`	フィールド区切り文字
`PARSE_HEADER`	`FALSE`	最初の行を列名として扱うかどうか
`SKIP_BLANK_LINES`	`FALSE`	空行をスキップするかどうか
`EMPTY_FIELD_AS_NULL`	`FALSE`	空のフィールドをNULLに変換するかどうか
`ENCODING`	`utf8`	ファイルエンコーディング

パフォーマンスヒント（LOAD DATA専用）

/*+ DIRECT(TRUE) PARALLEL(8) */

DIRECT(TRUE)：トランザクション層をバイパスし、ストレージエンジンに直接書き込みます（高速ですが、ロールバックはできません）。
PARALLEL(N)：ファイルを並列読み取りします（N ≤ ファイル数）。

顧客事例