Protocol Documentation

Table of Contents

Top

banyandb/cluster/v1/rpc.proto

SendRequest

Field Type Label Description
topic string
message_id uint64
body google.protobuf.Any
batch_mod bool

SendResponse

Field Type Label Description
message_id uint64
error string
body google.protobuf.Any

Service

Method Name Request Type Response Type Description
Send SendRequest stream SendResponse stream

Top

banyandb/common/v1/common.proto

Group

Group is an internal object for Group management

Field Type Label Description
metadata Metadata metadata define the group's identity
catalog Catalog catalog denotes which type of data the group contains
resource_opts ResourceOpts resourceOpts indicates the structure of the underlying kv storage
updated_at google.protobuf.Timestamp updated_at indicates when resources of the group are updated

IntervalRule

IntervalRule is a structured duration

Field Type Label Description
unit IntervalRule.Unit unit can only be UNIT_HOUR or UNIT_DAY
num uint32

Metadata

Metadata is for multi-tenant, multi-model use

Field Type Label Description
group string group contains a set of options, like retention policy, max
name string name of the entity
id uint32 id is the unique identifier of the entity if id is not set, the system will generate a unique id
create_revision int64 readonly. create_revision is the revision of last creation on this key.
mod_revision int64 readonly. mod_revision is the revision of last modification on this key.

ResourceOpts

Field Type Label Description
shard_num uint32 shard_num is the number of shards
segment_interval IntervalRule segment_interval indicates the length of a segment
ttl IntervalRule ttl indicates time to live, how long the data will be cached

Catalog

Name Number Description
CATALOG_UNSPECIFIED 0
CATALOG_STREAM 1
CATALOG_MEASURE 2

IntervalRule.Unit

Name Number Description
UNIT_UNSPECIFIED 0
UNIT_HOUR 1
UNIT_DAY 2

Top

banyandb/common/v1/trace.proto

Span

Span is the basic unit of a trace.

Field Type Label Description
start_time google.protobuf.Timestamp start_time is the start time of the span.
end_time google.protobuf.Timestamp end_time is the end time of the span.
error bool error indicates whether the span is an error span.
tags Tag repeated tags is a list of tags of the span.
message string message is the message generated by the span.
children Span repeated children is a list of child spans of the span.
duration int64 duration is the duration of the span.

Tag

Tag is the key-value pair of a span.

Field Type Label Description
key string key is the key of the tag.
value string value is the value of the tag.

Trace

Trace is the top level message of a trace.

Field Type Label Description
trace_id string trace_id is the unique identifier of the trace.
spans Span repeated spans is a list of spans in the trace.
error bool error indicates whether the trace is an error trace.

Top

banyandb/database/v1/database.proto

Node

Field Type Label Description
metadata banyandb.common.v1.Metadata
roles Role repeated
grpc_address string
http_address string
created_at google.protobuf.Timestamp

Shard

Field Type Label Description
id uint64
metadata banyandb.common.v1.Metadata
catalog banyandb.common.v1.Catalog
node string
total uint32
updated_at google.protobuf.Timestamp
created_at google.protobuf.Timestamp

Role

Name Number Description
ROLE_UNSPECIFIED 0
ROLE_META 1
ROLE_DATA 2
ROLE_LIAISON 3

Top

banyandb/model/v1/common.proto

FieldValue

Field Type Label Description
null google.protobuf.NullValue
str Str
int Int
binary_data bytes
float Float

Float

Field Type Label Description
value double

Int

Field Type Label Description
value int64

IntArray

Field Type Label Description
value int64 repeated

Str

Field Type Label Description
value string

StrArray

Field Type Label Description
value string repeated

TagFamilyForWrite

Field Type Label Description
tags TagValue repeated

TagValue

Field Type Label Description
null google.protobuf.NullValue
str Str
str_array StrArray
int Int
int_array IntArray
binary_data bytes

AggregationFunction

Name Number Description
AGGREGATION_FUNCTION_UNSPECIFIED 0
AGGREGATION_FUNCTION_MEAN 1
AGGREGATION_FUNCTION_MAX 2
AGGREGATION_FUNCTION_MIN 3
AGGREGATION_FUNCTION_COUNT 4
AGGREGATION_FUNCTION_SUM 5

