rpc.grpc-proto.2.1.0-BETA-9.source-code.query.proto Maven / Gradle / Ivy
/*
* Copyright The Stargate Authors
*
* Licensed 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";
import "google/protobuf/wrappers.proto";
import "google/rpc/status.proto";
option java_package = "io.stargate.proto";
option go_package = "stargate/proto";
package stargate;
// The consistency level used to execute a request.
enum Consistency {
ANY = 0x00;
ONE = 0x01;
TWO = 0x02;
THREE = 0x03;
QUORUM = 0x04;
ALL = 0x05;
LOCAL_QUORUM = 0x06;
EACH_QUORUM = 0x07;
SERIAL = 0x08;
LOCAL_SERIAL = 0x09;
LOCAL_ONE = 0x0A;
}
// A wrapper message for Consistency, for cases where the consistency level can be unset.
message ConsistencyValue {
Consistency value = 1;
}
// A CQL value for a collection type.
// For lists, sets and tuples, this contains the collection elements.
// For maps, this contains the key and values in order (e.g. key1, value1, key2, value2...)
message Collection {
repeated Value elements = 1;
}
// A value for a CQL user-defined type.
message UdtValue {
map fields = 1;
}
// A 128-bit (16-byte) UUID type encoded using big-endian byte order. For example, the UUID
// "00112233-4455-6677-8899-aabbccddeeff" would be store as the bytes:
// | 0x00 0x11 0x22 0x33 0x44 0x55 0x66 0x77 0x88 0x99 0xAA 0xBB 0xCC 0xDD 0xEE 0xFF |
// | MSB LSB |
message Uuid {
bytes value = 1;
}
// Either an IPv4 or IPv6 address stored as either 4 or 16 bytes, respectively. The addresses are
// encoded using big-endian byte order.
message Inet {
bytes value = 1;
}
message Varint {
bytes value = 1;
}
message Decimal {
uint32 scale = 1;
bytes value = 3;
}
message Duration {
sint32 months = 1;
sint32 days = 2;
sint64 nanos = 3;
}
// A CQL value. This is used both in requests to bind parameterized query strings, and in responses
// to represent the result data.
message Value {
message Null {}
message Unset {}
oneof inner {
// The CQL value NULL.
Null null = 1;
// An unset value.
// This can only be used for bind values in requests.
Unset unset = 2;
// CQL types: tinyint, smallint, int, bigint, counter, timestamp
sint64 int = 3;
// CQL types: float
float float = 4;
// CQL types: double
double double = 5;
// CQL types: boolean
bool boolean = 6;
// CQL types: ascii, varchar, text
string string = 7;
// CQL types: blob, custom
bytes bytes = 8;
// CQL types: inet
Inet inet = 9;
// CQL types: uuid, timeuuid
Uuid uuid = 10;
// CQL types: date
// An unsigned integer representing days with Unix epoch (January, 1 1970) at 2^31.
// Examples:
// 0: -5877641-06-23
// 2^31: 1970-1-1
// 2^32: 5881580-07-11
uint32 date = 11;
// CQL types: time
// An unsigned integer representing the number of nanoseconds since midnight. Valid values are
// in the range 0 to 86399999999999 (inclusive).
uint64 time = 12;
// CQL types: duration
Duration duration = 17;
// CQL types: list, set, map, tuple
Collection collection = 13;
// CQL types: user defined types
UdtValue udt = 14;
// CQL types: varint
Varint varint = 15;
// CQL types: decimal
Decimal decimal = 16;
}
}
// A single CQL query.
message Query {
// The query string. It can contain anonymous placeholders identified by a question mark (?), or
// named placeholders prefixed by a column (:name).
string cql = 1;
// The values to fill the placeholders in the query string.
Values values = 2;
// The execution parameters for the query.
QueryParameters parameters = 3;
}
// The values to bind to the placeholders in a query.
message Values {
// The values.
repeated Value values = 1;
// The value names, if the query uses named placeholders.
repeated string value_names = 2;
}
// The execution parameters for a Query message.
message QueryParameters {
// The keyspace to use when schema element names in the query (tables, UDTs, functions) are not
// fully qualified.
google.protobuf.StringValue keyspace = 1;
// The consistency level.
// If unset, it defaults to LOCAL_QUORUM.
ConsistencyValue consistency = 2;
// The maximum number of rows that will be returned in the response. If there are more results,
// the response will contain a paging state, and additional queries will be needed to retrieve
// subsequent pages.
// Note that this is only a suggestion, the server reserves the right to return slightly smaller
// or bigger pages.
// If unset, it defaults to 100.
google.protobuf.Int32Value page_size = 3;
// A paging state that indicates where to resume iteration in the result set. This is used to
// retrieve the next page of data when the number of results exceeds the page size.
// This should be filled with the value returned by the previous response (see
// ResultSet.paging_state). It is an opaque binary string that is only intended to be collected,
// stored and reused; any attempt to modify its contents or reuse it with a different statement
// will yield unpredictable results.
google.protobuf.BytesValue paging_state = 4;
// Whether the server should collect tracing information about the execution of the query.
// If this is set, then a Traces message will be included in the Response message.
bool tracing = 5;
// Whether to omit ResultSet.columns in the response.
// This can be used to optimize response size when the client already knows that information (for
// example when fetching multiple pages for the same query).
bool skip_metadata = 6;
// The query timestamp (in microseconds). This is used to order mutations on the server.
// If unset, the server will assign one based on the time it received the query.
google.protobuf.Int64Value timestamp = 7;
// The serial consistency level (if the query is a lightweight transaction).
// If unset, it defaults to SERIAL.
ConsistencyValue serial_consistency = 8;
// Forces the current time for the query (for testing purposes).
// This affects TTL cell liveness in read queries and local deletion time for tombstones and TTL
// cells in update requests.
google.protobuf.Int32Value now_in_seconds = 9;
// The consistency level to use to retrieve the query trace (if tracing is set).
// If unset, it defaults to ONE.
ConsistencyValue tracing_consistency = 10;
}
// A CQL column type.
message TypeSpec {
// A CQL primitive type.
enum Basic {
CUSTOM = 0x00;
ASCII = 0x01;
BIGINT = 0x02;
BLOB = 0x03;
BOOLEAN = 0x04;
COUNTER = 0x05;
DECIMAL = 0x06;
DOUBLE = 0x07;
FLOAT = 0x08;
INT = 0x09;
// Note that TEXT and VARCHAR are synonyms in Cassandra. gRPC responses will always use VARCHAR,
// regardless of the name that was used for creation.
TEXT = 0xA [deprecated = true];
TIMESTAMP = 0x0B;
UUID = 0x0C;
VARCHAR = 0x0D;
VARINT = 0x0E;
TIMEUUID = 0x0F;
INET = 0x10;
DATE = 0x11;
TIME = 0x12;
SMALLINT = 0x13;
TINYINT = 0x14;
DURATION = 0x15;
LINESTRING = 0x16;
POINT = 0x17;
POLYGON = 0x18;
}
message Map {
TypeSpec key = 1;
TypeSpec value = 2;
// optional, only required on schema definition (CREATE TYPE or CREATE TABLE)
bool frozen = 3;
}
message List {
TypeSpec element = 1;
// optional, only required on schema definition (CREATE TYPE or CREATE TABLE)
bool frozen = 2;
}
message Set {
TypeSpec element = 1;
// optional, only required on schema definition (CREATE TYPE or CREATE TABLE)
bool frozen = 2;
}
// A CQL User-Defined type: a collection of named fields.
message Udt {
// optional, only required when returned in ResultSet or used in CREATE TYPE,
// ignored on CREATE TABLE
map fields = 1;
string name = 2;
// optional, only required on schema definition (CREATE TYPE or CREATE TABLE)
bool frozen = 3;
}
// A CQL tuple: a collection of anonymous fields.
message Tuple {
repeated TypeSpec elements = 1;
}
oneof spec {
Basic basic = 1;
Map map = 2;
List list = 3;
Set set = 4;
Udt udt = 5;
Tuple tuple = 6;
};
}
// Metadata about a CQL column.
message ColumnSpec {
// The CQL type.
TypeSpec type = 1;
// The name.
string name = 2;
}
// Tracing information, included in the Response when it was requested by the client (see
// QueryParameters.tracing or BatchParameters.tracing)
message Traces {
// An event in a query trace.
message Event {
// Which activity the event corresponds to.
string activity = 1;
// Identifies the host having generated the event.
string source = 2;
// The number of microseconds elapsed on the source when this event occurred since the moment
// when the source started handling the query.
int64 source_elapsed = 3;
// The name of the server thread on which this event occurred.
string thread = 4;
// A technical identifier for the event.
string event_id = 5;
}
// A technical identifier for this trace.
string id = 1;
// The server-side duration of the query (in microseconds).
int64 duration = 2;
// The server-side timestamp of the start of the query.
int64 started_at = 3;
repeated Event events = 4;
}
// TODO: does this need to include indexes and materialized views?
// If a Query message is a DDL statement, this will be included in the Response to describe the
// how the CQL schema was impacted.
message SchemaChange {
enum Type {
CREATED = 0;
UPDATED = 1;
DROPPED = 2;
}
enum Target {
KEYSPACE = 0;
TABLE = 1;
TYPE = 2;
FUNCTION = 3;
AGGREGATE = 4;
}
// The nature of the change (created, updated or dropped).
Type change_type = 1;
// The type of schema object that was affected.
Target target = 2;
// The name of the keyspace.
string keyspace = 3;
// If the target is a keyspace element (table, type, etc), its name.
google.protobuf.StringValue name = 4;
// If the target is a function or aggregate, the CQL types of the arguments.
repeated string argument_types = 5;
}
// The response to a Query or Batch message.
message Response {
oneof result {
// The result data.
ResultSet result_set = 1;
// How the query changed the CQL schema.
SchemaChange schema_change = 4;
}
// The server-side warnings for the query, if any.
repeated string warnings = 2;
// The tracing information, if it was requested for the query.
Traces traces = 3;
}
message StreamingResponse {
oneof message{
Response response = 1;
google.rpc.Status status = 2;
}
}
// Thrown when the coordinator knows there is not enough replicas alive to perform a query with the
// requested consistency level.
message Unavailable {
// The consistency level of the operation that failed.
Consistency consistency = 1;
// The number of replica acknowledgements/responses required to perform the operation (with its
// required consistency level).
int32 required = 2;
// The number of replicas that were known to be alive by the coordinator node when it tried to
// execute the operation.
int32 alive = 3;
};
// A server-side timeout during a write query.
message WriteTimeout {
// The consistency level of the operation that failed.
Consistency consistency = 1;
// The number of replica that had acknowledged/responded to the operation before it failed.
int32 received = 2;
// The minimum number of replica acknowledgements/responses that were required to fulfill the
// operation.
int32 block_for = 3;
// The type of the write for which a timeout was raised.
string write_type = 4;
};
// A server-side timeout during a read query.
message ReadTimeout {
// The consistency level of the operation that failed.
Consistency consistency = 1;
// The number of replica that had acknowledged/responded to the operation before it failed.
int32 received = 2;
// The minimum number of replica acknowledgements/responses that were required to fulfill the
// operation.
int32 block_for = 3;
// Whether the actual data was amongst the received replica responses.
// During reads, Cassandra doesn't request data from every replica to minimize internal network
// traffic. Instead, some replicas are only asked for a checksum of the data. A read timeout may
// occur even if enough replicas have responded to fulfill the consistency level, if only checksum
// responses have been received. This field allows to detect that case.
bool data_present = 4;
};
// A non-timeout error during a read query.
// This happens when some of the replicas that were contacted by the coordinator replied with an
// error.
message ReadFailure {
// The consistency level of the operation that failed.
Consistency consistency = 1;
// The number of replica that had acknowledged/responded to the operation before it failed.
int32 received = 2;
// The minimum number of replica acknowledgements/responses that were required to fulfill the
// operation.
int32 block_for = 3;
// The number of replicas that experienced a failure while executing the request.
int32 num_failures = 4;
// Whether the actual data was amongst the received replica responses.
// During reads, Cassandra doesn't request data from every replica to minimize internal network
// traffic. Instead, some replicas are only asked for a checksum of the data. A read timeout may
// occur even if enough replicas have responded to fulfill the consistency level, if only checksum
// responses have been received. This field allows to detect that case.
bool data_present = 5;
};
// An error during the execution of a CQL function.
message FunctionFailure {
// The keyspace containing the function.
string keyspace = 1;
// The name of the function.
string function = 2;
// The CQL types of the arguments of the function.
repeated string arg_types = 3;
}
// A non-timeout error during a write query.
// This happens when some of the replicas that were contacted by the coordinator replied with an
// error.
message WriteFailure {
// The consistency level of the operation that failed.
Consistency consistency = 1;
// The number of replica that had acknowledged/responded to the operation before it failed.
int32 received = 2;
// The minimum number of replica acknowledgements/responses that were required to fulfill the
// operation.
int32 block_for = 3;
// The number of replicas that experienced a failure while executing the request.
int32 num_failures = 4;
// The type of the write for which an error was raised.
string write_type = 5;
}
// Thrown when a query attempts to create a keyspace or table that already exists.
message AlreadyExists {
string keyspace = 1;
string table = 2;
}
// An exception occured due to a contended Compare And Set write/update.
// The CAS operation was only partially completed and the operation may or may not get completed by
// the contending CAS write or SERIAL/LOCAL_SERIAL read.
message CasWriteUnknown {
// The consistency level of the operation that failed.
Consistency consistency = 1;
// The number of replica that had acknowledged/responded to the operation before it failed.
int32 received = 2;
// The minimum number of replica acknowledgements/responses that were required to fulfill the
// operation.
int32 block_for = 3;
}
// A single row in a result set.
message Row {
// The values for the columns (in the same order as ResultSet.columns).
repeated Value values = 1;
}
// The data returned in response to a CQL query.
message ResultSet {
// Metadata about the columns that this result set contains.
// This may be omitted if explicitly requested by the client (see QueryParameters.skip_metadata
// and BatchParameters.skip_metadata).
repeated ColumnSpec columns = 1;
// The rows of CQL data.
repeated Row rows = 2;
// If there are more pages, a paging state that will allow the client to build a new query for the
// next page.
google.protobuf.BytesValue paging_state = 3;
}
// A query inside of a Batch message.
message BatchQuery {
// The query string. It can contain anonymous placeholders identified by a question mark (?), or
// named placeholders prefixed by a column (:name).
string cql = 1;
// The values to fill the placeholders in the query string.
Values values = 2;
}
// The execution parameters for a Batch message.
message BatchParameters {
// The keyspace to use when schema element names in the queries (tables, UDTs, functions) are not
// fully qualified.
google.protobuf.StringValue keyspace = 1;
// The consistency level.
// If unset, it defaults to LOCAL_QUORUM.
ConsistencyValue consistency = 2;
// Whether the server should collect tracing information about the execution of the query.
// If this is set, then a Traces message will be included in the Response message.
bool tracing = 3;
// The query timestamp (in microseconds). This is used to order mutations on the server.
// If unset, the server will assign one based on the time it received the batch.
google.protobuf.Int64Value timestamp = 4;
// The serial consistency level (if the batch contains lightweight transactions).
// If unset, it defaults to SERIAL.
ConsistencyValue serial_consistency = 5;
// Forces the current time for the query (for testing purposes).
// This affects TTL cell liveness in read queries and local deletion time for tombstones and TTL
// cells in update requests.
google.protobuf.Int32Value now_in_seconds = 6;
// The consistency level to use to retrieve the query trace (if tracing is set).
// If unset, it defaults to ONE.
ConsistencyValue tracing_consistency = 7;
// Whether to omit ResultSet.columns in the response.
// This can be used to optimize response size when the client already knows that information.
bool skip_metadata = 8;
}
// A batch containing multiple CQL queries.
message Batch {
enum Type {
// A logged batch: Cassandra will first write the batch to its distributed batch log to ensure
// the atomicity of the batch (atomicity meaning that if any statement in the batch succeeds,
// all will eventually succeed).
LOGGED = 0;
// A batch that doesn't use Cassandra's distributed batch log. Such batch are not guaranteed to
// be atomic.
UNLOGGED = 1;
// A counter batch. Note that such batch is the only type that can contain counter operations
// and it can only contain these.
COUNTER = 2;
}
// The type of batch.
Type type = 1;
// The CQL queries with their values.
repeated BatchQuery queries = 2;
// The execution parameters for the batch.
BatchParameters parameters = 3;
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy