api.proto

path server/v1/api.proto

package tigrisdata.v1

---

Messages

BeginTransactionRequest

Start new transaction in database specified by "db".

Name	Type	Description
db	string	Database name this transaction belongs to.
options	TransactionOptions	The transaction options.

BeginTransactionResponse

Start transaction returns transaction context which uniquely identifies the transaction

Name	Type	Description
tx_ctx	TransactionCtx	Returns a tigris transactional context with details about the transactions.

Collation

A collation allows you to specify string comparison rules. Default is case-sensitive, to override it you can set this option to 'ci' that will apply to all the text fields in the filters.

Name	Type	Description
case	string

CollectionDescription

Name	Type	Description
collection	string	Name of the collection.
metadata	CollectionMetadata	Metadata about the collection.
schema	bytes	Collections schema
size	int64	Collection size in bytes

CollectionInfo

Name	Type	Description
collection	string	Collection name.
metadata	CollectionMetadata	Metadata about the collection.

CollectionMetadata

Name	Type	Description

CollectionOptions

Collection requests modifying options.

Name	Type	Description

CommitTransactionRequest

Commit transaction with the given ID

Name	Type	Description
db	string	Database name this transaction belongs to.

CommitTransactionResponse

Name	Type	Description
status	string	Status of commit transaction operation.

CreateDatabaseRequest

Name	Type	Description
db	string	Create database with this name.
options	DatabaseOptions

CreateDatabaseResponse

Name	Type	Description
message	string	A detailed response message.
status	string	An enum with value set as "created".

CreateOrUpdateCollectionRequest

Name	Type	Description
db	string	Database name where to create collection.
collection	string	Collection name to create.
schema	bytes	Schema of the documents in this collection. The schema specifications are same as JSON schema specification defined <a href="https://json-schema.org/specification.html" title="here">here</a>. <p></p>The following is an schema example: `{ "title": "user", "description": "Collection of documents with details of users", "properties": { "id": { "description": "A unique identifier for the user", "type": "integer" }, "name": { "description": "Name of the user", "type": "string", "maxLength": 100 }, "balance": { "description": "User account balance", "type": "number" } }, "primary_key": ["id"] }`
only_create	bool	If set to true then the update schema request to the collection will fail by returning a conflict with HTTP Status code 409. The default is false.
options	CollectionOptions

CreateOrUpdateCollectionResponse

Name	Type	Description
message	string	A detailed response message.
status	string	An enum with value set as "created" or "updated"

DatabaseDescription

Name	Type	Description

DatabaseInfo

Name	Type	Description
db	string	Database name.
metadata	DatabaseMetadata	Metadata about the database.

DatabaseMetadata

Name	Type	Description

DatabaseOptions

Database requests modifying options.

Name	Type	Description

DeleteRequest

Name	Type	Description
db	string	Database name where to insert documents.
collection	string	Collection name where to insert documents.
filter	bytes	Delete documents which matching specified filter. A filter can simply be key, value where key is the field name and value would be the value for this field. Or a filter can be logical where two or more fields can be logically joined using $or and $and. A few examples of filter: <li> To delete a user document where the id has a value 1: ```{"id": 1 }``` <li> To delete all the user documents where the key "id" has a value 1 or 2 or 3: `{"$or": [{"id": 1}, {"id": 2}, {"id": 3}]}`
options	DeleteRequestOptions

DeleteRequestOptions

Additional options for deleted requests.

Name	Type	Description
write_options	WriteOptions
collation	Collation	A collation allows you to specify string comparison rules. Default is case-sensitive, to override it you can set this option to 'ci' that will apply to all the text fields in the filters.

DeleteResponse

Name	Type	Description
metadata	ResponseMetadata	Has metadata related to the documents stored.
status	string	an enum with value set as "deleted"

DescribeCollectionRequest

Name	Type	Description
db	string	Name of the database.
collection	string	Name of the collection.
options	CollectionOptions	Collection options.

DescribeCollectionResponse

A detailed description of the collection. The description returns collection metadata and the schema.

Name	Type	Description
collection	string	Name of the collection.
metadata	CollectionMetadata	Metadata about the collection.
schema	bytes	Schema of this collection.
size	int64	The size of this collection in bytes.

