Tigris API Reference (0.0.1)

Download OpenAPI specification:Download

Overview

This section is organized around HTTP APIs. The APIs accepts JSON requests and returns JSON-encoded responses.The APIs conforms to standard HTTP status codes.

Errors

Tigris uses conventional HTTP response codes to indicate the success or failure of an API request.The response will contain an error code or other information that reveals the reason of the error. The error response is in JSON format and is structured like this:

 {
   "error": {
     "code": "ALREADY_EXISTS",
     "message": "row already exists"
   }
 }

Status 2xx

HTTP Code	Reason
200 - OK	Everything worked as expected.

Status 4xx

Status codes in the 400-499 range indicate errors that have been caused by the requesting application (e.g., a malformed request body has been sent). Retrying such requests with the same request body is pointless and will result in the same status code again. Some 4xx errors can be handled programmatically. Change the request accordingly before retrying. Below you can find the most frequent 4XX errors and how to fix them.

HTTP Code	Tigris Code	Reason
400 - Bad Request	INVALID_ARGUMENT	The request was unacceptable, often due to missing a required parameter. Examples: Missing documents for write request Collection or Database name is not following the allowed characters
401 - Unauthorized	UNAUTHENTICATED	No valid API key provided. Check that your `api_key` and `api_secret` are correct.
403 - Forbidden	PERMISSION_DENIED	The API key doesn't have permissions to perform the request.
404 - Not Found	NOT_FOUND	The requested resource doesn't exist. Examples: Database or Collection doesn't exists Access Token missing in the request header
409 - Conflict	ALREADY_EXISTS	TThe request conflicts with another request (perhaps due to using the same idempotent key). Examples: Trying to insert document again for the primary key that already exists Creating a database that already exists
429 - Too Many Requests	RESOURCE_EXHAUSTED	Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

Status 5xx

The 5xx range indicate an error with Tigris servers (these are rare).

HTTP Code	Tigris Code	Reason
500 - Internal Server Error	UNKNOWN	Something went wrong on Tigris server side.
501 - Not Implemented	UNIMPLEMENTED	Not supported by the Tigris server and cannot be handled.
502 - Bad Gateway	BAD_GATEWAY	The API key doesn't have permissions to perform the request.
503 - Service Unavailable	UNAVAILABLE	The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.
504 - Gateway Timeout	DEADLINE_EXCEEDED	Tigris server is unable to process the request timely. Common causes are that request is expensive, or server is overloaded.

Idempotent Requests

Tigris provides idempotency guarantees when an API call is disrupted and either no response is returned or an HTTP Status code 429,500,501,502,503 is returned. These errors ensure that the request is not committed and retrying the same request will have the same effect.

Limitations

Do not rely on case to distinguish between databases or collections names.

Database Name and Collection Name cannot be empty and can only have the characters matches the regex: ^[a-zA-Z]+[a-zA-Z0-9_]+$.

Duplicate field names are not allowed.

The maximum allowed document size is 100KB.

The maximum allowed transaction size is 10MB.

Application Keys

The application keys section provide APIs that can be used to manage application keys for your project. A single project can have one or more application keys.

List all the global app keys

Lists all the global app keys visible to requesting actor.

Authorizations:

BearerAuth

Responses

Response samples

200
default

Content type

application/json

{"app_keys": [{"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string"
}
]
}

Creates the global app key

Create a global app key. These keys can be used to operate on any project inside your account.

Authorizations:

BearerAuth

Request Body schema: application/json

name	string A human readable app name
description	string A human readable app description

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string"
}

Response samples

200
default

Content type

application/json

{"created_app_key": {"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string"
}
}

Deletes the global app key

Delete the global app key.

Authorizations:

BearerAuth

Request Body schema: application/json

id	string app_key id

Responses

Request samples

Payload

Content type

application/json

{"id": "string"
}

Response samples

200
default

Content type

application/json

{"deleted": true
}

Rotates the global app key secret

Endpoint is used to rotate the secret for the app key.

Authorizations:

BearerAuth

Request Body schema: application/json

id	string global app key id

Responses

Request samples

Payload

Content type

application/json

{"id": "string"
}

Response samples

200
default

Content type

application/json

{"app_key": {"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string"
}
}

Updates the description of the global app key

Update the description of the global app key.

Authorizations:

BearerAuth

Request Body schema: application/json

id	string app key id - this is not allowed to update
name	string A new human readable app name
description	string A new human readable app description

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string",
"description": "string"
}

Response samples

200
default

Content type

application/json

{"updated_app_key": {"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string"
}
}

List all the app keys

Lists all app keys visible to requesting actor.

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name filter

query Parameters

key_type

string

Optionally the key type one of [credentials, api_key]. Defaults to credentials

Responses

Response samples

200
default

Content type

application/json

{"app_keys": [{"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string",
"project": "string",
"role": "string",
"key_type": "string"
}
]
}

Creates the app key

Create an app key.

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name

Request Body schema: application/json

name	string A human readable app name
description	string A human readable app description
role	string role name
key_type	string key_type [credentials, api_key]

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string",
"role": "string",
"key_type": "string"
}

Response samples

200
default

Content type

application/json

{"created_app_key": {"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string",
"project": "string",
"role": "string",
"key_type": "string"
}
}

Deletes the app key

Delete an app key.

Authorizations:

BearerAuth

path Parameters

project

required

string

project name

Request Body schema: application/json

id	string app_key id

Responses

Request samples

Payload

Content type

application/json

{"id": "string"
}

Response samples

200
default

Content type

application/json

{"deleted": true
}

Rotates the app key secret

Endpoint is used to rotate the secret for the app key.

Authorizations:

BearerAuth

path Parameters

project

required

string

project name

Request Body schema: application/json

id	string app key id
project	string project name

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"project": "string"
}

Response samples

200
default

Content type

application/json

{"app_key": {"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string",
"project": "string",
"role": "string",
"key_type": "string"
}
}

Updates the description of the app key

Update the description of an app key.

Authorizations:

BearerAuth

path Parameters

project

required

string