Top

banyandb/model/v1/query.proto

Condition

Condition consists of the query condition with a single binary operator to be imposed For 1:1 BinaryOp, values in condition must be an array with length = 1, while for 1:N BinaryOp, values can be an array with length >= 1.

Field Type Label Description
name string
op Condition.BinaryOp
value TagValue
match_option Condition.MatchOption

Condition.MatchOption

Field Type Label Description
analyzer string
operator Condition.MatchOption.Operator

Criteria

tag_families are indexed.

Field Type Label Description
le LogicalExpression
condition Condition

LogicalExpression

LogicalExpression supports logical operation

Field Type Label Description
op LogicalExpression.LogicalOp op is a logical operation
left Criteria
right Criteria

QueryOrder

QueryOrder means a Sort operation to be done for a given index rule. The index_rule_name refers to the name of a index rule bound to the subject.

Field Type Label Description
index_rule_name string
sort Sort

Tag

Pair is the building block of a record which is equivalent to a key-value pair. In the context of Trace, it could be metadata of a trace such as service_name, service_instance, etc. Besides, other tags are organized in key-value pair in the underlying storage layer. One should notice that the values can be a multi-value.

Field Type Label Description
key string
value TagValue

TagFamily

Field Type Label Description
name string
tags Tag repeated

TagProjection

TagProjection is used to select the names of keys to be returned.

Field Type Label Description
tag_families TagProjection.TagFamily repeated

TagProjection.TagFamily

Field Type Label Description
name string
tags string repeated

TimeRange

TimeRange is a range query for uint64, the range here follows left-inclusive and right-exclusive rule, i.e. [begin, end) if both edges exist

Field Type Label Description
begin google.protobuf.Timestamp
end google.protobuf.Timestamp

Condition.BinaryOp

BinaryOp specifies the operation imposed to the given query condition For EQ, NE, LT, GT, LE and GE, only one operand should be given, i.e. one-to-one relationship. HAVING and NOT_HAVING allow multi-value to be the operand such as array/vector, i.e. one-to-many relationship. For example, "keyA" contains "valueA" and "valueB" MATCH performances a full-text search if the tag is analyzed. The string value applies to the same analyzer as the tag, but string array value does not. Each item in a string array is seen as a token instead of a query expression.

Name Number Description
BINARY_OP_UNSPECIFIED 0
BINARY_OP_EQ 1
BINARY_OP_NE 2
BINARY_OP_LT 3
BINARY_OP_GT 4
BINARY_OP_LE 5
BINARY_OP_GE 6
BINARY_OP_HAVING 7
BINARY_OP_NOT_HAVING 8
BINARY_OP_IN 9
BINARY_OP_NOT_IN 10
BINARY_OP_MATCH 11

Condition.MatchOption.Operator

Name Number Description
OPERATOR_UNSPECIFIED 0
OPERATOR_AND 1
OPERATOR_OR 2

LogicalExpression.LogicalOp

Name Number Description
LOGICAL_OP_UNSPECIFIED 0
LOGICAL_OP_AND 1
LOGICAL_OP_OR 2

Sort

Name Number Description
SORT_UNSPECIFIED 0
SORT_DESC 1
SORT_ASC 2

Top

banyandb/database/v1/schema.proto

Entity

Field Type Label Description
tag_names string repeated

FieldSpec

FieldSpec is the specification of field

Field Type Label Description
name string name is the identity of a field
field_type FieldType field_type denotes the type of field value
encoding_method EncodingMethod encoding_method indicates how to encode data during writing
compression_method CompressionMethod compression_method indicates how to compress data during writing

IndexRule

IndexRule defines how to generate indices based on tags and the index type IndexRule should bind to a subject through an IndexRuleBinding to generate proper indices.

Field Type Label Description
metadata banyandb.common.v1.Metadata metadata define the rule's identity
tags string repeated 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
type IndexRule.Type type is the IndexType of this IndexObject.
updated_at google.protobuf.Timestamp updated_at indicates when the IndexRule is updated
analyzer string analyzer analyzes tag value to support the full-text searching for TYPE_INVERTED indices. available analyzers are: - "standard" provides grammar based tokenization - "simple" breaks text into tokens at any non-letter character, such as numbers, spaces, hyphens and apostrophes, discards non-letter characters, and changes uppercase to lowercase. - "keyword" is a “noop” analyzer which returns the entire input string as a single token. - "url" breaks test into tokens at any non-letter and non-digit character.
no_sort bool no_sort indicates whether the index is not for sorting.

