AnalyticDB:CREATE EXTERNAL TABLE

Syntax

CREATE EXTERNAL TABLE [IF NOT EXISTS] table_name
(column_name column_type[, …])
[PARTITIONED BY (column_name column_type[, …])]
ROW FORMAT DELIMITED FIELDS TERMINATED BY ','
STORED AS {TEXTFILE|ORC|PARQUET|JSON|RCFILE|HUDI|ICEBERG|PAIMON}
LOCATION 'OSS_LOCATION'
[TBLPROPERTIES (
 'type' = 'cow|mor',
 'auto.create.location' = 'true|false',
 'metadata_location' = 'METADATA_LOCATION'
)];

Parameters

Examples

CREATE EXTERNAL TABLE IF NOT EXISTS adb_external_demo.osstest6
(id int,
name string,
age int,
city string)
PARTITIONED BY (p2 string)
ROW FORMAT DELIMITED FIELDS TERMINATED BY  ','
STORED AS TEXTFILE
LOCATION  'oss://testBucketName/osstest/p1=hangzhou/';

CREATE EXTERNAL TABLE IF NOT EXISTS adb_external_demo.osstest7
(id int,
name string,
age int,
city string)
PARTITIONED BY (p1 string,p2 string)
ROW FORMAT DELIMITED FIELDS TERMINATED BY  ','
STORED AS TEXTFILE
LOCATION  'oss://testBucketName/osstest/';

Syntax

CREATE EXTERNAL TABLE [IF NOT EXISTS] table_name
(column_name column_type[, …])
ENGINE='MYSQL'
TABLE_PROPERTIES='{  
	"url":"mysql_vpc_address",  
	"tablename":"mysql_table_name",  
	"username":"mysql_user_name",  
	"password":"mysql_user_password"
	[,"charset":"{gbk|utf8|utf8mb4}"]
  }';

Parameters

Example

CREATE EXTERNAL TABLE IF NOT EXISTS adb_external_demo.mysqltest (
	id int,
	name varchar(1023),
	age int
 ) ENGINE = 'MYSQL'
 TABLE_PROPERTIES = '{
   "url":"jdbc:mysql://rm-bp1gx6********.mysql.rds.aliyuncs.com:3306/test_adb",
   "tablename":"person",
   "username":"testUserName",
   "password":"testUserPassword",
   "charset":"utf8"
}';

Syntax

CREATE EXTERNAL TABLE [IF NOT EXISTS] table_name
(column_name column_type[, …])
ENGINE='MONGODB'
TABLE_PROPERTIES = '{
	"mapped_name":"table",
  "location":"location",
  "username":"user",
  "password":"password",
}';

Parameters

Example

CREATE EXTERNAL TABLE adb_external_demo.mongodbtest (
  id int,
  name string,
  age int
) ENGINE = 'MONGODB' TABLE_PROPERTIES ='{
"mapped_name":"person",
"location":"mongodb://testuser:****@dds-bp113d414bca8****.mongodb.rds.aliyuncs.com:3717,dds-bp113d414bca8****.mongodb.rds.aliyuncs.com:3717/test_mongodb",
"username":"testuser",
"password":"password",
}';

Syntax

CREATE EXTERNAL TABLE [IF NOT EXISTS] table_name
(column_name column_type[, …])
ENGINE='OTS'
TABLE_PROPERTIES = '{
	"mapped_name":"table_name",
	"location":"tablestore_vpc_address"
}';

Parameters

Example

CREATE EXTERNAL TABLE IF NOT EXISTS adb_external_demo.otstest (
	id int,
	name string,
	age int
) ENGINE = 'OTS' 
TABLE_PROPERTIES = '{
	"mapped_name":"person",
	"location":"https://w0****la.cn-hangzhou.vpc.tablestore.aliyuncs.com"
}';

Syntax

CREATE EXTERNAL TABLE [IF NOT EXISTS] table_name
(column_name column_type[, …])
ENGINE='ODPS'
TABLE_PROPERTIES='{
	"endpoint":"endpoint",
	"accessid":"accesskey_id",
	"accesskey":"accesskey_secret",
	["partition_column":"partition_column"],
	"project_name":"project_name",
	"table_name":"table_name",
	["auto_refresh":"true|false"],
	["auto_refresh_mode":"add_only|full"]
}';

