From 2ebaaa5694cfabb4d337330b090e56a3d6ef00ba Mon Sep 17 00:00:00 2001 From: ButterBright Date: Sun, 7 Dec 2025 21:08:44 +0800 Subject: [PATCH 1/3] Bump up API to support bulk write --- .../proto/banyandb/v1/banyandb-measure.proto | 24 +++++++++++++++++++ .../proto/banyandb/v1/banyandb-stream.proto | 18 +++++++++++--- .../proto/banyandb/v1/banyandb-trace.proto | 10 +++++--- 3 files changed, 46 insertions(+), 6 deletions(-) diff --git a/src/main/proto/banyandb/v1/banyandb-measure.proto b/src/main/proto/banyandb/v1/banyandb-measure.proto index 41602658..ce92d710 100644 --- a/src/main/proto/banyandb/v1/banyandb-measure.proto +++ b/src/main/proto/banyandb/v1/banyandb-measure.proto @@ -156,13 +156,31 @@ message TopNRequest { repeated string stages = 9; } +// TagFamilySpec defines the specification of a tag family. +message TagFamilySpec { + // name of the tag family + string name = 1; + // names of tags in the tag family + repeated string tag_names = 2; +} + +// DataPointSpec defines the specification of a data point. +message DataPointSpec { + // the tag family specification + repeated TagFamilySpec tag_family_spec = 1; + // the field names + repeated string field_names = 2; +} + // DataPointValue is the data point for writing. It only contains values. message DataPointValue { // timestamp is in the timeunit of milliseconds. google.protobuf.Timestamp timestamp = 1 [(validate.rules).timestamp.required = true]; // the order of tag_families' items match the measure schema + // the order of tag_families' items match DataPointSpec repeated model.v1.TagFamilyForWrite tag_families = 2 [(validate.rules).repeated.min_items = 1]; // the order of fields match the measure schema + // the order of fields match DataPointSpec repeated model.v1.FieldValue fields = 3; // the version of the data point int64 version = 4; @@ -172,10 +190,16 @@ message DataPointValue { message WriteRequest { // the metadata is required. common.v1.Metadata metadata = 1 [(validate.rules).message.required = true]; + // the metadata is required only for the first request of gRPC stream. + common.v1.Metadata metadata = 1; // the data_point is required. DataPointValue data_point = 2 [(validate.rules).message.required = true]; // the message_id is required. uint64 message_id = 3 [(validate.rules).uint64.gt = 0]; + // the data point specification. + // If this is not set with the indicated metadata, use the schema definition. + // If this is not set, use the existing spec declaration from previous requests in the current gRPC stream. + DataPointSpec data_point_spec = 4; } // WriteResponse is the response contract for write diff --git a/src/main/proto/banyandb/v1/banyandb-stream.proto b/src/main/proto/banyandb/v1/banyandb-stream.proto index 5f1f8a6c..e3512d59 100644 --- a/src/main/proto/banyandb/v1/banyandb-stream.proto +++ b/src/main/proto/banyandb/v1/banyandb-stream.proto @@ -80,6 +80,14 @@ message QueryRequest { repeated string stages = 10; } +// TagFamilySpec defines the specification of a tag family. +message TagFamilySpec { + // name of the tag family + string name = 1; + // names of tags in the tag family + repeated string tag_names = 2; +} + message ElementValue { // element_id could be span_id of a Span or segment_id of a Segment in the context of stream string element_id = 1; @@ -87,17 +95,21 @@ message ElementValue { // 1) either the start time of a Span/Segment, // 2) or the timestamp of a log google.protobuf.Timestamp timestamp = 2; - // the order of tag_families' items match the stream schema + // the order of tag_families' items match TagFamilySpec repeated model.v1.TagFamilyForWrite tag_families = 3; } message WriteRequest { - // the metadata is required. - common.v1.Metadata metadata = 1 [(validate.rules).message.required = true]; + // the metadata is required only for the first request of gRPC stream. + common.v1.Metadata metadata = 1; // the element is required. ElementValue element = 2 [(validate.rules).message.required = true]; // the message_id is required. uint64 message_id = 3 [(validate.rules).uint64.gt = 0]; + // the tag family specification. + // If this is not set with the indicated metadata, use the schema definition. + // If this is not set, use the existing spec declaration from previous requests in the current gRPC stream. + repeated TagFamilySpec tag_family_spec = 4; } message WriteResponse { diff --git a/src/main/proto/banyandb/v1/banyandb-trace.proto b/src/main/proto/banyandb/v1/banyandb-trace.proto index d58c969d..23650051 100644 --- a/src/main/proto/banyandb/v1/banyandb-trace.proto +++ b/src/main/proto/banyandb/v1/banyandb-trace.proto @@ -25,12 +25,16 @@ import "banyandb/v1/banyandb-model.proto"; option go_package = "github.com/apache/skywalking-banyandb/api/proto/banyandb/trace/v1"; option java_package = "org.apache.skywalking.banyandb.trace.v1"; -// Write messages +message TagSpec { + repeated string tag_names = 1; +} + message WriteRequest { common.v1.Metadata metadata = 1; - repeated model.v1.TagValue tags = 2; + repeated model.v1.TagValue tags = 2 [(validate.rules).repeated.min_items = 1]; bytes span = 3; - uint64 version = 4; + uint64 version = 4 [(validate.rules).uint64.gt = 0]; + TagSpec tag_spec = 5; } message WriteResponse { From 784303f4380ed57cdbb491001e5460ff32e2b3fe Mon Sep 17 00:00:00 2001 From: ButterBright Date: Sun, 7 Dec 2025 21:14:12 +0800 Subject: [PATCH 2/3] fix: add missing import for validation in banyandb-trace.proto --- src/main/proto/banyandb/v1/banyandb-trace.proto | 1 + 1 file changed, 1 insertion(+) diff --git a/src/main/proto/banyandb/v1/banyandb-trace.proto b/src/main/proto/banyandb/v1/banyandb-trace.proto index 23650051..15494350 100644 --- a/src/main/proto/banyandb/v1/banyandb-trace.proto +++ b/src/main/proto/banyandb/v1/banyandb-trace.proto @@ -21,6 +21,7 @@ package banyandb.trace.v1; import "banyandb/v1/banyandb-common.proto"; import "banyandb/v1/banyandb-model.proto"; +import "validate/validate.proto"; option go_package = "github.com/apache/skywalking-banyandb/api/proto/banyandb/trace/v1"; option java_package = "org.apache.skywalking.banyandb.trace.v1"; From d41ad5d5010286e19c5248628f26475ce00f7ce4 Mon Sep 17 00:00:00 2001 From: ButterBright Date: Sun, 7 Dec 2025 21:23:33 +0800 Subject: [PATCH 3/3] fix: remove redundant comments and clarify metadata requirement in DataPointValue and WriteRequest --- src/main/proto/banyandb/v1/banyandb-measure.proto | 4 ---- 1 file changed, 4 deletions(-) diff --git a/src/main/proto/banyandb/v1/banyandb-measure.proto b/src/main/proto/banyandb/v1/banyandb-measure.proto index ce92d710..973edecc 100644 --- a/src/main/proto/banyandb/v1/banyandb-measure.proto +++ b/src/main/proto/banyandb/v1/banyandb-measure.proto @@ -176,10 +176,8 @@ message DataPointSpec { message DataPointValue { // timestamp is in the timeunit of milliseconds. google.protobuf.Timestamp timestamp = 1 [(validate.rules).timestamp.required = true]; - // the order of tag_families' items match the measure schema // the order of tag_families' items match DataPointSpec repeated model.v1.TagFamilyForWrite tag_families = 2 [(validate.rules).repeated.min_items = 1]; - // the order of fields match the measure schema // the order of fields match DataPointSpec repeated model.v1.FieldValue fields = 3; // the version of the data point @@ -188,8 +186,6 @@ message DataPointValue { // WriteRequest is the request contract for write message WriteRequest { - // the metadata is required. - common.v1.Metadata metadata = 1 [(validate.rules).message.required = true]; // the metadata is required only for the first request of gRPC stream. common.v1.Metadata metadata = 1; // the data_point is required.