Protocol Documentation

Table of Contents

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
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
block_interval IntervalRule block_interval indicates the length of a block block_interval should be less than or equal to segment_interval
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/database/v1/database.proto

Node

Field Type Label Description
id string
addr string
updated_at google.protobuf.Timestamp
created_at google.protobuf.Timestamp

Shard

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

Top

banyandb/database/v1/event.proto

EntityEvent

Field Type Label Description
subject banyandb.common.v1.Metadata
entity_locator EntityEvent.TagLocator repeated
action Action
time google.protobuf.Timestamp

EntityEvent.TagLocator

Field Type Label Description
family_offset uint32
tag_offset uint32

ShardEvent

Field Type Label Description
shard Shard
action Action
time google.protobuf.Timestamp

Action

Name Number Description
ACTION_UNSPECIFIED 0
ACTION_PUT 1
ACTION_DELETE 2

Top

banyandb/model/v1/common.proto

FieldValue

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

ID

Field Type Label Description
value string

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
id ID

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

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

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.
location IndexRule.Location location indicates where to store index.
updated_at google.protobuf.Timestamp updated_at indicates when the IndexRule is updated
analyzer IndexRule.Analyzer analyzer analyzes tag value to support the full-text searching for TYPE_INVERTED indices.

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

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
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
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

IndexRule.Analyzer

Name Number Description
ANALYZER_UNSPECIFIED 0
ANALYZER_KEYWORD 1 Keyword analyzer is a “noop” analyzer which returns the entire input string as a single token.
ANALYZER_STANDARD 2 Standard analyzer provides grammar based tokenization
ANALYZER_SIMPLE 3 Simple analyzer 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.

IndexRule.Location

Name Number Description
LOCATION_UNSPECIFIED 0
LOCATION_SERIES 1
LOCATION_GLOBAL 2

IndexRule.Type

Type determine the index structure under the hood

Name Number Description
TYPE_UNSPECIFIED 0
TYPE_TREE 1
TYPE_INVERTED 2

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
TAG_TYPE_ID 6

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

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

StreamRegistryServiceCreateRequest

Field Type Label Description
stream Stream

StreamRegistryServiceCreateResponse

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

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

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

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
metadata banyandb.common.v1.Metadata metadata is required
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.

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

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
name string
value banyandb.model.v1.FieldValue

TopNRequest

TopNRequest is the request contract for query.

Field Type Label Description
metadata banyandb.common.v1.Metadata metadata is required
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 TODO validate enum defined_only
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

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.

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

InternalWriteRequest

Field Type Label Description
shard_id uint32
series_hash bytes
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.

WriteResponse

WriteResponse is the response contract for write

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

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

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

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

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
metadata banyandb.common.v1.Metadata metadata is required
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

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

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
request WriteRequest

WriteRequest

Field Type Label Description
metadata banyandb.common.v1.Metadata the metadata is only required in the first write.
element ElementValue the element is required.

WriteResponse

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)