IndexRuleBinding

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.

Field Type Label Description
metadata banyandb.common.v1.Metadata metadata is the identity of this binding
rules string repeated rules refers to the IndexRule
subject Subject subject indicates the subject of binding action
begin_at google.protobuf.Timestamp begin_at_nanoseconds is the timestamp, after which the binding will be active
expire_at google.protobuf.Timestamp expire_at_nanoseconds it the timestamp, after which the binding will be inactive expire_at_nanoseconds must be larger than begin_at_nanoseconds
updated_at google.protobuf.Timestamp updated_at indicates when the IndexRuleBinding is updated

Measure

Measure intends to store data point

Field Type Label Description
metadata banyandb.common.v1.Metadata metadata is the identity of a measure
tag_families TagFamilySpec repeated tag_families are for filter measures
fields FieldSpec repeated fields denote measure values
entity Entity entity indicates which tags will be to generate a series and shard a measure
interval string interval indicates how frequently to send a data point valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h", "d".
updated_at google.protobuf.Timestamp updated_at indicates when the measure is updated
index_mode bool index_mode specifies whether the data should be stored exclusively in the index, meaning it will not be stored in the data storage system.

Stream

Stream intends to store streaming data, for example, traces or logs

Field Type Label Description
metadata banyandb.common.v1.Metadata metadata is the identity of a trace series
tag_families TagFamilySpec repeated tag_families
entity Entity entity indicates how to generate a series and shard a stream
updated_at google.protobuf.Timestamp updated_at indicates when the stream is updated

Subject

Subject defines which stream or measure would generate indices

Field Type Label Description
catalog banyandb.common.v1.Catalog catalog is where the subject belongs to todo validate plugin exist bug https://github.com/bufbuild/protoc-gen-validate/issues/672
name string name refers to a stream or measure in a particular catalog

TagFamilySpec

Field Type Label Description
name string
tags TagSpec repeated tags defines accepted tags

TagSpec

Field Type Label Description
name string
type TagType
indexed_only bool indexed_only indicates whether the tag is stored True: It's indexed only, but not stored False: it's stored and indexed

TopNAggregation

TopNAggregation generates offline TopN statistics for a measure's TopN approximation

Field Type Label Description
metadata banyandb.common.v1.Metadata metadata is the identity of an aggregation
source_measure banyandb.common.v1.Metadata source_measure denotes the data source of this aggregation
field_name string field_name is the name of field used for ranking
field_value_sort banyandb.model.v1.Sort 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
group_by_tag_names string repeated group_by_tag_names groups data points into statistical counters
criteria banyandb.model.v1.Criteria criteria select partial data points from measure
counters_number int32 counters_number sets the number of counters to be tracked. The default value is 1000
lru_size int32 lru_size defines how much entry is allowed to be maintained in the memory
updated_at google.protobuf.Timestamp updated_at indicates when the measure is updated

CompressionMethod

Name Number Description
COMPRESSION_METHOD_UNSPECIFIED 0
COMPRESSION_METHOD_ZSTD 1

EncodingMethod

Name Number Description
ENCODING_METHOD_UNSPECIFIED 0
ENCODING_METHOD_GORILLA 1

FieldType

Name Number Description
FIELD_TYPE_UNSPECIFIED 0
FIELD_TYPE_STRING 1
FIELD_TYPE_INT 2
FIELD_TYPE_DATA_BINARY 3
FIELD_TYPE_FLOAT 4

IndexRule.Type

Type determine the index structure under the hood

Name Number Description
TYPE_UNSPECIFIED 0
TYPE_INVERTED 1

TagType

Name Number Description
TAG_TYPE_UNSPECIFIED 0
TAG_TYPE_STRING 1
TAG_TYPE_INT 2
TAG_TYPE_STRING_ARRAY 3
TAG_TYPE_INT_ARRAY 4
TAG_TYPE_DATA_BINARY 5

Top

banyandb/database/v1/rpc.proto

GroupRegistryServiceCreateRequest

