or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

examples

edge-cases.mdreal-world-scenarios.md
index.md
tile.json

quick-start.mddocs/guides/

Quick Start Guide

Get started with FoundationDB Java bindings in minutes.

Installation

Add to your pom.xml:

<dependency>
    <groupId>com.apple.foundationdb</groupId>
    <artifactId>fdb-java</artifactId>
    <version>7.4.3</version>
</dependency>

Basic Setup

  1. Select API version (required first step, once per JVM):
import com.apple.foundationdb.FDB;

FDB fdb = FDB.selectAPIVersion(740);
  1. Open database connection:
import com.apple.foundationdb.Database;

try (Database db = fdb.open()) {
    // Use database
}

Your First Transaction

import com.apple.foundationdb.*;

FDB fdb = FDB.selectAPIVersion(740);

try (Database db = fdb.open()) {
    // Write data
    db.run(tr -> {
        tr.set("key".getBytes(), "value".getBytes());
        return null;
    });
    
    // Read data
    String value = db.run(tr -> {
        byte[] result = tr.get("key".getBytes()).join();
        return result != null ? new String(result) : null;
    });
    
    System.out.println("Value: " + value);
}

Key Concepts

Automatic Retry

Use Database.run() for automatic retry on transient errors:

db.run(tr -> {
    // All operations here automatically retry on conflicts
    tr.set("key1".getBytes(), "value1".getBytes());
    tr.set("key2".getBytes(), "value2".getBytes());
    return null;
});

Read-Only Transactions

Use Database.read() for read-only operations:

List<String> keys = db.read(tr -> {
    List<String> result = new ArrayList<>();
    for (KeyValue kv : tr.getRange("prefix:".getBytes(), "prefix;".getBytes())) {
        result.add(new String(kv.getKey()));
    }
    return result;
});

Using Tuples for Structured Keys

import com.apple.foundationdb.tuple.Tuple;

Tuple key = Tuple.from("users", 1001, "profile");
byte[] packedKey = key.pack();

db.run(tr -> {
    tr.set(packedKey, "user data".getBytes());
    return null;
});

Using Subspaces for Namespacing

import com.apple.foundationdb.subspace.Subspace;
import com.apple.foundationdb.tuple.Tuple;

Subspace users = new Subspace(Tuple.from("users"));
byte[] key = users.pack(Tuple.from(1001));

db.run(tr -> {
    tr.set(key, "user data".getBytes());
    return null;
});

Next Steps

  • See Real-World Scenarios for common patterns
  • Review API Reference for detailed documentation
  • Check Edge Cases for advanced scenarios

Important Notes

  • API Version: Must call FDB.selectAPIVersion() before any other operations
  • Resource Management: Always close Database objects (use try-with-resources)
  • Thread Safety: Each thread should use its own Transaction object
  • Key Limits: Maximum key size 10KB, value size 100KB
  • System Keys: Keys starting with 0xFF are reserved