CREATE EXTERNAL TABLE

Iceberg 文档索引:Iceberg 文档总览。

外部表是指不在数据库里的表,是操作系统上的一个按照一定格式分割的文本文件,或是其他类型的表,对 MatrixOne 来说类似于视图,可以在数据库中像视图一样进行查询等操作,但是外部表在数据库中只有表结构,而数据存放在操作系统中。

语法说明

外部表是指不在数据库里的表,是操作系统上的一个按照一定格式分割的文本文件,或是其他类型的表,对 MatrixOne 来说类似于视图,可以在数据库中像视图一样进行查询等操作,但是外部表在数据库中只有表结构,而数据存放在操作系统中。

本篇文档将讲述如何在 MatrixOne 数据库外建表。

语法结构

通用语法

> CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name;
(
    name1 type1,
    name2 type2,
    ...
)

语法示例

## 创建指向本地文件的外表(指定压缩格式)
create external table t(...) localfile{"filepath"='<string>', "compression"='<string>'} FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\n';

## 创建指向本地文件的外表(不指定压缩格式,则为auto格式,自动检查文件的格式)
create external table t(...) localfile{"filepath"='<string>'} FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\n';


## 创建指向S3文件的外表(指定压缩格式)
create external table t(...) URL s3option{"endpoint"='<string>', "access_key_id"='<string>', "secret_access_key"='<string>', "bucket"='<string>', "filepath"='<string>', "region"='<string>', "compression"='<string>'} FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\n';

## 创建指向S3文件的外表(不指定压缩格式,则为auto格式,自动检查文件的格式)
create external table t(...) URL s3option{"endpoint"='<string>', "access_key_id"='<string>', "secret_access_key"='<string>', "bucket"='<string>', "filepath"='<string>', "region"='<string>'} FIELDS TERMINATED BY ',' ENCLOSED BY '\"' LINES TERMINATED BY '\n';

语法说明

参数说明

参数

描述

endpoint

终端节点是作为 AWS Web 服务的入口点的 URL。例如:s3.us-west-2.amazonaws.com

access_key_id

S3 的 Access key ID

secret_access_key

S3 的 Secret access key

bucket

需要访问的桶

filepath

访问文件的相对路径

region

s3 所在的区域

compression

S3 文件的压缩格式,为空表示非压缩文件,支持的字段或压缩格式为”auto”, “none”, “gzip”, “bzip2”, “flate”, “zlib”, “lz4”, “zstd”, “zip”

auto

压缩格式,表示通过文件后缀名自动检查文件的压缩格式

none

压缩格式,表示为非压缩格式,其余表示文件的压缩格式

备注

filepath 选项对非 Parquet 格式可以包含 shell 通配符 *、? 和 [(Parquet 使用其自身的目录/模式处理)。当路径包含通配符时,外部表会读取所有匹配的文件。多个匹配文件会作为整文件分片进行分发(每个文件一个读取线程),且 IGNORE n LINES 会应用到每个文件,而不是仅第一个文件。这也使得多个压缩文件可以并行读取。

示例

create external table ex_table_cpk(clo1 tinyint,clo2 smallint,clo3 int,clo4 bigint,clo5 tinyint unsigned,clo6 smallint unsigned,clo7 int unsigned,clo8 bigint unsigned,col9 float,col10 double,col11 varchar(255),col12 Date,col13 DateTime,col14 timestamp,col15 bool,col16 decimal(5,2),col17 text,col18 varchar(255),col19 varchar(255),col20 varchar(255))infile{"filepath"='<path>'} ;

更多关于使用外表指定 S3 文件,参见从 S3 对象存储服务读取数据并导入 MatrixOne。

INFILE Parquet 语法

MatrixOne 也支持通过 INFILE 子句在 Parquet 文件上创建外表:

CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    column2 type2,
    ...
) INFILE{'filepath'='<path>', 'format'='parquet'};

参数

说明

filepath

