aeon_crud.proto

syntax = "proto3";

import "aeon_error.proto";
import "aeon_value.proto";
import "aeon_schema.proto";

package aeon;

// ATTENTION: This module is EXPERIMENTAL and we do not recommend using it.

// CRUD API to Aeon - a distributed database based on Tarantool.
service CRUDService {
  // Transactionally executes a set of read and write operations.
  rpc Execute(ExecuteRequest) returns (ExecuteResponse) {}

  // Transactionally inserts tuples into a space.
  // Raises an error if a tuple with the same key already exists.
  rpc Insert(InsertRequest) returns (InsertResponse) {}

  // Transactionally replaces tuples in a space.
  // If a tuple with the same key already exists, it will be replaced.
  rpc Replace(ReplaceRequest) returns (ReplaceResponse) {}

  // Transactionally deletes tuples from a space.
  // If a key doesn't exist, it will be ignored (no error is raised).
  rpc Delete(DeleteRequest) returns (DeleteResponse) {}

  // Transactionally queries tuples from a space.
  rpc Get(GetRequest) returns (GetResponse) {}

  // Non-transactionally select tuples from a space.
  rpc Select(SelectRequest) returns (stream SelectResponse) {}
}

//
// DML requests.
//
// NOTE: Any DML request may fail due to a transient error caused by the stale
// range cache on the router. In this case the error will be set to TRY_AGAIN,
// and the user is supposed to retry after a reasonable timeout.
//

// Transactionally executes a set of read and write operations.

message ExecuteRequest {
  // Array of read operations.
  repeated Operation read_set = 1;
  // Array of write operations.
  repeated Operation write_set = 2;
  // Source code of a Lua function that will be used to update the write
  // operations. It's optional: if not set, the write operations will be
  // executed as is.
  //
  // The function is passed three arguments: the read set with filled tuples,
  // the original write set, and the optional extra argument set by the caller
  // (see below). If the function raises an error, the transaction will be
  // aborted, otherwise it will apply the write set. The function may update
  // the tuples in write operations (in-place), but it may not add or delete
  // operations or update the target spaces or keys.
  //
  // A read/write operation is passed in an array: {space, key, tuple}.
  // (without string key names).
  //
  // Below is an example of a Lua function that inserts tuples only if there
  // are no tuples with the same keys, otherwise returns the existing tuples.
  // It's supposed to be passed read and write sets with the same keys.
  //
  // function(read_set, write_set, flags)
  //     local exists = {}
  //     for _, op in pairs(read_set) do
  //         if op[3] ~= nil then
  //             table.insert(exists, op[3])
  //         end
  //     end
  //     if #exists > 0 then
  //         for _, op in pairs(write_set) do
  //             op[3] = nil
  //         end
  //     end
  //     return {exists = exists}
  // end
  //
  string func = 3;
  // Argument passed to the user-defined function. Optional.
  Value func_arg = 4;
  // Map : space name -> key format.
  // Contains formats of all provided keys. Optional.
  map<string, TupleFormat> key_formats = 5;
  // Map : space name -> tuple format.
  // Contains formats of all provided tuples. Optional.
  map<string, TupleFormat> tuple_formats = 6;
}

message ExecuteResponse {
  // Error information. Set only on failure.
  Error error = 1;
  // Array of executed read operations (with filled tuples).
  repeated Operation read_set = 2;
  // Array of executed write operations (updated by the user-defined function).
  repeated Operation write_set = 3;
  // Value returned by the user-defined function.
  Value func_ret = 4;
  // Map : space name -> tuple format.
  // Contains formats of all returned tuples.
  map<string, TupleFormat> tuple_formats = 5;
}

// Transactionally inserts tuples into a space.
// Raises an error if a tuple with the same key already exists.

message InsertRequest {
  message InsertFlags {
    // If set, return the inserted (new) tuples.
    bool return_tuples = 1;
  }
  // Target space name.
  string space = 1;
  // Tuples to insert into the space.
  repeated Tuple tuples = 2;
  // Optional flags, see above.
  InsertFlags flags = 3;
  // Format of the provided tuples. Optional.
  TupleFormat tuple_format = 4;
}

