Spice Java SDK v0.5.0

Highlights

This release introduces Parameterized Queries using ADBC (Arrow Database Connectivity), providing a safer and more efficient way to execute queries with dynamic parameters.

What's New

🎯 Parameterized Queries

The SDK now supports parameterized queries through the new queryWithParams() method. This is the recommended approach for queries with user input to prevent SQL injection attacks.

// 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

// With multiple parameters
ArrowReader reader = client.queryWithParams(
    "SELECT * FROM taxi_trips WHERE trip_distance > $1 AND fare_amount > $2 LIMIT 10",
    5.0, 20.0);

🔧 Explicit Type Control with Param Class

For precise control over Arrow types, use the new Param class with typed factory methods:

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

Available typed parameter constructors:

• Integers: int8, int16, int32, int64, uint8, uint16, uint32, uint64
• Floating point: float16, float32, float64
• Strings: string, largeString
• Binary: binary, largeBinary, fixedSizeBinary
• Boolean: bool
• Date/Time: date32, date64, time32, time64, timestamp, duration
• Decimals: decimal128, decimal256
• Null: nullValue

📦 New Dependencies

• Added Apache Arrow ADBC FlightSQL driver (adbc-driver-flight-sql:0.21.0)
• Added Apache Arrow ADBC Core (adbc-core:0.21.0)
• Added Gson (gson:2.13.1)
• Added SLF4J API (slf4j-api:2.0.17) for structured logging

⬆️ Updated Dependencies

• Apache Arrow Flight SQL: 17.0.0 → 18.3.0
• Netty: 4.1.108.Final → 4.1.130.Final
• SLF4J: 2.0.16 → 2.0.17 (moved to slf4j-api, slf4j-simple now test-scoped)

🔧 Updated Build Plugins

• maven-surefire-plugin: 3.3.0 → 3.5.4
• maven-source-plugin: 3.3.0 → 3.3.1
• maven-javadoc-plugin: 3.6.3 → 3.12.0
• maven-gpg-plugin: 3.2.1 → 3.2.8
• central-publishing-maven-plugin: 0.5.0 → 0.9.0

📝 Logging Support

The SDK now includes structured logging via SLF4J. Users can plug in their preferred logging implementation (Logback, Log4j2, etc.). Log messages are emitted at:

• DEBUG: Client initialization, query execution, ADBC connection lifecycle
• WARN: Recoverable errors during resource cleanup
• ERROR: Query failures, connection errors

New Files

• Param.java - Parameter class with typed factory methods
• ParameterizedQueryTest.java - Test suite for parameterized queries
• ExampleParameterizedQueries.java - Example usage of parameterized queries
• ExampleIteratingResults.java - Comprehensive example showing how to iterate through query results

Automatic Type Inference

The following Java types are automatically inferred when passed to queryWithParams():

Java Type	Arrow Type
byte	Int8
short	Int16
int	Int32
long	Int64
float	Float32
double	Float64
String	Utf8
boolean	Bool
byte[]	Binary
LocalDate	Date32
LocalTime	Time64 (microseconds)
LocalDateTime	Timestamp (microseconds, UTC)
Duration	Duration (microseconds)
BigDecimal	Decimal128/256
null	Null

🔒 Security Benefits

Parameterized queries provide protection against SQL injection attacks:

// ❌ Vulnerable to SQL injection
String userId = getUserInput(); // Could be: "1 OR 1=1"
String sql = "SELECT * FROM users WHERE id = " + userId;
FlightStream stream = client.query(sql);

// ✅ Safe from SQL injection
ArrowReader reader = client.queryWithParams(
    "SELECT * FROM users WHERE id = $1",
    userId);

Breaking Changes

None. This release is fully backward compatible with v0.4.0.

Upgrade Guide

Simply update your dependency version from 0.4.0 to 0.5.0:

Maven:

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

Gradle:

implementation 'ai.spice:spiceai:0.5.0'

Contributors

Thanks to everyone who contributed to this release!

What's Changed

• feat: Add x-spice-user-agent header by @peasee in #25
• docs: Add endgame release process by @peasee in #28
• feat: Add support for refresh options by @peasee in #27
• Adding custom User-Agent to Java SDK by @eadgbear in #29
• Prepend user-supplied user-agent by @phillipleblanc in #30
• Fix integration tests: Use quickstart dataset for Cloud by @sgrebnov in #33
• Add configurable Arrow memory limit - withArrowMemoryLimitMB by @kczimm in #32
• Set version to 0.4.0 in documentation by @sgrebnov in #34
• Update end_game.md with Maven Central steps by @sgrebnov in #35
• feat: Add Parameterized Queries & Logging by @lukekim in #37

New Contributors

• @peasee made their first contribution in #25
• @eadgbear made their first contribution in #29
• @phillipleblanc made their first contribution in #30
• @kczimm made their first contribution in #32
• @lukekim made their first contribution in #37

Full Changelog: v0.3.0...v0.5.0