Skip to main content

api.proto​

path server/v1/api.proto

package tigrisdata.v1


Messages​

BeginTransactionRequest​

Start new transaction in database specified by "db".

NameTypeDescription
dbstringDatabase name this transaction belongs to.
optionsTransactionOptionsThe transaction options.

BeginTransactionResponse​

Start transaction returns transaction context which uniquely identifies the transaction

NameTypeDescription
tx_ctxTransactionCtxReturns 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.

NameTypeDescription
casestring

CollectionDescription​

NameTypeDescription
collectionstringName of the collection.
metadataCollectionMetadataMetadata about the collection.
schemabytesCollections schema
sizeint64Collection size in bytes

CollectionInfo​

NameTypeDescription
collectionstringCollection name.
metadataCollectionMetadataMetadata about the collection.

CollectionMetadata​

NameTypeDescription

CollectionOptions​

Collection requests modifying options.

NameTypeDescription

CommitTransactionRequest​

Commit transaction with the given ID

NameTypeDescription
dbstringDatabase name this transaction belongs to.

CommitTransactionResponse​

NameTypeDescription
statusstringStatus of commit transaction operation.

CreateDatabaseRequest​

NameTypeDescription
dbstringCreate database with this name.
optionsDatabaseOptions

CreateDatabaseResponse​

NameTypeDescription
messagestringA detailed response message.
statusstringAn enum with value set as "created".

CreateOrUpdateCollectionRequest​

NameTypeDescription
dbstringDatabase name where to create collection.
collectionstringCollection name to create.
schemabytesSchema 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_createboolIf 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.
optionsCollectionOptions

CreateOrUpdateCollectionResponse​

NameTypeDescription
messagestringA detailed response message.
statusstringAn enum with value set as "created" or "updated"

DatabaseDescription​

NameTypeDescription

DatabaseInfo​

NameTypeDescription
dbstringDatabase name.
metadataDatabaseMetadataMetadata about the database.

DatabaseMetadata​

NameTypeDescription

DatabaseOptions​

Database requests modifying options.

NameTypeDescription

DeleteRequest​