包含 Parquet 文件的本地文件或目录路径。

format

设置为 'parquet' 表示 Parquet 格式外表。

Hive 风格分区 Parquet 外表

对于采用 Hive 风格目录分区组织的 Parquet 文件(如 year=2024/month=01/data.parquet),使用以下 INFILE 选项:

CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    partition_col1 type_p1,
    partition_col2 type_p2,
    ...
) INFILE{
    'filepath'='<path>',
    'format'='parquet',
    'hive_partitioning'='true',
    'hive_partition_columns'='partition_col1,partition_col2'
};

INFILE 选项

是否必填

说明

hive_partitioning

是

设为 'true' 以启用 Hive 风格分区发现。

hive_partition_columns

是

以逗号分隔的分区列名列表,须与表 schema 中声明的列匹配(不区分大小写)。

分区列行为:

  • 分区列在表 schema 中声明为普通列,其值从目录名称中填充。

  • 列名匹配不区分大小写。

  • 等值(=)和 IN 谓词作用于分区列时,会在文件扫描阶段进行分区裁剪,减少 I/O。

  • 名为 __HIVE_DEFAULT_PARTITION__ 的目录会映射为分区列的 SQL NULL。

  • 虚拟列 __mo_filepath 返回每行的源文件路径,所有外表均可使用。

示例 — 单级分区:

DROP DATABASE IF EXISTS hive_single_demo;
CREATE DATABASE hive_single_demo;
USE hive_single_demo;

CREATE EXTERNAL TABLE hive_single (
    id INT,
    name VARCHAR(50),
    year INT
) INFILE{
    'filepath'='<path>',
    'format'='parquet',
    'hive_partitioning'='true',
    'hive_partition_columns'='year'
};

SELECT * FROM hive_single WHERE year = 2024;
SELECT COUNT(DISTINCT __mo_filepath) FROM hive_single;

DROP DATABASE hive_single_demo;

示例 — 多级分区:

DROP DATABASE IF EXISTS hive_multi_demo;
CREATE DATABASE hive_multi_demo;
USE hive_multi_demo;

CREATE EXTERNAL TABLE hive_multi (
    id INT,
    value DOUBLE,
    year INT,
    month VARCHAR(2)
) INFILE{
    'filepath'='<path>',
    'format'='parquet',
    'hive_partitioning'='true',
    'hive_partition_columns'='year,month'
};

SELECT * FROM hive_multi WHERE year = 2024 AND month = '01';

DROP DATABASE hive_multi_demo;

Hive 外表的限制与说明:

  • 'format' 必须为 'parquet'。CSV 及其他格式不支持 hive 分区。

  • 分区列不能为 VECTOR 类型。

  • 若分区列定义为 NOT NULL,则名为 __HIVE_DEFAULT_PARTITION__ 的目录将被拒绝。

  • 目前不支持含 URL 编码(带有 %)的目录名。

  • 当 Parquet 文件的物理列与分区列名重叠时,目录路径中的分区值将覆盖物理列值。

  • 不支持对 hive 分区外表执行 LOAD DATA INFILE。

引擎特定外表

除了基于文件的外表之外,MatrixOne 还支持由 Apache Iceberg 目录、MongoDB 部署或 DataStream(jstfu)服务支撑的外表。它们通过 ENGINE 子句创建,而不是通过 INFILE/localfile/URL 子句。

Iceberg 外表

ENGINE = ICEBERG 将 MatrixOne 外表映射到 Iceberg REST 目录中注册的表。该目录必须先通过 CREATE ICEBERG CATALOG 创建。

CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    column2 type2,
    ...
) ENGINE = ICEBERG [WITH ("option" = 'value' [, "option" = 'value'] ...)];

选项

是否必填

说明

catalog

是

先前创建的 Iceberg 目录名称。

namespace

是

包含该表的 Iceberg namespace。

table

是

Iceberg 表名。

ref / default_ref

否

要读取的 Iceberg 引用(分支/标签/快照),默认为 main。