project name - this is not allowed to update

Request Body schema: application/json

id	string app key id - this is not allowed to update
name	string A new human readable app name
description	string A new human readable app description

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string",
"description": "string"
}

Response samples

200
default

Content type

application/json

{"updated_app_key": {"id": "string",
"name": "string",
"description": "string",
"secret": "string",
"created_at": 0,
"created_by": "string",
"updated_at": 0,
"updated_by": "string",
"project": "string",
"role": "string",
"key_type": "string"
}
}

Authentication

The auth section of API provides OAuth 2.0 APIs. Tigris supports pluggable OAuth provider. Pass the token in the headers for authentication, as an example -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6I"(replace it with your token). All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Access Token

Endpoint for receiving access token from Tigris Server. The endpoint requires Grant Type(grant_type) which has two possible values "REFRESH_TOKEN" or "CLIENT_CREDENTIALS" based on which either Refresh token(refresh_token) needs to be set or client credentials(client_id, client_secret).

Authorizations:

BearerAuth

Request Body schema: x-www-form-urlencoded

grant_type	string <enum> Enum: "REFRESH_TOKEN" "CLIENT_CREDENTIALS"
refresh_token	string Refresh token is required when grant type is set as `REFRESH_TOKEN`.
client_id	string Client Id is required when grant type is set as `CLIENT_CREDENTIALS`.
client_secret	string Your Tigris API Key is required when grant type is set as `CLIENT_CREDENTIALS`.

Responses

Response samples

200
default

Content type

application/json

{"access_token": "string",
"refresh_token": "string",
"expires_in": 0
}

Billing

The billing section provides APIs for managing invoices and payments infrastructure.

Lists all invoices for the user

ListInvoices fetches past invoices for this user

Authorizations:

BearerAuth

Request Body schema: application/json

starting_on	string <date-time> RFC 3339 timestamp (inclusive). Invoices will only be returned for billing periods that start at or after this time.
ending_before	string <date-time> RFC 3339 timestamp (exclusive). Invoices will only be returned for billing periods that end before this time.
invoice_id	string optionally filter by a specific invoice_id
page_size	integer <int32> maximum number of items to include in result set
next_page	string pagination token for fetching a particular result page, first page will be fetched if `null`

Responses

Request samples

Payload

Content type

application/json

{"starting_on": "2019-08-24T14:15:22Z",
"ending_before": "2019-08-24T14:15:22Z",
"invoice_id": "string",
"page_size": 0,
"next_page": "string"
}

Response samples

200
default

Content type

application/json

{"data": [{"id": "string",
"entries": [{"name": "string",
"quantity": 0,
"total": 0,
"charges": [{"name": "string",
"quantity": 0,
"subtotal": 0,
"tiers": [{"starting_at": 0,
"quantity": 0,
"price": 0,
"subtotal": 0
}
]
}
]
}
],
"start_time": "2019-08-24T14:15:22Z",
"end_time": "2019-08-24T14:15:22Z",
"subtotal": 0,
"total": 0,
"plan_name": "string"
}
],
"next_page": "string"
}

Get billed usage for the user over a time period

GetUsage gets the aggregate usage for this user in given time period

Authorizations:

BearerAuth

Request Body schema: application/json

start_time	string <date-time> RFC 3339 starting time to get usage from
end_time	string <date-time> RFC 3339 ending time to get usage until
metrics	Array of strings Optionally filter usage data by specific metrics. By default, all metrics are included in usage data
aggregate_by	string <enum> Enum: "HOUR" "DAY" Optionally aggregate data over a time window. By default, data will be aggregated "hourly"
next_page	string Optional pagination token for fetching a particular result page, first page will be fetched if `null`

Responses

Request samples

Payload

Content type

application/json

{"start_time": "2019-08-24T14:15:22Z",
"end_time": "2019-08-24T14:15:22Z",
"metrics": ["string"
],
"aggregate_by": "HOUR",
"next_page": "string"
}

Response samples

200
default

Content type

application/json

{"data": {"property1": {"series": [{"start_time": "2019-08-24T14:15:22Z",
"end_time": "2019-08-24T14:15:22Z",
"value": 0
}
]
},
"property2": {"series": [{"start_time": "2019-08-24T14:15:22Z",
"end_time": "2019-08-24T14:15:22Z",
"value": 0
}
]
}
},
"next_page": "string"
}

Cache

The cache section provide APIs that can be used to perform cache operations.

Lists all the caches for the given project

Authorizations:

BearerAuth

path Parameters

project

required

string

Tigris project name

Responses

Response samples

200
default

Content type

application/json

{"caches": [{"name": "string"
}
]
}

Creates the cache

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name
name required	string cache name

Request Body schema: application/json

object (CreateCacheOptions)

ttl_ms

integer <uint64>

Responses

Request samples

Payload

Content type

application/json

