数据工程数据湖大数据对象存储后端【免费下载链接】lakeFSlakeFS - Data version control for your data lake | Git for data项目地址https://gitcode.com/gh_mirrors/la/lakeFS点击查看免费下载导读PrepareGarbageCollectionCommitsStatus是 lakeFS Rust SDKclients/rust中用于描述GC Commits 准备任务状态的数据模型。在 lakeFS 的数据湖垃圾回收Garbage CollectionGC流程中用户需要先通过异步接口prepare_garbage_collection_commits_async启动活动提交列表的生成任务再通过状态查询接口prepare_garbage_collection_commits_status轮询该任务是否完成。本文以该模型为主线完整讲解其字段语义、JSON 序列化结构、在 Rust SDK 中的构造与反序列化用法、底层 API 调用方式并结合 lakeFS 服务端源码pkg/api/controller.go、pkg/catalog/catalog.go剖析该模型背后的任务状态机与产物位置信息帮助开发者正确接入 lakeFS 的 GC 提交准备流程。一、模型定义与字段说明PrepareGarbageCollectionCommitsStatus在 OpenAPI 规范中的定义位于 api/swagger.yml其属性如下字段名类型说明备注task_idString正在准备 GC commits 的任务 ID必填completedbool任务是否已完成成功或出错都算完成必填update_timeString任务状态最后一次更新的时间必填格式为 date-timeresultOptionGarbageCollectionPrepareResponse任务成功后的产物信息可选errorOptionError任务失败时的错误信息可选其中required字段task_id、completed、update_time在服务端响应中一定会出现而result与error视任务状态而定任务成功完成时completedtrue且result携带本次 GC 运行的产物位置任务执行失败时completedtrue且error携带错误消息任务仍在运行时completedfalseresult与error均为空。二、Rust 端源码实现Rust SDK 中对应的结构体定义在 clients/rust/src/models/prepare_garbage_collection_commits_status.rs由 openapi-generator 从 api/swagger.yml 生成并注册在 clients/rust/src/models/mod.rs#[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)] pub struct PrepareGarbageCollectionCommitsStatus { /// the id of the task preparing the GC commits #[serde(rename task_id)] pub task_id: String, /// true if the task has completed (either successfully or with an error) #[serde(rename completed)] pub completed: bool, /// last time the task status was updated #[serde(rename update_time)] pub update_time: String, #[serde(rename result, skip_serializing_if Option::is_none)] pub result: OptionBoxmodels::GarbageCollectionPrepareResponse, #[serde(rename error, skip_serializing_if Option::is_none)] pub error: OptionBoxmodels::Error, }值得注意的实现细节字段命名Rust 端字段采用 snake_casetask_id、update_time通过#[serde(rename ...)]与 JSON 中的 snake_case 键一一对应因此直接对服务端响应做serde_json::from_str即可完成反序列化。可选字段的序列化result与error标注了skip_serializing_if Option::is_none即构造请求体如单元测试中构造该结构时未设置的可选字段不会出现在序列化结果中。Box 包裹两个嵌套模型GarbageCollectionPrepareResponse、Error被Box包裹这是递归数据结构的常见优化写法不影响 API 使用。构造函数SDK 提供new(task_id, completed, update_time)便捷构造函数默认把result、error置为None用于测试或手动构造状态对象。三、关联模型result 与 error3.1 GarbageCollectionPrepareResponseresultresult字段指向 clients/rust/docs/GarbageCollectionPrepareResponse.md 中定义的模型它描述了一次 GC 准备运行run的产物字段名类型说明run_idString本次 GC 作业生成的唯一标识gc_commits_locationString生成的 commits CSV 表位置按 run_id 分区gc_addresses_locationString过期地址 parquet 表的写入位置按 run_id 分区gc_commits_presigned_urlOptionString下载 commits CSV 的预签名 URL可选3.2 Errorerrorerror字段指向 clients/rust/docs/Error.md 中定义的模型仅包含一个message字段String用于给出简要错误说明。服务端在任务失败时会把底层任务的ErrorMsg写入该对象见下文源码剖析。四、底层 API 与调用链4.1 启动异步任务在 clients/rust/docs/InternalApi.md 中InternalApi 提供两个相关的入口prepare_garbage_collection_commits同步POST /repositories/{repository}/gc/prepare_commits直接返回GarbageCollectionPrepareResponseprepare_garbage_collection_commits_async异步POST /repositories/{repository}/gc/prepare_commits/async返回TaskCreation仅含任务 ID。异步接口用于大仓库场景生成活动提交列表可能耗时较长服务端会把它放入后台任务执行客户端拿到任务 ID 后轮询状态。TaskCreation模型定义在 clients/rust/docs/TaskCreation.md只有一个id字段。4.2 查询任务状态状态查询接口签名clients/rust/docs/InternalApi.mdGET /repositories/{repository}/gc/prepare_commits/status?id{id}参数说明参数类型说明是否必填repositoryString仓库名必填idString准备 GC commits 任务的唯一标识必填返回类型为models::PrepareGarbageCollectionCommitsStatus。认证支持basic_auth、cookie_auth、jwt_tokenAccept 头为application/json。Rust SDK 的对应实现位于 clients/rust/src/apis/internal_api.rspub async fn prepare_garbage_collection_commits_status( configuration: configuration::Configuration, repository: str, id: str, ) - Resultmodels::PrepareGarbageCollectionCommitsStatus, ErrorPrepareGarbageCollectionCommitsStatusError { let local_var_uri_str format!( {}/repositories/{repository}/gc/prepare_commits/status, local_var_configuration.base_path, repository crate::apis::urlencode(repository) ); let mut local_var_req_builder local_var_client.request(reqwest::Method::GET, local_var_uri_str.as_str()); local_var_req_builder local_var_req_builder.query([(id, id.to_string())]); // ... 认证头注入User-Agent / basic_auth / bearer_access_token ... let local_var_resp local_var_client.execute(local_var_req).await?; // 2xx 时通过 serde_json::from_str 反序列化为 PrepareGarbageCollectionCommitsStatus }调用要点使用reqwest发送 GET 请求id以 query 参数形式传递认证信息从configuration中读取支持 Basic Auth 与 Bearer Token成功响应直接反序列化为PrepareGarbageCollectionCommitsStatus非 2xx 响应包装为ErrorPrepareGarbageCollectionCommitsStatusError类型别名定义在同文件 clients/rust/src/apis/internal_api.rs 附近。4.3 典型轮询流程结合三个接口一个完整的 GC Commits 准备流程如下调用prepare_garbage_collection_commits_async(repository)获得任务 IDTaskCreation.id循环调用prepare_garbage_collection_commits_status(repository, id)直到completed true若error非空说明任务失败按error.message处理若result非空取出run_id、gc_commits_location、gc_addresses_location及可选的gc_commits_presigned_url交给后续 GC 步骤使用。五、服务端实现剖析任务状态从哪来5.1 Controller 层组装响应PrepareGarbageCollectionCommitsStatus的 JSON 由服务端 pkg/api/controller.go 中的PrepareGarbageCollectionCommitsStatus处理器组装。该处理器的关键逻辑先做权限校验要求PrepareGarbageCollectionCommitsAction权限对应 pkg/permissions/actions.go 中定义的 GC 准备动作调用c.Catalog.GetGarbageCollectionPrepareStatus(ctx, repository, taskID)获取任务状态把任务状态映射为响应TaskId、Completed、UpdateTime来自任务的时间戳任务有错误消息时填充Error任务完成且GcCommitsLocation非空时通过BlockAdapter.GetPreSignedURL生成 commits CSV 的预签名下载 URL 并填充到result.gc_commits_presigned_url生成失败时仅记录日志不影响其余响应内容。5.2 Catalog 层的任务执行与持久化任务本身在 pkg/catalog/catalog.go 的PrepareExpiredCommitsAsync中创建taskID : NewTaskID(GarbageCollectionPrepareCommitsPrefix) // 前缀 GCPC见 pkg/catalog/catalog.go#L80 err c.RunBackgroundTaskSteps(ctx, repository, OpGCPrepareCommits, taskID, taskSteps, taskStatus)任务内容为调用c.Store.SaveGarbageCollectionCommits计算活动/过期提交并把结果RunId、GcCommitsLocation、GcAddressesLocation写入GarbageCollectionPrepareCommitsInfoproto 定义见 pkg/catalog/catalog.pb.go。状态查询路径GetGarbageCollectionPrepareStatuspkg/catalog/catalog.go通过GetValidatedTaskStatus从 KV 存储读取任务状态任务 ID 需要满足前缀校验IsTaskID(GCPC, taskID)否则视为不存在pkg/catalog/task.go。5.3 底层计算SaveGarbageCollectionCommits真正生成活动提交列表的逻辑位于 graveler 层Graveler.SaveGarbageCollectionCommitspkg/graveler/graveler.go读取仓库的 GC 规则按分支的保留天数配置交由GarbageCollectionManager.SaveGarbageCollectionCommitspkg/graveler/retention/garbage_collection_manager.go执行返回的GarbageCollectionRunMetadatapkg/graveler/graveler.go包含三个字段RunID、CommitsCSVLocation活动提交 CSV 在对象存储上的位置、AddressLocation过期地址 parquet 表的写入位置。这正是result中run_id、gc_commits_location、gc_addresses_location三个字段的来源它们指向对象存储上按run_id分区的表目录供后续 GC 作业如 Spark 端的ActiveCommitsAddressLister消费。六、多语言 SDK 对照与客户端用法参考该模型在所有官方 SDK 中均有对应实现字段命名与语义一致便于多语言项目对照语言文件路径Rustclients/rust/src/models/prepare_garbage_collection_commits_status.rsJavaclients/java/src/main/java/io/lakefs/clients/sdk/model/PrepareGarbageCollectionCommitsStatus.javaPythonclients/python/lakefs_sdk/models/prepare_garbage_collection_commits_status.pyJava 侧还有对应的单元测试 clients/java/src/test/java/io/lakefs/clients/sdk/model/PrepareGarbageCollectionCommitsStatusTest.java可参考其构造与断言方式。七、命令行参考lakectl gc 配套命令lakeFS 官方 CLIlakectl也封装了同一组接口便于不写代码直接验证实现见 cmd/lakectl/cmd/gc_prepare.go 与 cmd/lakectl/cmd/gc_check.go# 1. 异步启动 GC commits 准备任务输出任务 ID lakectl gc prepare-async lakefs://my-repo # 2. 用任务 ID 查询状态对应 PrepareGarbageCollectionCommitsStatus lakectl gc check-async lakefs://my-repo --id IDcheck-async的输出模板cmd/lakectl/cmd/gc_check.go会展示任务是否 Completed / Running失败时的错误信息成功时result存在的 Commits location、可选的 Presigned URL、Run ID最后更新时间update_time。check-async通过PrepareGarbageCollectionCommitsStatusWithResponse调用同一个状态接口收到200 OK后把响应体渲染为上面的模板——这与 Rust SDK 中反序列化到PrepareGarbageCollectionCommitsStatus后自行读取各字段是等价的。八、使用建议与注意事项用update_time判断轮询节奏任务运行期间状态不会立即刷新建议结合update_time做间隔轮询避免对服务端造成不必要的压力任务完成后该值即为最后一次更新时刻。completedtrue不代表成功按模型注释completed 表示结束成功或失败都结束。必须先判error是否为空再读取result。gc_commits_presigned_url可空服务端生成预签名 URL 失败时会继续返回其余字段见 pkg/api/controller.go因此客户端应把该字段作为可选处理必要时改从gc_commits_location直接访问对象存储。任务 ID 前缀约束服务端校验任务 ID 必须以GCPC开头pkg/catalog/task.go轮询时请使用prepare_garbage_collection_commits_async返回的原始 ID不要自行拼接或改写。产物按 run_id 分区gc_commits_location与gc_addresses_location都是按run_id分区的表路径后续 Spark GC 作业可参考 clients/spark/src/main/scala/io/treeverse/gc/ActiveCommitsAddressLister.scala需要把run_id一起传入以定位本次运行的数据。综上PrepareGarbageCollectionCommitsStatus是 lakeFS GC 异步准备流程中连接任务调度与产物消费的关键数据模型。理解其字段语义与服务端任务状态机的对应关系即可在 Rust或其他语言客户端中稳健地实现 GC Commits 的准备与轮询逻辑。赞分享数据工程数据湖大数据对象存储后端【免费下载链接】lakeFSlakeFS - Data version control for your data lake | Git for data项目地址https://gitcode.com/gh_mirrors/la/lakeFS点击查看免费下载相关推荐lakeFS Rust SDK 的 RepositoryRestoreStatus 模型详解仓库恢复异步任务的状态字段与轮询实战lakeFS Rust SDK 的 RepositoryRestoreStatus 模型详解仓库恢复异步任务的状态字段与轮询实战 导读 RepositoryR数据工程数据湖大数据对象存储后端lakeFS Rust SDK 中 TaskCreation 模型详解异步 GC 任务句柄与完整使用链路lakeFS Rust SDK 中 TaskCreation 模型详解异步 GC 任务句柄与完整使用链路 TaskCreation 是 lakeFS Rust数据工程数据湖大数据对象存储后端lakeFS Python SDK 模型解析TaskCreation —— 异步 GC 任务的标识符lakeFS Python SDK 模型解析TaskCreation —— 异步 GC 任务的标识符 导读 TaskCreation 是 lakeFS 官方数据工程数据湖大数据对象存储后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考