--- title: "CREATE EXTERNAL TABLE - OceanBase 数据库 V4.3.0 | OceanBase 文档中心" description: CREATE EXTERNAL TABLE 描述 该语句用来在数据库中创建一张新的外表。 外表是数据库管理系统中的一项关键功能，通常数据库中的表存放于数据库的存储空间中，而外表的数据存储于外部存储服务中。 创建外表时需要定义数据的文件路径和文件格式，之后用户可以通过外表从外部存储服务中读取文件的数据。外表是只读的，可… --- 切换语言 - 中文站 - 简体中文 - International - English - 日本站 - 日本語 文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*P8CuR4UJ_FkAAAAAAAAAAAAADiGDAQ/original) OceanBase 数据库分布式版 - V 4.3.0 # CREATE EXTERNAL TABLE 更新时间：2026-04-10 11:58:35 [编辑](https://github.com/oceanbase/oceanbase-doc/edit/V4.3.0/zh-CN/700.reference/500.sql-reference/100.sql-syntax/200.common-tenant-of-mysql-mode/600.sql-statement-of-mysql-mode/2200.create-external-table-of-mysql-mode.md) ## 描述 该语句用来在数据库中创建一张新的外表。 外表是数据库管理系统中的一项关键功能，通常数据库中的表存放于数据库的存储空间中，而外表的数据存储于外部存储服务中。 创建外表时需要定义数据的文件路径和文件格式，之后用户可以通过外表从外部存储服务中读取文件的数据。外表是只读的，可以在查询语句使用，但是不能执行 DML 操作。外表不支持定义约束和创建索引。 ## 语法 ```sql CREATE EXTERNAL TABLE ( [ [AS ] ] [ , [AS ] ] [ , ... ] ) LOCATION = '' FORMAT = ( TYPE = 'CSV' LINE_DELIMITER = '' | FIELD_DELIMITER = '' | ESCAPE = '' | FIELD_OPTIONALLY_ENCLOSED_BY = '' | ENCODING = 'charset' NULL_IF = ('' | , '' | ...) SKIP_HEADER = SKIP_BLANK_LINES = { TRUE | FALSE } TRIM_SPACE = { TRUE | FALSE } EMPTY_FIELD_AS_NULL = { TRUE | FALSE } ) [ PATTERN = '' ] ``` ## 参数说明 | **参数** | **描述** | | --- | --- | | table_name | 要创建的外表的名称。 | | column_name | 外表的列名称。默认情况下，文件中的数据列和外表定义的列是自动按顺序对应起来的。 | | column_type | 定义外表的列类型，但是不能定义约束（例如，`DEFAULT`、`NOT NULL`、`UNIQUE`、`CHECK`、`PRIMARY KEY`、`FOREIGN KEY` 等）。 | | AS | 用于手动指定列映射。当文件中的列顺序与外表的列所定义顺序不一致时，可以通过 `metadata$filecol{N}` 所表示的伪列来指定外表的列与文件中的第 N 列的对应关系。例如，`c2 INT AS (metadata$filecol4)` 表示外表的 `c2` 列对应文件中的第 4 列。需要注意的是，如果指定了手动列映射，那么自动映射关系将会失效，而且所有的列都需要手动定义映射关系。 | | LOCATION | 指定外表文件存放的路径。通常外表的数据文件存放于单独一个目录中，文件夹中可以包含子目录，在创建表时，外表会自动收集该目录中的所有文件。 - 本地 `LOCATION` 格式为 `LOCATION = '[file://] local_file_path'`，其中 `local_file_path` 可以为相对路径，也可以为绝对路径。如果填写的是相对路径，则当前目录必须为 OceanBase 数据库的安装目录；`secure_file_priv` 用于配置 OBServer 节点有权限访问的文件路径。`local_file_path` 只能是 `secure_file_priv` 路径的子路径。 - 远程 `LOCATION` 格式为 `LOCATION = '{oss\\|cos}://$ACCESS_ID:$ACCESS_KEY@$HOST/remote_file_path'`，其中 `$ACCESS_ID`、`$ACCESS_KEY` 和 `$HOST` 是访问 OSS/COS 时需要配置的访问信息，这些敏感的访问信息会以加密的方式存放在数据库的系统表中。 #### 注意 使用对象存储路径时，对象存储路径的各项参数由 `&` 符号进行分隔，请确保您输入的参数值中仅包含英文字母大小写、数字、`/-_$+=` 以及通配符。如果您输入了上述以外的其他字符，可能会导致设置失败。 | | FORMAT | 指定外部文件的格式。 - `TYPE`：指定外部文件的类型，当前仅支持 CSV 类型。 - `LINE_DELIMITER`：指定 CSV 文件的行分隔符。默认值为 `LINE_DELIMITER='\n'` - `FIELD_DELIMITER`：指定 CSV 文件的列分隔符。默认值为 `FIELD_DELIMITER='\t'`。 - `ESCAPE`：指定 CSV 文件的转义符号，只能为 1 个字节。默认值为 `ESCAPE ='\'`。 - `FIELD_OPTIONALLY_ENCLOSED_BY`：指定 CSV 文件中包裹字段值的符号。默认值为空。 - `ENCODING`：指定文件的字符集编码格式，当前 MySQL 模式支持的所有字符集请参见 [字符集](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000643965)。如果不指定，默认值为 UTF8MB4。 - `NULL_IF`：指定被当作 `NULL` 处理的字符串。默认值为空。 - `SKIP_HEADER`：跳过文件头，并指定跳过的行数。 - `SKIP_BLANK_LINES`：指定是否跳过空白行。默认值为 `FALSE`，表示不跳过空白的行。 - `TRIM_SPACE`：指定是否删除文件中字段的头部和尾部空格。默认值为 `FALSE`，表示不删除文件中字段头尾的空格。 - `EMPTY_FIELD_AS_NULL`：指定是否将空字符串当作 `NULL` 处理。默认值为 `FALSE`，表示不将空字符串当做 `NULL` 处理。 | | PATTERN | 指定一个正则模式串，用于过滤 `LOCATION` 目录下的文件。对于每个 `LOCATION` 目录下的文件路径，如果能够匹配该模式串，外表会访问这个文件，否则外表会跳过这个文件。如果不指定该参数，则默认可以访问 `LOCATION` 目录下的所有文件。外表会将`LOCATION` 指定路径下满足 `PATTERN` 的文件列表保存在数据库系统表中，外表扫描时会根据这个列表来访问外部的文件。 | ## 使用说明 - 当外部文件被删除时，外表访问文件列表中的文件将会不存在，这种情况下，外表会忽略不存在的文件。 - 当外部文件被修改时，外表访问外部文件的最新的数据。当外部文件的修改与外表查询并发时，可能会产生不符合预期的结果，需要避免在查询外表的同时修改外部文件。 - 当外部目录下有新增文件时，外表仅会访问文件列表中的文件，如果需要将新增文件添加到外表的文件列表中，需要执行更新外表文件操作。 ## 示例 1. 准备数据。首先需要设置 `secure_file_priv` 的路径为 `/home/admin/`，将要导入的外表数据所对应的 CSV 文件 `extdata.csv` 放在当前本地连接的 OBServer 节点的 `/home/admin/test` 路径中。 设置全局安全路径的示例如下。 ```shell obclient> SET GLOBAL secure_file_priv = "/home/admin/"; Query OK, 0 rows affected obclinet> \q Bye ``` #### 说明 由于 `secure_file_priv` 是 `GLOBAL` 变量，所以需要执行 `\q` 退出使之生效。 CSV 文件中的内容如下： ```shell 1,'Dave','Smith','dsmith@outlook.com','friend',32 2,'Xena','Johnson','xjonson@outlook.com','contact',45 3,'Fred','Jackon','fjackson@outlook.com','co-worker',19 4,'Alma','Tyler','atyler@outlook.com','friend',53 ``` 2. 用户租户登录数据库后，创建外表 `contacts`。 ```shell obclient> CREATE EXTERNAL TABLE contacts ( id INT, firstname VARCHAR(100), lastname VARCHAR(100), email VARCHAR(255), category CHAR(30), age NUMBER ) LOCATION = '/home/admin/test' FORMAT = ( TYPE = 'CSV' FIELD_DELIMITER = ',' FIELD_OPTIONALLY_ENCLOSED_BY ='\'' ) PATTERN = 'extdata.csv'; ``` 3. 查询外表 `contacts` 中的数据。 ```shell obclient> SELECT * FROM contacts; +----+-----------+----------+----------------------+-----------+------+ | id | firstname | lastname | email | category | age | +----+-----------+----------+----------------------+-----------+------+ | 1 | Dave | Smith | dsmith@outlook.com | friend | 32 | | 2 | Xena | Johnson | xjonson@outlook.com | contact | 45 | | 3 | Fred | Jackon | fjackson@outlook.com | co-worker | 19 | | 4 | Alma | Tyler | atyler@outlook.com | friend | 53 | +----+-----------+----------+----------------------+-----------+------+ 4 rows in set ``` ## 相关文档 [创建外表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000642772) [外部文件管理](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000642773) [更新外表文件列表](https://www.oceanbase.com/docs/common-oceanbase-database-cn-1000000000643124) 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线