Field Type Label Description
group banyandb.common.v1.Group

GroupRegistryServiceCreateResponse

GroupRegistryServiceDeleteRequest

Field Type Label Description
group string

GroupRegistryServiceDeleteResponse

Field Type Label Description
deleted bool

GroupRegistryServiceExistRequest

Field Type Label Description
group string

GroupRegistryServiceExistResponse

Field Type Label Description
has_group bool

GroupRegistryServiceGetRequest

Field Type Label Description
group string

GroupRegistryServiceGetResponse

Field Type Label Description
group banyandb.common.v1.Group

GroupRegistryServiceListRequest

GroupRegistryServiceListResponse

Field Type Label Description
group banyandb.common.v1.Group repeated

GroupRegistryServiceUpdateRequest

Field Type Label Description
group banyandb.common.v1.Group

GroupRegistryServiceUpdateResponse

IndexRuleBindingRegistryServiceCreateRequest

Field Type Label Description
index_rule_binding IndexRuleBinding

IndexRuleBindingRegistryServiceCreateResponse

IndexRuleBindingRegistryServiceDeleteRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

IndexRuleBindingRegistryServiceDeleteResponse

Field Type Label Description
deleted bool

IndexRuleBindingRegistryServiceExistRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

IndexRuleBindingRegistryServiceExistResponse

Field Type Label Description
has_group bool
has_index_rule_binding bool

IndexRuleBindingRegistryServiceGetRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

IndexRuleBindingRegistryServiceGetResponse

Field Type Label Description
index_rule_binding IndexRuleBinding

IndexRuleBindingRegistryServiceListRequest

Field Type Label Description
group string

IndexRuleBindingRegistryServiceListResponse

Field Type Label Description
index_rule_binding IndexRuleBinding repeated

IndexRuleBindingRegistryServiceUpdateRequest

Field Type Label Description
index_rule_binding IndexRuleBinding

IndexRuleBindingRegistryServiceUpdateResponse

IndexRuleRegistryServiceCreateRequest

Field Type Label Description
index_rule IndexRule

IndexRuleRegistryServiceCreateResponse

IndexRuleRegistryServiceDeleteRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

IndexRuleRegistryServiceDeleteResponse

Field Type Label Description
deleted bool

IndexRuleRegistryServiceExistRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

IndexRuleRegistryServiceExistResponse

Field Type Label Description
has_group bool
has_index_rule bool

IndexRuleRegistryServiceGetRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

IndexRuleRegistryServiceGetResponse

Field Type Label Description
index_rule IndexRule

IndexRuleRegistryServiceListRequest

Field Type Label Description
group string

IndexRuleRegistryServiceListResponse

Field Type Label Description
index_rule IndexRule repeated

IndexRuleRegistryServiceUpdateRequest

Field Type Label Description
index_rule IndexRule

IndexRuleRegistryServiceUpdateResponse

MeasureRegistryServiceCreateRequest

Field Type Label Description
measure Measure

MeasureRegistryServiceCreateResponse

Field Type Label Description
mod_revision int64

MeasureRegistryServiceDeleteRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

MeasureRegistryServiceDeleteResponse

Field Type Label Description
deleted bool

MeasureRegistryServiceExistRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

MeasureRegistryServiceExistResponse

Field Type Label Description
has_group bool
has_measure bool

MeasureRegistryServiceGetRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

MeasureRegistryServiceGetResponse

Field Type Label Description
measure Measure

MeasureRegistryServiceListRequest

Field Type Label Description
group string

MeasureRegistryServiceListResponse

Field Type Label Description
measure Measure repeated

MeasureRegistryServiceUpdateRequest

Field Type Label Description
measure Measure

MeasureRegistryServiceUpdateResponse

Field Type Label Description
mod_revision int64

StreamRegistryServiceCreateRequest

Field Type Label Description
stream Stream

StreamRegistryServiceCreateResponse

Field Type Label Description
mod_revision int64

StreamRegistryServiceDeleteRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

StreamRegistryServiceDeleteResponse

Field Type Label Description
deleted bool

StreamRegistryServiceExistRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

StreamRegistryServiceExistResponse

Field Type Label Description
has_group bool
has_stream bool

StreamRegistryServiceGetRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

