[Breaking change] Bump APIs (#53)

Author: hanahmily

CHANGES.md

@@ -8,6 +8,7 @@ Release Notes.
 ### Features
 
 * Support JDK21 build. Upgrade lombok version to 1.18.30.
+* Bump up the API of BanyanDB Server.
 
 ### Bugs
 

src/main/java/org/apache/skywalking/banyandb/v1/client/metadata/Group.java

@@ -38,37 +38,32 @@ public abstract class Group extends NamedSchema<BanyandbCommon.Group> {
      */
     abstract int shardNum();
 
-    @Nullable
-    abstract IntervalRule blockInterval();
-
     @Nullable
     abstract IntervalRule segmentInterval();
 
     @Nullable
     abstract IntervalRule ttl();
 
-    public static Group create(String name, Catalog catalog, int shardNum, IntervalRule blockInterval, IntervalRule segmentInterval, IntervalRule ttl) {
+    public static Group create(String name, Catalog catalog, int shardNum, IntervalRule segmentInterval, IntervalRule ttl) {
         Preconditions.checkArgument(shardNum > 0, "shardNum should more than 0");
-        Preconditions.checkNotNull(blockInterval, "blockInterval is null");
         Preconditions.checkNotNull(segmentInterval, "segmentInterval is null");
         Preconditions.checkNotNull(ttl, "ttl is null");
-        return new AutoValue_Group(null, name, null, catalog, shardNum, blockInterval, segmentInterval, ttl);
+        return new AutoValue_Group(null, name, null, catalog, shardNum, segmentInterval, ttl);
     }
 
-    public static Group create(String name, Catalog catalog, int shardNum, IntervalRule blockInterval, IntervalRule segmentInterval, IntervalRule ttl, ZonedDateTime updatedAt) {
+    public static Group create(String name, Catalog catalog, int shardNum, IntervalRule segmentInterval, IntervalRule ttl, ZonedDateTime updatedAt) {
         Preconditions.checkArgument(shardNum > 0, "shardNum should more than 0");
-        Preconditions.checkNotNull(blockInterval, "blockInterval is null");
         Preconditions.checkNotNull(segmentInterval, "segmentInterval is null");
         Preconditions.checkNotNull(ttl, "ttl is null");
-        return new AutoValue_Group(null, name, updatedAt, catalog, shardNum, blockInterval, segmentInterval, ttl);
+        return new AutoValue_Group(null, name, updatedAt, catalog, shardNum, segmentInterval, ttl);
     }
 
     public static Group create(String name) {
-        return new AutoValue_Group(null, name, null, Catalog.UNSPECIFIED, 0, null, null, null);
+        return new AutoValue_Group(null, name, null, Catalog.UNSPECIFIED, 0, null, null);
     }
 
     public static Group create(String name, ZonedDateTime updatedAt) {
-        return new AutoValue_Group(null, name, updatedAt, Catalog.UNSPECIFIED, 0, null, null, null);
+        return new AutoValue_Group(null, name, updatedAt, Catalog.UNSPECIFIED, 0, null, null);
     }
 
         @Override
@@ -80,7 +75,6 @@ public BanyandbCommon.Group serialize() {
             if (shardNum() > 0) {
                 builder.setResourceOpts(BanyandbCommon.ResourceOpts.newBuilder()
                         .setShardNum(shardNum())
-                        .setBlockInterval(blockInterval().serialize())
                         .setSegmentInterval(segmentInterval().serialize())
                         .setTtl(ttl().serialize())
                         .build());
@@ -104,7 +98,6 @@ public static Group fromProtobuf(BanyandbCommon.Group group) {
                 TimeUtils.parseTimestamp(group.getUpdatedAt()),
                 catalog,
                 opts == null ? 0 : opts.getShardNum(),
-                opts == null ? null : IntervalRule.fromProtobuf(opts.getBlockInterval()),
                 opts == null ? null : IntervalRule.fromProtobuf(opts.getSegmentInterval()),
                 opts == null ? null : IntervalRule.fromProtobuf(opts.getTtl()));
     }

src/main/java/org/apache/skywalking/banyandb/v1/client/metadata/IndexRule.java

@@ -27,6 +27,7 @@
 
 import javax.annotation.Nullable;
 import java.time.ZonedDateTime;
+import java.util.Objects;
 
 @AutoValue
 public abstract class IndexRule extends NamedSchema<BanyandbDatabase.IndexRule> {
@@ -42,11 +43,6 @@ public abstract class IndexRule extends NamedSchema<BanyandbDatabase.IndexRule>
      */
     abstract IndexType indexType();
 
-    /**
-     * indexLocation indicates where to store index.
-     */
-    abstract IndexLocation indexLocation();
-
     /**
      * analyzer indicates how to analyze the value.
      */
@@ -63,20 +59,18 @@ public final IndexRule withAnalyzer(Analyzer analyzer) {
         return toBuilder().setAnalyzer(analyzer).build();
     }
 
-    public static IndexRule create(String name, IndexType indexType, IndexLocation indexLocation) {
+    public static IndexRule create(String name, IndexType indexType) {
         return new AutoValue_IndexRule.Builder().setName(name)
                 .setTags(ImmutableList.of(name))
                 .setIndexType(indexType)
-                .setIndexLocation(indexLocation)
                 .build();
     }
 
     @VisibleForTesting
-    static IndexRule create(String group, String name, IndexType indexType, IndexLocation indexLocation) {
+    static IndexRule create(String group, String name, IndexType indexType) {
         return new AutoValue_IndexRule.Builder().setGroup(group).setName(name)
                 .setTags(ImmutableList.of(name))
                 .setIndexType(indexType)
-                .setIndexLocation(indexLocation)
                 .build();
     }
 
@@ -90,8 +84,6 @@ abstract static class Builder {
 
         abstract Builder setIndexType(IndexType indexType);
 
-        abstract Builder setIndexLocation(IndexLocation indexLocation);
-
         abstract Builder setAnalyzer(Analyzer analyzer);
 
         abstract Builder setUpdatedAt(ZonedDateTime updatedAt);
@@ -104,7 +96,6 @@ public BanyandbDatabase.IndexRule serialize() {
         final BanyandbDatabase.IndexRule.Builder b = BanyandbDatabase.IndexRule.newBuilder()
                 .setMetadata(buildMetadata())
                 .addAllTags(tags())
-                .setLocation(indexLocation().location)
                 .setType(indexType().type);
         Analyzer a = analyzer();
         if (a != null) {
@@ -118,51 +109,27 @@ public BanyandbDatabase.IndexRule serialize() {
 
     public static IndexRule fromProtobuf(BanyandbDatabase.IndexRule pb) {
         IndexType indexType = IndexType.fromProtobuf(pb.getType());
-        IndexLocation indexLocation = IndexLocation.fromProtobuf(pb.getLocation());
         Analyzer analyzer = Analyzer.fromProtobuf(pb.getAnalyzer());
         return new AutoValue_IndexRule.Builder()
                 .setGroup(pb.getMetadata().getGroup())
                 .setName(pb.getMetadata().getName())
                 .setUpdatedAt(TimeUtils.parseTimestamp(pb.getUpdatedAt()))
-                .setIndexLocation(indexLocation)
                 .setIndexType(indexType)
                 .setAnalyzer(analyzer)
                 .setTags(ImmutableList.copyOf(pb.getTagsList())).build();
     }
 
     @RequiredArgsConstructor
     public enum IndexType {
-        TREE(BanyandbDatabase.IndexRule.Type.TYPE_TREE), INVERTED(BanyandbDatabase.IndexRule.Type.TYPE_INVERTED);
+        INVERTED(BanyandbDatabase.IndexRule.Type.TYPE_INVERTED);
 
         private final BanyandbDatabase.IndexRule.Type type;
 
         private static IndexType fromProtobuf(BanyandbDatabase.IndexRule.Type type) {
-            switch (type) {
-                case TYPE_TREE:
-                    return TREE;
-                case TYPE_INVERTED:
-                    return INVERTED;
-                default:
-                    throw new IllegalArgumentException("unrecognized index type");
-            }
-        }
-    }
-
-    @RequiredArgsConstructor
-    public enum IndexLocation {
-        SERIES(BanyandbDatabase.IndexRule.Location.LOCATION_SERIES), GLOBAL(BanyandbDatabase.IndexRule.Location.LOCATION_GLOBAL);
-
-        private final BanyandbDatabase.IndexRule.Location location;
-
-        private static IndexLocation fromProtobuf(BanyandbDatabase.IndexRule.Location loc) {
-            switch (loc) {
-                case LOCATION_GLOBAL:
-                    return GLOBAL;
-                case LOCATION_SERIES:
-                    return SERIES;
-                default:
-                    throw new IllegalArgumentException("unrecognized index location");
+            if (Objects.requireNonNull(type) == BanyandbDatabase.IndexRule.Type.TYPE_INVERTED) {
+                return INVERTED;
             }
+            throw new IllegalArgumentException("unrecognized index type");
         }
     }
 

src/main/proto/banyandb/v1/banyandb-common.proto

@@ -35,7 +35,9 @@ message Metadata {
   // group contains a set of options, like retention policy, max
   string group = 1;
   // name of the entity
-  string name = 2 [(validate.rules).string.min_len = 1];
+  string name = 2;
+  // id is the unique identifier of the entity
+  // if id is not set, the system will generate a unique id
   uint32 id = 3;
   // readonly. create_revision is the revision of last creation on this key.
   int64 create_revision = 4;
@@ -58,13 +60,10 @@ message IntervalRule {
 message ResourceOpts {
   // shard_num is the number of shards
   uint32 shard_num = 1 [(validate.rules).uint32.gt = 0];
-  // block_interval indicates the length of a block
-  // block_interval should be less than or equal to segment_interval
-  IntervalRule block_interval = 2 [(validate.rules).message.required = true];
   // segment_interval indicates the length of a segment
-  IntervalRule segment_interval = 3 [(validate.rules).message.required = true];;
+  IntervalRule segment_interval = 2 [(validate.rules).message.required = true];
   // ttl indicates time to live, how long the data will be cached
-  IntervalRule ttl = 4 [(validate.rules).message.required = true];
+  IntervalRule ttl = 3 [(validate.rules).message.required = true];
 }
 
 // Group is an internal object for Group management

src/main/proto/banyandb/v1/banyandb-database.proto

@@ -22,6 +22,7 @@ option java_package = "org.apache.skywalking.banyandb.database.v1";
 package banyandb.database.v1;
 
 import "google/protobuf/timestamp.proto";
+import "validate/validate.proto";
 import "banyandb/v1/banyandb-common.proto";
 import "banyandb/v1/banyandb-model.proto";
 
@@ -32,18 +33,17 @@ enum TagType {
   TAG_TYPE_STRING_ARRAY = 3;
   TAG_TYPE_INT_ARRAY = 4;
   TAG_TYPE_DATA_BINARY = 5;
-  TAG_TYPE_ID = 6;
 }
 
 message TagFamilySpec {
-  string name = 1;
+  string name = 1 [(validate.rules).string.min_len = 1];
   // tags defines accepted tags
-  repeated TagSpec tags = 2;
+  repeated TagSpec tags = 2 [(validate.rules).repeated.min_items = 1];
 }
 
 message TagSpec {
-  string name = 1;
-  TagType type = 2;
+  string name = 1 [(validate.rules).string.min_len = 1];
+  TagType type = 2 [(validate.rules).enum.defined_only = true];
   // indexed_only indicates whether the tag is stored
   // True: It's indexed only, but not stored
   // False: it's stored and indexed
@@ -53,17 +53,17 @@ message TagSpec {
 // Stream intends to store streaming data, for example, traces or logs
 message Stream {
   // metadata is the identity of a trace series
-  common.v1.Metadata metadata = 1;
+  common.v1.Metadata metadata = 1 [(validate.rules).message.required = true];
   // tag_families
-  repeated TagFamilySpec tag_families = 2;
+  repeated TagFamilySpec tag_families = 2 [(validate.rules).repeated.min_items = 1];
   // entity indicates how to generate a series and shard a stream
-  Entity entity = 3;
+  Entity entity = 3 [(validate.rules).message.required = true];
   // updated_at indicates when the stream is updated
   google.protobuf.Timestamp updated_at = 4;
 }
 
 message Entity {
-  repeated string tag_names = 1;
+  repeated string tag_names = 1 [(validate.rules).repeated.min_items = 1];
 }
 
 enum FieldType {
@@ -87,25 +87,25 @@ enum CompressionMethod {
 // FieldSpec is the specification of field
 message FieldSpec {
   // name is the identity of a field
-  string name = 1;
+  string name = 1 [(validate.rules).string.min_len = 1];
   // field_type denotes the type of field value
-  FieldType field_type = 2;
+  FieldType field_type = 2 [(validate.rules).enum.defined_only = true];
   // encoding_method indicates how to encode data during writing
-  EncodingMethod encoding_method = 3;
+  EncodingMethod encoding_method = 3 [(validate.rules).enum.defined_only = true];
   // compression_method indicates how to compress data during writing
-  CompressionMethod compression_method = 4;
+  CompressionMethod compression_method = 4 [(validate.rules).enum.defined_only = true];
 }
 
 // Measure intends to store data point
 message Measure {
   // metadata is the identity of a measure
-  common.v1.Metadata metadata = 1;
+  common.v1.Metadata metadata = 1 [(validate.rules).message.required = true];
   // tag_families are for filter measures
-  repeated TagFamilySpec tag_families = 2;
+  repeated TagFamilySpec tag_families = 2 [(validate.rules).repeated.min_items = 1];
   // fields denote measure values
   repeated FieldSpec fields = 3;
   // entity indicates which tags will be to generate a series and shard a measure
-  Entity entity = 4;
+  Entity entity = 4 [(validate.rules).message.required = true];
   // interval indicates how frequently to send a data point
   // valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h", "d".
   string interval = 5;
@@ -116,15 +116,16 @@ message Measure {
 // TopNAggregation generates offline TopN statistics for a measure's TopN approximation
 message TopNAggregation {
   // metadata is the identity of an aggregation
-  common.v1.Metadata metadata = 1;
+  common.v1.Metadata metadata = 1 [(validate.rules).message.required = true];
   // source_measure denotes the data source of this aggregation
-  common.v1.Metadata source_measure = 2;
+  common.v1.Metadata source_measure = 2 [(validate.rules).message.required = true];
   // field_name is the name of field used for ranking
-  string field_name = 3;
+  string field_name = 3 [(validate.rules).string.min_len = 1];
   // field_value_sort indicates how to sort fields
   // ASC: bottomN
   // DESC: topN
   // UNSPECIFIED: topN + bottomN
+  // todo validate plugin exist bug https://github.com/bufbuild/protoc-gen-validate/issues/672
   model.v1.Sort field_value_sort = 4;
   // group_by_tag_names groups data points into statistical counters
   repeated string group_by_tag_names = 5;
@@ -142,28 +143,20 @@ message TopNAggregation {
 // IndexRule should bind to a subject through an IndexRuleBinding to generate proper indices.
 message IndexRule {
   // metadata define the rule's identity
-  common.v1.Metadata metadata = 1;
+  common.v1.Metadata metadata = 1 [(validate.rules).message.required = true];
   // tags are the combination that refers to an indexed object
   // If the elements in tags are more than 1, the object will generate a multi-tag index
   // Caveat: All tags in a multi-tag MUST have an identical IndexType
-  repeated string tags = 2;
+  repeated string tags = 2 [(validate.rules).repeated.min_items = 1];
   // Type determine the index structure under the hood
   enum Type {
     TYPE_UNSPECIFIED = 0;
-    TYPE_TREE = 1;
-    TYPE_INVERTED = 2;
+    TYPE_INVERTED = 1;
   }
   // type is the IndexType of this IndexObject.
-  Type type = 3;
-  enum Location {
-    LOCATION_UNSPECIFIED = 0;
-    LOCATION_SERIES = 1;
-    LOCATION_GLOBAL = 2;
-  }
-  // location indicates where to store index.
-  Location location = 4;
+  Type type = 3 [(validate.rules).enum.defined_only = true];
   // updated_at indicates when the IndexRule is updated
-  google.protobuf.Timestamp updated_at = 5;
+  google.protobuf.Timestamp updated_at = 4;
   enum Analyzer {
     ANALYZER_UNSPECIFIED = 0;
     // Keyword analyzer is a “noop” analyzer which returns the entire input string as a single token.
@@ -176,32 +169,33 @@ message IndexRule {
     ANALYZER_SIMPLE = 3;
   }
   // analyzer analyzes tag value to support the full-text searching for TYPE_INVERTED indices.
-  Analyzer analyzer = 6;
+  Analyzer analyzer = 5;
 }
 
 // Subject defines which stream or measure would generate indices
 message Subject {
   // catalog is where the subject belongs to
+  // todo validate plugin exist bug https://github.com/bufbuild/protoc-gen-validate/issues/672
   common.v1.Catalog catalog = 1;
   // name refers to a stream or measure in a particular catalog
-  string name = 2;
+  string name = 2 [(validate.rules).string.min_len = 1];
 }
 
 // IndexRuleBinding is a bridge to connect severalIndexRules to a subject
 // This binding is valid between begin_at_nanoseconds and expire_at_nanoseconds, that provides flexible strategies
 // to control how to generate time series indices.
 message IndexRuleBinding {
   // metadata is the identity of this binding
-  common.v1.Metadata metadata = 1;
+  common.v1.Metadata metadata = 1 [(validate.rules).message.required = true];
   // rules refers to the IndexRule
-  repeated string rules = 2;
+  repeated string rules = 2 [(validate.rules).repeated.min_items = 1];
   // subject indicates the subject of binding action
-  Subject subject = 3;
+  Subject subject = 3 [(validate.rules).message.required = true];
   // begin_at_nanoseconds is the timestamp, after which the binding will be active
-  google.protobuf.Timestamp begin_at = 4;
+  google.protobuf.Timestamp begin_at = 4 [(validate.rules).timestamp.required = true];
   // expire_at_nanoseconds it the timestamp, after which the binding will be inactive
   // expire_at_nanoseconds must be larger than begin_at_nanoseconds
-  google.protobuf.Timestamp expire_at = 5;
+  google.protobuf.Timestamp expire_at = 5 [(validate.rules).timestamp.required = true];
   // updated_at indicates when the IndexRuleBinding is updated
   google.protobuf.Timestamp updated_at = 6;
 }