DescribeDatabaseRequest

Name	Type	Description
db	string	Name of the database.

DescribeDatabaseResponse

A detailed description of the database and all the associated collections. Description of the collection includes schema details as well.

Name	Type	Description
db	string	Name of the database.
metadata	DatabaseMetadata	Metadata about the database.
collections	CollectionDescription	A detailed description about all the collections. The description returns collection metadata and the schema.
size	int64	Sum of all the collections sizes present in this database

DropCollectionRequest

Name	Type	Description
db	string	Database name of the collection.
collection	string	Collection name to drop.
options	CollectionOptions

DropCollectionResponse

Name	Type	Description
message	string	A detailed response message.
status	string	An enum with value set as "dropped".

DropDatabaseRequest

Name	Type	Description
db	string	Drop database with this name. **Note**: Deletes all the collections in the database. Use with caution.
options	DatabaseOptions

DropDatabaseResponse

Name	Type	Description
message	string	A detailed response message.
status	string	An enum with value set as "dropped".

Error

The Error type defines a logical error model

Name	Type	Description
code	Code	The status code is a short, machine parsable string, which uniquely identifies the error type. Tigris to HTTP code mapping [here](/references/http-code)
message	string	A developer-facing descriptive error message

ErrorDetails

ErrorDetails defines error format passed by Tigris HTTP protocol

Name	Type	Description
code	string
message	string
retry	RetryInfo

EventsRequest

Name	Type	Description
db	string
collection	string
options	EventsRequestOptions

EventsRequestOptions

Name	Type	Description

EventsResponse

Name	Type	Description
event	StreamEvent

FacetCount

Name	Type	Description
count	int64
value	string

FacetStats

Additional stats for faceted field

Name	Type	Description
avg	double	Average of all values in a field. Only available for numeric fields
max	double	Maximum of all values in a field. Only available for numeric fields
min	double	Minimum of all values in a field. Only available for numeric fields
sum	double	Sum of all values in a field. Only available for numeric fields
count	int64	Total number of values in a field

GetInfoRequest

Name	Type	Description

GetInfoResponse

Name	Type	Description
server_version	string
error	Error	NOTE: This is a hack to propagate this object definition to OpenAPI

InsertRequest

Name	Type	Description
db	string	Database name where to insert documents.
collection	string	Collection name where to insert documents.
documents	bytes	Array of documents to insert. Each document is a JSON object.
options	InsertRequestOptions

InsertRequestOptions

additional options for insert requests.

Name	Type	Description
write_options	WriteOptions

InsertResponse

Name	Type	Description
metadata	ResponseMetadata	Has metadata related to the documents stored.
status	string	An enum with value set as "inserted"
keys	bytes	an array returns the value of the primary keys.

ListCollectionsRequest

Name	Type	Description
db	string	List collection in this database.
options	CollectionOptions

ListCollectionsResponse

Name	Type	Description
db	string	Name of the database.
collections	CollectionInfo	List of the collections info in the database.

ListDatabasesRequest

Name	Type	Description

ListDatabasesResponse

Name	Type	Description
databases	DatabaseInfo	List of the databases.

Page

Pagination metadata for SearchResponse

Name	Type	Description
current	int32	Number representing the current page of results
size	int32	Maximum number of results per page

PublishRequest

Name	Type	Description
db	string
collection	string
messages	bytes
options	PublishRequestOptions

PublishRequestOptions

Name	Type	Description
partition	int32

PublishResponse

Name	Type	Description
metadata	ResponseMetadata
status	string
keys	bytes

ReadRequest

Name	Type	Description
db	string	Database name to read documents from.
collection	string	Collection name to read documents from.
filter	bytes	Returns documents matching this filter. A filter can simply be a key, value pair where a key is the field name and the value would be the value for this field. Tigris also allows complex filtering by passing logical expressions. Logical filters are applied on two or more fields using `$or` and `$and`. A few examples of filters: <li> To read a user document where the id has a value 1: ```{"id": 1 }``` <li> To read all the user documents where the key "id" has a value 1 or 2 or 3: `{"$or": [{"id": 1}, {"id": 2}, {"id": 3}]}` Filter allows setting collation on an individual field level. To set collation for all the fields see options. The detailed documentation of the filter is <a href="https://docs.tigrisdata.com/overview/query#specification-1" title="here">here</a>.
fields	bytes	To read specific fields from a document. Default is all.
options	ReadRequestOptions	Options that can be used to modify the results, for example `limit` to control the number of documents returned by the server.