StreamRegistryServiceGetResponse

Field Type Label Description
stream Stream

StreamRegistryServiceListRequest

Field Type Label Description
group string

StreamRegistryServiceListResponse

Field Type Label Description
stream Stream repeated

StreamRegistryServiceUpdateRequest

Field Type Label Description
stream Stream

StreamRegistryServiceUpdateResponse

Field Type Label Description
mod_revision int64

TopNAggregationRegistryServiceCreateRequest

Field Type Label Description
top_n_aggregation TopNAggregation

TopNAggregationRegistryServiceCreateResponse

TopNAggregationRegistryServiceDeleteRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

TopNAggregationRegistryServiceDeleteResponse

Field Type Label Description
deleted bool

TopNAggregationRegistryServiceExistRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

TopNAggregationRegistryServiceExistResponse

Field Type Label Description
has_group bool
has_top_n_aggregation bool

TopNAggregationRegistryServiceGetRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata

TopNAggregationRegistryServiceGetResponse

Field Type Label Description
top_n_aggregation TopNAggregation

TopNAggregationRegistryServiceListRequest

Field Type Label Description
group string

TopNAggregationRegistryServiceListResponse

Field Type Label Description
top_n_aggregation TopNAggregation repeated

TopNAggregationRegistryServiceUpdateRequest

Field Type Label Description
top_n_aggregation TopNAggregation

TopNAggregationRegistryServiceUpdateResponse

GroupRegistryService

Method Name Request Type Response Type Description
Create GroupRegistryServiceCreateRequest GroupRegistryServiceCreateResponse
Update GroupRegistryServiceUpdateRequest GroupRegistryServiceUpdateResponse
Delete GroupRegistryServiceDeleteRequest GroupRegistryServiceDeleteResponse
Get GroupRegistryServiceGetRequest GroupRegistryServiceGetResponse
List GroupRegistryServiceListRequest GroupRegistryServiceListResponse
Exist GroupRegistryServiceExistRequest GroupRegistryServiceExistResponse Exist doesn't expose an HTTP endpoint. Please use HEAD method to touch Get instead

IndexRuleBindingRegistryService

Method Name Request Type Response Type Description
Create IndexRuleBindingRegistryServiceCreateRequest IndexRuleBindingRegistryServiceCreateResponse
Update IndexRuleBindingRegistryServiceUpdateRequest IndexRuleBindingRegistryServiceUpdateResponse
Delete IndexRuleBindingRegistryServiceDeleteRequest IndexRuleBindingRegistryServiceDeleteResponse
Get IndexRuleBindingRegistryServiceGetRequest IndexRuleBindingRegistryServiceGetResponse
List IndexRuleBindingRegistryServiceListRequest IndexRuleBindingRegistryServiceListResponse
Exist IndexRuleBindingRegistryServiceExistRequest IndexRuleBindingRegistryServiceExistResponse Exist doesn't expose an HTTP endpoint. Please use HEAD method to touch Get instead

IndexRuleRegistryService

Method Name Request Type Response Type Description
Create IndexRuleRegistryServiceCreateRequest IndexRuleRegistryServiceCreateResponse
Update IndexRuleRegistryServiceUpdateRequest IndexRuleRegistryServiceUpdateResponse
Delete IndexRuleRegistryServiceDeleteRequest IndexRuleRegistryServiceDeleteResponse
Get IndexRuleRegistryServiceGetRequest IndexRuleRegistryServiceGetResponse
List IndexRuleRegistryServiceListRequest IndexRuleRegistryServiceListResponse
Exist IndexRuleRegistryServiceExistRequest IndexRuleRegistryServiceExistResponse Exist doesn't expose an HTTP endpoint. Please use HEAD method to touch Get instead

MeasureRegistryService

Method Name Request Type Response Type Description
Create MeasureRegistryServiceCreateRequest MeasureRegistryServiceCreateResponse
Update MeasureRegistryServiceUpdateRequest MeasureRegistryServiceUpdateResponse
Delete MeasureRegistryServiceDeleteRequest MeasureRegistryServiceDeleteResponse
Get MeasureRegistryServiceGetRequest MeasureRegistryServiceGetResponse
List MeasureRegistryServiceListRequest MeasureRegistryServiceListResponse
Exist MeasureRegistryServiceExistRequest MeasureRegistryServiceExistResponse Exist doesn't expose an HTTP endpoint. Please use HEAD method to touch Get instead

