lakeFS Python SDK PathList 模型详解:批量删除对象路径清单的完整实战指南
lakeFS Python SDK PathList 模型详解:批量删除对象路径清单的完整实战指南
PathList 是 lakeFS Python SDK(lakefs_sdk)中用于批量删除对象的核心数据模型,它承载一组对象路径并作为 delete_objects API 的请求体。本文围绕该模型展开:先解析其字段定义与序列化方法,再结合 OpenAPI 规范、Python SDK 实现 与 服务端控制器 说明它的真实调用链与约束,最后给出可直接运行的批量删除代码示例。读完本文,你将掌握如何在 lakeFS 中安全、高效地一次删除多条对象路径,并理解其背后的权限校验、数量上限与错误回报机制。
一、PathList 是什么
在 lakeFS 的数据湖版本控制体系中,对象(Object)是存储在分支(Branch)上的数据文件。当需要对同一分支上的多个对象执行删除时,逐条发起 HTTP 请求既低效又难以保证语义一致性。为此,lakeFS 在 objects API 中提供了批量删除端点,而 PathList 正是这个端点所要求的请求体结构——一个仅包含单一必需字段 paths 的轻量模型。
从 OpenAPI 规范(api/swagger.yml)可以看到它的完整定义:
PathList:
type: object
required:
- paths
properties:
paths:
type: array
items:
type: string
description: Object path
即:PathList 是一个对象(type: object),paths 为必填字段,类型是字符串数组,数组中每个元素是一条对象路径。
二、字段属性一览
PathList 的全部属性如下表所示:
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
| paths | List[str] | 是 | 待删除的对象路径列表;每个元素对应一条对象路径(Object path) |
该模型没有可选字段。在 Python SDK 模型源码 中,这一结构被实现为一个 Pydantic 模型:
class PathList(BaseModel):
"""
PathList
"""
paths: conlist(StrictStr) = Field(...)
__properties = ["paths"]
class Config:
"""Pydantic configuration"""
allow_population_by_field_name = True
validate_assignment = True
其中:
conlist(StrictStr)表示paths是元素类型为严格字符串(StrictStr)的受约束列表,即 SDK 在反序列化与赋值时会强制校验每个元素必须是字符串;allow_population_by_field_name = True允许通过字段名直接构造实例;validate_assignment = True意味着对字段的赋值也会触发校验,防止运行期误传非字符串元素。
因此,在使用时请保证 paths 中每一项都是字符串类型的对象路径,例如 "data/part-0001.parquet",而不是数字、字典或 None。
三、模型的核心方法:JSON 与字典互转
SDK 为该模型提供了四个开箱即用的转换方法(见 path_list.py),覆盖了从 HTTP 序列化到程序内交互的全部需求:
| 方法 | 作用 | 内部实现要点 |
|---|---|---|
to_str() |
返回带别名的可打印字符串表示 | 通过 pprint.pformat(self.dict(by_alias=True)) 输出 |
to_json() |
将模型序列化为 JSON 字符串 | 内部调用 json.dumps(self.to_dict()) |
from_json(json_str) |
从 JSON 字符串反序列化为 PathList 实例 |
先 json.loads 再交给 from_dict |
to_dict() |
转换为 Python 字典 | 使用 by_alias=True 且 exclude_none=True |
from_dict(obj) |
从字典构造 PathList 实例 |
通过 parse_obj 完成字段映射 |
其中 from_dict 对 paths 字段的处理逻辑是直接读取字典键 "paths":
@classmethod
def from_dict(cls, obj: dict) -> PathList:
if obj is None:
return None
if not isinstance(obj, dict):
return PathList.parse_obj(obj)
_obj = PathList.parse_obj({
"paths": obj.get("paths")
})
return _obj
这也是与 OpenAPI 规范中字段名 paths 一一对应的关键路径。
四、PathList 的核心应用场景:批量删除对象
PathList 在整个 Python SDK 中被 ObjectsApi.delete_objects 方法使用,对应 HTTP 端点为:
POST /repositories/{repository}/branches/{branch}/objects/delete
该端点的 OpenAPI 定义位于 api/swagger.yml#L5220-L5268,其语义为:"delete objects. Missing objects will not return a NotFound error."(删除对象,缺失的对象不会返回 NotFound 错误)。也就是说,批量删除是幂等的——传入一个并不存在的路径,服务端会将其视为删除成功,而不是中断整批操作。
方法签名与参数
def delete_objects(self, repository: StrictStr, branch: StrictStr,
path_list: PathList,
force: Optional[StrictBool] = None,
no_tombstone: Optional[StrictBool] = None, **kwargs) -> ObjectErrorList:
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
repository |
str | 是 | 仓库名称 |
branch |
str | 是 | 分支名称 |
path_list |
PathList | 是 | 包含待删除路径清单的模型实例 |
force |
bool | 否 | 强制删除,默认 false;用于绕过对象存在的检查(如删除物理对象) |
no_tombstone |
bool | 否 | 实验性参数:在可能的情况下不写删除墓碑(tombstone)直接删除条目 |
该方法同步发起 HTTP 请求并返回 ObjectErrorList;若需要异步执行,可传入 async_req=True 获得线程对象后调用 .get()。
返回值:ObjectErrorList
批量删除的响应体是一个 ObjectErrorList(见 api/swagger.yml#L890-L898),结构如下:
ObjectErrorList:
type: object
required:
- errors
properties:
errors:
type: array
items:
$ref: "#/components/schemas/ObjectError"
其中 errors 数组中的每个 ObjectError 元素包含三个字段(见 object_error.py):
| 字段 | 类型 | 说明 |
|---|---|---|
status_code |
int | 该路径操作对应的 HTTP 状态码 |
message |
str | 解释状态码的简短消息 |
path |
str | 受影响的路径 |
由于该接口"缺失对象不报错"的语义,返回的 errors 列表通常为空数组,表示整批删除全部成功。
五、服务端实现原理:从请求到落库的完整链路
要理解 PathList 的约束与行为,有必要看一下服务端的处理逻辑。Go 侧控制器 pkg/api/controller.go#L691-L767 的 DeleteObjects 方法完整呈现了批量删除的三个关键阶段:
1. 数量上限校验
// limit check
if len(body.Paths) > DefaultMaxDeleteObjects {
err := fmt.Errorf("%w, max paths is set to %d", ErrRequestSizeExceeded, DefaultMaxDeleteObjects)
writeError(w, r, http.StatusBadRequest, err)
return
}
单次请求的路径数量上限为 DefaultMaxDeleteObjects = 1000(定义于 controller.go#L63)。一次性传入超过 1000 条路径会直接返回 400 Bad Request(ErrRequestSizeExceeded),因此大批量删除时应按 1000 条分批调用。
2. 逐路径权限校验
服务端会为 paths 中的每一条路径独立执行授权检查,只有授权通过(拥有对该对象路径的 DeleteObjectAction 权限)的路径才会进入真正的删除流程;未授权的路径会被记入 ObjectErrorList,状态码为 401:
for _, objectPath := range body.Paths {
if !c.authorize(w, r, permissions.Node{
Permission: permissions.Permission{
Action: permissions.DeleteObjectAction,
Resource: permissions.ObjectArn(repository, objectPath),
},
}) {
errs = append(errs, apigen.ObjectError{
Path: swag.String(objectPath),
StatusCode: http.StatusUnauthorized,
Message: http.StatusText(http.StatusUnauthorized),
})
} else {
pathsToDelete = append(pathsToDelete, objectPath)
}
}
这意味着调用方需要对清单中每一条路径都具备删除权限,否则该路径会以 401 错误出现在响应中,其余路径不受影响。
3. 批量删除与错误分类
授权通过的路径会一次性交给 catalog 层执行批量删除:
delErr := c.Catalog.DeleteEntries(ctx, repository, branch, pathsToDelete,
graveler.WithForce(swag.BoolValue(params.Force)),
graveler.WithNoTombstone(swag.BoolValue((*bool)(params.NoTombstone))),
)
随后服务端将每条路径的失败原因分类映射为 HTTP 状态码:
graveler.ErrNotFound:路径不存在——仅记录 Debug 日志,不计入错误列表(呼应"缺失对象不报错"的接口语义);ErrWriteToProtectedBranch或ErrReadOnlyRepository:分支受保护或仓库只读,记入 403 Forbidden;catalog.ErrPathRequiredValue:空路径删除——记录日志但不报错(这是为兼容 Spark 删除"main/"这类带斜杠分支路径的行为,详见代码注释 issue #1706);- 其他错误:记入 500 Internal Server Error;
- 成功路径:仅记录 Debug 日志。
最后统一以 200 OK 返回 ObjectErrorList:
response := apigen.ObjectErrorList{
Errors: errs,
}
writeResponse(w, r, http.StatusOK, response)
六、完整可运行的实战示例
下面给出一个基于 lakefs_sdk 的完整批量删除示例,涵盖模型构造、API 调用与响应处理:
from lakefs_sdk.models.path_list import PathList
from lakefs_sdk.api.objects_api import ObjectsApi
from lakefs_sdk.api_client import ApiClient
from lakefs_sdk.configuration import Configuration
# 1. 配置连接信息(以实际部署的 lakeFS 服务为准)
configuration = Configuration(
host="http://localhost:8000",
username="YOUR_ACCESS_KEY_ID",
password="YOUR_SECRET_ACCESS_KEY",
)
client = ApiClient(configuration)
objects_api = ObjectsApi(client)
# 2. 构造 PathList:paths 是唯一且必填的字段
path_list = PathList(
paths=[
"data/part-0001.parquet",
"data/part-0002.parquet",
"data/part-0003.parquet",
]
)
# 3. 调用批量删除接口(删除 main 分支上的三个对象)
result = objects_api.delete_objects(
repository="example-repo",
branch="main",
path_list=path_list,
)
# 4. 处理返回的 ObjectErrorList:errors 为空表示全部删除成功
if not result.errors:
print("所有对象均已成功删除(含不存在对象,幂等语义)")
else:
for err in result.errors:
print(f"path={err.path} status_code={err.status_code} message={err.message}")
批量大于 1000 条时的分批策略
由于服务端限制单次请求最多 1000 条路径,当清单较大时应分批构造 PathList:
all_paths = ["data/part-%04d.parquet" % i for i in range(2500)]
BATCH_SIZE = 1000
for i in range(0, len(all_paths), BATCH_SIZE):
batch = all_paths[i : i + BATCH_SIZE]
result = objects_api.delete_objects(
repository="example-repo",
branch="main",
path_list=PathList(paths=batch),
)
if result.errors:
for err in result.errors:
print(f"批次 {i // BATCH_SIZE} 失败: {err.path} -> {err.status_code} {err.message}")
使用序列化方法在调试中检查请求体
在排查问题时,可以利用模型自带的转换方法打印请求体:
path_list = PathList(paths=["a.txt", "b.txt"])
print(path_list.to_json()) # {"paths": ["a.txt", "b.txt"]}
print(path_list.to_dict()) # {'paths': ['a.txt', 'b.txt']}
# 从 JSON 字符串反序列化
restored = PathList.from_json('{"paths": ["a.txt", "b.txt"]}')
# 从字典反序列化
restored_2 = PathList.from_dict({"paths": ["a.txt", "b.txt"]})
七、测试与验证
仓库为 PathList 模型及 delete_objects 接口提供了对应的单元测试桩,可作为理解模型的参考:
- clients/python/test/test_path_list.py:
PathList的单元测试,其中make_instance展示了构造实例时paths字段的两种形态(仅必填字段 / 全部字段),并验证了testPathList用例; - clients/python/test/test_objects_api.py#L44-L49:
test_delete_objects用例,验证delete_objects方法的调用签名; - Go 侧 pkg/api/controller_test.go#L3431 中构造了
api.DefaultMaxDeleteObjects + 1个对象来测试超限场景,印证了 1000 条上限的校验逻辑。
八、常见问题与注意事项
paths必须传数组且元素为字符串:模型使用了conlist(StrictStr)约束,传入非字符串元素会触发 Pydantic 校验错误。- 单次上限 1000 条:超过
DefaultMaxDeleteObjects会被服务端以 400 拒绝,需分批处理。 - 缺失路径不报错:接口语义为幂等删除,路径不存在不会产生错误条目;无需先查询再删除。
- 权限是逐路径校验的:清单中任何一条路径无删除权限,都会在该路径上返回 401 错误,但不会阻塞其他路径的删除。
- 受保护分支与只读仓库:对应路径会返回 403;如需强制操作,可关注
force参数的语义,但需结合分支保护配置(参见仓库中 protected-branches 设计文档)。 no_tombstone为实验性参数:它影响删除时是否写入 tombstone,仅在你明确理解其行为时使用。
九、小结
PathList 虽是一个只有单一字段的轻量模型,却是 lakeFS 批量对象删除能力的数据载体:它通过 delete_objects 接口一次处理最多 1000 条路径,以"缺失不报错"的幂等语义简化调用方逻辑,并将逐路径的权限校验与错误分类收敛在服务端。理解它的字段约束、序列化方法以及服务端实现细节,能让你在实际的数据治理与清理任务中写出正确、高效且可观测的删除代码。