ReadRequestOptions

Options that can be used to modify the results, for example "limit" to control the number of documents returned by the server.

Name	Type	Description
limit	int64	Limit the number of documents returned by the read operation.
skip	int64	Number of documents to skip before starting to return resulting documents.
offset	bytes	A cursor for use in pagination. The next streams will return documents after this offset.
collation	Collation	A collation allows you to specify string comparison rules. Default is case-sensitive, to override it you can set this option to 'ci' that will apply to all the text fields in the filters.

ReadResponse

Name	Type	Description
data	bytes	Object containing the collection document.
resume_token	bytes	An internal key, used for pagination.
metadata	ResponseMetadata	Has metadata related to the documents stored.

ReplaceRequest

Name	Type	Description
db	string	Database name where to replace documents.
collection	string	Collection name where to replace documents.
documents	bytes	Array of documents to be replaced. Each document is a JSON object.
options	ReplaceRequestOptions

ReplaceRequestOptions

Additional options for replace requests.

Name	Type	Description
write_options	WriteOptions

ReplaceResponse

Name	Type	Description
metadata	ResponseMetadata	Has metadata related to the documents stored.
status	string	an enum with value set as "replaced"
keys	bytes	an array returns the value of the primary keys.

ResponseMetadata

Has metadata related to the documents stored.

Name	Type	Description
created_at	google.protobuf.Timestamp	Time at which the document was inserted/replaced. Measured in nano-seconds since the Unix epoch.
updated_at	google.protobuf.Timestamp	Time at which the document was updated. Measured in nano-seconds since the Unix epoch.
deleted_at	google.protobuf.Timestamp	Time at which the document was deleted. Measured in nano-seconds since the Unix epoch.

RetryInfo

Contains retry information

Name	Type	Description
delay	int32	retry delay advice in milliseconds

RollbackTransactionRequest

Rollback transaction with the given ID

Name	Type	Description
db	string	Database name this transaction belongs to.

RollbackTransactionResponse

Name	Type	Description
status	string	Status of rollback transaction operation.

SearchFacet

Name	Type	Description
counts	FacetCount
stats	FacetStats

SearchHit

Name	Type	Description
data	bytes	Actual search document
metadata	SearchHitMeta	Has metadata related to the search hit

SearchHitMeta

Contains metadata related to the search hit, has information about document created_at/updated_at as well.

Name	Type	Description
created_at	google.protobuf.Timestamp	Time at which the document was inserted/replaced. Measured in nano-seconds since the Unix epoch.
updated_at	google.protobuf.Timestamp	Time at which the document was updated. Measured in nano-seconds since the Unix epoch.

SearchMetadata

Name	Type	Description
found	int64	Total number of search results across all pages
total_pages	int32	Number representing the total pages of results
page	Page

SearchRequest

Name	Type	Description
db	string	Database name to read documents from.
collection	string	Collection name to read documents from.
q	string	Query string for searching across text fields
search_fields	string	Array of fields to project search query against
filter	bytes	Filter stacks on top of query results to further narrow down the results. Similar to `ReadRequest.filter`
facet	bytes	Facet query to aggregate results on given fields. The field name for the facet search can be passed like this `{"brand": { "size": 10 }}` where the size controls the total facets for this field.
sort	bytes	Array of fields and corresponding sort orders to order the results `[{ "salary": "$desc" }]`
include_fields	string	Array of document field names to include in results. By default, all fields are included.
exclude_fields	string	Array of document field names to exclude from results. `include_fields`, if specified, takes precedence over `exclude_fields`.
page_size	int32	Optionally can set the number of hits to be returned per page, default is 20.
page	int32	Optionally can specify the page to retrieve. If page is set then only hits for this page is returned
collation	Collation	A collation allows you to specify string comparison rules. Default is case-sensitive, to override it you can set this option to 'ci' that will apply to all the text fields in the filters.

SearchResponse

Response struct for search