{"options": {"ttl_ms": 0
}
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Deletes the cache

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name
name required	string cache name

Request Body schema: application/json

object (DeleteCacheRequest)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Lists all the key for this cache

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name
name required	string cache name

query Parameters

cursor	integer <uint64> optional - cursor - skip this argument if no cursor is associated
count	integer <int64> optional - count of keys to return a stream response line.
pattern	string optional key pattern

Responses

Response samples

200
default

Content type

application/json

{"keys": ["string"
],
"cursor": 0
}

Deletes an entry from cache

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name
name required	string cache name
key required	string cache key

Request Body schema: application/json

object (DelRequest)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Reads an entry from cache

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name
name required	string cache name
key required	string cache key

Responses

Response samples

200
default

Content type

application/json

{"value": "string",
"expires_in_ms": 0
}

Sets an entry in the cache and returns the previous value if exists

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name
name required	string cache name
key required	string cache key

Request Body schema: application/json

value

string <byte>

free form byte[] value

Responses

Request samples

Payload

Content type

application/json

{"value": "string"
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string",
"old_value": "string"
}

Sets an entry in the cache

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name
name required	string cache name
key required	string cache key

Request Body schema: application/json

value	string <byte> free form byte[] value
ex	integer <uint64> optional - ttl specific to this key in second
px	integer <uint64> optional - ttl specific to this key in millisecond
nx	boolean set only if the key doesn't exist
xx	boolean set only if the key exist

Responses

Request samples

Payload

Content type

application/json

{"value": "string",
"ex": 0,
"px": 0,
"nx": true,
"xx": true
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Collections

The Collections section provide APIs that can be used to manage collections. A collection can have one or more documents.

Create or update a batch of collections

Similar to creating a single collection, this API performs batch creation or upgrade of collections. An error is returned as soon as first operation in the batch fails. This API is not atomic i.e. each operation is performed individually and in the serial order.

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name whose db is under target to create or update collection.

Request Body schema: application/json

branch	string Optionally specify a database branch name to perform operation on
schemas	Array of objects collections to create.
only_create	boolean
options	object (CollectionOptions) Collection requests modifying options.

Responses

Request samples

Payload

Content type

application/json

{"branch": "string",
"schemas": [{ }
],
"only_create": true,
"options": { }
}

Response samples

200
default

Content type

application/json

{"resp": [{"status": "string"
}
],
"failedAtIndex": 0,
"error": {"code": "OK",
"message": "string"
}
}

Create or update a collection

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.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to create or update collection.
collection required	string Collection name to create.

Request Body schema: application/json

schema	object The schema specifications are same as JSON schema specification defined here. 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": 128 }, "balance": { "description": "User account balance", "type": "number" } }, "primary_key": ["id"] }`
only_create	boolean 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	object (CollectionOptions) Collection requests modifying options.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"schema": { },
"only_create": true,
"options": { },
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Describe Collection

Returns the information related to the collection. This can be used to retrieve the schema or size of the collection.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to get description of its collection.
collection required	string Name of the collection.

Request Body schema: application/json

project	string Project name whose db is under target to get description of its collection.
collection	string Name of the collection.
schema_format	string Return schema in the requested format. Format can be JSON, Go, TypeScript, Java. Default is JSON.
options	object (CollectionOptions) Collection requests modifying options.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"collection": "string",
"schema_format": "string",
"options": { },
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"collection": "string",
"metadata": { },
"schema": { },
"size": 0,
"indexes": [{"name": "string",
"state": "string",
"fields": [{"name": "string"
}
]
}
],
"search_status": "string"
}

Count Documents

Count returns the number of documents in the collection. The filter parameter can be used to select which documents contribute to the count. An empty filter means count all documents in the collection.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to count documents from.
collection required	string Collection name to count documents from.

Request Body schema: application/json

project	string Project name whose db is under target to count documents from.
collection	string Collection name to count documents from.
filter	string <byte> Count documents matching this filter. An empty filter means count all documents. 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`. The detailed documentation of the filter is here.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"collection": "string",
"filter": "string",
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"count": 0
}

Delete Documents

Delete a range of documents in the collection using the condition provided in the filter. No partial deletes are possible as the API provides ACID semantics.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to delete documents.
collection required	string Collection name where to insert documents.

Request Body schema: application/json

filter	object 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: To delete a user document where the id has a value 1: `{"id": 1 }` 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}]}`
	object (DeleteRequestOptions) Additional options for deleted requests.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"filter": { },
"options": {"write_options": { },
"collation": {"case": "string"
},
"limit": 0
},
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"status": "string",
"deleted_count": 0
}

Explain Read Documents

Explain takes the same parameters as Read and returns how the Tigris Query Planner would process the response

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to read documents from.
collection required	string Collection name to read documents from.

Request Body schema: application/json

filter	object 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: To read a user document where the id has a value 1: `{"id": 1 }` 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 here.
fields	object To read specific fields from a document. Default is all.
	object (ReadRequestOptions) Options that can be used to modify the results, for example "limit" to control the number of documents returned by the server.
sort	Array of objects Array of fields and corresponding sort orders to order the results. Ex: 1 `[{ "salary": "$desc" }]`, Ex: 2 `[{ "salary": "$asc"}]`
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"filter": { },
"fields": { },
"options": {"limit": 0,
"skip": 0,
"offset": "string",
"collation": {"case": "string"
}
},
"sort": [{ }
],
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"collection": "string",
"read_type": "string",
"filter": "string",
"sorting": "string",
"key_range": ["string"
],
"field": "string"
}

Import Documents

Imports documents into the collection.

It automatically:

Detects the schema of the documents in the batch
Evolves the schema as soon as it's backward compatible
Creates collection with inferred schema (if requested)

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to import documents.
collection required	string Collection name where to import documents.

Request Body schema: application/json

documents	Array of objects Array of documents to import. Each document is a JSON object.
	object (ImportRequestOptions) additional options for import requests.
branch	string Optionally specify a database branch name to perform operation on
create_collection	boolean Allow to create collection if it doesn't exists
primary_key	Array of strings List of fields which constitutes primary key of the collection If not specified and field with name 'id' is present, it's used as a primary key, further if inferred type is UUID, then it's set as autogenerated.
autogenerated	Array of strings The list of autogenerated fields of the collection

Responses

Request samples

Payload

Content type

application/json

{"documents": [{ }
],
"options": {"write_options": { }
},
"branch": "string",
"create_collection": true,
"primary_key": ["string"
],
"autogenerated": ["string"
]
}

Response samples

200
default

Content type

application/json

{"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"status": "string",
"keys": ["string"
]
}

Build Index

Reads all the documents in the collection and rebuild the secondary indexes for this collection.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to index documents.
collection required	string Name of the collection.

Request Body schema: application/json

project	string Project name whose db is under target to index documents.
collection	string Name of the collection.
branch	string Optionally specify a database branch name to perform operation on.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"collection": "string",
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"indexes": [{"name": "string",
"state": "string",
"fields": [{"name": "string"
}
]
}
]
}

Insert Documents

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.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to insert documents.
collection required	string Collection name where to insert documents.

Request Body schema: application/json