NameTypeDescription
dbstringDatabase name where to insert documents.
collectionstringCollection name where to insert documents.
filterbytesDelete 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}]}`
optionsDeleteRequestOptions

DeleteRequestOptions​

Additional options for deleted requests.

NameTypeDescription
write_optionsWriteOptions
collationCollationA 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​

NameTypeDescription
metadataResponseMetadataHas metadata related to the documents stored.
statusstringan enum with value set as "deleted"

DescribeCollectionRequest​

NameTypeDescription
dbstringName of the database.
collectionstringName of the collection.
optionsCollectionOptionsCollection options.

DescribeCollectionResponse​

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

NameTypeDescription
collectionstringName of the collection.
metadataCollectionMetadataMetadata about the collection.
schemabytesSchema of this collection.
sizeint64The size of this collection in bytes.

DescribeDatabaseRequest​

NameTypeDescription
dbstringName of the database.

DescribeDatabaseResponse​

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

NameTypeDescription
dbstringName of the database.
metadataDatabaseMetadataMetadata about the database.
collectionsCollectionDescriptionA detailed description about all the collections. The description returns collection metadata and the schema.
sizeint64Sum of all the collections sizes present in this database

DropCollectionRequest​

NameTypeDescription
dbstringDatabase name of the collection.
collectionstringCollection name to drop.
optionsCollectionOptions

DropCollectionResponse​

NameTypeDescription
messagestringA detailed response message.
statusstringAn enum with value set as "dropped".

DropDatabaseRequest​

NameTypeDescription
dbstringDrop database with this name. **Note**: Deletes all the collections in the database. Use with caution.
optionsDatabaseOptions

DropDatabaseResponse​

NameTypeDescription
messagestringA detailed response message.
statusstringAn enum with value set as "dropped".

Error​

The Error type defines a logical error model

NameTypeDescription
codeCodeThe status code is a short, machine parsable string, which uniquely identifies the error type. Tigris to HTTP code mapping [here](/reference/http-code)
messagestringA developer-facing descriptive error message

ErrorDetails​

ErrorDetails defines error format passed by Tigris HTTP protocol

NameTypeDescription
codestring
messagestring
retryRetryInfo

EventsRequest​

NameTypeDescription
dbstring
collectionstring
optionsEventsRequestOptions

EventsRequestOptions​

NameTypeDescription

EventsResponse​

NameTypeDescription
eventStreamEvent

FacetCount​

NameTypeDescription
countint64
valuestring

FacetStats​

Additional stats for faceted field

NameTypeDescription
avgdoubleAverage of all values in a field. Only available for numeric fields
maxdoubleMaximum of all values in a field. Only available for numeric fields
mindoubleMinimum of all values in a field. Only available for numeric fields
sumdoubleSum of all values in a field. Only available for numeric fields
countint64Total number of values in a field

GetInfoRequest​

NameTypeDescription

GetInfoResponse​

NameTypeDescription
server_versionstring
errorErrorNOTE: This is a hack to propagate this object definition to OpenAPI

InsertRequest​

NameTypeDescription
dbstringDatabase name where to insert documents.
collectionstringCollection name where to insert documents.
documentsbytesArray of documents to insert. Each document is a JSON object.
optionsInsertRequestOptions

InsertRequestOptions​

additional options for insert requests.

NameTypeDescription
write_optionsWriteOptions

InsertResponse​

NameTypeDescription
metadataResponseMetadataHas metadata related to the documents stored.
statusstringAn enum with value set as "inserted"
keysbytesan array returns the value of the primary keys.

ListCollectionsRequest​

NameTypeDescription
dbstringList collection in this database.
optionsCollectionOptions

ListCollectionsResponse​

NameTypeDescription
dbstringName of the database.
collectionsCollectionInfoList of the collections info in the database.

ListDatabasesRequest​

NameTypeDescription

ListDatabasesResponse​

NameTypeDescription
databasesDatabaseInfoList of the databases.

Page​

Pagination metadata for SearchResponse

NameTypeDescription
currentint32Number representing the current page of results
sizeint32Maximum number of results per page

PublishRequest​

NameTypeDescription
dbstring
collectionstring
messagesbytes
optionsPublishRequestOptions

PublishRequestOptions​

NameTypeDescription
partitionint32

PublishResponse​

NameTypeDescription
metadataResponseMetadata
statusstring
keysbytes

ReadRequest​

NameTypeDescription
dbstringDatabase name to read documents from.
collectionstringCollection name to read documents from.
filterbytesReturns 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>.
fieldsbytesTo read specific fields from a document. Default is all.
optionsReadRequestOptionsOptions 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.

NameTypeDescription
limitint64Limit the number of documents returned by the read operation.
skipint64Number of documents to skip before starting to return resulting documents.
offsetbytesA cursor for use in pagination. The next streams will return documents after this offset.
collationCollationA 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​

NameTypeDescription
databytesObject containing the collection document.
resume_tokenbytesAn internal key, used for pagination.
metadataResponseMetadataHas metadata related to the documents stored.

ReplaceRequest​

NameTypeDescription
dbstringDatabase name where to replace documents.
collectionstringCollection name where to replace documents.
documentsbytesArray of documents to be replaced. Each document is a JSON object.
optionsReplaceRequestOptions

ReplaceRequestOptions​

Additional options for replace requests.

NameTypeDescription
write_optionsWriteOptions

ReplaceResponse​

NameTypeDescription
metadataResponseMetadataHas metadata related to the documents stored.
statusstringan enum with value set as "replaced"
keysbytesan array returns the value of the primary keys.

ResponseMetadata​

Has metadata related to the documents stored.

NameTypeDescription
created_atgoogle.protobuf.TimestampTime at which the document was inserted/replaced. Measured in nano-seconds since the Unix epoch.
updated_atgoogle.protobuf.TimestampTime at which the document was updated. Measured in nano-seconds since the Unix epoch.
deleted_atgoogle.protobuf.TimestampTime at which the document was deleted. Measured in nano-seconds since the Unix epoch.

RetryInfo​

Contains retry information

NameTypeDescription
delayint32retry delay advice in milliseconds

RollbackTransactionRequest​

Rollback transaction with the given ID

NameTypeDescription
dbstringDatabase name this transaction belongs to.

RollbackTransactionResponse​

NameTypeDescription
statusstringStatus of rollback transaction operation.

SearchFacet​

NameTypeDescription
countsFacetCount
statsFacetStats

SearchHit​

NameTypeDescription
databytesActual search document
metadataSearchHitMetaHas metadata related to the search hit

SearchHitMeta​

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

NameTypeDescription
created_atgoogle.protobuf.TimestampTime at which the document was inserted/replaced. Measured in nano-seconds since the Unix epoch.
updated_atgoogle.protobuf.TimestampTime at which the document was updated. Measured in nano-seconds since the Unix epoch.

SearchMetadata​

NameTypeDescription
foundint64Total number of search results across all pages
total_pagesint32Number representing the total pages of results
pagePage

SearchRequest​

NameTypeDescription
dbstringDatabase name to read documents from.
collectionstringCollection name to read documents from.
qstringQuery string for searching across text fields
search_fieldsstringArray of fields to project search query against
filterbytesFilter stacks on top of query results to further narrow down the results. Similar to `ReadRequest.filter`
facetbytesFacet 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.
sortbytesArray of fields and corresponding sort orders to order the results `[{ "salary": "$desc" }]`
include_fieldsstringArray of document field names to include in results. By default, all fields are included.
exclude_fieldsstringArray of document field names to exclude from results. `include_fields`, if specified, takes precedence over `exclude_fields`.
page_sizeint32Optionally can set the number of hits to be returned per page, default is 20.
pageint32Optionally can specify the page to retrieve. If page is set then only hits for this page is returned
collationCollationA 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

NameTypeDescription
hitsSearchHit
facetsSearchResponse.FacetsEntry
metaSearchMetadata

SearchResponse.FacetsEntry​

NameTypeDescription
keystring
valueSearchFacet

StreamEvent​

NameTypeDescription
tx_idbytes
collectionstring
opstring
keybytes
lkeybytes
rkeybytes
databytes
lastbool

SubscribeRequest​

NameTypeDescription
dbstring
collectionstring
optionsSubscribeRequestOptions
filterbytesFilter allows you to subscribe only for events that you need. Filter syntax is similar to `ReadRequest.filter`.

SubscribeRequestOptions​

NameTypeDescription
partitionsint32

SubscribeResponse​

NameTypeDescription
messagebytes

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.

NameTypeDescription
idstringUnique for a single transactional request.
originstringServes as an internal identifier.

TransactionOptions​

Options that can be used to modify the transaction semantics.

NameTypeDescription

UpdateRequest​

NameTypeDescription
dbstringDatabase name where to update documents
collectionstringCollection name where to update documents
fieldsbytesFields contains set of fields with the values which need to be updated. Should be proper JSON object.
filterbytesUpdate 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}]}`
optionsUpdateRequestOptions

