FILE 类型

适用于： Databricks SQL Databricks Runtime 18 LTS 及更高版本

该 FILE 类型表示对非结构化文件及其元数据的引用。 用它来管理和处理 Unity 目录中的文档、图片、音频以及结构化数据。

FILE 类型仅支持Delta Lake表。

Syntax

{ FILE MANAGED | FILE EXTERNAL }

当你声明一个带有 的表列时，使用 FILE MANAGED 或 FILE EXTERNAL 作为列 CREATE TABLE类型。 你不能在不指定 FILE 或 MANAGED的情况下声明表列 。EXTERNAL FILE 仅允许作为参数或返回类型，在UDF、存储过程或投射时使用。

关于和的比较FILE MANAGED，包括架构图，请参见FILE EXTERNAL。

字段

一个 FILE 值包含以下字段：

Limits

• 类型 FILE 不保证一定能下单。 你不能用列 FILE 作为划分列、聚类列、 MAP 键、连接键或分组表达式。 要按文件分组，就按其 uri 字段分组。

Literals

要创建一个 FILE 值，请参见以下函数：

• to_file 函数 从路径创建一个 FILE 引用。
• try_to_file 函数 从路径创建一个 FILE 引用，如果文件不存在，函数会返回 NULL 。
• create_file 函数 将内容上传到路径并返回 FILE 引用。
• copy_file 函数 将文件复制到目标路径并返回 FILE 引用。

对CASTaVARIANT或STRUCT值为：FILE

• A STRUCT 必须恰好拥有这些字段，并具有这些名称和类型： struct<uri:string, offset:bigint, size:bigint, content_type:string, checksum:string>。
• VARIANT必须包含uri场地。 其他所有字段均为可选，其他键被忽略。

铸为 FILE，而非 。FILE EXTERNALFILE MANAGED 目标列决定最终引用是外部引用还是管理引用。 当你写入 FILE MANAGED 列的外部引用时，Databricks 会将其导入托管存储。

备注

• 作为顶层表列， FILE 必须声明为 FILE MANAGED 或 FILE EXTERNAL。 其他情况下的使用 FILE ：
  • 作为 SQL、Python 和 Scala 用户自定义函数（UDF）以及 SQL 存储过程中的参数或返回类型。
  • 作为a的目标类型 CAST ，来自a VARIANT 或 STRUCT 值。
  • 嵌套在 STRUCT、 ARRAY、 中，则 的 MAP值为 ，或 VARIANT。 在 VARIANT.
• 要读取文件元数据，可以使用uri带有点符号的 、 offset、 sizecontent_type、 和 checksum 字段，例如 file_column.uri。
• 要从文件中提取结构化内容，将一个值传递FILE给函数函数ai_parse_document。
• 要在查询结果中预览文件内容，请参见“ FILE 列中的预览文件”。 预览读取文件内容，这需要访问文件本身，而不仅仅是访问表。 参见 元数据和内容访问。

示例

要声明带有受管理 FILE 列的表，将表属性设置为 databricks.filespace-preview Unity 目录用作托管存储的卷路径：

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

要声明一个带有外部 FILE 列的表：

CREATE TABLE attachments (id BIGINT, attachment FILE EXTERNAL);

要从卷中已有的文件填充：

INSERT INTO attachments
  SELECT row_number() OVER (ORDER BY file.uri), file
  FROM read_files('/Volumes/my_catalog/my_schema/my_volume/', format => 'file');

使用点符号读取文件元数据：

SELECT attachment.uri, attachment.size, attachment.checksum
  FROM attachments;

要从结构体构造 FILE 一个值：

SELECT named_struct(
  'uri', '/Volumes/my_catalog/my_schema/my_volume/report.pdf',
  'offset', null,
  'size', CAST(19494 AS BIGINT),
  'content_type', 'application/pdf',
  'checksum', 'ETAG:v1')::FILE;

Related

• to_file 函数
• try_to_file 函数
• create_file 函数
• copy_file 函数
• try_copy_file 函数
• list_files 表值函数
• ai_parse_document 函数
• cast 函数
• try_cast 函数
• 文件类型与非结构化数据