Java quick start

Use Fauna’s JVM driver to query e-commerce demo data in a Java 17 app. You’ll set up the app using Gradle.

Create a database with demo data
Log in to the Fauna Dashboard, and create a database with the following configuration:
- Region group: Choose your preferred region group, which determines where your data resides.
- Use demo data: Enabled.
- Enable backups: Disabled.
Leave the other options as is.
Create an authentication secret
Fauna supports several types of authentication secrets. Create a key, which is a type of secret, with the built-in server-readonly role:
1. In the Dashboard’s Explorer page, select your demo database.
2. In the database’s Keys tab, click Create Key.
3. Choose a Role of server (read-only).
4. Click Save.
5. Copy the Key Secret.
Set the FAUNA_SECRET environment variable
Set the FAUNA_SECRET environment variable to your key’s secret. Fauna’s client drivers can access the secret from this variable.
export FAUNA_SECRET=<KEY_SECRET>

Create a Gradle project

Create a new directory for your app and initialize a Gradle project:

mkdir example
cd example
gradle init \
  --type java-application \
  --dsl groovy \
  --test-framework junit \
  --project-name app \
  --package app \
  --java-version 17 \
  --no-incubating \
  --no-split-project

Add the JVM driver as a dependency
In the example/app directory, edit example/app/build.gradle and add the JVM driver as a dependency:
dependencies { ... implementation "com.fauna:fauna-jvm:1.0.0" ... }

Create a basic app

In the example/app directory, edit the example/app/src/main/java/app/App.java file and replace the code with the following:

package app;

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.ExecutionException;

import com.fauna.client.Fauna;
import com.fauna.client.FaunaClient;
import com.fauna.exception.FaunaException;
import com.fauna.query.builder.Query;
import com.fauna.response.QuerySuccess;
import com.fauna.types.Page;

import static com.fauna.codec.Generic.pageOf;
import static com.fauna.query.builder.Query.fql;

public class App {

    // Define class for `Product` documents
    // in expected results.
    public static class Product {
        public String name;

        public String description;

        public Integer price;
    }

    public static void main(String[] args) {
        try {
            // Initialize the client to connect to Fauna
            // using the `FAUNA_SECRET` environment variable.
            FaunaClient client = Fauna.client();

            // Compose a query using an FQL template string.
            // The query calls the `Product` collection's
            // `sortedByPriceLowToHigh()` index. It projects the `name`,
            // `description`, and `price` fields covered by the index.
            Query query = fql("""
                Product.sortedByPriceLowToHigh() {
                    name,
                    description,
                    price
                }
            """);

            // Run the query.
            System.out.println("Running synchronous query:");
            runSynchronousQuery(client, query);
        } catch (FaunaException e) {
            System.err.println("Fauna error occurred: " + e.getMessage());
            e.printStackTrace();
        }
    }

    private static void runSynchronousQuery(FaunaClient client, Query query) throws FaunaException {
        // Use `query()` to run a synchronous query.
        // Synchronous queries block the current thread until the query completes.
        // Accepts the query, expected result class, and a nullable set of query options.
        QuerySuccess<Page<Product>> result = client.query(query, pageOf(Product.class));
        printResults(result.getData());
    }

    // Iterate through the products in the page.
    private static void printResults(Page<Product> page) {
        for (Product product : page.getData()) {
            System.out.println("Name: " + product.name);
            System.out.println("Description: " + product.description);
            System.out.println("Price: " + product.price);
            System.out.println("--------");
        }
        // Print the `after` cursor to paginate through results.
        System.out.println("After: " + page.getAfter());
    }
}

Run the app
Run the script from the example directory. The script prints a list of e-commerce products from the demo data in the terminal.
./gradlew run