Quickstart: HTTP
The following guide will get you up and running with Tigris. It covers data modeling, creating database and collection, writing queries to read and write data, and performing search all without touching any infrastructure.
Prerequisites
All you'll need is any computer running macOS or Linux.
Install Tigris CLI
Use the command below to install the CLI on macOS
- macOS
- linux
brew install tigrisdata/tigris/tigris-cli
curl -sSL https://tigris.dev/cli-linux | sudo tar -xz -C /usr/local/bin
Alternative ways of installation can be found here.
Sign up for Tigris Cloud
You will need to have a Tigris Cloud account to complete this quickstart. If you don't already have an account, you can sign up for Tigris Cloud.
Login and set up the application credentials
Login to your Tigris Cloud account
tigris login
The next step is to create the project for the application we will be building
tigris create project quickstart
Now we can generate credentials to be used in this quickstart
tigris create app_key default "default key" -p quickstart
Once the command is executed, it would create the application credentials
(clientID and clientSecret) and print it on the screen. Make a note of id
and secret
from the output.
Output
{
"id": "your_client_id_here",
"name": "default",
"description": "default key",
"secret": "your_client_secret_here",
"created_at": 1666248043000,
"created_by": "google-oauth2|xxx",
"project": "quickstart"
}
Quickstart
Fetch auth token
We will have to fetch the auth token first. For all the subsequent API calls we will be using this token.
curl -X POST https://{your_tigris_uri}/v1/auth/token \
--header 'content-type: application/x-www-form-urlencoded' \
--data grant_type=client_credentials \
--data-urlencode client_id=your_client_id_here \
--data-urlencode client_secret=your_client_secret_here
Use the clientID and clientSecret from the output of the tigris create project
command above.
Output
{ "access_token": "{your_token_here}", "expires_in": 86400 }
We will be using the token in all the subsequent API calls.
Creating collection
For this quickstart we will create a collection named users.
A collection is instantaneously created through the API. In Tigris, a collection is an ordered set of records called documents that all follow a specific schema and whose fields are strongly typed.
curl https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/createOrUpdate \
-X POST \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"schema": {
"title": "users",
"properties": {
"balance": {
"type": "number",
"searchIndex": true
},
"id": {
"type": "integer",
"format": "int32",
"autoGenerate": true
},
"name": {
"type": "string",
"searchIndex": true
}
},
"primary_key": [
"id"
]
}
}'
Output
{
"message": "collection of type 'documents' created successfully",
"status": "created"
}
The schema of the collections created above can be fetched as follows
curl -X POST https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/describe \
-H "Authorization: Bearer your_token_here"
Output
{
"collection": "users",
"metadata": {},
"schema": {
"title": "users",
"properties": {
"balance": {
"type": "number",
"searchIndex": true
},
"id": {
"type": "integer",
"format": "int32",
"autoGenerate": true
},
"name": {
"type": "string",
"searchIndex": true
}
},
"primary_key": ["id"]
},
"size": 0,
"indexes": [
{
"name": "_tigris_created_at",
"state": "INDEX ACTIVE"
},
{
"name": "_tigris_updated_at",
"state": "INDEX ACTIVE"
}
],
"search_status": "Search Active"
}
Insert some documents
The following example will replace documents with the same id
if they already
exist, or create new documents if they don't exist with the same id
.
curl https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/documents/insert \
-X POST \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"documents": [
{"name": "Jania McGrory", "balance": 6045.7},
{"name": "Bunny Instone", "balance": 2948.87}
]
}'
Output
{
"metadata": { "created_at": "2023-05-27T02:16:14.710313878Z" },
"status": "inserted",
"keys": [{ "id": 1 }, { "id": 2 }]
}
Read a document using the primary key field
Read the document from the collection by using its id
.
curl https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/documents/read \
-X POST \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"filter": {"id": 1}
}'
Output
{
"result": {
"data": { "name": "Jania McGrory", "balance": 6045.7, "id": 1 },
"metadata": { "created_at": "2023-05-27T02:16:14.710313878Z" },
"resume_token": "ZGF0YQAAAAIAAB/jAAAf5AEA/wD/H+UAFQE="
}
}
Read a document using any field in the schema
Read the document from the collection by using the field name
.
curl https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/documents/read \
-X POST \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"filter": {"name": "Jania McGrory"}
}'
Output
{
"result": {
"data": { "name": "Jania McGrory", "balance": 6045.7, "id": 1 },
"metadata": { "created_at": "2023-05-27T02:16:14.710313878Z" },
"resume_token": "ZGF0YQAAAAIAAB/jAAAf5AEA/wD/H+UAFQE="
}
}
Update a document
Update one of the fields in a document by using its id
.
curl https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/documents/update \
-X PUT \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"fields": {
"$set": {"balance": 2448.87}
},
"filter": {"id": 2}
}'
Output
{
"metadata": { "updated_at": "2023-05-27T02:18:37.917374249Z" },
"status": "updated",
"modified_count": 1
}
Search
Search for users with name
like "bunny" and balance
greater than 500
curl https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/documents/search \
-X POST \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"q": "bunny",
"search_fields": ["name"],
"filter": {"balance": {"$gt": 500}}
}'
Output
{
"result": {
"hits": [
{
"data": { "id": 2, "name": "Bunny Instone", "balance": 2448.87 },
"metadata": {
"created_at": "2023-05-27T02:16:14.710313878Z",
"updated_at": "2023-05-27T02:18:37.917374249Z"
}
}
],
"facets": {},
"meta": {
"found": 1,
"total_pages": 1,
"page": { "current": 1, "size": 20 },
"matched_fields": null
}
}
}
Delete documents
Use the delete API to remove the documents from the collection based on the filter.
curl https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/documents/delete \
-X DELETE \
-H "Authorization: Bearer your_token_here" \
-H "Content-Type: application/json" \
-d '{
"filter": {
"$or": [
{"id": 1},
{"id": 2}
]
}
}'
Output
{
"metadata": { "deleted_at": "2023-05-27T02:20:47.402085521Z" },
"status": "deleted"
}
Drop database
Finally, drop the database users we have created for this quickstart with all its collections.
curl -X DELETE https://{your_tigris_uri}/v1/projects/quickstart/database/collections/users/drop \
-H "Authorization: Bearer your_token_here"
Output
{ "message": "collection dropped successfully", "status": "dropped" }
Where to go from here?
🚀 Signup for Tigris Cloud - and start building your next application with it. We are here to help you get started. Join our Discord community to ask any questions you might have.