文件类型与非结构化数据

该 FILE 类型存储对非结构化文件的受控引用，包含路径和大小等元数据。 在Unity Catalog中使用 FILE 列来存储文档、图片和音频，同时存储结构化数据。

对于 FILE MANAGED 列，Unity Catalog 存储文件副本并用表格管理：删除行后，引用的文件有资格进行垃圾回收，因此表格和文件保持同步。

关于类型参考，请参见 FILE 类型。

下图显示了一个名为 video 的 FILE 列，该列引用驾驶片段，以及路线、场景描述和危险标签等结构化列：

文件元数据与存储

对于每一行，类型 FILE 存储元数据和存储中文件的受控链接。 一个 FILE 值包括 uri、 size、 content_type和 checksum 元数据字段。 元数据查询不需要完整读取文件，从而提升了查询性能。

可以将值传递给 FILE AI 函数（如ai_parse_document函数）和用户定义的函数（UDF）。

下图展示了一个示例的管理 FILE 列，包含路径和大小元数据以及存储中文件的引用：

为什么用FILE而不是BINARY或STRING

下表详细列出了处理BINARY或STRING类型的大型非结构化文件时面临的挑战：

列类型	Description	图表
BINARY	每次读取时都会将整个对象完整加载出来，即使你只需要文件大小或路径等元数据。 这导致了不必要的计算和查询速度缓慢。
STRING	存储一个没有元数据（如大小或版本信息）的文件路径，也没有表与文件之间的管理链接。 如果其他工作负载删除了该文件，表中的信息已经过时。 如果你移除了某一行表，引用的文件会一直存储在存储中，直到你手动移除它。

校验和

该 checksum 字段是用于文件字节的完整性令牌，格式为 <prefix>:<digest>。 用它来比较文件或确认文件没有变化。 读取器会忽略带有无法识别前缀的校验和。

校验和并不总是可用。 to_file 函数、create_file 函数和copy_file 函数会在对象存储返回一个 ETAG 时填充校验和。 list_files 表值函数 和 read_files 表值函数 不填充校验和。

该 checksum 字段使用以下前缀之一：

例如，MD5 校验和看起来像 MD5:d41d8cd98f00b204e9800998ecf8427e，而对象存储的 eTag 看起来像 ETAG:"686897696a7c876b7e"，其中包括对象存储返回的双引号。

在 FILE 和 BINARY 之间选择

下表比较了处理非结构化文件的各种选项：

受管文件和外部文件

该 FILE 类型支持两种文件管理方式：

• FILE MANAGED 列会将文件复制到托管存储中。 通过该表格简化和管理权限。 当你删除行，或更新行以引用不同文件时，未被引用的文件就有资格进行垃圾回收，因此表和文件保持同步。对于通过表访问文件的工作载荷，如机器学习训练或检索增强生成（RAG），以及从外部来源导入的文件，可以使用这种方法。 有关摄入模式，请参阅将文件作为 FILE 类型摄入。
• FILE EXTERNAL 列引用 Unity Catalog 卷中的现有文件。 文件由 Unity 目录卷权限保护，但它们的生命周期不由 Unity 目录管理，也不会被复制。 当你需要引用文件，而又不想移动数据或干扰从现有卷读取数据的工具时，请使用这种方法。

Azure Databricks 建议FILE MANAGED适合需要文件级权限和内置合规性的工作负载：每个文件的访问都通过引用该文件的表来管理，删除行后，被引用的文件才有资格进行垃圾回收。 当文件必须保留在其现有卷路径中，以供在表外读取这些文件的工具使用时，请使用 FILE EXTERNAL。

查询时，管理文件和外部文件没有区别。

下图展示了 FILE 类型如何将你的代码连接到云对象存储中的文件：

FILE MANAGED

FILE MANAGED 列将文件的副本存储在 FileSpace 中，即您为该表声明并用作托管存储的 Unity Catalog 卷。 它们的生命周期与引用它们的表绑定：删除行后，被引用的文件有资格进行垃圾回收，因此表和文件保持同步。

以下行为适用于 FILE MANAGED：

• 声明 FileSpace 需要 databricks.filespace-preview 表属性。
• 读取或写入受管理文件需要同时访问表和支持该 FileSpace文件的卷。
• 测试版不支持自动对未引用文件进行垃圾回收。

存储在外部来源（如 SharePoint、Google Drive、OneDrive 和 SFTP）中的非结构化文件必须先作为托管文件被导入，才能与函数和ai_parse_document用户定义函数（UDF）等功能一起使用。 有关摄入模式，请参阅将文件作为 FILE 类型摄入。

要使用受管文件，请创建一个包含 FILE MANAGED 列的表，并将 databricks.filespace-preview 表属性设置为卷路径，以此声明卷 FileSpace：

'databricks.filespace-preview' = '/Volumes/<catalog>/<schema>/<volume_name>/<optional_path>'

完整示例请参见以下 FILE MANAGED 示例。

FILE MANAGED 示例

要创建带有 FILE MANAGED 列的表：

CREATE TABLE reports (id BIGINT, file FILE MANAGED)
  TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

要向现有表添加 FILE MANAGED 列，请在添加列之前设置 databricks.filespace-preview 表属性，如下代码所示：

ALTER TABLE reports SET TBLPROPERTIES ('databricks.filespace-preview' = '/Volumes/my_catalog/my_schema/my_managed_volume/');

ALTER TABLE reports ADD COLUMN attachment FILE MANAGED;

向没有FileSpace的表添加FILE MANAGED列会失败。

删除未被引用的托管文件

由于不支持自动垃圾回收，请自行删除未引用的文件。 以下笔记本会查找 FileSpace 中未被任何表版本引用的文件，并可选择将其删除：

文件类型垃圾回收笔记本

获取笔记本

FILE EXTERNAL

FILE EXTERNAL 列是 Unity Catalog 卷中已存在文件的引用。

如果你对该卷拥有必要的权限，可以更新或删除这些文件。 Databricks建议你使用不可变文件。 对表的授权会使文件元数据可被访问，但要读取文件的字节内容，还需要具备底层卷上的 READ VOLUME 权限。

外部文件将每行表数据映射到 Unity Catalog 卷中其现有路径下的文件：

FILE EXTERNAL 示例

要创建带有 FILE EXTERNAL 列的表：

CREATE TABLE documents (id BIGINT, file FILE EXTERNAL);

要向现有表添加 FILE EXTERNAL 一列：

ALTER TABLE documents ADD COLUMN file FILE EXTERNAL;

要从卷中创建并填充表，为每个文件分配唯一ID：

CREATE TABLE documents AS
  SELECT monotonically_increasing_id() AS id, file
  FROM list_files('/Volumes/samples/sec/contracts/');

治理与生命周期比较

下表比较了 FILE EXTERNAL 和 FILE MANAGED 如何控制文件访问并处理文件生命周期：

FILE 类型用例

托管类型和外部 FILE 类型都应对了使用非结构化数据的用例面临的以下挑战：

后续步骤

• FILE 类型

• 将文件作为 FILE 类型导入

• ai_parse_document 函数