lakeFS Java SDK 中的 ImportCreation:对象存储数据导入请求模型详解

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

lakeFS Java SDK 中的 ImportCreation:对象存储数据导入请求模型详解

导读

本文聚焦 lakeFS Java SDK 中负责发起对象存储导入任务的请求模型 ImportCreation,它是调用 POST /repositories/{repository}/branches/{branch}/import 接口(ImportApi#importStart)时提交的核心请求体。读完本文,你将掌握 ImportCreation 的 paths、commit、force 三个字段的语义与使用约束,理解它与 ImportLocation、CommitCreation 的嵌套关系,并通过源码了解 lakeFS 服务端处理导入请求的完整链路。

ImportCreation 在 lakeFS 数据导入体系中的定位

lakeFS 的"导入"(Import)能力允许用户把外部对象存储(如 S3、GCS、Azure Blob)中已有的数据,以不复制对象本体的方式注册进 lakeFS 仓库的某个分支,并随之生成一次提交,从而让这些数据立即获得版本控制能力。整个导入流程由三个接口组成(见 ImportApi.md):

接口 HTTP 方法与路径 说明
importStart POST /repositories/{repository}/branches/{branch}/import 提交导入请求,请求体即 ImportCreation,返回 ImportCreationResponse
importStatus GET /repositories/{repository}/branches/{branch}/import 查询导入任务进度,返回 ImportStatus
importCancel DELETE /repositories/{repository}/branches/{branch}/import 取消进行中的导入任务

ImportCreation 就是其中 importStart 的请求体模型,是整个导入功能的"入口单据"。在 OpenAPI 规范 swagger.yml 中,它被定义为包含两个必填字段(paths、commit)和一个可选字段(force)的对象。

字段详解

ImportCreation 共三个字段,完整定义如下(源自 ImportCreation.md 及 Java 实现 ImportCreation.java):

字段名 类型 必填 说明
paths List<ImportLocation> 是 导入源位置列表,可同时导入多个源
commit CommitCreation 是 导入完成后自动生成的提交(commit)的创建参数
force Boolean 否 是否强制写入,默认 false

从 ImportCreation.java 的校验逻辑可以看出服务端对字段的硬性要求:paths 和 commit 同时出现在 openapiRequiredFields 中,即请求体中二者缺一不可;而 force 未在必填集合内。反序列化时,如果请求缺少必填字段或 paths 不是 JSON 数组,会抛出 IllegalArgumentException。

paths:导入源与目标映射列表

paths 是一个 ImportLocation 数组。每个 ImportLocation(见 ImportLocation.md)包含三个字段:

字段名 类型 说明
type TypeEnum 路径类型,取值为 common_prefix 或 object
path String 源位置,指向一个 common_prefix(前缀)或单个 object(对象),必须匹配 lakeFS 安装所配置的 blockstore 类型,例如 s3://my-bucket/production/collections/
destination String 导入对象在目标分支上的位置。若 type 为 object,则是该对象在分支下的精确对象名;若为 common_prefix,则是分支下的前缀

TypeEnum 的可选值在 swagger.yml 中限定为 common_prefix 与 object 二选一。这两个类型对应服务端 pkg/catalog/catalog.go 中定义的 ImportPathTypePrefix 与 ImportPathTypeObject(见 catalog.go),GetImportPathType 会校验传入的字符串是否合法。

swagger.yml 给出了一个同时使用两种类型、双路径的示例请求体(见 swagger.yml):

{
  "commit": {
    "message": "Importing collections from S3"
  },
  "paths": [
    {
      "path": "s3://my-bucket/production/collections/",
      "destination": "collections/",
      "type": "common_prefix"
    },
    {
      "path": "s3://my-bucket/production/collections/file1",
      "destination": "collections/file1",
      "type": "object"
    }
  ]
}

该示例同时演示了两种典型用法:用 common_prefix 一次导入整个目录树,用 object 精确导入单个文件。

commit:导入提交的创建参数

commit 字段类型为 CommitCreation(见 CommitCreation.md),用于描述导入任务完成后自动创建的提交:

字段名 类型 必填 说明
message String 是 提交信息
metadata Map<String, String> 否 附加元数据键值对
date Long 否 覆盖提交创建时间(Unix 时间戳,秒)
allowEmpty Boolean 否 是否允许提交不包含任何变更
force Boolean 否 提交强制选项

服务端会把 message 与 metadata 带入最终的提交记录:在 controller.go 中,body.Commit.Message 与 body.Commit.Metadata 被提取进 catalog.ImportCommit;若用户未填写 message,服务端会在 catalog.go 自动使用默认提交信息 "Import objects"。提交者(committer)则由服务端从当前认证用户中解析,客户端无需也不应指定。

force:强制写入开关

force 为可选布尔字段,默认 false(ImportCreation.java)。服务端在 controller.go 通过 swag.BoolValue(body.Force) 读取其值,并一路透传到 range/metarange 写入(graveler.WithForce(params.Force),见 catalog.go)与提交创建(catalog.go),用于控制底层写入操作是否允许强制覆盖已存在的对象。

完整的导入调用链:请求、轮询、取消

ImportCreation 仅用于发起导入。一次完整的导入实践通常包含三步:

  1. 发起:调用 importStart(repository, branch, importCreation),成功时返回 HTTP 202 Accepted 及 ImportCreationResponse,其中 id 字段是导入进程的唯一标识(见 ImportCreationResponse.md)。
  2. 轮询:携带上一步拿到的 id 调用 importStatus(repository, branch, id),通过返回的 ImportStatus 判断进度。ImportStatus(见 ImportStatus.md)包含 completed、updateTime、ingestedObjects(已处理对象数)、metarangeId、commit 与 error 等字段。
  3. 取消:需要中止时调用 importCancel(repository, branch, id),成功返回 HTTP 204 No Content。

Java SDK 调用示例

以下代码演示用 Java SDK 构造 ImportCreation 并启动一次导入(认证与客户端配置部分参照 ImportApi.md):

// Import classes:
import io.lakefs.clients.sdk.ApiClient;
import io.lakefs.clients.sdk.ApiException;
import io.lakefs.clients.sdk.Configuration;
import io.lakefs.clients.sdk.auth.*;
import io.lakefs.clients.sdk.ImportApi;
import io.lakefs.clients.sdk.model.*;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = Configuration.getDefaultApiClient();
    defaultClient.setBasePath("http://localhost:8000/api/v1");

    // 认证方式三选一:basic_auth / cookie_auth / jwt_token
    HttpBasicAuth basic_auth = (HttpBasicAuth) defaultClient.getAuthentication("basic_auth");
    basic_auth.setUsername("YOUR USERNAME");
    basic_auth.setPassword("YOUR PASSWORD");

    ImportApi apiInstance = new ImportApi(defaultClient);
    String repository = "my-repo";
    String branch = "main";

    // 1. 构造导入源
    ImportLocation loc = new ImportLocation()
        .path("s3://my-bucket/production/collections/")
        .destination("collections/")
        .type(ImportLocation.TypeEnum.COMMON_PREFIX);

    // 2. 构造提交参数
    CommitCreation commit = new CommitCreation()
        .message("Importing collections from S3");

    // 3. 组装 ImportCreation 请求体
    ImportCreation importCreation = new ImportCreation()
        .addPathsItem(loc)
        .commit(commit)
        .force(false);

    try {
      // 发起导入,返回进程 id
      ImportCreationResponse resp = apiInstance
          .importStart(repository, branch, importCreation)
          .execute();
      String id = resp.getId();
      System.out.println("Import started, id=" + id);

      // 轮询状态直至完成
      ImportStatus status;
      do {
        Thread.sleep(5000);
        status = apiInstance.importStatus(repository, branch, id).execute();
        System.out.println("ingested objects: " + status.getIngestedObjects());
      } while (!Boolean.TRUE.equals(status.getCompleted()));
    } catch (ApiException e) {
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      e.printStackTrace();
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
    }
  }
}