UpdateRequestOptions​

Additional options for update requests.

NameTypeDescription
write_optionsWriteOptions
collationCollationA 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​

NameTypeDescription
metadataResponseMetadataHas metadata related to the documents stored.
modified_countint32Returns the number of documents modified.
statusstringan enum with value set as "updated".

WriteOptions​

Additional options to modify write requests.

NameTypeDescription

Enums​

Code​

Codes returned by the Tigris server in the case of error

NameNumberDescription
OK0200
CANCELLED1499
UNKNOWN2500
INVALID_ARGUMENT3400
DEADLINE_EXCEEDED4504
NOT_FOUND5404
ALREADY_EXISTS6409
PERMISSION_DENIED7403
RESOURCE_EXHAUSTED8429
FAILED_PRECONDITION9412
ABORTED10409
OUT_OF_RANGE11400
UNIMPLEMENTED12501
INTERNAL13500
UNAVAILABLE14503
DATA_LOSS15500
UNAUTHENTICATED16401
CONFLICT17409
BAD_GATEWAY18502
METHOD_NOT_ALLOWED19405

Services​

Tigris​

BeginTransaction​

MethodBeginTransaction
RequestBeginTransactionRequest
ResponseBeginTransactionResponse
DescriptionStarts a new transaction and returns a transactional object. All reads/writes performed within a transaction will run with serializable isolation.