StreamRegistryService

Method Name Request Type Response Type Description
Create StreamRegistryServiceCreateRequest StreamRegistryServiceCreateResponse
Update StreamRegistryServiceUpdateRequest StreamRegistryServiceUpdateResponse
Delete StreamRegistryServiceDeleteRequest StreamRegistryServiceDeleteResponse
Get StreamRegistryServiceGetRequest StreamRegistryServiceGetResponse
List StreamRegistryServiceListRequest StreamRegistryServiceListResponse
Exist StreamRegistryServiceExistRequest StreamRegistryServiceExistResponse Exist doesn't expose an HTTP endpoint. Please use HEAD method to touch Get instead

TopNAggregationRegistryService

Method Name Request Type Response Type Description
Create TopNAggregationRegistryServiceCreateRequest TopNAggregationRegistryServiceCreateResponse
Update TopNAggregationRegistryServiceUpdateRequest TopNAggregationRegistryServiceUpdateResponse
Delete TopNAggregationRegistryServiceDeleteRequest TopNAggregationRegistryServiceDeleteResponse
Get TopNAggregationRegistryServiceGetRequest TopNAggregationRegistryServiceGetResponse
List TopNAggregationRegistryServiceListRequest TopNAggregationRegistryServiceListResponse
Exist TopNAggregationRegistryServiceExistRequest TopNAggregationRegistryServiceExistResponse Exist doesn't expose an HTTP endpoint. Please use HEAD method to touch Get instead

Top

banyandb/measure/v1/query.proto

DataPoint

DataPoint is stored in Measures

Field Type Label Description
timestamp google.protobuf.Timestamp timestamp is in the timeunit of milliseconds.
tag_families banyandb.model.v1.TagFamily repeated tag_families contains tags selected in the projection
fields DataPoint.Field repeated fields contains fields selected in the projection
sid uint64 sid is the series id of the data point
version int64 version is the version of the data point in a series sid, timestamp and version are used to identify a data point

DataPoint.Field

Field Type Label Description
name string
value banyandb.model.v1.FieldValue

QueryRequest

QueryRequest is the request contract for query.

Field Type Label Description
groups string repeated groups indicate where the data points are stored.
name string name is the identity of a measure.
time_range banyandb.model.v1.TimeRange time_range is a range query with begin/end time of entities in the timeunit of milliseconds.
criteria banyandb.model.v1.Criteria tag_families are indexed.
tag_projection banyandb.model.v1.TagProjection tag_projection can be used to select tags of the data points in the response
field_projection QueryRequest.FieldProjection field_projection can be used to select fields of the data points in the response
group_by QueryRequest.GroupBy group_by groups data points based on their field value for a specific tag and use field_name as the projection name
agg QueryRequest.Aggregation agg aggregates data points based on a field
top QueryRequest.Top top limits the result based on a particular field. If order_by is specified, top sorts the dataset based on order_by's output
offset uint32 offset is used to support pagination, together with the following limit. If top is specified, offset processes the dataset based on top's output
limit uint32 limit is used to impose a boundary on the number of records being returned. If top is specified, limit processes the dataset based on top's output
order_by banyandb.model.v1.QueryOrder order_by is given to specify the sort for a tag.
trace bool trace is used to enable trace for the query

QueryRequest.Aggregation

Field Type Label Description
function banyandb.model.v1.AggregationFunction
field_name string field_name must be one of files indicated by the field_projection

QueryRequest.FieldProjection

Field Type Label Description
names string repeated

QueryRequest.GroupBy

Field Type Label Description
tag_projection banyandb.model.v1.TagProjection tag_projection must be a subset of the tag_projection of QueryRequest
field_name string field_name must be one of fields indicated by field_projection

QueryRequest.Top

Field Type Label Description
number int32 number set the how many items should be returned
field_name string field_name must be one of files indicated by the field_projection
field_value_sort banyandb.model.v1.Sort field_value_sort indicates how to sort fields ASC: bottomN DESC: topN UNSPECIFIED: topN

QueryResponse

QueryResponse is the response for a query to the Query module.

