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 11
OpenJDK 17
OpenJDK 21
OracleJDK 11
OracleJDK 17
OracleJDK 21
OracleJDK 22
Installation
<dependency>
<groupId>ai.spice</groupId>
<artifactId>spiceai</artifactId>
<version>0.3.0</version>
<scope>compile</scope>
</dependency>
Usage
1. Import the package.
import ai.spice.SpiceClient;
2. Create a SpiceClient
by providing 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 tpch.lineitem 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)
.
Contributing
Contribute to or file an issue with the spice-rs
library at: https://github.com/spiceai/spice-java
Last updated
Was this helpful?