External Database设置加载范围-实时数仓 Hologres(Hologres)-阿里云帮助中心

前提条件

Hologres实例版本为V4.1.5及以上。如何查看实例版本，请参见实例配置概览。
已创建External Database，详情请参见CREATE EXTERNAL DATABASE。
执行相关命令的用户需要具备Superuser权限。

功能说明

设置加载范围后，REFRESH CACHE FOR EXTERNAL DATABASE命令执行时，只会加载符合范围规则的Schema和Table的元数据。

重要

加载范围仅影响间接加载元数据的行为（如执行REFRESH CACHE FOR EXTERNAL DATABASE）。通过SELECT * FROM ext_db.ext_schema.ext_table直接指定目标表的查询操作，不受加载范围限制，不会校验是否在加载范围内。

参数说明

参数名称	说明	默认值
`include_pattern`	白名单规则。JSON格式字符串，用于指定允许加载的Schema和Table范围。未设置时，默认所有Schema和Table均可加载。	无（不限制）
`exclude_pattern`	黑名单规则。JSON格式字符串，用于指定需要排除加载的Schema和Table范围。未设置时，默认不排除任何Schema和Table。	无（不限制）
`table_count_limitation_per_schema`	单个External Schema内元数据刷新时允许加载的最大表数量。设置为0表示不限制。	2000

说明

table_count_limitation_per_schema默认值2000仅对V4.1.5及以上版本新创建的External Database生效。对于之前版本创建的存量External Database，该值视为0（不限制）。
当单个Schema下的表数量超过table_count_limitation_per_schema设定值时，系统会按照表名排序后选取前N张表进行元数据刷新。

Pattern规则说明

include_pattern和exclude_pattern的值均为JSON格式字符串，结构如下：

{"schema_pattern": ["table_pattern_1", "table_pattern_2"], "schema_pattern_2": ["table_pattern_3"]}

Key：Schema匹配模式（schema_pattern），用于匹配Schema名称。
Value：Table匹配模式列表（table_pattern_list），用于匹配该Schema下的Table名称。

Pattern使用fnmatch通配规则（基本等同于Shell通配规则），支持以下通配符：

通配符	说明	示例
`*`	匹配任意数量的任意字符	`test_*`匹配`test_abc`、`test_123`
`?`	匹配单个任意字符	`test_?`匹配`test_a`、`test_1`
`[seq]`	匹配seq中的任意单个字符	`test_[abc]`匹配`test_a`、`test_b`、`test_c`
`[!seq]`	匹配不在seq中的任意单个字符	`test_[!abc]`匹配`test_d`、`test_1`

匹配规则

include_pattern（白名单）规则：

未设置include_pattern时，视为所有Schema和Table都通过白名单校验。
设置include_pattern后，Table匹配模式列表中任意一个匹配成功即算通过。

exclude_pattern（黑名单）规则：

未设置exclude_pattern时，视为所有Schema和Table都通过黑名单校验。
设置exclude_pattern后，Table匹配模式列表中所有规则都不匹配才算通过。

最终判定：同时通过include_pattern和exclude_pattern校验的Schema/Table才会被纳入加载范围。

说明

如果一个Schema名称能匹配上多个Key（schema_pattern），其行为是未定义的。请编写规则时确保Schema名称只能匹配到唯一的Key。

语法说明

创建External Database时设置加载范围

CREATE EXTERNAL DATABASE <ext_database_name> WITH
  metastore_type '<type>'
  -- 其他必填参数...
  include_pattern '<pattern_json>'
  exclude_pattern '<pattern_json>'
  table_count_limitation_per_schema '<number>';

修改已有External Database的加载范围

-- 设置或更新加载范围
ALTER EXTERNAL DATABASE <ext_database_name> WITH
  include_pattern '<pattern_json>'
  exclude_pattern '<pattern_json>';

-- 设置单个Schema内加载表数量限制
ALTER EXTERNAL DATABASE <ext_database_name> WITH
  table_count_limitation_per_schema '<number>';

