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