read_mode

否

append_only(默认)或 merge_on_read。

write_mode

否

read_only(默认)、append_only 或 merge_on_read。

外部表定义必须显式提供 MatrixOne 对外暴露的列。当前语法不会自动物化远端 Iceberg schema。

DROP DATABASE IF EXISTS iceberg_demo;
DROP ICEBERG CATALOG IF EXISTS my_cat;

CREATE DATABASE iceberg_demo;
USE iceberg_demo;

CREATE ICEBERG CATALOG my_cat WITH ('uri' = 'https://catalog.example.com/rest');
CREATE EXTERNAL TABLE ext_orders (
    order_id BIGINT,
    amount DOUBLE
) ENGINE = ICEBERG WITH ("catalog" = 'my_cat', "namespace" = 'sales', "table" = 'orders');

DROP DATABASE iceberg_demo;
DROP ICEBERG CATALOG IF EXISTS my_cat;

MongoDB 外表

ENGINE = MONGODB 将 MatrixOne 外表映射到 MongoDB 集合。MongoDB 连接必须先通过 CREATE MONGODB CONNECTION 创建。

CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    column2 type2,
    ...
) ENGINE = MONGODB [WITH ("option" = 'value' [, "option" = 'value'] ...)];

选项

是否必填

说明

connection

是

先前创建的 MongoDB 连接名称。

database

是

MongoDB 数据库名。

collection

是

MongoDB 集合名。

schema_mode

否

仅支持 explicit。

conversion_mode

否

strict(默认)或 try_null。

split_key

否

为未来并行扫描支持保留,当前尚未生效。不要依赖该选项提高扫描并行度。

max_parallelism

否

仅支持 1。

每个列映射到一个 BSON 字段路径。默认情况下,列映射到同名字段;使用 MONGODB_PATH 'path' 列属性可覆盖它,使用 MONGODB_CONVERT 'strict'|'try_null' 可覆盖该列的转换模式:

CREATE MONGODB CONNECTION docs_mongo WITH (
    "hosts" = 'mongo1.example.com:27017',
    "credential_secret_ref" = 'secret://env/MO_MONGODB_DOCS_CREDENTIAL'
);

CREATE EXTERNAL TABLE ext_users (
    id INT,
    profile VARCHAR(255) MONGODB_PATH 'profile.name'
) ENGINE = MONGODB WITH ("connection" = 'docs_mongo', "database" = 'app', "collection" = 'users');

该示例需要可用的 MongoDB 部署,并满足 CREATE MONGODB CONNECTION 中描述的安全前置条件:端点必须被 CN 的主机名/CIDR 允许列表放行,且 credential_secret_ref 必须指向账户级密钥。该示例并非可直接粘贴运行的脚本。

DataStream 外表

ENGINE = DATASTREAM 将 MatrixOne 外部表映射到远程 DataStream(jstfu)服务提供的数据源。该表为只读,查询时按需从服务端流式读取数据。完整语法与选项参见 CREATE EXTERNAL TABLE … ENGINE = DATASTREAM。

CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    column2 type2,
    ...
) ENGINE = DATASTREAM [WITH ("option" = 'value' [, "option" = 'value'] ...)];

选项

是否必填

说明

server

是

DataStream 服务端的主机名或 IP 地址。

port

是

DataStream 服务端的端口号。

table

是

服务端上要读取的数据源名称。

recheck

否

true(默认)在本地重新执行下推的过滤条件;false 则信任服务端。

apikey

否

可选共享密钥,或使用 env:NAME 从环境变量读取密钥。

SQL 与 ESQL 外部表

ENGINE = SQL 与 ENGINE = ESQL 将 MatrixOne 外部表映射到外部 SQL 数据库或 Elasticsearch ES|QL 源,其行数据由扫描时通过隐藏列 __mo_query 或 query 表选项提供的查询文本产生。该表只读,支持 config、query 以及(仅 SQL)pushdown 选项。完整语法与选项参见 CREATE EXTERNAL TABLE … ENGINE = SQL|ESQL。

