feat: define external snapshot API contracts (part1)

client/go.mod

@@ -7,7 +7,7 @@ require (
 	github.com/cockroachdb/errors v1.9.1
 	github.com/google/uuid v1.6.0
 	github.com/grpc-ecosystem/go-grpc-middleware v1.3.0
-	github.com/milvus-io/milvus-proto/go-api/v3 v3.0.0-20260514121806-9b60a053353f
+	github.com/milvus-io/milvus-proto/go-api/v3 v3.0.0-20260608071413-e90ee63ad3fc
 	github.com/milvus-io/milvus/pkg/v3 v3.0.0-beta
 	github.com/quasilyte/go-ruleguard/dsl v0.3.23
 	github.com/samber/lo v1.52.0

client/go.sum

@@ -222,8 +222,8 @@ github.com/mattn/go-isatty v0.0.14/go.mod h1:7GGIvUiUoEMVVmxf/4nioHXj79iQHKdU27k
 github.com/mattn/goveralls v0.0.2/go.mod h1:8d1ZMHsd7fW6IRPKQh46F2WRpyib5/X4FOpevwGNQEw=
 github.com/mediocregopher/radix/v3 v3.4.2/go.mod h1:8FL3F6UQRXHXIBSPUs5h0RybMF8i4n7wVopoX3x7Bv8=
 github.com/microcosm-cc/bluemonday v1.0.2/go.mod h1:iVP4YcDBq+n/5fb23BhYFvIMq/leAFZyRl6bYmGDlGc=
-github.com/milvus-io/milvus-proto/go-api/v3 v3.0.0-20260514121806-9b60a053353f h1:Z2paGeFL0i1a3Dqw82DwRwZ2ix3FtyKU7+u6rR7jbUs=
-github.com/milvus-io/milvus-proto/go-api/v3 v3.0.0-20260514121806-9b60a053353f/go.mod h1:rbKpv5JToISTKTTLl0duL5r6wbYnjJ9SsD0QgXMzKy0=
+github.com/milvus-io/milvus-proto/go-api/v3 v3.0.0-20260608071413-e90ee63ad3fc h1:xCVd6Oei8Y+Qo2vRXkpz8aT+7L/8F5hGXxZZctwiHCk=
+github.com/milvus-io/milvus-proto/go-api/v3 v3.0.0-20260608071413-e90ee63ad3fc/go.mod h1:rbKpv5JToISTKTTLl0duL5r6wbYnjJ9SsD0QgXMzKy0=
 github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
 github.com/mitchellh/mapstructure v1.1.2/go.mod h1:FVVH3fgwuzCH5S8UJGiWEs2h04kUh9fWfEaFds41c1Y=
 github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=

client/milvusclient/snapshot.go

@@ -111,6 +111,58 @@ func (c *Client) RestoreSnapshot(ctx context.Context, opt RestoreSnapshotOption,
 	return jobID, err
 }
 
+func (c *Client) RestoreExternalSnapshot(ctx context.Context, opt RestoreExternalSnapshotOption, callOptions ...grpc.CallOption) (int64, error) {
+	if opt == nil {
+		return 0, merr.WrapErrParameterInvalid("RestoreExternalSnapshotOption", "nil", "option cannot be nil")
+	}
+	req := opt.Request()
+	if req.DbName == "" {
+		req.DbName = c.getCurrentDB()
+	}
+	if timeout := opt.RequestTimeout(); timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, timeout)
+		defer cancel()
+	}
+
+	var jobID int64
+	err := c.callService(func(milvusService milvuspb.MilvusServiceClient) error {
+		resp, err := milvusService.RestoreExternalSnapshot(ctx, req, callOptions...)
+		if err := merr.CheckRPCCall(resp, err); err != nil {
+			return err
+		}
+		jobID = resp.GetJobId()
+		return nil
+	})
+	return jobID, err
+}
+
+func (c *Client) ExportSnapshot(ctx context.Context, opt ExportSnapshotOption, callOptions ...grpc.CallOption) (string, error) {
+	if opt == nil {
+		return "", merr.WrapErrParameterInvalid("ExportSnapshotOption", "nil", "option cannot be nil")
+	}
+	req := opt.Request()
+	if req.DbName == "" {
+		req.DbName = c.getCurrentDB()
+	}
+	if timeout := opt.RequestTimeout(); timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, timeout)
+		defer cancel()
+	}
+
+	var snapshotMetadataURI string
+	err := c.callService(func(milvusService milvuspb.MilvusServiceClient) error {
+		resp, err := milvusService.ExportSnapshot(ctx, req, callOptions...)
+		if err := merr.CheckRPCCall(resp, err); err != nil {
+			return err
+		}
+		snapshotMetadataURI = resp.GetSnapshotMetadataUri()
+		return nil
+	})
+	return snapshotMetadataURI, err
+}
+
 // GetRestoreSnapshotState gets the state of a restore snapshot job
 func (c *Client) GetRestoreSnapshotState(ctx context.Context, opt GetRestoreSnapshotStateOption, callOptions ...grpc.CallOption) (*milvuspb.RestoreSnapshotInfo, error) {
 	if opt == nil {

client/milvusclient/snapshot_options.go

@@ -17,6 +17,8 @@
 package milvusclient
 
 import (
+	"time"
+
 	"github.com/milvus-io/milvus-proto/go-api/v3/commonpb"
 	"github.com/milvus-io/milvus-proto/go-api/v3/milvuspb"
 )
@@ -206,6 +208,112 @@ func NewRestoreSnapshotOption(name string, collectionName string, targetCollecti
 	}
 }
 
+type RestoreExternalSnapshotOption interface {
+	Request() *milvuspb.RestoreExternalSnapshotRequest
+	RequestTimeout() time.Duration
+}
+
+type restoreExternalSnapshotOption struct {
+	dbName               string
+	targetCollectionName string
+	snapshotMetadataURI  string
+	externalSpec         string
+	requestTimeout       time.Duration
+}
+
+func (opt *restoreExternalSnapshotOption) Request() *milvuspb.RestoreExternalSnapshotRequest {
+	return &milvuspb.RestoreExternalSnapshotRequest{
+		DbName:               opt.dbName,
+		TargetCollectionName: opt.targetCollectionName,
+		SnapshotMetadataUri:  opt.snapshotMetadataURI,
+		ExternalSpec:         opt.externalSpec,
+	}
+}
+
+func (opt *restoreExternalSnapshotOption) WithDbName(dbName string) *restoreExternalSnapshotOption {
+	opt.dbName = dbName
+	return opt
+}
+
+func (opt *restoreExternalSnapshotOption) WithExternalSpec(externalSpec string) *restoreExternalSnapshotOption {
+	opt.externalSpec = externalSpec
+	return opt
+}
+
+func (opt *restoreExternalSnapshotOption) WithRequestTimeout(timeout time.Duration) *restoreExternalSnapshotOption {
+	opt.requestTimeout = timeout
+	return opt
+}
+
+func (opt *restoreExternalSnapshotOption) RequestTimeout() time.Duration {
+	if opt.requestTimeout <= 0 {
+		return 120 * time.Second
+	}
+	return opt.requestTimeout
+}
+
+func NewRestoreExternalSnapshotOption(targetCollectionName string, snapshotMetadataURI string) *restoreExternalSnapshotOption {
+	return &restoreExternalSnapshotOption{
+		targetCollectionName: targetCollectionName,
+		snapshotMetadataURI:  snapshotMetadataURI,
+	}
+}
+
+type ExportSnapshotOption interface {
+	Request() *milvuspb.ExportSnapshotRequest
+	RequestTimeout() time.Duration
+}
+
+type exportSnapshotOption struct {
+	name           string
+	dbName         string
+	collectionName string
+	targetS3Path   string
+	externalSpec   string
+	requestTimeout time.Duration
+}
+
+func (opt *exportSnapshotOption) Request() *milvuspb.ExportSnapshotRequest {
+	return &milvuspb.ExportSnapshotRequest{
+		Base:           &commonpb.MsgBase{},
+		Name:           opt.name,
+		DbName:         opt.dbName,
+		CollectionName: opt.collectionName,
+		TargetS3Path:   opt.targetS3Path,
+		ExternalSpec:   opt.externalSpec,
+	}
+}
+
+func (opt *exportSnapshotOption) WithDbName(dbName string) *exportSnapshotOption {
+	opt.dbName = dbName
+	return opt
+}
+
+func (opt *exportSnapshotOption) WithExternalSpec(externalSpec string) *exportSnapshotOption {
+	opt.externalSpec = externalSpec
+	return opt
+}
+
+func (opt *exportSnapshotOption) WithRequestTimeout(timeout time.Duration) *exportSnapshotOption {
+	opt.requestTimeout = timeout
+	return opt
+}
+
+func (opt *exportSnapshotOption) RequestTimeout() time.Duration {
+	if opt.requestTimeout <= 0 {
+		return 120 * time.Second
+	}
+	return opt.requestTimeout
+}
+
+func NewExportSnapshotOption(name string, collectionName string, targetS3Path string) *exportSnapshotOption {
+	return &exportSnapshotOption{
+		name:           name,
+		collectionName: collectionName,
+		targetS3Path:   targetS3Path,
+	}
+}
+
 // GetRestoreSnapshotStateOption interface for getting restore snapshot state options
 type GetRestoreSnapshotStateOption interface {
 	Request() *milvuspb.GetRestoreSnapshotStateRequest