-- 解除单个Schema内加载表数量限制
ALTER EXTERNAL DATABASE <ext_database_name> WITH
  table_count_limitation_per_schema default;
-- 等效写法
ALTER EXTERNAL DATABASE <ext_database_name> WITH
  table_count_limitation_per_schema '0';

检测Schema/Table是否在加载范围内

-- 检测Schema是否在加载范围内
SELECT hologres.hg_external_database_includes('<database_name>', '<schema_name>');

-- 检测Table是否在加载范围内
SELECT hologres.hg_external_database_includes('<database_name>', '<schema_name>', '<table_name>');

使用示例

示例一：仅加载特定前缀的Schema和Table

CREATE EXTERNAL DATABASE ext_mc_db WITH
  metastore_type 'maxcompute'
  mc_project 'my_mc_project'
  include_pattern '{"prod_*": ["fact_*", "dim_*"]}';

ALTER EXTERNAL DATABASE ext_mc_db WITH
  include_pattern '{"prod_*": ["fact_*", "dim_*"]}';

REFRESH CACHE FOR EXTERNAL DATABASE ext_mc_db WITH(cache_level = 'metadata');

示例二：排除特定Schema

ALTER EXTERNAL DATABASE ext_mc_db WITH
  exclude_pattern '{"tmp": ["*"], "test_*": ["*"]}';

示例三：组合使用白名单和黑名单

ALTER EXTERNAL DATABASE ext_mc_db WITH
  include_pattern '{"dev_*": ["2025*"]}'
  exclude_pattern '{"dev_*": ["2025_tmp*"]}';

示例四：限制单个Schema内加载表数量

CREATE EXTERNAL DATABASE ext_mc_db WITH
  metastore_type 'maxcompute'
  mc_project 'my_mc_project'
  table_count_limitation_per_schema '1000';

ALTER EXTERNAL DATABASE ext_mc_db WITH
  table_count_limitation_per_schema '1000';

ALTER EXTERNAL DATABASE ext_mc_db WITH
  table_count_limitation_per_schema '0';

示例五：验证加载范围

SELECT hologres.hg_external_database_includes('ext_mc_db', 'prod_order');
-- 返回: true

SELECT hologres.hg_external_database_includes('ext_mc_db', 'prod_order', 'fact_sales');
-- 返回: true

SELECT hologres.hg_external_database_includes('ext_mc_db', 'test_dev');
-- 返回: false

最佳实践

合理规划加载范围：根据业务实际需要，仅加载需要频繁访问的Schema和Table，避免不必要的元数据刷新开销。
先用白名单缩小范围，再用黑名单排除例外：建议先通过include_pattern圈定大范围，再通过exclude_pattern排除其中的特殊情况。
设置合理的表数量限制：对于Schema下表数量极大的场景（如数万张表），建议设置table_count_limitation_per_schema为合理值，避免元数据刷新耗时过长。
使用检测函数验证规则：在设置Pattern后，使用hologres.hg_external_database_includes函数验证目标Schema和Table是否如预期被包含在加载范围内。
避免Schema Pattern冲突：确保include_pattern和exclude_pattern中的Schema Pattern不会同时匹配到同一个Schema名称的多个Key，否则行为未定义。

常见问题

Q：设置加载范围后，是否还能查询不在范围内的表？

A：可以。加载范围仅影响REFRESH CACHE FOR EXTERNAL DATABASE时间接加载元数据的行为。通过完整路径ext_db.ext_schema.ext_table直接查询的操作不受限制。

Q：修改加载范围后，是否需要手动刷新元数据？

A：修改加载范围后，新的规则会在下一次元数据刷新时生效。您可以主动执行REFRESH CACHE FOR EXTERNAL DATABASE命令来立即生效。

Q：table_count_limitation_per_schema对存量External Database如何生效？

A：对于V4.1.5之前创建的存量External Database，该值默认视为0（不限制）。如需限制，需要通过ALTER EXTERNAL DATABASE命令显式设置。