Field Type Label Description
data_points DataPoint repeated data_points are the actual data returned
trace banyandb.common.v1.Trace trace contains the trace information of the query when trace is enabled

Top

banyandb/measure/v1/topn.proto

TopNList

TopNList contains a series of topN items

Field Type Label Description
timestamp google.protobuf.Timestamp timestamp is in the timeunit of milliseconds.
items TopNList.Item repeated items contains top-n items in a list

TopNList.Item

Field Type Label Description
entity banyandb.model.v1.Tag repeated
value banyandb.model.v1.FieldValue

TopNRequest

TopNRequest is the request contract for query.

Field Type Label Description
groups string repeated groups indicate where the data points are stored.
name string name is the identity of a measure.
time_range banyandb.model.v1.TimeRange time_range is a range query with begin/end time of entities in the timeunit of milliseconds.
top_n int32 top_n set the how many items should be returned in each list.
agg banyandb.model.v1.AggregationFunction agg aggregates lists grouped by field names in the time_range
conditions banyandb.model.v1.Condition repeated criteria select counters. Only equals are acceptable.
field_value_sort banyandb.model.v1.Sort field_value_sort indicates how to sort fields
trace bool trace is used to enable trace for the query

TopNResponse

TopNResponse is the response for a query to the Query module.

Field Type Label Description
lists TopNList repeated lists contain a series topN lists ranked by timestamp if agg_func in query request is specified, lists' size should be one.
trace banyandb.common.v1.Trace trace contains the trace information of the query when trace is enabled

Top

banyandb/model/v1/write.proto

Status

Status is the response status for write

Name Number Description
STATUS_UNSPECIFIED 0
STATUS_SUCCEED 1
STATUS_INVALID_TIMESTAMP 2
STATUS_NOT_FOUND 3
STATUS_EXPIRED_SCHEMA 4
STATUS_INTERNAL_ERROR 5

Top

banyandb/measure/v1/write.proto

DataPointValue

DataPointValue is the data point for writing. It only contains values.

Field Type Label Description
timestamp google.protobuf.Timestamp timestamp is in the timeunit of milliseconds.
tag_families banyandb.model.v1.TagFamilyForWrite repeated the order of tag_families' items match the measure schema
fields banyandb.model.v1.FieldValue repeated the order of fields match the measure schema
version int64 the version of the data point
type DataPointValue.Type

InternalWriteRequest

Field Type Label Description
shard_id uint32
series_hash bytes
entity_values banyandb.model.v1.TagValue repeated
request WriteRequest

WriteRequest

WriteRequest is the request contract for write

Field Type Label Description
metadata banyandb.common.v1.Metadata the metadata is required.
data_point DataPointValue the data_point is required.
message_id uint64 the message_id is required.

WriteResponse

WriteResponse is the response contract for write

Field Type Label Description
message_id uint64 the message_id from request.
status banyandb.model.v1.Status status indicates the request processing result
metadata banyandb.common.v1.Metadata the metadata from request when request fails

DataPointValue.Type

the type of the data point cumulative or delta

Name Number Description
TYPE_UNSPECIFIED 0 TYPE_UNSPECIFIED is the default value.
TYPE_CUMULATIVE 1 TYPE_CUMULATIVE is the cumulative data
TYPE_DELTA 2 TYPE_DELTA is the delta data

Top

banyandb/measure/v1/rpc.proto

MeasureService

Method Name Request Type Response Type Description
Query QueryRequest QueryResponse
Write WriteRequest stream WriteResponse stream
TopN TopNRequest TopNResponse

Top

banyandb/property/v1/property.proto

Metadata

Metadata is for multi-tenant use

Field Type Label Description
container banyandb.common.v1.Metadata container is created when it receives the first property
id string id identifies a property

Property

Property stores the user defined data

Field Type Label Description
metadata Metadata metadata is the identity of a property
tags banyandb.model.v1.Tag repeated tag stores the content of a property
updated_at google.protobuf.Timestamp updated_at indicates when the property is updated
lease_id int64 readonly. lease_id is the ID of the lease that attached to key.
ttl string ttl indicates the time to live of the property. It's a string in the format of "1h", "2m", "3s", "1500ms". It defaults to 0s, which means the property never expires. The minimum allowed ttl is 1s.

