Skip to main content

Quickstart: Java

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, with JDK 1.8 or newer installed.

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​

Add the client library dependency to your project​

<dependency>
  <groupId>com.tigrisdata</groupId>
  <artifactId>tigris-client</artifactId>
  <version>${tigris.client.java.version}</version>
</dependency>

For latest version and for other dependency management or build tool you can refer to dependency snippet from here

Code​

TigrisApp.java
import com.tigrisdata.db.annotation.TigrisPrimaryKey;
import com.tigrisdata.db.client.Filters;
import com.tigrisdata.db.client.InsertResponse;
import com.tigrisdata.db.client.StandardTigrisClient;
import com.tigrisdata.db.client.TigrisClient;
import com.tigrisdata.db.client.TigrisCollection;
import com.tigrisdata.db.client.TigrisDatabase;
import com.tigrisdata.db.client.UpdateFields;
import com.tigrisdata.db.client.config.TigrisConfiguration;
import com.tigrisdata.db.client.error.TigrisException;
import com.tigrisdata.db.type.TigrisDocumentCollectionType;

import java.util.Objects;

public class TigrisApp {
    public static void main(String[] args) throws TigrisException {
        // configure the client
        TigrisConfiguration config =
            TigrisConfiguration.newBuilder("api.preview.tigrisdata.cloud")
                .withAuthConfig(
                    new TigrisConfiguration.AuthConfig("paste client_id here", "paste client_secret here"))
                .build();

        // initialize the client
        TigrisClient client = StandardTigrisClient.getInstance(config);

        // create the database if it does not exist,
        // and fetch the database object
        TigrisDatabase helloDB = client.createDatabaseIfNotExists("hello-db");

        // create the collections if they don't exist, or
        // update the collection schema
        helloDB.createOrUpdateCollections(User.class);

        // fetch the collection object, all the CRUD operations on the
        // collection will be performed through this collection object
        TigrisCollection<User> users = helloDB.getCollection(User.class);

        // insert
        User jania = new User("Jania McGrory", 6045.7);
        User bunny = new User("Bunny Instone", 2948.87);
        users.insert(jania);
        users.insert(bunny);

        // read the auto-generated ids
        int janiaId = jania.getUserId();
        int bunnyId = bunny.getUserId();

        // find the user by primary key field
        User user = users.readOne(Filters.eq("userId", janiaId)).get();

        // find user with Name Jania McGrory
        User user = users.readOne(Filters.eq("name", "Jania McGrory")).get();

        // update
        users.update(
            Filters.eq("userId", janiaId),
            UpdateFields.newBuilder()
                .set("name", "Jania McGrover")
                .build()
        );

        // transaction - transfer balance between users
        helloDB.transact(
          (tx) -> {
              try {
                  users.update(
                      tx,
                      Filters.eq("userId", janiaId),
                      UpdateFields
                          .newBuilder()
                          .set("balance", jania.getBalance() - 100)
                          .build());
                  users.update(
                      tx,
                      Filters.eq("userId", bunnyId),
                      UpdateFields
                          .newBuilder()
                          .set("balance", bunny.getBalance() + 100)
                          .build());
              } catch (TigrisException tigrisException) {
                  // auto-rollback after throwing exception.
                  throw new IllegalStateException("Transaction failed", tigrisException);
              }
          });

        // Search for users with `name` like "bunny" and `balance` greater than 500
        SearchRequest request = SearchRequest.newBuilder()
                                    .withQuery("bunny")
                                    .withSearchFields("name")
                                    .withFilter(Filters.gt("balance", 500))
                                    .build();
        Iterator<SearchResult<User>> results = users.search(request);
        while (results.hasNext()) {
            SearchResult<User> result = results.next();
        }

        // delete users
        users.delete(Filters.eq("userId", janiaId));
        users.delete(Filters.eq("userId", bunnyId));

        // drop the database and its collections
        client.dropDatabase("hello-db");
    }

    public static class User implements TigrisDocumentCollectionType {
        @TigrisPrimaryKey(order = 1, autoGenerate = true)
        private int userId;
        private String name;
        private double balance;

        public User() {
        }

        public User(String name, double balance) {
            this.name = name;
            this.balance = balance;
        }

        public int getUserId() {
            return userId;
        }

        public void setUserId(int userId) {
            this.userId = userId;
        }

        public String getName() {
            return name;
        }

        public void setName(String name) {
            this.name = name;
        }

        public double getBalance() {
            return balance;
        }

        public void setBalance(double balance) {
            this.balance = balance;
        }

        @Override
        public boolean equals(Object o) {
            if (this == o) return true;
            if (o == null || getClass() != o.getClass()) return false;
            User user = (User) o;
            return userId == user.userId
                      && Double.compare(user.balance, balance) == 0
                      && Objects.equals(name, user.name);
        }

        @Override
        public int hashCode() {
            return Objects.hash(userId, name, balance);
        }
    }
}

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.