Name	Type	Description
hits	SearchHit
facets	SearchResponse.FacetsEntry
meta	SearchMetadata

SearchResponse.FacetsEntry

Name	Type	Description
key	string
value	SearchFacet

StreamEvent

Name	Type	Description
tx_id	bytes
collection	string
op	string
key	bytes
lkey	bytes
rkey	bytes
data	bytes
last	bool

SubscribeRequest

Name	Type	Description
db	string
collection	string
options	SubscribeRequestOptions
filter	bytes	Filter allows you to subscribe only for events that you need. Filter syntax is similar to `ReadRequest.filter`.

SubscribeRequestOptions

Name	Type	Description
partitions	int32

SubscribeResponse

Name	Type	Description
message	bytes

TransactionCtx

Contains ID which uniquely identifies transaction This context is returned by BeginTransaction request and should be passed in the metadata (headers) of subsequent requests in order to run them in the context of the same transaction.

Name	Type	Description
id	string	Unique for a single transactional request.
origin	string	Serves as an internal identifier.

TransactionOptions

Options that can be used to modify the transaction semantics.

Name	Type	Description

UpdateRequest

Name	Type	Description
db	string	Database name where to update documents
collection	string	Collection name where to update documents
fields	bytes	Fields contains set of fields with the values which need to be updated. Should be proper JSON object.
filter	bytes	Update documents which matching specified filter. A filter can simply be key, value where key is the field name and value would be the value for this field. Or a filter can be logical where two or more fields can be logically joined using $or and $and. A few examples of filter: <li> To update a user document where the id has a value 1: ```{"id": 1 }``` <li> To update all the user documents where the key "id" has a value 1 or 2 or 3: `{"$or": [{"id": 1}, {"id": 2}, {"id": 3}]}`
options	UpdateRequestOptions

UpdateRequestOptions

Additional options for update requests.

Name	Type	Description
write_options	WriteOptions
collation	Collation	A collation allows you to specify string comparison rules. Default is case-sensitive, to override it you can set this option to 'ci' that will apply to all the text fields in the filters.

UpdateResponse

Name	Type	Description
metadata	ResponseMetadata	Has metadata related to the documents stored.
modified_count	int32	Returns the number of documents modified.
status	string	an enum with value set as "updated".

WriteOptions

Additional options to modify write requests.

Name	Type	Description

---

Enums

Code

Codes returned by the Tigris server in the case of error

Name	Number	Description
OK	0	200
CANCELLED	1	499
UNKNOWN	2	500
INVALID_ARGUMENT	3	400
DEADLINE_EXCEEDED	4	504
NOT_FOUND	5	404
ALREADY_EXISTS	6	409
PERMISSION_DENIED	7	403
RESOURCE_EXHAUSTED	8	429
FAILED_PRECONDITION	9	412
ABORTED	10	409
OUT_OF_RANGE	11	400
UNIMPLEMENTED	12	501
INTERNAL	13	500
UNAVAILABLE	14	503
DATA_LOSS	15	500
UNAUTHENTICATED	16	401
CONFLICT	17	409
BAD_GATEWAY	18	502
METHOD_NOT_ALLOWED	19	405

---

Services

Tigris

BeginTransaction

Method	BeginTransaction
Request	BeginTransactionRequest
Response	BeginTransactionResponse
Description	Starts a new transaction and returns a transactional object. All reads/writes performed within a transaction will run with serializable isolation.

CommitTransaction

Method	CommitTransaction
Request	CommitTransactionRequest
Response	CommitTransactionResponse
Description	Atomically commit all the changes performed in the context of the transaction. Commit provides all or nothing semantics by ensuring no partial updates are in the database due to a transaction failure.

RollbackTransaction

Method	RollbackTransaction
Request	RollbackTransactionRequest
Response	RollbackTransactionResponse
Description	Rollback transaction discards all the changes performed in the transaction

Insert

Method	Insert
Request	InsertRequest
Response	InsertResponse
Description	Inserts new documents in the collection and returns an AlreadyExists error if any of the documents in the request already exists. Insert provides idempotency by returning an error if the document already exists. To replace documents, use REPLACE API instead of INSERT.

Replace

