Skip to main content
Version: Next (v1.11)

Java SDK

Java SDK for Spice.ai​

github.com/spiceai/spice-java

Installation​

Add the following dependency:

<dependency>
    <groupId>ai.spice</groupId>
    <artifactId>spiceai</artifactId>
    <version>0.5.0</version>
    <scope>compile</scope>
</dependency>

Connect to Spice runtime​

Create a SpiceClient using default configuration. Requires local Spice OSS running: follow the quickstart

import org.apache.arrow.flight.FlightStream;
import ai.spice.SpiceClient;

public class App 
{
    public static void main( String[] args )
    {
        try {
            SpiceClient client = SpiceClient.builder()
                    .build();

            FlightStream res = client.query("SELECT \"VendorID\", \"tpep_pickup_datetime\", \"fare_amount\" FROM taxi_trips LIMIT 10");

            while (res.next()) {
                System.out.println(res.getRoot().contentToTSVString());
            }
        } catch (Exception e) {
            System.err.println("An unexpected error occurred: " + e.getMessage());
        }
    }
}

Or pass custom flight address:

SpiceClient client = SpiceClient.builder()
    .withFlightAddress(new URI("grpc://my_remote_spice_instance:50051"))
    .build();

Connection retry​

The SpiceClient implements connection retry mechanism (3 attempts by default). The number of attempts can be configured with withMaxRetries:

SpiceClient client = SpiceClient.builder()
    .withMaxRetries(5) // Setting to 0 will disable retries
    .build();

Retries are performed for connection and system internal errors. It is the SDK user's responsibility to properly handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429).

Parameterized Queries​

The SDK supports parameterized queries using ADBC (v0.5.0+). Use queryWithParams() for queries with user input to prevent SQL injection:

import org.apache.arrow.vector.VectorSchemaRoot;
import org.apache.arrow.vector.ipc.ArrowReader;
import ai.spice.SpiceClient;

public class Example {
    public static void main(String[] args) {
        try (SpiceClient client = SpiceClient.builder().build()) {

            // Query with automatic type inference
            ArrowReader reader = client.queryWithParams(
                "SELECT * FROM taxi_trips WHERE trip_distance > $1 LIMIT 10",
                5.0); // Double is inferred as Float64

            while (reader.loadNextBatch()) {
                VectorSchemaRoot root = reader.getVectorSchemaRoot();
                System.out.println(root.contentToTSVString());
            }
            reader.close();

        } catch (Exception e) {
            System.err.println("Error: " + e.getMessage());
        }
    }
}

For explicit type control, use the Param class:

import ai.spice.Param;

ArrowReader reader = client.queryWithParams(
    "SELECT * FROM orders WHERE order_id = $1 AND amount >= $2",
    Param.int64(12345),
    Param.decimal128(new BigDecimal("99.99"), 10, 2));

For more details, see Parameterized Queries.

Memory Configuration​

The SpiceClient uses an Arrow RootAllocator for managing off-heap memory. By default, it uses all available memory. You can configure the memory limit using megabytes:

SpiceClient client = SpiceClient.builder()
    .withArrowMemoryLimitMB(1024) // 1GB limit
    .build();

Spice.ai Runtime commands​

Accelerated dataset refresh​

Use refresh method to perform Accelerated Dataset refresh. See full dataset refresh example.

SpiceClient client = SpiceClient.builder()
    ..
    .build();

client.refresh("taxi_trips")