Kafka 外部表

ENGINE = KAFKA 将 MatrixOne 外部表映射到 Apache Kafka 主题的单个分区。该表只读,支持 brokers、topic、partition、autocommit、group、format、separator 选项,以及合成的 __mo_* 元数据列与由 WHERE 驱动的读取控制。完整语法与选项参见 CREATE EXTERNAL TABLE … ENGINE = KAFKA。

外部表错误模式

文件型外部表暴露隐藏列 __mo_file_line、__mo_error_message 与 __mo_error_text,使 CSV 或 JSONLine 扫描能把坏记录作为行报告,而不是在第一条坏记录处失败。参见 External Table Error Mode。

可写外部表

可写外部表通过 WRITE_FILE_PATTERN 选项支持 INSERT ... SELECT 和 LOAD DATA 将数据写入 stage 中的外部文件,支持 CSV 和 JSONLine 两种输出格式,提供完整的列类型保真度和读写往返一致性。

概述

从 v4.1.0 开始,MatrixOne 支持向 stage 中的外部表写入数据。当创建外部表时在 INFILE 子句中指定 WRITE_FILE_PATTERN 选项后,即可通过 INSERT ... SELECT 和 LOAD DATA 语句向该外部表写入行数据。每个写入管道在 stage 目录下生成一个独立的文件;通过表的读 glob(FILEPATH)回读时可以看到所有管道写入的全部文件。

写入器遵循表的 FIELDS 和 LINES 选项——字段分隔符、包围符、转义符、行终止符以及 LINES STARTING BY——确保写入的文件可以被完美回读。支持的输出格式为 CSV(默认)和 JSONLine('format'='jsonline')。

语法

创建可写外部表

> CREATE EXTERNAL TABLE [IF NOT EXISTS] [db.]table_name (
    column1 type1,
    column2 type2,
    ...
) INFILE{
    "filepath"='<stage_glob>',
    "format"='csv|jsonline',
    "write_file_pattern"='<stage_write_pattern>'
    [, "jsondata"='object']
} [FIELDS TERMINATED BY '<char>' [ENCLOSED BY '<char>' [ESCAPED BY '<char>']]]
  [LINES TERMINATED BY '<string>' [STARTING BY '<string>']];