message InsertResponse {
  // Error information. Set only on failure.
  Error error = 1;
  // Inserted (new) tuples (only if return_tuples flag was set).
  repeated Tuple tuples = 2;
  // Format of the returned tuples.
  TupleFormat tuple_format = 3;
}

// Transactionally replaces tuples in a space.
// If a tuple with the same key already exists, it will be replaced.

message ReplaceRequest {
  message ReplaceFlags {
    // If set, return the inserted (new) tuples.
    bool return_tuples = 1;
  }
  // Target space name.
  string space = 1;
  // Tuple to replace in the space.
  repeated Tuple tuples = 2;
  // Optional flags, see above.
  ReplaceFlags flags = 3;
  // Format of the provided tuples. Optional.
  TupleFormat tuple_format = 4;
}

message ReplaceResponse {
  // Error information. Set only on failure.
  Error error = 1;
  // Inserted (new) tuples (only if return_tuples flag was set).
  repeated Tuple tuples = 2;
  // Format of the returned tuples.
  TupleFormat tuple_format = 3;
}

// Transactionally deletes tuples from a space.
// If a key doesn't exist, it will be ignored (no error is raised).

message DeleteRequest {
  message DeleteFlags {
    // If set, return the deleted (old) tuples.
    bool return_tuples = 1;
  }
  // Target space name.
  string space = 1;
  // Keys to delete from the space.
  repeated Tuple keys = 2;
  // Optional flags, see above.
  DeleteFlags flags = 3;
  // Format of the provided keys. Optional.
  TupleFormat key_format = 4;
}

message DeleteResponse {
  // Error information. Set only on failure.
  Error error = 1;
  // Deleted (old) tuples (only if return_tuples flag was set).
  repeated Tuple tuples = 2;
  // Format of the returned tuples.
  TupleFormat tuple_format = 3;
}

// Transactionally queries keys from a space.

message GetRequest {
  // Target space name.
  string space = 1;
  // Keys to query from the space.
  repeated Tuple keys = 2;
  // Format of the provided keys. Optional.
  TupleFormat key_format = 3;
}

message GetResponse {
  // Error information. Set only on failure.
  Error error = 1;
  // Retrieved tuples.
  repeated Tuple tuples = 2;
  // Format of the returned tuples.
  TupleFormat tuple_format = 3;
}

// Non-transactionally select tuples from a space. The tuples will be
// returned as an array of chunks, where the last chunk will contain no
// more than chunk_size tuples, and all the rest will contain exactly
// chunk_size tuples.

enum SelectIterator {
  SELECT_ITERATOR_GT = 0;
  SELECT_ITERATOR_GE = 1;
  SELECT_ITERATOR_LT = 2;
  SELECT_ITERATOR_LE = 3;
  SELECT_ITERATOR_PP = 4;
  SELECT_ITERATOR_NP = 5;
}

message SelectRequest {
  // Target space name.
  string space = 1;
  // Key or partial key to query from the space.
  Tuple key = 2;
  // The type of iterator to use in the select.
  SelectIterator iterator = 3;
  // Max number of tuples to return.
  uint64 limit = 4;
  // Max number of function calls allowed.
  uint64 calls_limit = 5;
  // Function callback that allows to control output values. The function
  // receives the following arguments: tuple, tuple_key (extracted key from
  // the tuple) and func_arg. The callback must return:
  // - key - for the next iteration,
  // - iterator - for the next iteration,
  // - tuple (or nil) - to store in the result set,
  // - eof flag (true or false) - to stop all iterations if true.
  string func = 6;
  // Function argument.
  Value func_arg = 7;
  // Max number of tuples in each response.
  uint64 chunk_size = 8;
}

message SelectResponse {
  // Error information. Set only on failure.
  Error error = 1;
  // Retrieved tuples in the chunk.
  repeated Tuple tuples = 2;
  // Number of calls in the chunk.
  int64 calls = 3;
  // Number of roundtrips done to get all returned tuples.
  int64 roundtrips = 4;
  // Key for the next chunk.
  Tuple key = 5;
  // Iterator for the next chunk.
  SelectIterator iterator = 6;
  // True if there are no more tuples left, false otherwise.
  bool is_eof = 7;
  // Format of the returned tuples.
  TupleFormat tuple_format = 8;
}