Method	Replace
Request	ReplaceRequest
Response	ReplaceResponse
Description	Inserts the documents or replaces the existing documents in the collections.

Delete

Method	Delete
Request	DeleteRequest
Response	DeleteResponse
Description	Delete a range of documents in the collection using the condition provided in the filter.

Update

Method	Update
Request	UpdateRequest
Response	UpdateResponse
Description	Update a range of documents in the collection using the condition provided in the filter.

Read

Method	Read
Request	ReadRequest
Response	ReadResponse stream
Description	Reads a range of documents from the collection, or messages from a collection in case of event streaming. Tigris does not require you to index any fields and automatically index all the fields which means you can filter by any field in the document. An empty filter will trigger reading all the documents inside this collection. The API supports pagination that can be used by passing `Limit/Skip` parameters. The `skip` parameter skips the number of documents from the start and the `limit` parameter is used to specify the number of documents to read. You can find more detailed documentation of the Read API <a href="https://docs.tigrisdata.com/overview/query" title="here">here</a>.

Search

Method	Search
Request	SearchRequest
Response	SearchResponse stream
Description	Searches a collection for the documents matching the query, or messages in case of event streaming. A search can be a term search or a phrase search. Search API allows filtering the result set using filters as documented <a href="https://docs.tigrisdata.com/overview/query#specification-1" title="here">here</a>. You can also perform a faceted search by passing the fields in the facet parameter. You can find more detailed documentation of the Search API with multiple examples <a href="https://docs.tigrisdata.com/overview/search" title="here">here</a>.

CreateOrUpdateCollection

Method	CreateOrUpdateCollection
Request	CreateOrUpdateCollectionRequest
Response	CreateOrUpdateCollectionResponse
Description	Creates a new collection or atomically upgrades the collection to the new schema provided in the request. Schema changes are applied atomically and immediately without any downtime. This endpoint allows the creation of a collection based on the type. <p></p> There are two collection types supported by Tigris: <li> DOCUMENTS: Support CRUD APIs. <li> MESSAGES: Supports Pub/Sub APIs.

DropCollection

Method	DropCollection
Request	DropCollectionRequest
Response	DropCollectionResponse
Description	Drop the collection inside this database. This API deletes all of the documents inside this collection and any metadata associated with it.

ListDatabases

Method	ListDatabases
Request	ListDatabasesRequest
Response	ListDatabasesResponse
Description	List returns all the databases.

ListCollections

Method	ListCollections
Request	ListCollectionsRequest
Response	ListCollectionsResponse
Description	List all the collections present in the database passed in the request.

CreateDatabase

Method	CreateDatabase
Request	CreateDatabaseRequest
Response	CreateDatabaseResponse
Description	Creates a new database. Returns an AlreadyExists error with a status code 409 if the database already exists.

DropDatabase

Method	DropDatabase
Request	DropDatabaseRequest
Response	DropDatabaseResponse
Description	Drop database deletes all the collections in this database along with all of the documents, and associated metadata for these collections.

DescribeDatabase

Method	DescribeDatabase
Request	DescribeDatabaseRequest
Response	DescribeDatabaseResponse
Description	This API returns information related to the database along with all the collections inside the database. This can be used to retrieve the size of the database or to retrieve schemas and the size of all the collections present in this database.

DescribeCollection

Method	DescribeCollection
Request	DescribeCollectionRequest
Response	DescribeCollectionResponse
Description	Returns the information related to the collection. This can be used to retrieve the schema or size of the collection.

Events

Method	Events
Request	EventsRequest
Response	EventsResponse stream
Description	Stream real-time events for mutations made to the collections in the database. Each stream will have a transaction identifier attached to it and will have a boolean flag “last” set to the last event of the transaction which will be useful if a transaction performed more than one operation in the collection.

GetInfo

Method	GetInfo
Request	GetInfoRequest
Response	GetInfoResponse
Description	Provides the information about the server. This information includes returning the server version, etc.

Publish

Method	Publish
Request	PublishRequest
Response	PublishResponse
Description	Publish API is use to publish messages to the collection.

Subscribe

Method	Subscribe
Request	SubscribeRequest
Response	SubscribeResponse stream
Description	Subscribe is used to subscribe to the collection and receive messages from it.

---