Top

banyandb/property/v1/rpc.proto

ApplyRequest

Field Type Label Description
property Property
strategy ApplyRequest.Strategy strategy indicates how to update a property. It defaults to STRATEGY_MERGE

ApplyResponse

Field Type Label Description
created bool created indicates whether the property existed. True: the property is absent. False: the property existed.
tags_num uint32
lease_id int64

DeleteRequest

Field Type Label Description
metadata Metadata
tags string repeated

DeleteResponse

Field Type Label Description
deleted bool
tags_num uint32

GetRequest

Field Type Label Description
metadata Metadata
tags string repeated

GetResponse

Field Type Label Description
property Property

KeepAliveRequest

Field Type Label Description
lease_id int64

KeepAliveResponse

ListRequest

Field Type Label Description
container banyandb.common.v1.Metadata
ids string repeated
tags string repeated

ListResponse

Field Type Label Description
property Property repeated

ApplyRequest.Strategy

Name Number Description
STRATEGY_UNSPECIFIED 0
STRATEGY_MERGE 1
STRATEGY_REPLACE 2

PropertyService

Method Name Request Type Response Type Description
Apply ApplyRequest ApplyResponse Apply creates a property if it's absent, or update a existed one based on a strategy.
Delete DeleteRequest DeleteResponse
Get GetRequest GetResponse
List ListRequest ListResponse
KeepAlive KeepAliveRequest KeepAliveResponse

Top

banyandb/stream/v1/query.proto

Element

Element represents (stream context) a Span defined in Google Dapper paper or equivalently a Segment in Skywalking. (Log context) a log

Field Type Label Description
element_id string element_id could be span_id of a Span or segment_id of a Segment in the context of stream
timestamp google.protobuf.Timestamp timestamp represents a millisecond 1) either the start time of a Span/Segment, 2) or the timestamp of a log
tag_families banyandb.model.v1.TagFamily repeated fields contains all indexed Field. Some typical names, - stream_id - duration - service_name - service_instance_id - end_time_milliseconds

QueryRequest

QueryRequest is the request contract for query.

Field Type Label Description
groups string repeated groups indicate where the elements are stored.
name string name is the identity of a stream.
time_range banyandb.model.v1.TimeRange time_range is a range query with begin/end time of entities in the timeunit of milliseconds. In the context of stream, it represents the range of the startTime for spans/segments, while in the context of Log, it means the range of the timestamp(s) for logs. it is always recommended to specify time range for performance reason
offset uint32 offset is used to support pagination, together with the following limit
limit uint32 limit is used to impose a boundary on the number of records being returned
order_by banyandb.model.v1.QueryOrder order_by is given to specify the sort for a field. So far, only fields in the type of Integer are supported
criteria banyandb.model.v1.Criteria tag_families are indexed.
projection banyandb.model.v1.TagProjection projection can be used to select the key names of the element in the response
trace bool trace is used to enable trace for the query

QueryResponse

QueryResponse is the response for a query to the Query module.

Field Type Label Description
elements Element repeated elements are the actual data returned
trace banyandb.common.v1.Trace trace contains the trace information of the query when trace is enabled

Top

banyandb/stream/v1/write.proto

ElementValue

Field Type Label Description
element_id string element_id could be span_id of a Span or segment_id of a Segment in the context of stream
timestamp google.protobuf.Timestamp timestamp is in the timeunit of milliseconds. It represents 1) either the start time of a Span/Segment, 2) or the timestamp of a log
tag_families banyandb.model.v1.TagFamilyForWrite repeated the order of tag_families' items match the stream schema

InternalWriteRequest

Field Type Label Description
shard_id uint32
series_hash bytes
entity_values banyandb.model.v1.TagValue repeated
request WriteRequest

WriteRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata the metadata is required.
element ElementValue the element is required.
message_id uint64 the message_id is required.

WriteResponse

Field Type Label Description
message_id uint64 the message_id from request.
status banyandb.model.v1.Status status indicates the request processing result
metadata banyandb.common.v1.Metadata the metadata from request when request fails

Top

banyandb/stream/v1/rpc.proto

StreamService

Method Name Request Type Response Type Description
Query QueryRequest QueryResponse
Write WriteRequest stream WriteResponse stream

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)