documents	Array of objects Array of documents to insert. Each document is a JSON object.
	object (InsertRequestOptions) additional options for insert requests.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"documents": [{ }
],
"options": {"write_options": { }
},
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"status": "string",
"keys": ["string"
]
}

Read Documents

Reads a range of documents from the collection. 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 documentations of the Read API here. This API is streaming as it allows continuous transmission of documents between the server and the client, with no need for the client to wait for a complete response before processing the data.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to read documents from.
collection required	string Collection name to read documents from.

Request Body schema: application/json

filter	object 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: To read a user document where the id has a value 1: `{"id": 1 }` 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 here.
fields	object To read specific fields from a document. Default is all.
	object (ReadRequestOptions) Options that can be used to modify the results, for example "limit" to control the number of documents returned by the server.
sort	Array of objects Array of fields and corresponding sort orders to order the results. Ex: 1 `[{ "salary": "$desc" }]`, Ex: 2 `[{ "salary": "$asc"}]`
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"filter": { },
"fields": { },
"options": {"limit": 0,
"skip": 0,
"offset": "string",
"collation": {"case": "string"
}
},
"sort": [{ }
],
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"result": {"data": { },
"resume_token": "string",
"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
}
},
"error": {"code": "OK",
"message": "string"
}
}

Insert or Replace Documents

Inserts the documents or replaces the existing documents in the collections. All the operations are executed in the context of a transaction and provides all-or-nothing semantics.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to replace documents.
collection required	string Collection name where to replace documents.

Request Body schema: application/json

documents	Array of objects Array of documents to be replaced. Each document is a JSON object.
	object (ReplaceRequestOptions) Additional options for replace requests.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"documents": [{ }
],
"options": {"write_options": { }
},
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"status": "string",
"keys": ["string"
]
}

Search Documents

Searches a collection for the documents matching the query. A search can be a term search, phrase search or a vector search. Search API allows filtering the result set using filters as documented here. 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 here. This API is streaming which means a page as soon as it is processed is pushed to the client immediately.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to search documents from.
collection required	string Collection name to search documents from.

Request Body schema: application/json

q	string Query string for searching across text fields
search_fields	Array of strings Array of fields to project search query against
filter	object Filter stacks on top of query results to further narrow down the results. Similar to `ReadRequest.filter`
facet	object 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	Array of objects Array of fields and corresponding sort orders to order the results `[{ "salary": "$desc" }]`
include_fields	Array of strings Array of document field names to include in results. By default, all fields are included.
exclude_fields	Array of strings Array of document field names to exclude from results. `include_fields`, if specified, takes precedence over `exclude_fields`.
page_size	integer <int32> Optionally can set the number of hits to be returned per page, default is 20.
page	integer <int32> Optionally can specify the page to retrieve. If page is set then only hits for this page is returned
	object (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.
branch	string Optionally specify a database branch name to perform operation on
group_by	string <byte> Group by can be used to group search results. For example, to group by city field the syntax would be: `{ "fields": ["city"]}`. Optionally a grouping limit can be set. By default it is 3 per group.
vector	string <byte> Vector is an object that is used for vector search. For example, to vector search on a "vec" field the syntax would be: `{ "vec": [0.34, 0.12, 0.95], "top_k": 10}`.
fields	object

Responses

Request samples

Payload

Content type

application/json

{"q": "string",
"search_fields": ["string"
],
"filter": { },
"facet": { },
"sort": [{ }
],
"include_fields": ["string"
],
"exclude_fields": ["string"
],
"page_size": 0,
"page": 0,
"collation": {"case": "string"
},
"branch": "string",
"group_by": "string",
"vector": "string",
"fields": { }
}

Response samples

200
default

Content type

application/json

{"result": {"hits": [{"data": { },
"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"match": {"fields": [{"name": "string"
}
],
"score": "string",
"vector_distance": 0
}
}
}
],
"facets": {"property1": {"counts": [{"count": 0,
"value": "string"
}
],
"stats": {"avg": 0,
"max": 0,
"min": 0,
"sum": 0,
"count": 0
}
},
"property2": {"counts": [{"count": 0,
"value": "string"
}
],
"stats": {"avg": 0,
"max": 0,
"min": 0,
"sum": 0,
"count": 0
}
}
},
"meta": {"found": 0,
"total_pages": 0,
"page": {"current": 0,
"size": 0
},
"matched_fields": ["string"
]
},
"group": [{"group_keys": ["string"
],
"hits": [{"data": { },
"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"match": {"fields": [{"name": null
}
],
"score": "string",
"vector_distance": 0
}
}
}
]
}
]
},
"error": {"code": "OK",
"message": "string"
}
}

Build Search Index

Reads all the documents in the collection and rebuild the search index for this collection.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to index documents.
collection required	string Name of the collection.

Request Body schema: application/json

project	string Project name whose db is under target to index documents.
collection	string Name of the collection.
branch	string Optionally specify a database branch name to perform operation on.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"collection": "string",
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"status": "string"
}

Update Documents.

Update a range of documents in the collection using the condition provided in the filter. No partial updates are possible as the API provides ACID semantics.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to update documents
collection required	string Collection name where to update documents

Request Body schema: application/json

