api/proto/banyandb/v1/query.proto

// Licensed to Apache Software Foundation (ASF) under one or more contributor
// license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright
// ownership. Apache Software Foundation (ASF) licenses this file to you under
// the Apache License, Version 2.0 (the "License"); you may
// not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.

syntax = "proto3";

option java_package = "org.apache.skywalking.banyandb";
option go_package = "github.com/apache/skywalking-banyandb/api/proto/banyandb/v1;v1";

package banyandb.v1;

import "google/protobuf/timestamp.proto";
import "banyandb/v1/database.proto";

// IntPair in a typed pair with an array of int64 as values
message IntPair {
  string key = 1;
  repeated int64 values = 2;
}

// StrPair in a typed pair with an array of string as values
message StrPair {
  string key = 1;
  repeated string values = 2;
}

// 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 fields/tags are organized in key-value pair in the underlying storage layer.
// One should notice that the values can be a multi-value.
message TypedPair {
  oneof typed {
    IntPair int_pair = 1;
    StrPair str_pair = 2;
  }
}

// PairQuery 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.
message PairQuery {
  // 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"
  enum BinaryOp {
    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;
  }
  BinaryOp op = 1;
  TypedPair condition = 2;
}

// QueryOrder means a Sort operation to be done for a given field.
// The key_name refers to the key of a Pair.
message QueryOrder {
  string key_name = 1;
  enum Sort {
    SORT_UNSPECIFIED = 0;
    SORT_DESC = 1;
    SORT_ASC = 2;
  }
  Sort sort = 2;
}

// Entity represents
// (Trace context) a Span defined in Google Dapper paper or equivalently a Segment in Skywalking.
// (Log context) a log
message Entity {
  // entity_id could be span_id of a Span or segment_id of a Segment in the context of Trace
  string entity_id = 1;
  // timestamp represents
  // 1) either the start time of a Span/Segment,
  // 2) or the timestamp of a log
  google.protobuf.Timestamp timestamp = 2;
  // data_binary contains all un-indexed Tags and other key-value pairs
  bytes data_binary = 3;
  // fields contains all indexed Field. Some typical names,
  // - trace_id
  // - duration
  // - service_name
  // - service_instance_id
  // - end_time_nanoseconds
  repeated TypedPair fields = 4;
}

// QueryResponse is the response for a query to the Query module.
message QueryResponse {
  // entities are the actual data returned
  repeated Entity entities = 1;
}

// Projection is used to select the names of keys to be returned.
message Projection {
  // The key_name refers to the key(s) of Pair(s).
  repeated string key_names = 1;
}

// 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
message TimeRange {
  google.protobuf.Timestamp begin = 1;
  google.protobuf.Timestamp end = 2;
}

// QueryRequest is the request contract for query.
message QueryRequest {
  // metadata is required
  Metadata metadata = 1;
  // time_range is a range query with begin/end time of entities in the timeunit of nanoseconds.
  // In the context of Trace, 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
  TimeRange time_range = 2;
  // offset is used to support pagination, together with the following limit
  uint32 offset = 3;
  // limit is used to impose a boundary on the number of records being returned
  uint32 limit = 4;
  // order_by is given to specify the sort for a field. So far, only fields in the type of Integer are supported
  QueryOrder order_by = 5;
  // fields are indexed. Some typical fields are listed below,
  // - trace_id: if given, it takes precedence over other fields and will be used to retrieve entities before other conditions are imposed
  // - duration: typical for trace context
  repeated PairQuery fields = 6;
  // projection can be used to select the key names of the entities in the response
  Projection projection = 7;
}