适用于：
Databricks Runtime 18 LTS 及更高版本
Important
此功能在 Beta 版中。 工作区管理员可以从 预览 页控制对此功能的访问。 请参阅 Manage Azure Databricks 预览版。
FileType 是 PySpark 对 SQL FILE 类型的类型，SQL类型是对非结构文件及其元数据的引用。 用它来声明 FILE Python 用户自定义函数（UDF）中的参数和返回类型。 在 Python 中，FILE值是一个FileRef对象，用于存储文件的元数据并读取其字节。
关于SQL类型参考和概念概述，请参见 FILE 类型 和 文件类型以及非结构化数据。 关于文件处理UDF的示例，请参见 带有UDF的进程文件。
注释
这种 FILE 类型在无服务器笔记本上不被支持。 它支持连接到无服务器 Databricks SQL 仓库的笔记本。
Import
from pyspark.sql.types import FileType, FileRef
FileType
FileType 必须是 pyspark.sql.types.DataType 的子类。 可以将其用作UDF的参数或返回类型，或者作为模式中的字段类型。
FileType 不指定 MANAGED 或 EXTERNAL。 这些限定符仅 FILE 适用于表列，该列决定引用是托管存储还是外部。 UDF传递和返回 FILE 引用，目标列决定每个引用在写入表时的存储方式。
你可以以下方式使用 FileType ，这些方法同样适用于 SQL 和 Scala UDF 以及 SQL 存储过程：
- 作为顶级类型。
- 嵌套在
StructTypea 或ArrayType. - 作为 的值类型
MapType，但不是作为MapType键。 - 在 ，
VariantType但只用于外部文件。
当查询FILE返回一列给 Python，无论是在 UDF 内部还是通过 DataFrame.collect()，每个值都是 FileRef。
文件参考
A FileRef 是 的 Python 值FILE。 它保存文件的元数据，并有读取文件字节和创建新引用的方法。
特性
| Attribute | 类型 | Description |
|---|---|---|
uri |
str |
文件的URI。 总是准备好。 |
offset |
int |
文件中的偏移量，以字节为单位。 |
size |
int |
以字节为单位的文件的大小。 |
content_type |
str |
文件的MIME类型（已知时）。 |
checksum |
str |
文件字节的完整性令牌，形式 <algorithm>:<digest>为 。 关于认可的算法，请参见 校验和。 |
Methods
| 方法 | Description |
|---|---|
as_local_file() |
返回文件 pathlib.Path 。 将结果传递给任何接受路径的库。 可在 Azure Databricks 计算（笔记本和 UDF 工作者）上使用。 在Databricks Connect客户端上，比如IDE或本地应用，运行代码的Azure Databricks计算外，是无法提供的。 |
open() |
打开文件进行二进制读取，返回一个文件对象。 来电者关上了电话。 与 具有相同的计算需求 as_local_file()。 |
from_bytes(content, path=None, content_type=None) |
课程方法。 向Unity Catalog卷路径上传content（值bytes），由给出path，返回。FileRef 如果目标路径上已有文件，则失败。 仅支持UDF内部。 |
from_local_file(local_file, path=None, content_type=None) |
课程方法。 将本地文件上传到Unity Catalog卷，并返回一个 FileRef。
path和content_type参数的行为如下from_bytes。 仅支持UDF内部。 |
Example
在以下代码中，标量UDF接收 FILE 到一个值， FileRef打开图像，返回其尺寸：
from pyspark.sql.functions import col, udf
from pyspark.sql.types import FileRef, StringType
from PIL import Image
@udf(returnType=StringType())
def image_resolution(file: FileRef) -> str:
with Image.open(file.as_local_file()) as img:
return f"{img.width}x{img.height}"
spark.read.table("images").select(image_resolution(col("photo"))).display()
关于更多文件处理UDF示例，包括生成带有UDTF的文件，请参见 带UDF的进程文件。 关于通用的UDF创作，请参见Python标量用户自定义函数（UDFs）和Python用户定义表函数（UDTF）。
限制
在 PySpark 中使用 FileType 有以下限制：
- PySpark 不支持声明
FILE MANAGED、FILE EXTERNAL表列或批量导入文件。 这些操作用SQL。 PySpark 仅支持FILE，作为FileType，在 UDF 和文件读取中。 -
as_local_file()并且open()需要集群端访问，因此它们无法在 Databricks Connect 客户端上使用。 改用UDF或集群计算调用它们。 - 对于
from_bytes和from_local_file，Python UDF是从路径扩展推断content_type的，而Scala UDF是从文件的魔力字节推断。 - 从向
FileRef列写入的 UDF 返回FILE MANAGED是不受支持的。