Skip to content

Latest commit

 

History

History
103 lines (74 loc) · 2.69 KB

java-sdk.md

File metadata and controls

103 lines (74 loc) · 2.69 KB
Raw

Java SDK

The Java SDK is the easiest way to query the Spice Cloud Platform from Java.

It uses Apache Arrow Flight to efficiently stream data to the client and Apache Arrow Records as data frames.

Supported Java Versions

This library supports the following Java implementations:

  • OpenJDK 17
  • OpenJDK 21
  • OracleJDK 17
  • OracleJDK 21
  • OracleJDK 22

Installation

{% tabs %} {% tab title="Maven" %}

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

{% endtab %}

{% tab title="Gradle" %}

implementation 'ai.spice:spiceai:0.1.0'

{% endtab %} {% endtabs %}

Usage

1. Import the package.

import ai.spice.SpiceClient;

2. Create a SpiceClient passing in your API key. Get your free API key at spice.ai.

SpiceClient spice = SpiceClient.builder()
    .withApiKey(ApiKey)
    .withSpiceCloud()
    .build()

3. Execute a query and get back a FlightStream.

FlightStream stream = spice.query("SELECT * FROM eth.recent_blocks ORDER BY number LIMIT 10");

5. Iterate through the FlightStream to access the records.

while (stream.next()) {
    try (VectorSchemaRoot batches = stream.getRoot()) {
        System.out.println(batches.contentToTSVString());
    }
}

Check full example to learn more.

Usage with local Spice.ai OSS runtime

Follow the quickstart guide to install and run spice locally.

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

Or using custom flight address:

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

Check Spice OSS documentation or Java SDK Sample to learn more

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