SDK 侧对请求体的序列化与校验由 Gson 驱动:ImportCreation 内建的 CustomTypeAdapterFactory(见 ImportCreation.java)在序列化时剔除 additionalProperties,在反序列化时先调用 validateJsonElement 校验必填字段,再通过 fromJson/toJson 与 JSON 字符串互转(ImportCreation.java)。

服务端如何消费 ImportCreation:源码级原理

权限校验

服务端 ImportStart 处理器(controller.go)对请求做组合权限校验:调用方必须同时拥有目标分支的 WriteObjectAction 与 CreateCommitAction;此外,对 paths 中每个源,还需具备对应源位置的 ImportFromStorageAction 与目标位置的 WriteObjectAction。这意味着 paths 列表的每一项都会参与权限判定。

路径安全校验与存储类型检查

  • 存储支持检查:lakeFS 会通过 GetStorageNamespaceInfo 检查当前仓库的存储后端是否支持导入,若不支持(ImportSupport == false)则直接返回 403 Forbidden(controller.go)。
  • 路径合法性:verifyImportPaths(catalog.go)禁止导入源位于仓库自身存储命名空间内部或包含仓库命名空间,防止把 lakeFS 管理的对象误当成外部数据导入。

异步执行与状态持久化

Import(catalog.go)首先为任务生成唯一 ID(基于 xid),把初始状态写入 KV 存储(避免返回响应后状态不可见,即代码注释提到的 race condition 问题),随后异步执行真正的导入:importAsync(catalog.go)为每个 paths 项创建对象存储 walker 与 WalkEntryIterator,并行摄取对象,然后写入 range、合并 metarange,最后调用 Store.Import 生成提交并更新状态为 completed。这也是为什么 importStart 返回 202 Accepted 而非 200——导入是后台任务,需要配合 importStatus 轮询。

取消语义

CancelImport(catalog.go)会先检查任务状态:若任务已完成则返回冲突错误(graveler.ErrConflictFound),否则把错误标记为 ImportCanceled 写入 KV 存储,使异步任务感知取消并中止后续写入。

小结

ImportCreation 是 lakeFS 数据导入功能的请求载体:paths 声明"从哪里导、导到哪"(支持 common_prefix 与 object 两种粒度),commit 定义导入完成后自动提交的元信息,force 控制底层写入是否允许强制覆盖。理解这个模型,配合 importStart / importStatus / importCancel 三个接口,即可用 Java SDK 完整驱动 lakeFS 的对象存储数据导入流程。相关模型与接口文档可继续阅读 ImportApi.md、ImportLocation.md、CommitCreation.md、ImportStatus.md 与 ImportCreationResponse.md;服务端实现细节可参考 pkg/api/controller.go 与 pkg/catalog/catalog.go。

登录后查看全文
lakeFS