Directory Table
自 v1.5.3 版本起,Apache Cloudberry 引入了 Directory Table,用于统一纳管对象存储上的非结构化数据。
在大模型 AI 快速发展的背景下,AI 应用催生出了管理非结构化多模态语料数据的需求。需要持续准备大量非结构化的高质量精选语料、数据迭代训练大模型,以及归纳丰富的知识库。因此,在结构化语料数据管理与语料加工方面,面临技术挑战。
面对这些技术挑战,Apache Cloudberry 定义了一种 Directory Table 表,用于纳管多种类型的非结构化数据。开发者用户只需使用简单的 SQL 语句就能调用各种计算引擎的能力,实现一站式数据加工和应用开发。
Directory Table 定位于存储、管理和分析非结构化数据对象。Directory Table 位于表空间中,将非结构化数据文件导入 Directory Table 后,会在 Directory Table 上创建一条记录,即该文件的元数据信息,而文件本身则加载进对象存储中。表上的元数据与对象 存储上的对应文件相关联。
使用说明
创建 Directory Table
你可以在本地存储的表空间中创建 Directory Table,也可以在外部存储(如对象存储服务或 HDFS 等分布式文件系统)的表空间中创建 Directory Table。
在本地存储中创建
在本地存储创建 Directory Table 的语法如下。你需要将 <table_name>
和 <tablespace_name>
替换为实际的表名和表空间名。
-- 方法一:不指定表空间,即在已有的默认表空间中创建 Directory Table。
CREATE DIRECTORY TABLE <table_name>;
-- 方法二:先创建表空间,再在表空间中创建 Directory Table。
CREATE TABLESPACE <tablespace_name>
LOCATION '<tablespace_path>';
CREATE DIRECTORY TABLE <table_name>
TABLESPACE <tablespace_name>;
在外部存储中创建
要在外部存储中创建 Directory Table,你需要先在外部存储中创建表空间。你需要提供访问外部存储服务器所需要的连接信息,包括服务器的 IP 地址、协议、访问密钥等。以下示例展示如何在青云对象存储和 HDFS 上创建 Directory Table。
-
创建服务器对象,并定义外部数据源的连接方式。Apache Cloudberry 支持多种存储的协议,包括 S3 对象存储 和 HDFS。以下示例分别在青云和 HDFS 上创建了名为
oss_server
和hdfs_server
的服务器对象。-
青云:
CREATE STORAGE SERVER oss_server OPTIONS(protocol 'qingstor', prefix '<路径前缀>', endpoint '<终端地址>', https 'true', virtual_host 'false');
-
HDFS:
CREATE STORAGE SERVER hdfs_server OPTIONS(protocol 'hdfs', namenode '<HDFS 节点 IP:端口>', https 'false');
以上命令中涉及的参数如下:
protocol
:用于连接外部数据源的协议。在上面示例中,'qingstor'
表示使用青云对象存储服务的协议,'hdfs'
表示使用 HDFS 存储服务协议。prefix
:设置访问对象存储时的路径前缀。设置了该前缀,表明所有操作都将限定在这个特定的路径下,例如prefix '/rose-oss-test4/usf1'
。这通常用于组织和隔离存储在同一存储桶中的数据。endpoint
:指定外部对象存储服务的网络地址。例如,'pek3b.qingstor.com'
是青云服务的一个特定区域节点。通过这个端点,Apache Cloudberry 可以访问外部数据。https
:指定是否通过 HTTPS 协议连接到对象存储服务。在此命令中,'false'
表示使用非加密的 HTTP 连接。这个设置可能受到数据传输安全要求的影响,通常推荐使用 HTTPS 来确保数据安全。virtual_host
:确定是否使用虚拟主机方式访问存储桶。'false'
意味着不使用虚拟主机样式的桶访问(即,URL 中不包括存储桶名称)。这个选项通常取决于存储服务提供商的 URL 格式支持。namenode
:表示 HDFS 节点的 IP。你需要将<HDFS 节点 IP:端口>
替换为实际的 IP 地址和端口号,例如'192.168.51.106:8020'
。
-
-
创建用户映射,为当前用户提供访问这些外部服务器所需的认证信息。
-
青云:
CREATE STORAGE USER MAPPING FOR CURRENT_USER STORAGE SERVER oss_server OPTIONS (accesskey '<青云的 accesskey 密钥>', secretkey '<青云的 secretkey 密钥>');
-
HDFS:
CREATE STORAGE USER MAPPING FOR CURRENT_USER STORAGE SERVER hdfs_server OPTIONS (auth_method 'simple');
以上命令中涉及的参数如下:
accesskey
和secretkey
:这两个参数提供必要的认证信息。'accesskey'
和'secretkey'
类似于用户名和密码,用于访问对象存储服务。auth_method
:表示访问 HDFS 的认证模式。simple
表示简单认证模式,kerberos
表示使用 Kerberos 认证模式。
-
-
在外部服务器上创建表空间。这些表空间特定地链接到了前面定义的外部服务器,表空间的
location
选项指向了外部存储上的特定路径。以下示例分别在青云和 HDFS 上创建表空间dir_oss
和dir_hdfs
。-
青云:
CREATE TABLESPACE dir_oss location '<对象存储上的表空间路径>' SERVER oss_server HANDLER '$libdir/dfs_tablespace, remote_file_handler';
-- 你需要将 <对象存储上的表空间路径> 替换为实际的路径,例如 /tbs-49560-0-mgq-multi/oss-server-01-17。 -
HDFS:
CREATE TABLESPACE dir_hdfs location '<对象存储上的表空间路径>' SERVER hdfs_server HANDLER '$libdir/dfs_tablespace, remote_file_handler';
-- 你需要将 <对象存储上的表空间路径> 替换为实际的路径,例如 /tbs-49560-0-mgq-multi/oss-server-01-17。
-
-
在表空间中创建 Directory Table。以下语句分别在表空间
dir_oss
和dir_hdfs
中创建了 Directory Tabledir_table_oss
和dir_table_hdfs
。CREATE DIRECTORY TABLE dir_table_oss TABLESPACE dir_oss;
CREATE DIRECTORY TABLE dir_table_hdfs TABLESPACE dir_hdfs;提示如果你在创建表空间时,遇到
directory ... does not exist
的报错,你需要为集群配置shared_preload_libraries
并导入到对象存储。例如先执行gpconfig -c shared_preload_libraries -v 'dfs_tablespace'
,再执行gpstop -ra
重启集群。
查看 Directory Table 的字段信息
\dY -- 列 出当前所有的 Directory Table。
\d <directory_table> -- 查看某张 Directory Table 的字段信息。
通常 Directory Table 的字段如下:
字段名 | 数据类型 | 注意事项 |
---|---|---|
RELATIVE_PATH | TEXT | |
SIZE | NUMBER | |
LAST_MODIFIED | TIMESTAMP_LTZ | |
MD5 | HEX | |
TAGS | JSONB | 用户自定义标签。可用来标记数据血缘,文件上传部门/团队,分类等。"k1=v1, k2=v2" |
加载文件至 Directory Table
将文件上传至 Directory Table 后,该文件被上传至 Apache Cloudberry 管理的本地存储或对象存储中,而 Directory Table 则纳管该文件的元数据。Apache Cloudberry v1.5.3 暂不支持用户自行管理对象存储目录文件。
从本地上传文件至数据库对象存储语法如下:
\COPY '<directory_table_name>' FROM '<local_path_to_file> <target_path>';
COPY '<directory_table_name>' FROM '<local_path_to_file> <target_path>'; -- 可以省略开头的 \
-- <directory_table_name> 为 Directory Table 的表名
-- <local_path_to_file> 为待上传文件的本地路径
-- <target_path> 为本地或对象存储中的目标路径,文件会被上传至该路径
建议利用 <path>
的子目录能力,以确保上传后的目录路径与本地一致,方便对文件进行管理。
为了更好地管理或跟踪文件和数据流,你还可以在上传命令中添加 tag
,以提供附加信息或标记:
\COPY '<directory_table_name>' FROM '<local_path_to_file>' '<target_path>' WITH tag '<tag_name>';
示例如下:
-- 将文件上传至根目录
\COPY BINARY dir_table_oss FROM '/data/country.data' 'country.data';
-- 将文件上传至特定路径 top_level/second_level
\COPY BINARY dir_table_oss FROM '/data/region.tbl' 'top_level/second_level/region.tbl';
-- 将文件上传至根目录,并使用 tag
\COPY BINARY dir_table_oss FROM '/data/country1.data' 'country1.data' with tag 'country';
-- 将文件上传至特定路径 top_level/second_level,并使用 tag
\COPY BINARY dir_table_oss FROM '/data/region1.tbl' 'top_level/second_level/region1.tbl' with tag 'region';
你还可以使用命令行工具 cbload
将文件批量上传至对象存储。使用 cbload --inputfile <目录>
语法将一个目录中的文件上传至对象存储。cbload
的命令行参数如下:
用法:
cbload [flags]
参数:
--database string 要连接的数据库(默认为 gpadmin)
--dest-path string 相对于表根目录的路径(默认:表的根目录)
--force-password-auth 强制密码提示(默认为 false)
--help 打印帮助信息并退出
--host string 要连接的主机(默认为 localhost)
--input-file strings 输入的文件或目录
--logfile string 将日志输出到日志文件(默认无)
--port int 要连接的端口(默认为 5432)
--stop-on-error 当发生错误时停止加载文件(默认为 false)
--table string 要加载到的表
--tag string 文件标签
--tasks int 同时加载文件的最大数量(默认为 1)
--user string 作为用户连接(默认为 gpadmin)
--verbose 指示工具应生成详细输出(默认为 false)
--version 打印版本信息并退出
查询和使用 Directory Table 文件
查询 Directory Table 表内的文件元信息:
-- 使用表函数 directory_table() 读取文件元数据及内容
SELECT relative_path,
size,
last_modified,
md5,
tag,
content
FROM directory_table('<directory_table>');
-- 使用以下任一语句查询某张的 Directory Table 内的数据。
SELECT * FROM <directory_table>;
SELECT * FROM DIRECTORY_TABLE('<directory_table>');
删除 Directory Table 所纳管的文件
要删除 Directory Table 所纳管的文件,你需要有管理员权限:
SELECT remove_file('dir_table_oss', 'country.data');
-- 该命令删除 dir_table_oss 表所纳管的文件 country.data
删除 Directory Table
删除指定的 Directory Table。删除后,表内的所有文件也会被删除。 要删除 Directory Table,你需要有管理员权限。
DROP DIRECTORY TABLE <table_name>;