Updates

Author: lukekim

README.md

@@ -213,6 +213,69 @@ SpiceClient client = SpiceClient.builder()
     .build();
 ```
 
+### Iterating Through Results
+
+For more control over query results, you can iterate through rows and access individual field values:
+
+```java
+import org.apache.arrow.flight.FlightStream;
+import org.apache.arrow.vector.FieldVector;
+import org.apache.arrow.vector.Float8Vector;
+import org.apache.arrow.vector.VarCharVector;
+import org.apache.arrow.vector.VectorSchemaRoot;
+import org.apache.arrow.vector.types.pojo.Field;
+
+try (SpiceClient client = SpiceClient.builder().build()) {
+    FlightStream stream = client.query("SELECT * FROM taxi_trips LIMIT 10;");
+
+    while (stream.next()) {
+        try (VectorSchemaRoot root = stream.getRoot()) {
+            int rowCount = root.getRowCount();
+
+            // Print column names and types
+            for (Field field : root.getSchema().getFields()) {
+                System.out.printf("Column: %s, Type: %s%n", field.getName(), field.getType());
+            }
+
+            // Iterate through rows generically
+            for (int row = 0; row < rowCount; row++) {
+                for (FieldVector vector : root.getFieldVectors()) {
+                    String columnName = vector.getName();
+                    Object value = vector.isNull(row) ? null : vector.getObject(row);
+                    System.out.printf("%s = %s%n", columnName, value);
+                }
+            }
+
+            // Access specific columns with type safety
+            FieldVector fareVector = root.getVector("fare_amount");
+            if (fareVector instanceof Float8Vector) {
+                Float8Vector fareVec = (Float8Vector) fareVector;
+                for (int row = 0; row < rowCount; row++) {
+                    if (!fareVec.isNull(row)) {
+                        double fare = fareVec.get(row);
+                        System.out.printf("Fare: $%.2f%n", fare);
+                    }
+                }
+            }
+
+            // Access string columns
+            FieldVector vendorVector = root.getVector("vendor_id");
+            if (vendorVector instanceof VarCharVector) {
+                VarCharVector strVec = (VarCharVector) vendorVector;
+                for (int row = 0; row < rowCount; row++) {
+                    if (!strVec.isNull(row)) {
+                        String vendorId = new String(strVec.get(row), java.nio.charset.StandardCharsets.UTF_8);
+                        System.out.printf("Vendor: %s%n", vendorId);
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+See [ExampleIteratingResults.java](/src/main/java/ai/spice/example/ExampleIteratingResults.java) for a comprehensive example.
+
 ### Spice.ai Runtime commands
 
 #### Accelerated dataset refresh
@@ -228,6 +291,40 @@ client.refresh("taxi_trips")
 
 ```
 
+### Logging
+
+The SDK uses SLF4J for logging, allowing you to plug in your preferred logging implementation (Logback, Log4j2, java.util.logging, etc.).
+
+**Adding a logging implementation (Maven):**
+
+```xml
+<!-- Using Logback -->
+<dependency>
+    <groupId>ch.qos.logback</groupId>
+    <artifactId>logback-classic</artifactId>
+    <version>1.5.18</version>
+</dependency>
+
+<!-- Or using SLF4J Simple (console output) -->
+<dependency>
+    <groupId>org.slf4j</groupId>
+    <artifactId>slf4j-simple</artifactId>
+    <version>2.0.17</version>
+</dependency>
+```
+
+**Log levels used:**
+
+- `DEBUG` - Client initialization, query execution, connection lifecycle
+- `WARN` - Recoverable errors during resource cleanup
+- `ERROR` - Query failures, connection errors
+
+To enable debug logging with `slf4j-simple`, set the system property:
+
+```bash
+-Dorg.slf4j.simpleLogger.defaultLogLevel=debug
+```
+
 ## 🤝 Connect with us
 
 Use [issues](https://github.com/spiceai/spice-java/issues), [hey@spice.ai](mailto:hey@spice.ai) or [Slack](https://spiceai.org/slack) to send us feedback, suggestions, or if you need help installing or using the library.

docs/release_notes/v0.5.0.md

@@ -51,12 +51,13 @@ ArrowReader reader = client.queryWithParams(
 - 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 Simple: 2.0.16 → 2.0.17
+- SLF4J: 2.0.16 → 2.0.17 (moved to `slf4j-api`, `slf4j-simple` now test-scoped)
 
 ### 🔧 Updated Build Plugins
 
@@ -66,11 +67,20 @@ ArrowReader reader = client.queryWithParams(
 - 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
 

pom.xml

@@ -63,10 +63,16 @@
             <artifactId>netty-all</artifactId>
             <version>4.1.130.Final</version>
         </dependency>
+        <dependency>
+            <groupId>org.slf4j</groupId>
+            <artifactId>slf4j-api</artifactId>
+            <version>2.0.17</version>
+        </dependency>
         <dependency>
             <groupId>org.slf4j</groupId>
             <artifactId>slf4j-simple</artifactId>
             <version>2.0.17</version>
+            <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>junit</groupId>

src/main/java/ai/spice/SpiceClient.java

@@ -112,13 +112,17 @@ of this software and associated documentation files (the "Software"), to deal
 import com.google.gson.Gson;
 
 import org.apache.arrow.flight.sql.FlightSqlClient;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 /**
  * Client to execute SQL queries against Spice.ai Cloud and Spice.ai OSS.
  * Supports both regular queries and parameterized queries using ADBC.
  */
 public class SpiceClient implements AutoCloseable {
 
+    private static final Logger logger = LoggerFactory.getLogger(SpiceClient.class);
+    
     private static final long BYTES_PER_MB = 1024L * 1024L;
 
     // Cached Gson instance for JSON serialization (thread-safe)
@@ -210,6 +214,7 @@ public SpiceClient(String appId, String apiKey, URI flightAddress, URI httpAddre
         if (Strings.isNullOrEmpty(apiKey)) {
             this.flightClient = new FlightSqlClient(builder.build());
             initRetryers();
+            logger.debug("SpiceClient initialized (unauthenticated) - flightAddress={}", this.flightAddress);
             return;
         }
 
@@ -238,6 +243,8 @@ public SpiceClient(String appId, String apiKey, URI flightAddress, URI httpAddre
 
         // Initialize cached retryers (immutable, built once)
         initRetryers();
+        
+        logger.debug("SpiceClient initialized (authenticated) - flightAddress={}, appId={}", this.flightAddress, this.appId);
     }
 
     /**
@@ -286,10 +293,14 @@ public FlightStream query(String sql) throws ExecutionException {
             throw new IllegalArgumentException("No SQL query provided");
         }
 
+        logger.debug("Executing query: {}", sql);
         try {
-            return this.queryInternalWithRetry(sql);
+            FlightStream result = this.queryInternalWithRetry(sql);
+            logger.debug("Query executed successfully");
+            return result;
         } catch (RetryException e) {
             Throwable err = e.getLastFailedAttempt().getExceptionCause();
+            logger.error("Query failed after {} attempts: {}", e.getNumberOfFailedAttempts(), err.getMessage());
             throw new ExecutionException("Failed to execute query due to error: " + err.toString(), err);
         }
     }
@@ -339,13 +350,18 @@ public ArrowReader queryWithParams(String sql, Object... params) throws Executio
             throw new IllegalArgumentException("No SQL query provided");
         }
 
+        logger.debug("Executing parameterized query with {} parameters: {}", params != null ? params.length : 0, sql);
         try {
             initADBCIfNeeded();
-            return queryWithParamsInternal(sql, params);
+            ArrowReader result = queryWithParamsInternal(sql, params);
+            logger.debug("Parameterized query executed successfully");
+            return result;
         } catch (AdbcException e) {
+            logger.error("Parameterized query failed: {}", e.getMessage());
             throw new ExecutionException("Failed to execute parameterized query: " + e.getMessage(), e);
         } catch (RetryException e) {
             Throwable err = e.getLastFailedAttempt().getExceptionCause();
+            logger.error("Parameterized query failed after {} attempts: {}", e.getNumberOfFailedAttempts(), err.getMessage());
             throw new ExecutionException("Failed to execute parameterized query due to error: " + err.toString(), err);
         }
     }
@@ -359,6 +375,8 @@ private synchronized void initADBCIfNeeded() throws AdbcException {
             return;
         }
 
+        logger.debug("Initializing ADBC connection");
+        
         // Format the URI for ADBC FlightSQL driver
         String uri = this.flightAddress.toString();
 
@@ -391,6 +409,8 @@ private synchronized void initADBCIfNeeded() throws AdbcException {
         FlightSqlDriver driver = new FlightSqlDriver(allocator);
         adbcDatabase = driver.open(options);
         adbcConnection = adbcDatabase.connect();
+        
+        logger.debug("ADBC connection established - uri={}", uri);
     }
 
     /**
@@ -400,16 +420,18 @@ private void closeADBC() {
         if (adbcConnection != null) {
             try {
                 adbcConnection.close();
+                logger.debug("ADBC connection closed");
             } catch (Exception e) {
-                // Log but don't fail
+                logger.warn("Error closing ADBC connection: {}", e.getMessage());
             }
             adbcConnection = null;
         }
         if (adbcDatabase != null) {
             try {
                 adbcDatabase.close();
+                logger.debug("ADBC database closed");
             } catch (Exception e) {
-                // Log but don't fail
+                logger.warn("Error closing ADBC database: {}", e.getMessage());
             }
             adbcDatabase = null;
         }
@@ -787,6 +809,7 @@ public void refreshDataset(String dataset, RefreshOptions refreshOptions) throws
             throw new IllegalArgumentException("No dataset name provided");
         }
 
+        logger.debug("Refreshing dataset: {}", dataset);
         try {
             HttpRequest.Builder builder = HttpRequest.newBuilder()
                     .uri(new URI(String.format("%s/v1/datasets/%s/acceleration/refresh", this.httpAddress, dataset)))
@@ -804,19 +827,23 @@ public void refreshDataset(String dataset, RefreshOptions refreshOptions) throws
             HttpResponse<String> response = HTTP_CLIENT.send(request, HttpResponse.BodyHandlers.ofString());
 
             if (response.statusCode() != 201) {
+                logger.error("Dataset refresh failed - dataset={}, statusCode={}, response={}", dataset, response.statusCode(), response.body());
                 throw new ExecutionException(
                         String.format("Failed to trigger dataset refresh. Status Code: %d, Response: %s",
                                 response.statusCode(),
                                 response.body()),
                         null);
             }
+            logger.debug("Dataset refresh triggered successfully: {}", dataset);
         } catch (ExecutionException e) {
             // no need to wrap ExecutionException
             throw e;
         } catch (ConnectException err) {
+            logger.error("Cannot connect to Spice runtime at {}: {}", this.httpAddress, err.getMessage());
             throw new ExecutionException(
                     String.format("The Spice runtime is unavailable at %s. Is it running?", this.httpAddress), err);
         } catch (Exception err) {
+            logger.error("Dataset refresh failed: {}", err.getMessage());
             throw new ExecutionException("Failed to trigger dataset refresh due to error: " + err.toString(), err);
         }
     }
@@ -845,28 +872,34 @@ private boolean shouldRetry(CallStatus status) {
 
     @Override
     public void close() throws Exception {
+        logger.debug("Closing SpiceClient");
         List<Exception> exceptions = new ArrayList<>();
 
         // Close ADBC resources first
         try {
             closeADBC();
         } catch (Exception e) {
+            logger.warn("Error during ADBC cleanup: {}", e.getMessage());
             exceptions.add(e);
         }
 
         // Close Flight client
         try {
             this.flightClient.close();
+            logger.debug("Flight client closed");
         } catch (Exception e) {
+            logger.warn("Error closing Flight client: {}", e.getMessage());
             exceptions.add(e);
         }
 
         // Close allocator
         try {
             if (this.allocator != null) {
                 this.allocator.close();
+                logger.debug("Arrow allocator closed");
             }
         } catch (Exception e) {
+            logger.warn("Error closing Arrow allocator: {}", e.getMessage());
             exceptions.add(e);
         }
 
@@ -875,7 +908,10 @@ public void close() throws Exception {
             for (int i = 1; i < exceptions.size(); i++) {
                 first.addSuppressed(exceptions.get(i));
             }
+            logger.error("SpiceClient closed with {} error(s)", exceptions.size());
             throw first;
         }
+        
+        logger.debug("SpiceClient closed successfully");
     }
 }