CommitTransaction​

MethodCommitTransaction
RequestCommitTransactionRequest
ResponseCommitTransactionResponse
DescriptionAtomically 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​

MethodRollbackTransaction
RequestRollbackTransactionRequest
ResponseRollbackTransactionResponse
DescriptionRollback transaction discards all the changes performed in the transaction

Insert​

MethodInsert
RequestInsertRequest
ResponseInsertResponse
DescriptionInserts 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​

MethodReplace
RequestReplaceRequest
ResponseReplaceResponse
DescriptionInserts the documents or replaces the existing documents in the collections.

Delete​

MethodDelete
RequestDeleteRequest
ResponseDeleteResponse
DescriptionDelete a range of documents in the collection using the condition provided in the filter.

Update​

MethodUpdate
RequestUpdateRequest
ResponseUpdateResponse
DescriptionUpdate a range of documents in the collection using the condition provided in the filter.

Read​

MethodRead
RequestReadRequest
ResponseReadResponse stream
DescriptionReads 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>.
MethodSearch
RequestSearchRequest
ResponseSearchResponse stream
DescriptionSearches 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​

MethodCreateOrUpdateCollection
RequestCreateOrUpdateCollectionRequest
ResponseCreateOrUpdateCollectionResponse
DescriptionCreates 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​

MethodDropCollection
RequestDropCollectionRequest
ResponseDropCollectionResponse
DescriptionDrop the collection inside this database. This API deletes all of the documents inside this collection and any metadata associated with it.

ListDatabases​

MethodListDatabases
RequestListDatabasesRequest
ResponseListDatabasesResponse
DescriptionList returns all the databases.

ListCollections​

MethodListCollections
RequestListCollectionsRequest
ResponseListCollectionsResponse
DescriptionList all the collections present in the database passed in the request.

CreateDatabase​

MethodCreateDatabase
RequestCreateDatabaseRequest
ResponseCreateDatabaseResponse
DescriptionCreates a new database. Returns an AlreadyExists error with a status code 409 if the database already exists.

DropDatabase​

MethodDropDatabase
RequestDropDatabaseRequest
ResponseDropDatabaseResponse
DescriptionDrop database deletes all the collections in this database along with all of the documents, and associated metadata for these collections.

DescribeDatabase​

MethodDescribeDatabase
RequestDescribeDatabaseRequest
ResponseDescribeDatabaseResponse
DescriptionThis 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​

MethodDescribeCollection
RequestDescribeCollectionRequest
ResponseDescribeCollectionResponse
DescriptionReturns the information related to the collection. This can be used to retrieve the schema or size of the collection.

Events​

MethodEvents
RequestEventsRequest
ResponseEventsResponse stream
DescriptionStream 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​

MethodGetInfo
RequestGetInfoRequest
ResponseGetInfoResponse
DescriptionProvides the information about the server. This information includes returning the server version, etc.

Publish​

MethodPublish
RequestPublishRequest
ResponsePublishResponse
DescriptionPublish API is use to publish messages to the collection.

Subscribe​

MethodSubscribe
RequestSubscribeRequest
ResponseSubscribeResponse stream
DescriptionSubscribe is used to subscribe to the collection and receive messages from it.