WRITE_FILE_PATTERN 是一个 stage 路径模板(stage://<stage_name>/<prefix>_%U.<ext>),用于控制输出文件的命名方式。

向外部表写入数据

> INSERT INTO ext_table SELECT ... FROM source_table;
> INSERT INTO ext_table VALUES (...);
> LOAD DATA INFILE '<file>' INTO TABLE ext_table [FIELDS ...] [LINES ...];

选项与参数

选项

说明

WRITE_FILE_PATTERN

输出文件的 stage 路径模板。每个写入管道将模板展开为不同的文件路径。必须是 stage://... 路径。

'format'

必须为 'csv' 或 'jsonline'。Parquet 等格式不可写。

'jsondata'

JSONLine 可写表的必填项,必须为 'object'。'array' 模式不支持写入。

模板指令

指令

说明

%U

展开为唯一标识符(32 个十六进制字符)。推荐使用。

%<n>N

展开为宽度 n 的零填充十进制计数器。n 至少为 6 才能区分并行写入器。

%Y、%m、%d

strftime 格式的日期指令。各写入器产生相同值,不能作为模板中唯一的指令。

模板必须至少包含一个 %U 或 %<n>N,以确保并行管道写入不同文件。仅包含日期指令的模板(如 out-%Y%m%d.csv)会被拒绝。

CSV 输出格式

CSV 是默认的可写格式。写入器支持完整的 CSV 选项集:

  • FIELDS TERMINATED BY:任意单字符或多字符字符串。首字节不能为引号字符("、')、CR、LF 或 NUL。

  • ENCLOSED BY:单个字符,采用 OPTIONALLY ENCLOSED 语义——仅当值中包含字段分隔符、包围符本身、转义符、行终止符字节或 LINES STARTING BY 前缀字节时才被包围。显式空字符串 '' 回退为默认值 "。

  • ESCAPED BY:单个字节,用于转义值中的包围符、转义符本身和特殊字节。不能是控制字符。不能等于包围符。设为 '' 将禁用转义;包围符加倍仍然可以保护带引号值中的特殊字符。

  • LINES TERMINATED BY:记录分隔符。默认为 '\n';也支持 '\r\n' 和自定义多字符终止符。

  • LINES STARTING BY:每条记录前输出的前缀字符串。读取器在回读时将其去除。与 COMMENT 互斥。

自动包围规则

当值的字符串表示包含任何可能混淆读取器解析器的字节时,写入器会自动对其进行包围:

  • 字段分隔符(或其多字符版本中的任一字节)

  • 包围符

  • 转义符(启用转义时)

  • 行终止符的任一字节

  • LINES STARTING BY 前缀的任一字节

  • 配置了 COMMENT 标记时的前导 #

这确保即使字段分隔符出现在 DATE 值(如 2026-06-12)或 DECIMAL 值(如 123.45)中,也能正确往返。

NULL 处理

SQL NULL 以转义后的 NULL 标记 \N 写入。空字符串 '' 与真正的 NULL 互不混淆,可正确往返。

JSONLine 输出格式

JSONLine 可写表('format'='jsonline')将每行数据写为一个 JSON 对象,每行一个。

要求:

  • 'jsondata' 必须设为 'object'(写入器输出对象而非数组)。

  • 不支持 BIT(N) 和 BLOB 列——原始字节无法通过 JSON 字符串往返。

  • 不支持 COMMENT(JSON 对象始终以 { 开头,每行都会匹配为注释前缀)。

  • 仅支持 LINES TERMINATED BY '\n' 或 '\r\n';自定义行终止符会被拒绝。

  • FIELDS ENCLOSED BY 对 JSONLine 输出无效果;JSON 引号遵循 JSON 规范。

SHOW CREATE TABLE 往返

对可写外部表执行 SHOW CREATE TABLE 会输出包含 WRITE_FILE_PATTERN 的完整 DDL。可以先删除表再从该输出重建——新建的表可以读取已有的 stage 文件并接受新的写入。空的选项键不会出现在输出中。

列类型支持

CSV 和 JSONLine 可写外部表均支持的列类型:

  • 整数:TINYINT、SMALLINT、INT、BIGINT(有符号和无符号)

  • 浮点数:FLOAT、DOUBLE

  • 定点数:DECIMAL

  • 字符串:CHAR、VARCHAR、TEXT

  • 日期/时间:DATE、DATETIME、TIMESTAMP、TIME

  • 布尔:BOOL

  • JSON:JSON

  • 枚举:ENUM

  • Bit(仅 CSV):BIT(N)——原始字节被包围和转义。JSONLine 不支持。

可写外部表不支持:

  • VECTOR 列

  • JSONLine 格式中的 BLOB 列

  • JSONLine 格式中的 BIT 列

  • 生成列(col INT AS (expr) STORED)

  • AUTO_INCREMENT 列

NOT NULL 约束执行

NOT NULL 约束在写入时生效。尝试向 NOT NULL 列插入 NULL 值会触发约束违反错误。

LINES STARTING BY 往返

指定 LINES STARTING BY 时,写入器在每条记录前输出前缀,读取器在回读时将其去除。包含前缀字符串的数据值会被自动包围,避免被误判为记录边界。

自定义 ESCAPED BY

FIELDS ESCAPED BY 选项控制 CSV 输出中转义字符的处理方式。支持自定义转义字符(如 '!')。写入器在每个字段中将转义字符加倍;读取器对带引号和不带引号的字段都进行反转义。设为 ESCAPED BY '' 则完全禁用转义(包围符加倍仍然保护引号和分隔符)。

多管道与多 CN 写入调度

在多 CN 集群中,大型 INSERT ... SELECT 语句编译为多 CN 计划。源扫描范围连同其上的外部写入插入操作通过管道协议分发到远程 CN。各 CN 通过 WRITE_FILE_PATTERN 中的 %U 指令写入不同的文件。在单 CN 上,插入以并行管道方式运行,每个管道拥有自己的写入器和文件。不同部署拓扑下的结果一致。

示例

以下示例演示了 CSV 和 JSONLine 可写外部表、多次插入累积、SHOW CREATE TABLE 往返以及 NOT NULL 约束执行。

DROP DATABASE IF EXISTS dbextwrite;
CREATE DATABASE dbextwrite;
USE dbextwrite;

CREATE STAGE wstage URL = 'file:///tmp/dbextwrite-stage/';

-- 为 INSERT ... SELECT 准备源数据
CREATE TABLE src(a INT, b VARCHAR(20), c DOUBLE);
INSERT INTO src VALUES (1, 'alice', 1.5), (2, 'bob', 2.5), (3, 'carol', 3.5);

-- 创建 CSV 可写外部表
CREATE EXTERNAL TABLE ext_csv(a INT, b VARCHAR(20), c DOUBLE)
INFILE{'FILEPATH'='stage://wstage/dbextwrite_csv_*.csv', 'FORMAT'='csv', 'WRITE_FILE_PATTERN'='stage://wstage/dbextwrite_csv_%U.csv'}
FIELDS TERMINATED BY ',';

-- 通过 INSERT ... SELECT 写入并回读
INSERT INTO ext_csv SELECT * FROM src;
SELECT * FROM ext_csv ORDER BY a;

-- 第二次插入写入新文件;读 glob 可看到所有文件
INSERT INTO ext_csv SELECT a+10, b, c FROM src;
SELECT COUNT(*) FROM ext_csv;

-- SHOW CREATE TABLE 保留 WRITE_FILE_PATTERN 以支持重建
SHOW CREATE TABLE ext_csv;

-- 创建 JSONLine 可写外部表
CREATE EXTERNAL TABLE ext_jl(a INT, b VARCHAR(20), c DOUBLE)
INFILE{'FILEPATH'='stage://wstage/dbextwrite_jl_*.jl', 'FORMAT'='jsonline', 'JSONDATA'='object', 'WRITE_FILE_PATTERN'='stage://wstage/dbextwrite_jl_%U.jl'}
FIELDS TERMINATED BY ',';

INSERT INTO ext_jl SELECT * FROM src;
SELECT * FROM ext_jl ORDER BY a;

-- 可写外部表强制执行 NOT NULL 约束
CREATE EXTERNAL TABLE ext_nn(a INT NOT NULL, b VARCHAR(10))
INFILE{'FILEPATH'='stage://wstage/dbextwrite_nn_*.csv', 'FORMAT'='csv', 'WRITE_FILE_PATTERN'='stage://wstage/dbextwrite_nn_%U.csv'}
FIELDS TERMINATED BY ',';

INSERT INTO ext_nn VALUES (1, 'ok');
-- Expected-Success: false
INSERT INTO ext_nn VALUES (NULL, 'boom');

DROP TABLE IF EXISTS ext_csv;
DROP TABLE IF EXISTS ext_jl;
DROP TABLE IF EXISTS ext_nn;
DROP TABLE IF EXISTS src;
DROP STAGE IF EXISTS wstage;
DROP DATABASE dbextwrite;

LOAD DATA 写入可写外部表

LOAD DATA INFILE 也可向可写外部表写入数据。输入文件的格式由 LOAD DATA 语句自身的 FIELDS/LINES 子句描述(描述源文件),输出格式则由外部表存储的 FIELDS/LINES 选项决定。

DROP DATABASE IF EXISTS dbextwrite;
CREATE DATABASE dbextwrite;
USE dbextwrite;

DROP STAGE IF EXISTS wstage;
CREATE STAGE wstage URL = 'file:///tmp/dbextwrite-stage/';
remove files from stage if exists 'stage://wstage/time_date_1.csv';

-- 将源 CSV 文件写入 stage
SELECT save_file(CAST('stage://wstage/time_date_1.csv' AS datalink), '1000-01-01,0001-01-01,1970-01-02 00:00:01,0');

CREATE EXTERNAL TABLE ext_load(col1 DATE NOT NULL, col2 DATETIME, col3 TIMESTAMP, col4 BOOL)
INFILE{'FILEPATH'='stage://wstage/dbextwrite_load_*.csv', 'FORMAT'='csv', 'WRITE_FILE_PATTERN'='stage://wstage/dbextwrite_load_%U.csv'}
FIELDS TERMINATED BY ',';

LOAD DATA INFILE 'stage://wstage/time_date_1.csv' INTO TABLE ext_load FIELDS TERMINATED BY ',';
SELECT * FROM ext_load ORDER BY col1;

DROP TABLE IF EXISTS ext_load;
DROP STAGE IF EXISTS wstage;
DROP DATABASE dbextwrite;

限制

  • 不支持对可写外部表进行 UPDATE、DELETE 和 TRUNCATE 操作。TRUNCATE 会被明确拒绝,因为 stage 文件不受表管理。

  • 不支持对外部表执行 REPLACE INTO。

  • 不支持 AUTO_INCREMENT 列。

  • 不支持生成列(col INT AS (expr) STORED)。

  • 不支持 IGNORE ... LINES;写入器不会输出标题行。

  • 不支持压缩(无论是显式 'compression' 选项还是从文件后缀推断的压缩格式)。写入器始终输出未压缩文件。

错误场景

以下配置在 CREATE EXTERNAL TABLE 时即被拒绝:

  • WRITE_FILE_PATTERN 不是以 stage:// 开头的有效 stage 路径。

  • WRITE_FILE_PATTERN 缺少 %U 或 %<n>N 指令(并行写入器将互相覆盖)。

  • 'format' 不是 'csv' 或 'jsonline'(仅此两种格式可写)。

  • 'format'='jsonline' 且 'jsondata'='array'(写入器输出对象而非数组)。

  • 'format'='jsonline' 且包含 BIT 或 BLOB 列。

  • 'format'='jsonline' 且使用自定义 LINES TERMINATED BY(仅允许 '\n' 或 '\r\n')。

  • 'format'='jsonline' 且指定了 COMMENT 选项。

  • 'compression' 设为非空值。

  • FILEPATH 后缀暗含压缩格式(如 .csv.gz)。

  • INFILE 选项列表中存在重复键。

  • FIELDS ESCAPED BY 设为控制字符字节(读取器会将转义序列映射为控制字符)。

  • FIELDS ESCAPED BY 与 ENCLOSED BY 相同。

  • ENCLOSED BY 字节出现在字段/行终止符或 LINES STARTING BY 中。

  • FIELDS TERMINATED BY 以引号、CR、LF 或 NUL 字节开头。

  • COMMENT 与 LINES STARTING BY 同时使用。

  • COMMENT 前缀与包围符、转义符、NULL 标记 \N 或字段分隔符字节冲突。

限制

  • 所有外部表均支持 SELECT 查询。

  • INSERT ... SELECT 和 INSERT ... VALUES 仅支持可写外部表(带有 WRITE_FILE_PATTERN 的表)。

  • LOAD DATA INFILE 支持可写外部表。

  • 所有外部表均不支持 UPDATE、DELETE、TRUNCATE 和 REPLACE INTO。

  • 可写外部表不支持 AUTO_INCREMENT、生成列和 IGNORE ... LINES。

  • 仅 CSV 和 JSONLine 格式可写入。Parquet 外部表为只读。