Parameters

Example

CREATE EXTERNAL TABLE IF NOT EXISTS adb_external_demo.mctest (
	id int,
	name varchar(1023),
	age int,
	dt string
) ENGINE='ODPS'
TABLE_PROPERTIES='{
	"accessid":"LTAI****************",
	"endpoint":"http://service.cn-hangzhou.maxcompute.aliyun.com/api",
	"accesskey":"yourAccessKeySecret",
	"partition_column":"dt",
	"project_name":"test_adb",
	"table_name":"person"
}';

Automatic schema refresh (auto refresh)

MaxCompute external tables support automatic schema refresh. After it is enabled, schema changes in the MaxCompute source table are automatically synchronized to the external table on each refresh cycle, without recreating the external table or refreshing it manually. Whether it is enabled and the refresh scope are controlled by the auto_refresh and auto_refresh_mode parameters that you specify when you create the table. For more information, see Parameters above.

Cluster-level configuration

Before you use the table-level auto_refresh=true setting to enable automatic schema refresh, you must run the following statements to enable the cluster-level automatic refresh switch.

-- Enable the automatic schema refresh feature.
SET ADB_CONFIG external_table_schema_refresh_enabled=true;

-- The polling interval for automatic schema refresh, in milliseconds. Default value: 300000 (5 minutes). This configuration takes effect after you restart the cluster.
SET ADB_CONFIG external_table_schema_refresh_poll_interval_ms=300000;

Examples

The following example creates a MaxCompute external table with automatic schema refresh enabled in add_only mode:

CREATE EXTERNAL TABLE IF NOT EXISTS adb_external_demo.mctest_add_only (
	id BIGINT,
	name VARCHAR(1024),
	amount DOUBLE
) ENGINE='ODPS'
TABLE_PROPERTIES='{
	"accessid":"LTAI****************",
	"accesskey":"yourAccessKeySecret",
	"endpoint":"https://service.cn-hangzhou-vpc.maxcompute.aliyun-inc.com/api",
	"project_name":"test_adb",
	"table_name":"person",
	"auto_refresh":"true",
	"auto_refresh_mode":"add_only"
}';

After a column is added to the MaxCompute source table, the external table automatically adds the corresponding column after the next refresh. Dropped columns or column type changes in the source table are not automatically applied.

The following example creates a MaxCompute external table with automatic schema refresh enabled in full mode:

CREATE EXTERNAL TABLE IF NOT EXISTS adb_external_demo.mctest_full (
	id BIGINT,
	name VARCHAR(1024),
	amount DOUBLE
) ENGINE='ODPS'
TABLE_PROPERTIES='{
	"accessid":"LTAI****************",
	"accesskey":"yourAccessKeySecret",
	"endpoint":"https://service.cn-hangzhou-vpc.maxcompute.aliyun-inc.com/api",
	"project_name":"test_adb",
	"table_name":"person",
	"auto_refresh":"true",
	"auto_refresh_mode":"full"
}';

After columns are added, dropped, or their types are changed in the MaxCompute source table, the external table synchronizes the metadata after the next refresh.

Usage notes

• Automatic schema refresh is supported only for MaxCompute external tables that use ENGINE='ODPS'.

• add_only is the default mode and is suitable for production environments in which only column additions are allowed.

• full mode automatically synchronizes dropped columns and column type changes, which may affect the SQL statements, applications, reports, or views that depend on the old columns. Use this mode with caution.

• If you create a view that uses * on the MaxCompute external table (for example, CREATE VIEW view_name AS SELECT * FROM external_table), the * is expanded and saved as a fixed list of columns when the view is created. After full mode synchronizes a dropped or renamed column from the source table and the change involves a column saved in the view, querying the view returns an error indicating that the view is stale and must be re-created. This is expected behavior. We recommend that you avoid using * in views. For more information, see CREATE VIEW.