fields	object Fields contains set of fields with the values which need to be updated. Should be proper JSON object.
filter	object 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: To update a user document where the id has a value 1: `{"id": 1 }` 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}]}`
	object (UpdateRequestOptions) Additional options for update requests.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"fields": { },
"filter": { },
"options": {"write_options": { },
"collation": {"case": "string"
},
"limit": 0
},
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"deleted_at": "2019-08-24T14:15:22Z"
},
"modified_count": 0,
"status": "string"
}

Drop Collection

Drops the collection inside this project. This API deletes all of the documents inside this collection and any metadata associated with it.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to delete collection.
collection required	string Collection name to delete.

Request Body schema: application/json

options	object (CollectionOptions) Collection requests modifying options.
branch	string Optionally specify a project branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"options": { },
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Database

The Database section provide APIs that can be used to interact with the database. A single Database can have one or more collections. A database is created automatically for you when you create a project.

List database branches

Authorizations:

BearerAuth

path Parameters

project

required

string

List database branches in this project

Responses

Response samples

200
default

Content type

application/json

{"branches": [{"branch": "string",
"metadata": { }
}
]
}

Create a database branch

Creates a new database branch, if not already existing.

Authorizations:

BearerAuth

path Parameters

project required	string Create a database branch in this project
branch required	string Name of the database branch to be created. Note: `main` is a reserved branch name for primary database and is automatically created with CreateProject

Request Body schema: application/json

object (CreateBranchRequest)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Delete a database branch

Deletes a database branch, if exists. Throws 400 Bad Request if "main" branch is being deleted

Authorizations:

BearerAuth

path Parameters

project required	string Delete a database branch in this project
branch required	string Name of the database branch to delete. Note: `main` branch cannot be deleted, use DeleteProject instead

Request Body schema: application/json

object (DeleteBranchRequest)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

List Collections

List all the collections present in the project passed in the request.

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name whose db is under target to list collections.

query Parameters

branch

string

Optionally specify a database branch name to perform operation on

Responses

Response samples

200
default

Content type

application/json

{"collections": [{"collection": "string",
"metadata": { }
}
]
}

Describe database

This API returns information related to the project along with all the collections inside the project. This can be used to retrieve the schemas or the size of the project which means size of all the database branches and the size of all the collections present in this project.

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name whose db is under target to get description.

Request Body schema: application/json

project	string Project name whose db is under target to get description.
schema_format	string Return schema in the requested format. Format can be JSON, Go, TypeScript, Java. Default is JSON.
branch	string Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"schema_format": "string",
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"metadata": { },
"collections": [{"collection": "string",
"metadata": { },
"schema": { },
"size": 0,
"indexes": [{"name": "string",
"state": "string",
"fields": [{"name": "string"
}
]
}
]
}
],
"size": 0,
"branches": ["string"
]
}

Begin a transaction

Starts a new transaction and returns a transactional object. All reads/writes performed within a transaction will run with serializable isolation. Tigris offers global transactions, with ACID properties and strict serializability.

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name whose DB this transaction belongs to.

Request Body schema: application/json

options	object (TransactionOptions) Options that can be used to modify the transaction semantics.
branch	string Optionally specify a project branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"options": { },
"branch": "string"
}

Response samples

200
default

Content type

application/json

{"tx_ctx": {"id": "string",
"origin": "string"
}
}

Commit a Transaction

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 project due to a transaction failure.

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name whose DB this transaction belongs to.

Request Body schema: application/json

branch

string

Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"branch": "string"
}

Response samples

200
default

Content type

application/json

{"status": "string"
}

Rollback a transaction

Rollback transaction discards all the changes performed in the transaction

Authorizations:

BearerAuth

path Parameters

project

required

string

Project name whose DB this transaction belongs to.

Request Body schema: application/json

branch

string

Optionally specify a database branch name to perform operation on

Responses

Request samples

Payload

Content type

application/json

{"branch": "string"
}

Response samples

200
default

Content type

application/json

{"status": "string"
}

Management

The Management section provide APIs that can be used to manage users, and app_keys.

Creates invitations to join the namespace

Creates invitations to the namespace

Authorizations:

BearerAuth

Request Body schema: application/json

Array of objects (InvitationInfo)

Array

email	string Required: Email address to invite
role	string Required: Role to associate this user to
invitation_sent_by_name	string Invitation sender name

Responses

Request samples

Payload

Content type

application/json

{"invitations": [{"email": "string",
"role": "string",
"invitation_sent_by_name": "string"
}
]
}

Response samples

200
default

Content type

application/json

{"status": "string",
"message": "string",
"count": 0
}

Deletes invitations to join the namespace

Deletes invitations to the namespace

Authorizations:

BearerAuth

Request Body schema: application/json

email	string
status	string

Responses

Request samples

Payload

Content type

application/json

{"email": "string",
"status": "string"
}

Response samples

200
default

Content type

application/json

{"status": "string",
"message": "string"
}

Lists all the invitations to join the namespace

Lists all the invitations to the namespace

Authorizations:

BearerAuth

query Parameters

status

string

optional status - an enum [PENDING, EXPIRED, ACCEPTED]

Responses

Response samples

200
default

Content type

application/json

{"invitations": [{"email": "string",
"role": "string",
"status": "string",
"tigris_namespace": "string",
"tigris_namespace_name": "string",
"created_by": "string",
"created_by_name": "string",
"expiration_time": 0
}
]
}

Verifies the invitation

Verify invitation

Authorizations:

BearerAuth

Request Body schema: application/json

email	string invited email address
code	string code
dry	boolean dry

Responses

Request samples

Payload

Content type

application/json

{"email": "string",
"code": "string",
"dry": true
}

Response samples

200
default

Content type

application/json

{"tigris_namespace": "string",
"tigris_namespace_name": "string",
"role": "string"
}

Lists the users in current namespace

List users

Authorizations:

BearerAuth

Responses

Response samples

200
default

Content type

application/json

{"users": [{"email": "string",
"name": "string",
"created_at": 0,
"picture": "string",
"role": "string"
}
]
}

Reads the Namespace Metadata

GetNamespaceMetadata inserts the user metadata object

Authorizations:

BearerAuth

path Parameters

metadataKey

required

string

Request Body schema: application/json

metadataKey	string
value	object

Responses

Request samples

Payload

Content type

application/json

{"metadataKey": "string",
"value": { }
}

Response samples

200
default

Content type

application/json

{"metadataKey": "string",
"namespaceId": 0,
"value": { }
}

Inserts Namespace Metadata

InsertNamespaceMetadata inserts the namespace metadata object

Authorizations:

BearerAuth

path Parameters

metadataKey

required

string

Request Body schema: application/json

metadataKey	string
value	object

Responses

Request samples

Payload

Content type

application/json

{"metadataKey": "string",
"value": { }
}

Response samples

200
default

Content type

application/json

{"metadataKey": "string",
"namespaceId": 0,
"value": { }
}

Updates Namespace Metadata

UpdateNamespaceMetadata updates the user metadata object

Authorizations:

BearerAuth

path Parameters

metadataKey

required

string

Request Body schema: application/json

metadataKey	string
value	object

Responses

Request samples

Payload

Content type

application/json

{"metadataKey": "string",
"value": { }
}

Response samples

200
default

Content type

application/json

{"metadataKey": "string",
"namespaceId": 0,
"value": { }
}

Creates a Namespace

Creates a new namespace, if it does not exist

Authorizations:

BearerAuth

Request Body schema: application/json

code	integer <uint32> Optional: unique id
id	string Optional: unique string id
name	string Required: The display name for namespace.

Responses

Request samples

Payload

Content type

application/json

{"code": 0,
"id": "string",
"name": "string"
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string",
"namespace": {"code": 0,
"id": "string",
"name": "string"
}
}

Lists all Namespaces

List all namespace and optionally lists specific namespace by namespaceId filter, also supports describe request.

Authorizations:

BearerAuth

path Parameters

namespace_id

required

string

Optionally filter by specific namespaceId

query Parameters

describe

boolean

Optionally specify if the description of each namespace is requested

Responses

Response samples

200
default

Content type

application/json

{"namespaces": [{"code": 0,
"id": "string",
"name": "string"
}
],
"data": {"details": "string"
}
}

Deletes the namespace

DeleteNamespace deletes the namespace and all the data inside it

Authorizations:

BearerAuth

path Parameters

namespace_id

required

string

string namespace id to delete.

Responses

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Reads the User Metadata

GetUserMetadata inserts the user metadata object

Authorizations:

BearerAuth

path Parameters

metadataKey

required

string

Request Body schema: application/json

metadataKey	string
value	object

Responses

Request samples

Payload

Content type

application/json

{"metadataKey": "string",
"value": { }
}

Response samples

200
default

Content type

application/json

{"metadataKey": "string",
"userId": "string",
"namespaceId": 0,
"value": "string"
}

Inserts User Metadata

insertUserMetadata inserts the user metadata object

Authorizations:

BearerAuth

path Parameters

metadataKey

required

string

Request Body schema: application/json

metadataKey	string
value	object

Responses

Request samples

Payload

Content type

application/json

{"metadataKey": "string",
"value": { }
}

Response samples

200
default

Content type

application/json

{"metadataKey": "string",
"userId": "string",
"namespaceId": 0,
"value": { }
}

Updates User Metadata

updateUserMetadata updates the user metadata object

Authorizations:

BearerAuth

path Parameters

metadataKey

required

string

Request Body schema: application/json

metadataKey	string
value	object

Responses

Request samples

Payload

Content type

application/json

{"metadataKey": "string",
"value": { }
}

Response samples

200
default

Content type

application/json

{"metadataKey": "string",
"userId": "string",
"namespaceId": 0,
"value": { }
}

Observability

The Observability section has APIs that provides full visibility into the health, metrics, and monitoring of the Server.

Health Check

This endpoint can be used to check the liveness of the server.

Responses

Response samples

200
default

Content type

application/json

{"response": "string"
}

Information about the server

Provides the information about the server. This information includes returning the server version, etc.

Authorizations:

BearerAuth

Responses

Response samples

200
default

Content type

application/json

{"server_version": "string"
}

Queries time series metrics

Authorizations:

BearerAuth

Request Body schema: application/json

db	string
branch	string
collection	string
from	integer <int64>
to	integer <int64>
metric_name	string
tigris_operation	string <enum> Enum: "ALL" "READ" "WRITE" "METADATA"
space_aggregation	string <enum> Enum: "AVG" "MIN" "MAX" "SUM"
space_aggregated_by	Array of strings
function	string <enum> Enum: "RATE" "COUNT" "NONE"
quantile	number <float>
	Array of objects (AdditionalFunction)

Responses

Request samples

Payload

Content type

application/json

{"db": "string",
"branch": "string",
"collection": "string",
"from": 0,
"to": 0,
"metric_name": "string",
"tigris_operation": "ALL",
"space_aggregation": "AVG",
"space_aggregated_by": ["string"
],
"function": "RATE",
"quantile": 0,
"additionalFunctions": [{"rollup": {"aggregator": "ROLLUP_AGGREGATOR_SUM",
"interval": 0
}
}
]
}

Response samples

200
default

Content type

application/json

{"from": 0,
"to": 0,
"query": "string",
"series": [{"from": 0,
"to": 0,
"metric": "string",
"scope": "string",
"dataPoints": [{"timestamp": 0,
"value": 0
}
]
}
]
}

Queries current namespace quota limits

Returns current namespace quota limits

Authorizations:

BearerAuth

Request Body schema: application/json

object (QuotaLimitsRequest)

Request current namespace quota limits

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{"ReadUnits": 0,
"WriteUnits": 0,
"StorageSize": 0
}

Queries current namespace quota usage

Returns current namespace quota limits

Authorizations:

BearerAuth

Request Body schema: application/json

object (QuotaUsageRequest)

Request current namespace quota usage

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{"ReadUnits": 0,
"WriteUnits": 0,
"StorageSize": 0,
"ReadUnitsThrottled": 0,
"WriteUnitsThrottled": 0,
"StorageSizeThrottled": 0
}

Information about the current user

Authorizations:

BearerAuth

Responses

Response samples

200
default

Content type

application/json

{"sub": "string",
"namespace": "string",
"role": "string",
"auth_method": "string",
"user_type": "string"
}

Projects

Every Tigris projects comes with a transactional document database built on FoundationDB, one of the most resilient and battle-tested open source distributed key-value store. A database is created automatically for you when you create a project.

List Projects

List returns all the projects.

Authorizations:

BearerAuth

Responses

Response samples

200
default

Content type

application/json

{"projects": [{"project": "string",
"metadata": { },
"limits": {"max_collections": 0,
"max_search_indexes": 0
}
}
]
}

Create Project

Creates a new project. An AlreadyExists error with a status code 409 is returned if the project already exists.

Authorizations:

BearerAuth

path Parameters

project

required

string

Create project with this name.

Request Body schema: application/json

object (ProjectOptions)

object (ProjectLimits)

max_collections	integer <int32> maximum number of collections in the Project
max_search_indexes	integer <int32> maximum number of search indexes in the Project

Responses

Request samples

Payload

Content type

application/json

{"options": {"limits": {"max_collections": 0,
"max_search_indexes": 0
}
}
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Delete Project and all resources under project

Delete Project deletes all the collections in this project along with all of the documents, and associated metadata for these collections.

Authorizations:

BearerAuth

path Parameters

project

required

string

Delete Project with this name.

Note: Deletes all resources under this project. Use with caution.

Request Body schema: application/json

object (DeleteProjectRequest)

Responses

Request samples

Payload

Content type

application/json

{ }

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Update a project configuration and metadata

Update Project configuration and metadata

Authorizations:

BearerAuth

path Parameters

project

required

string

Update project with this name.

Request Body schema: application/json

project	string Update project with this name.
	object (ProjectOptions)

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"options": {"limits": {"max_collections": 0,
"max_search_indexes": 0
}
}
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Realtime

The realtime section provide APIs that can be used realtime operations.

Get all channels for your application project

Authorizations:

BearerAuth

path Parameters

project

required

string

Responses

Response samples

200
default

Content type

application/json

{"channels": [{"channel": "string"
}
]
}

Get the details about a channel

Authorizations:

BearerAuth

path Parameters

project required	string
channel required	string

Responses

Response samples

200
default

Content type

application/json

{"channel": "string"
}

Get all messages for a channel

Authorizations:

BearerAuth

path Parameters

project required	string
channel required	string

query Parameters

session_id	string
socket_id	string
event	string
start	string
end	string
limit	integer <int64>

Responses

Response samples

200
default

Content type

application/json

{"message": {"id": "string",
"name": "string",
"sequence": "string",
"data": "string"
}
}

push messages to a single channel

Authorizations:

BearerAuth

path Parameters

project required	string
channel required	string

Request Body schema: application/json

project	string
channel	string
	Array of objects (Message)

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"channel": "string",
"messages": [{"id": "string",
"name": "string",
"sequence": "string",
"data": "string"
}
]
}

Response samples

200
default

Content type

application/json

{"ids": ["string"
]
}

Presence about the channel

Authorizations:

BearerAuth

path Parameters

project required	string
channel required	string

Responses

Response samples

200
default

Content type

application/json

{"response": "string"
}

Get the subscriptions details about a channel

Authorizations:

BearerAuth

path Parameters

project required	string
channel required	string

query Parameters

page_size	integer <int32>
page	integer <int32>

Responses

Response samples

200
default

Content type

application/json

{"devices": ["string"
]
}

Search

The search section provides you APIs that can be used to implement powerful apps with search experiences. You can manage storing documents on your own or you can simply integrate it with your database.

List search indexes

Authorizations:

BearerAuth

path Parameters

project

required

string

Tigris project name.

query Parameters

filter.type	string An index can be either managed by user explicitly then the type is set as "user" or the index is backed by Tigris collection. In case it is backed by Tigris collection the type is "tigris".
filter.collection	string Applicable only in case index is backed by Tigris collection.
filter.branch	string Applicable only in case index is backed by Tigris collection. This is the database branch for the above collection. For primary database it can be omitted or "main" can be passed.

Responses

Response samples

200
default

Content type

application/json

{"indexes": [{"name": "string",
"schema": { }
}
]
}

Get a single or multiple documents

Retrieves one or more documents by id. The response is an array of documents in the same order it is requests. A null is returned for the documents that are not found.

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name.
index required	string index name where to create documents.

query Parameters

ids	Array of strings document id.

Responses

Response samples

200
default

Content type

application/json

{"documents": [{"data": { },
"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"match": {"fields": [{"name": "string"
}
],
"score": "string",
"vector_distance": 0
}
}
}
]
}

Create or replace documents in an index

Creates or replaces one or more documents. Each document is a JSON object. A document is replaced if it already exists. An "id" is generated automatically in case it is missing in the document. The document is created if "id" doesn't exists otherwise it is replaced. Returns an array of status indicating the status of each document.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to insert documents.
index required	string index name where to create documents.

Request Body schema: application/json

project	string Project name whose db is under target to insert documents.
index	string index name where to create documents.
documents	Array of objects An array of documents to create. Each document is a JSON object. In case an id is missing then the server will automatically generate it for you and create the document and in case an id is provided in the document and the document already exists then that document will not index and in the response there will be an error corresponding to that document id other documents will succeed.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"index": "string",
"documents": [{ }
]
}

Response samples

200
default

Content type

application/json

{"status": [{"id": "string",
"error": {"code": "OK",
"message": "string"
}
}
]
}

Create multiple documents

Create is used for indexing a single or multiple documents. The API expects an array of documents. Each document is a JSON object. An "id" is optional and the server can automatically generate it for you in case it is missing. In cases when an id is provided in the document and the document already exists then that document will not be indexed and in the response there will be an error corresponding to that document id other documents will succeed. Returns an array of status indicating the status of each document.

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name.
index required	string index name where to create documents.

Request Body schema: application/json

project	string Tigris project name.
index	string index name where to create documents.
documents	Array of objects An array of documents to be created or replaced. Each document is a JSON object.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"index": "string",
"documents": [{ }
]
}

Response samples

200
default

Content type

application/json

{"status": [{"id": "string",
"error": {"code": "OK",
"message": "string"
}
}
]
}

Delete documents by ids

Delete one or more documents by id. Returns an array of status indicating the status of each document. Each status has an error field that is set to null in case document is deleted successfully otherwise it will non null with an error code and message.

Authorizations:

BearerAuth

path Parameters

project required	string The project name.
index required	string The index name of the documents that needs deletion.

Request Body schema: application/json

project	string The project name.
index	string The index name of the documents that needs deletion.
ids	Array of strings A list of ids

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"index": "string",
"ids": ["string"
]
}

Response samples

200
default

Content type

application/json

{"status": [{"id": "string",
"error": {"code": "OK",
"message": "string"
}
}
]
}

Update documents in an index

Updates one or more documents by "id". Each document is required to have the "id" field in it. Returns an array of status indicating the status of each document. Each status has an error field that is set to null in case document is updated successfully otherwise the error field is set with a code and message.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to insert documents.
index required	string Index name where to create documents.

Request Body schema: application/json

project	string Project name whose db is under target to insert documents.
index	string Index name where to create documents.
documents	Array of objects An array of documents. Each document should have "id" present which will be used by Tigris for updating the document.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"index": "string",
"documents": [{ }
]
}

Response samples

200
default

Content type

application/json

{"status": [{"id": "string",
"error": {"code": "OK",
"message": "string"
}
}
]
}

Delete documents by query

DeleteByQuery is used to delete documents that match the filter. A filter is required. To delete document by id, you can pass the filter as follows {"id": "test"}. Returns a count of number of documents deleted.

Authorizations:

BearerAuth

path Parameters

project required	string The project name.
index required	string The index name of the documents that needs deletion.

Request Body schema: application/json

project	string The project name.
index	string The index name of the documents that needs deletion.
filter	object A filter is required to delete matching documents. To delete document by id, you can pass the filter as follows `{"id": "test"}`

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"index": "string",
"filter": { }
}

Response samples

200
default

Content type

application/json

{"count": 0
}

Search Documents.

Searches an index for the documents matching the query. A search can be a term search or a phrase search. Search API allows filtering the result set using filters as documented here. 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 here.

Authorizations:

BearerAuth

path Parameters

project required	string Project name whose db is under target to search documents from.
index required	string The index name to search documents from.

Request Body schema: application/json

project	string Project name whose db is under target to search documents from.
index	string The index name to search documents from.
q	string Query string for searching across text fields
search_fields	Array of strings Array of fields to project search query against
filter	object Filter stacks on top of query results to further narrow down the results. Similar to `ReadRequest.filter`
facet	object 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	Array of objects Array of fields and corresponding sort orders to order the results `[{ "salary": "$desc" }]`
include_fields	Array of strings Array of document field names to include in results. By default, all fields are included.
exclude_fields	Array of strings Array of document field names to exclude from results. `include_fields`, if specified, takes precedence over `exclude_fields`.
page_size	integer <int32> Optionally can set the number of hits to be returned per page, default is 20.
page	integer <int32> Optionally can specify the page to retrieve. If page is set then only hits for this page is returned
	object (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.
group_by	string <byte> Group by can be used to group search results. For example, to group by city field the syntax would be: `{ "fields": ["city"]}`. Optionally a grouping limit can be set. By default it is 3 per group.
vector	string <byte> Vector is an object that is used for vector search. For example, to vector search on a "vec" field the syntax would be: `{ "vec": [0.34, 0.12, 0.95], "top_k": 10}`.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"index": "string",
"q": "string",
"search_fields": ["string"
],
"filter": { },
"facet": { },
"sort": [{ }
],
"include_fields": ["string"
],
"exclude_fields": ["string"
],
"page_size": 0,
"page": 0,
"collation": {"case": "string"
},
"group_by": "string",
"vector": "string"
}

Response samples

200
default

Content type

application/json

{"hits": [{"data": { },
"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"match": {"fields": [{"name": "string"
}
],
"score": "string",
"vector_distance": 0
}
}
}
],
"facets": {"property1": {"counts": [{"count": 0,
"value": "string"
}
],
"stats": {"avg": 0,
"max": 0,
"min": 0,
"sum": 0,
"count": 0
}
},
"property2": {"counts": [{"count": 0,
"value": "string"
}
],
"stats": {"avg": 0,
"max": 0,
"min": 0,
"sum": 0,
"count": 0
}
}
},
"meta": {"found": 0,
"total_pages": 0,
"page": {"current": 0,
"size": 0
},
"matched_fields": ["string"
]
},
"group": [{"group_keys": ["string"
],
"hits": [{"data": { },
"metadata": {"created_at": "2019-08-24T14:15:22Z",
"updated_at": "2019-08-24T14:15:22Z",
"match": {"fields": [{"name": "string"
}
],
"score": "string",
"vector_distance": 0
}
}
}
]
}
]
}

Create a single document

CreateById is used for indexing a single document. The API expects a single document. An "id" is optional and the server can automatically generate it for you in case it is missing. In cases an id is provided in the document and the document already exists then that document will not be indexed and an error is returned with HTTP status code 409.

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name.
index required	string index name where to create document.
id required	string document id.

Request Body schema: application/json

project	string Tigris project name.
index	string index name where to create document.
id	string document id.
document	object A JSON document that needs to be indexed.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"index": "string",
"id": "string",
"document": { }
}

Response samples

200
default

Content type

application/json

{"id": "string"
}

Get information about a search index

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name.
name required	string index name.

Responses

Response samples

200
default

Content type

application/json

{"index": {"name": "string",
"schema": { }
}
}

Creates or updates search index

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name.
name required	string search index name.

Request Body schema: application/json

project	string Tigris project name.
name	string search index name.
schema	object schema of the index. The schema specifications are same as JSON schema specification defined here. Schema example: `{ "title": "ecommerce_index", "description": "an ecommerce store search index", "properties": { "name": { "description": "Name of the product", "type": "string", "maxLength": 128 }, "brand": { "description": "Brand of the product", "type": "string" }, "price": { "description": "Price of the product", "type": "number" } } }`
only_create	boolean If set to `true` then a conflict with HTTP Status code 409 is returned if an index already exists. The default is false.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"name": "string",
"schema": { },
"only_create": true
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}

Deletes search index

Authorizations:

BearerAuth

path Parameters

project required	string Tigris project name.
name required	string index name.

Request Body schema: application/json

project	string Tigris project name.
name	string index name.

Responses

Request samples

Payload

Content type

application/json

{"project": "string",
"name": "string"
}

Response samples

200
default

Content type

application/json

{"message": "string",
"status": "string"
}