Skip to main content

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

brew install tigrisdata/tigris/tigris-cli

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 generate credentials to be used by the application we will be building in this quickstart

tigris create app_key quickstart "quickstart application"

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": "quickstart",
  "description": "quickstart application",
  "secret": "your_client_secret_here",
  "created_at": 1666248043000,
  "created_by": "google-oauth2|xxx"
}

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://api.preview.tigrisdata.cloud/v1/auth/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=your_client_id_here \
  --data client_secret=your_client_secret_here

Use the clientID and clientSecret from the output of the tigris create application command above.

Output
{ "access_token": "your_token_here", "expires_in": 41437 }

We will be using the token in all the subsequent API calls.

Creating database and collection​

For this quickstart we will create a database named sampledb and then create a collection users inside it.

Creating a database is as easy as calling an API, and it is ready in an instant.

curl https://api.preview.tigrisdata.cloud/v1/databases/sampledb/create \
      -X POST \
      -H "Authorization: Bearer your_token_here"

Similarly, 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://api.preview.tigrisdata.cloud/v1/databases/sampledb/collections/users/createOrUpdate \
      -X POST \
      -H "Authorization: Bearer your_token_here" \
      -H "Content-Type: application/json" \
      -d '{
        "schema": {
          "title": "users",
          "properties": {
            "balance": {
              "type": "number"
            },
            "id": {
              "type": "integer",
              "format": "int32",
              "autoGenerate": true
            },
            "name": {
              "type": "string"
            }
          },
          "primary_key": [
            "id"
          ]
        }
      }'

The schema of the collections created above can be fetched as follows

curl -X POST https://api.preview.tigrisdata.cloud/v1/databases/sampledb/collections/users/describe \
      -H "Authorization: Bearer your_token_here"

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://api.preview.tigrisdata.cloud/v1/databases/sampledb/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}
        ]
      }'

Read a document using the primary key field​

Read the document from the collection by using its id.

curl https://api.preview.tigrisdata.cloud/v1/databases/sampledb/collections/users/documents/read \
      -X POST \
      -H "Authorization: Bearer your_token_here" \
      -H "Content-Type: application/json" \
      -d '{
        "filter": {"id": 1}
      }'

Read a document using any field in the schema​

Read the document from the collection by using the field name.

curl https://api.preview.tigrisdata.cloud/v1/databases/sampledb/collections/users/documents/read \
      -X POST \
      -H "Authorization: Bearer your_token_here" \
      -H "Content-Type: application/json" \
      -d '{
        "filter": {"name": "Jania McGrory"}
      }'

Update a document​

Update one of the fields in a document by using its id.

curl https://api.preview.tigrisdata.cloud/v1/databases/sampledb/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}
      }'

Search for users with name like "bunny" and balance greater than 500

curl https://api.preview.tigrisdata.cloud/v1/databases/sampledb/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}}
      }'

Delete documents​

Use the delete API to remove the documents from the collection based on the filter.

curl https://api.preview.tigrisdata.cloud/v1/databases/sampledb/collections/users/documents/delete \
      -X DELETE \
      -H "Authorization: Bearer your_token_here" \
      -H "Content-Type: application/json" \
      -d '{
        "filter": {
          "$or": [
            {"id": 1},
            {"id": 2}
          ]
        }
      }'

Drop database​

Finally, drop the database sampledb we have created for this quickstart with all its collections.

curl -X DELETE https://api.preview.tigrisdata.cloud/v1/databases/sampledb/drop \
      -H "Authorization: Bearer your_token_here"

Where to go from here?​

🚀 Signup for Tigris Cloud - a hosted of Tigris, and try out the open source developer data platform in the cloud.

Browse through the docs in your own areas of interest, or join our Discord community to ask any questions you might have.