docs: fix v2.2 cookbook validation issues (#595)

Author: phillipleblanc

clickhouse/README.md

@@ -47,18 +47,18 @@ Follow the [getting started guide](https://docs.spiceai.org/getting-started) to
 
 See the [datasets reference](https://docs.spiceai.org/reference/spicepod/datasets) for more dataset configuration options.
 
-Set the environment variable `CLICKHOUSE_PASS` to the Clickhouse instance password. Environment variables can be specified on the command line when running the Spice runtime or in a `.env` file in the same directory as `spicepod.yaml`. The password is not required if the Clickhouse instance does not have a password set.
+For a password-protected Clickhouse instance, add the password parameter under the dataset's `params`:
 
-i.e. to set the password in a `.env` file:
-
-```bash
-echo "CLICKHOUSE_PASS=<password>" > .env
+```yaml
+clickhouse_pass: ${env:CLICKHOUSE_PASS}
 ```
 
-A `.env` file is created in the project directory with the following content:
+Then set `CLICKHOUSE_PASS` to the Clickhouse instance password. Environment variables can be specified on the command line when running the Spice runtime or in a `.env` file in the same directory as `spicepod.yaml`. Omit `clickhouse_pass` for an instance that does not have a password.
+
+i.e. to set the password in a `.env` file:
 
 ```bash
-CLICKHOUSE_PASS=<password>
+echo "CLICKHOUSE_PASS=<password>" > .env
 ```
 
 If you followed the above [preparation](#preparation) to generate a Clickhouse server use this:

clickhouse/spicepod.yaml

@@ -9,7 +9,6 @@ datasets:
       clickhouse_db: default
       clickhouse_tcp_port: 9000
       clickhouse_user: default
-      clickhouse_pass: ${env:CLICKHOUSE_PASS}
       clickhouse_secure: false # Defaults to true.  Set to false if not connecting over SSL
     acceleration:
       enabled: true

clients/adbc/README.md

@@ -2,7 +2,7 @@
 
 Works with `v1.0+`
 
-This repository provides a simple cookbook example demonstrating how to use Python to query Spice via the Apache Arrow Database Connectivity (ADBC) API with the Flight SQL interface to Spice OSS. The example script connects to a local Spice OSS runtime, executes a parameterized query and a simple query, and fetches results as Arrow Tables.
+This repository provides a simple cookbook example demonstrating how to use Python to query Spice via the Apache Arrow Database Connectivity (ADBC) API with the Flight SQL interface to Spice OSS. The example script connects to a local Spice OSS runtime, executes a parameterized query, and fetches results as an Arrow Table.
 
 ## Requirements
 
@@ -22,7 +22,7 @@ cd cookbook/clients/adbc
 ### 2. Install dependencies
 
 ```bash
-python -m venv .venv
+python3 -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
 ```
@@ -60,7 +60,7 @@ AccountId: [["account123","account789","account456"]]
 ServiceId: [["service789","service789","service789"]]
 AddOnSid: [["addon3","addon7","addon10"]]
 AddOnTypeSid: [["type123","type123","type789"]]
-AddOnJson: [["{\feature\":\"voice_integration\"}"","{\feature\":\"voice_integration\"}"","{\feature\":\"mms_support\"}""]]
+AddOnJson: [["{"feature":"voice_integration"}","{"feature":"voice_integration"}","{"feature":"mms_support"}"]]
 DateCreated: [[2025-04-03 15:45:00,2025-04-07 11:30:00,2025-04-10 09:45:00]]
 DateUpdated: [[2025-04-03 15:45:00,2025-04-07 11:30:00,2025-04-10 09:45:00]]
 ```

clients/adbc/data/test_data.csv

@@ -1,11 +1,11 @@
 AccountId,ServiceId,AddOnSid,AddOnTypeSid,AddOnJson,DateCreated,DateUpdated
-account123,service456,addon1,type789,"{\"feature\":\"sms_analytics\"}",2025-04-01 10:00:00,2025-04-01 10:00:00
-account123,service456,addon2,type789,"{\"feature\":\"mms_support\"}",2025-04-02 12:30:00,2025-04-03 09:15:00
-account123,service789,addon3,type123,"{\"feature\":\"voice_integration\"}",2025-04-03 15:45:00,2025-04-03 15:45:00
-account456,service456,addon4,type789,"{\"feature\":\"sms_analytics\"}",2025-04-04 08:20:00,2025-04-05 11:10:00
-account456,service123,addon5,type456,"{\"feature\":\"chatbot\"}",2025-04-05 14:00:00,2025-04-05 14:00:00
-account123,service456,addon6,type789,"{\"feature\":\"mms_support\"}",2025-04-06 09:00:00,2025-04-07 16:25:00
-account789,service789,addon7,type123,"{\"feature\":\"voice_integration\"}",2025-04-07 11:30:00,2025-04-07 11:30:00
-account789,service456,addon8,type789,"{\"feature\":\"sms_analytics\"}",2025-04-08 13:15:00,2025-04-09 10:40:00
-account123,service123,addon9,type456,"{\"feature\":\"chatbot\"}",2025-04-09 17:00:00,2025-04-09 17:00:00
-account456,service789,addon10,type789,"{\"feature\":\"mms_support\"}",2025-04-10 09:45:00,2025-04-10 09:45:00
+account123,service456,addon1,type789,"{""feature"":""sms_analytics""}",2025-04-01 10:00:00,2025-04-01 10:00:00
+account123,service456,addon2,type789,"{""feature"":""mms_support""}",2025-04-02 12:30:00,2025-04-03 09:15:00
+account123,service789,addon3,type123,"{""feature"":""voice_integration""}",2025-04-03 15:45:00,2025-04-03 15:45:00
+account456,service456,addon4,type789,"{""feature"":""sms_analytics""}",2025-04-04 08:20:00,2025-04-05 11:10:00
+account456,service123,addon5,type456,"{""feature"":""chatbot""}",2025-04-05 14:00:00,2025-04-05 14:00:00
+account123,service456,addon6,type789,"{""feature"":""mms_support""}",2025-04-06 09:00:00,2025-04-07 16:25:00
+account789,service789,addon7,type123,"{""feature"":""voice_integration""}",2025-04-07 11:30:00,2025-04-07 11:30:00
+account789,service456,addon8,type789,"{""feature"":""sms_analytics""}",2025-04-08 13:15:00,2025-04-09 10:40:00
+account123,service123,addon9,type456,"{""feature"":""chatbot""}",2025-04-09 17:00:00,2025-04-09 17:00:00
+account456,service789,addon10,type789,"{""feature"":""mms_support""}",2025-04-10 09:45:00,2025-04-10 09:45:00

clients/java/README.md

@@ -6,7 +6,7 @@ This guide demonstrates how to use Java to query Spice via the Apache Arrow Flig
 
 ## Requirements
 
-- Java 11 or newer
+- JDK 17
 - [Maven](https://maven.apache.org/) installed
 - [Spice CLI](https://docs.spiceai.org/getting-started) installed and Spice OSS runtime available
 
@@ -36,7 +36,6 @@ spice run
 ### 4. Run the Java client
 
 ```bash
-MAVEN_OPTS="--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED" \
 mvn exec:exec \
   -Dexec.mainClass="MessagingServiceApp"
 ```

clients/java/src/main/resources/test_data.csv

@@ -1,11 +1,11 @@
 AccountId,ServiceId,AddOnSid,AddOnTypeSid,AddOnJson,DateCreated,DateUpdated
-account123,service456,addon1,type789,"{\"feature\":\"sms_analytics\"}",2025-04-01 10:00:00,2025-04-01 10:00:00
-account123,service456,addon2,type789,"{\"feature\":\"mms_support\"}",2025-04-02 12:30:00,2025-04-03 09:15:00
-account123,service789,addon3,type123,"{\"feature\":\"voice_integration\"}",2025-04-03 15:45:00,2025-04-03 15:45:00
-account456,service456,addon4,type789,"{\"feature\":\"sms_analytics\"}",2025-04-04 08:20:00,2025-04-05 11:10:00
-account456,service123,addon5,type456,"{\"feature\":\"chatbot\"}",2025-04-05 14:00:00,2025-04-05 14:00:00
-account123,service456,addon6,type789,"{\"feature\":\"mms_support\"}",2025-04-06 09:00:00,2025-04-07 16:25:00
-account789,service789,addon7,type123,"{\"feature\":\"voice_integration\"}",2025-04-07 11:30:00,2025-04-07 11:30:00
-account789,service456,addon8,type789,"{\"feature\":\"sms_analytics\"}",2025-04-08 13:15:00,2025-04-09 10:40:00
-account123,service123,addon9,type456,"{\"feature\":\"chatbot\"}",2025-04-09 17:00:00,2025-04-09 17:00:00
-account456,service789,addon10,type789,"{\"feature\":\"mms_support\"}",2025-04-10 09:45:00,2025-04-10 09:45:00
+account123,service456,addon1,type789,"{""feature"":""sms_analytics""}",2025-04-01 10:00:00,2025-04-01 10:00:00
+account123,service456,addon2,type789,"{""feature"":""mms_support""}",2025-04-02 12:30:00,2025-04-03 09:15:00
+account123,service789,addon3,type123,"{""feature"":""voice_integration""}",2025-04-03 15:45:00,2025-04-03 15:45:00
+account456,service456,addon4,type789,"{""feature"":""sms_analytics""}",2025-04-04 08:20:00,2025-04-05 11:10:00
+account456,service123,addon5,type456,"{""feature"":""chatbot""}",2025-04-05 14:00:00,2025-04-05 14:00:00
+account123,service456,addon6,type789,"{""feature"":""mms_support""}",2025-04-06 09:00:00,2025-04-07 16:25:00
+account789,service789,addon7,type123,"{""feature"":""voice_integration""}",2025-04-07 11:30:00,2025-04-07 11:30:00
+account789,service456,addon8,type789,"{""feature"":""sms_analytics""}",2025-04-08 13:15:00,2025-04-09 10:40:00
+account123,service123,addon9,type456,"{""feature"":""chatbot""}",2025-04-09 17:00:00,2025-04-09 17:00:00
+account456,service789,addon10,type789,"{""feature"":""mms_support""}",2025-04-10 09:45:00,2025-04-10 09:45:00

clients/scala/README.md

@@ -6,7 +6,7 @@ This guide demonstrates how to use Scala to query Spice via the Apache Arrow Fli
 
 ## Requirements
 
-- Scala 2.13+
+- JDK 17
 - [sbt](https://www.scala-sbt.org/) installed
 - [Spice CLI](https://docs.spiceai.org/getting-started) installed and Spice OSS runtime available
 
@@ -21,11 +21,13 @@ cd cookbook/clients/scala
 
 ### 2. Install dependencies
 
-Ensure you have sbt and Scala installed:
+Install sbt and JDK 17:
 
 ```bash
-brew install scala
+brew install openjdk@17
 brew install sbt
+export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"
+export PATH="$JAVA_HOME/bin:$PATH"
 ```
 
 ### 3. Start Spice OSS
@@ -47,16 +49,16 @@ Expected output:
 
 ```
 [info] Add-ons by account and service:
-[info] MessagingServiceAddOn(account123,service456,addon6,type789,{\feature\":\"mms_support\"}",2025-04-06 16:00:00.0,2025-04-07 23:25:00.0)
-[info] MessagingServiceAddOn(account123,service456,addon2,type789,{\feature\":\"mms_support\"}",2025-04-02 19:30:00.0,2025-04-03 16:15:00.0)
-[info] MessagingServiceAddOn(account123,service456,addon1,type789,{\feature\":\"sms_analytics\"}",2025-04-01 17:00:00.0,2025-04-01 17:00:00.0)
+[info] addon6
+[info] addon2
+[info] addon1
 [info] Add-ons by add-on type:
-[info] MessagingServiceAddOn(account123,service456,addon1,type789,{\feature\":\"sms_analytics\"}",2025-04-01 17:00:00.0,2025-04-01 17:00:00.0)
-[info] MessagingServiceAddOn(account123,service456,addon2,type789,{\feature\":\"mms_support\"}",2025-04-02 19:30:00.0,2025-04-03 16:15:00.0)
-[info] MessagingServiceAddOn(account456,service456,addon4,type789,{\feature\":\"sms_analytics\"}",2025-04-04 15:20:00.0,2025-04-05 18:10:00.0)
-[info] MessagingServiceAddOn(account123,service456,addon6,type789,{\feature\":\"mms_support\"}",2025-04-06 16:00:00.0,2025-04-07 23:25:00.0)
-[info] MessagingServiceAddOn(account789,service456,addon8,type789,{\feature\":\"sms_analytics\"}",2025-04-08 20:15:00.0,2025-04-09 17:40:00.0)
-[info] MessagingServiceAddOn(account456,service789,addon10,type789,{\feature\":\"mms_support\"}",2025-04-10 16:45:00.0,2025-04-10 16:45:00.0)
+[info] addon1
+[info] addon2
+[info] addon4
+[info] addon6
+[info] addon8
+[info] addon10
 ```
 
 ## Learn more

clients/scala/build.sbt

@@ -12,6 +12,6 @@ libraryDependencies ++= Seq(
 )
 
 
-run / javaOptions += "--add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED"
+run / javaOptions += "--add-opens=java.base/java.nio=ALL-UNNAMED"
 run / javaOptions += "--add-opens=java.base/java.lang=ALL-UNNAMED"
 run / fork := true

clients/scala/data/test_data.csv

@@ -1,11 +1,11 @@
 AccountId,ServiceId,AddOnSid,AddOnTypeSid,AddOnJson,DateCreated,DateUpdated
-account123,service456,addon1,type789,"{\"feature\":\"sms_analytics\"}",2025-04-01 10:00:00,2025-04-01 10:00:00
-account123,service456,addon2,type789,"{\"feature\":\"mms_support\"}",2025-04-02 12:30:00,2025-04-03 09:15:00
-account123,service789,addon3,type123,"{\"feature\":\"voice_integration\"}",2025-04-03 15:45:00,2025-04-03 15:45:00
-account456,service456,addon4,type789,"{\"feature\":\"sms_analytics\"}",2025-04-04 08:20:00,2025-04-05 11:10:00
-account456,service123,addon5,type456,"{\"feature\":\"chatbot\"}",2025-04-05 14:00:00,2025-04-05 14:00:00
-account123,service456,addon6,type789,"{\"feature\":\"mms_support\"}",2025-04-06 09:00:00,2025-04-07 16:25:00
-account789,service789,addon7,type123,"{\"feature\":\"voice_integration\"}",2025-04-07 11:30:00,2025-04-07 11:30:00
-account789,service456,addon8,type789,"{\"feature\":\"sms_analytics\"}",2025-04-08 13:15:00,2025-04-09 10:40:00
-account123,service123,addon9,type456,"{\"feature\":\"chatbot\"}",2025-04-09 17:00:00,2025-04-09 17:00:00
-account456,service789,addon10,type789,"{\"feature\":\"mms_support\"}",2025-04-10 09:45:00,2025-04-10 09:45:00
+account123,service456,addon1,type789,"{""feature"":""sms_analytics""}",2025-04-01 10:00:00,2025-04-01 10:00:00
+account123,service456,addon2,type789,"{""feature"":""mms_support""}",2025-04-02 12:30:00,2025-04-03 09:15:00
+account123,service789,addon3,type123,"{""feature"":""voice_integration""}",2025-04-03 15:45:00,2025-04-03 15:45:00
+account456,service456,addon4,type789,"{""feature"":""sms_analytics""}",2025-04-04 08:20:00,2025-04-05 11:10:00
+account456,service123,addon5,type456,"{""feature"":""chatbot""}",2025-04-05 14:00:00,2025-04-05 14:00:00
+account123,service456,addon6,type789,"{""feature"":""mms_support""}",2025-04-06 09:00:00,2025-04-07 16:25:00
+account789,service789,addon7,type123,"{""feature"":""voice_integration""}",2025-04-07 11:30:00,2025-04-07 11:30:00
+account789,service456,addon8,type789,"{""feature"":""sms_analytics""}",2025-04-08 13:15:00,2025-04-09 10:40:00
+account123,service123,addon9,type456,"{""feature"":""chatbot""}",2025-04-09 17:00:00,2025-04-09 17:00:00
+account456,service789,addon10,type789,"{""feature"":""mms_support""}",2025-04-10 09:45:00,2025-04-10 09:45:00

clients/scala/src/main/scala/DemoApp.scala

@@ -71,11 +71,11 @@ object MessagingServiceApp {
     try {
       val addOns1 = dao.getMessagingServiceAddOns("account123", "service456")
       println("Add-ons by account and service:")
-      addOns1.asScala.foreach(println)
+      addOns1.asScala.foreach(addOn => println(addOn.AddOnSid))
 
       val addOns2 = dao.getMessagingServiceAddOnByAddOnType("type789", 10)
       println("\nAdd-ons by add-on type:")
-      addOns2.asScala.foreach(println)
+      addOns2.asScala.foreach(addOn => println(addOn.AddOnSid))
     } finally {
       dbi.close(dao)
     }