lakeFS Python SDK PathList 模型详解:批量删除对象路径清单的完整实战指南

原创2026-10-12 10:27:361,677 阅读
文章标签:数据湖后端对象存储数据工程版本控制

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 接口提供了对应的单元测试桩,可作为理解模型的参考:

八、常见问题与注意事项

  1. paths 必须传数组且元素为字符串:模型使用了 conlist(StrictStr) 约束,传入非字符串元素会触发 Pydantic 校验错误。
  2. 单次上限 1000 条:超过 DefaultMaxDeleteObjects 会被服务端以 400 拒绝,需分批处理。
  3. 缺失路径不报错:接口语义为幂等删除,路径不存在不会产生错误条目;无需先查询再删除。
  4. 权限是逐路径校验的:清单中任何一条路径无删除权限,都会在该路径上返回 401 错误,但不会阻塞其他路径的删除。
  5. 受保护分支与只读仓库:对应路径会返回 403;如需强制操作,可关注 force 参数的语义,但需结合分支保护配置(参见仓库中 protected-branches 设计文档)。
  6. no_tombstone 为实验性参数:它影响删除时是否写入 tombstone,仅在你明确理解其行为时使用。

九、小结

PathList 虽是一个只有单一字段的轻量模型,却是 lakeFS 批量对象删除能力的数据载体:它通过 delete_objects 接口一次处理最多 1000 条路径,以"缺失不报错"的幂等语义简化调用方逻辑,并将逐路径的权限校验与错误分类收敛在服务端。理解它的字段约束、序列化方法以及服务端实现细节,能让你在实际的数据治理与清理任务中写出正确、高效且可观测的删除代码。

登录后查看全文
lakeFS