diff --git a/client-sdk/curl-sample/README.md b/client-sdk/curl-sample/README.md new file mode 100644 index 00000000..f17cfaa0 --- /dev/null +++ b/client-sdk/curl-sample/README.md @@ -0,0 +1,48 @@ +# cURL Cloud Sample + +Use [cURL](https://curl.se/) to run SQL against [Spice.ai Cloud](https://spice.ai) over HTTP. + +## Links + +- [cURL](https://curl.se/) +- [Spice.ai Cloud](https://spice.ai) +- [Spice.ai Cloud API documentation](https://docs.spiceai.org/api) + +## Prerequisites + +- [cURL](https://curl.se/) +- A Spice.ai Cloud API key +- A dataset available in your Cloud app + +## Quick Start + +```bash +git clone https://github.com/spiceai/cookbook.git +cd cookbook/client-sdk/curl-sample +``` + +Set your cloud values for the commands in this README: + +```bash +export SPICE_API_KEY="your_api_key" +export SPICE_DATASET="your_dataset" +``` + +The script snippet keeps inline placeholders by design. Replace the API key and dataset placeholders in `query_cloud_http.sh`, then run: + +```bash +bash query_cloud_http.sh +``` + +## Manual Query (HTTP) + +```bash +curl -X POST https://data.spiceai.io/v1/sql \ + -H "Content-Type: application/json" \ + -H "X-API-Key: ${SPICE_API_KEY}" \ + -d "{\"query\": \"SELECT * FROM ${SPICE_DATASET} LIMIT 10\"}" +``` + +## Expected Result + +You should receive JSON with query results in a `data` array. diff --git a/client-sdk/curl-sample/query_cloud_http.sh b/client-sdk/curl-sample/query_cloud_http.sh new file mode 100644 index 00000000..e1e02ce0 --- /dev/null +++ b/client-sdk/curl-sample/query_cloud_http.sh @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail + +curl -sS -X POST https://data.spiceai.io/v1/sql \ + -H "Content-Type: application/json" \ + -H "X-API-Key: \"\"" \ + -d "{\"query\": \"SELECT * FROM LIMIT 10\"}" +echo diff --git a/client-sdk/gospice-sdk-sample/README.md b/client-sdk/gospice-sdk-sample/README.md index e7eedd96..b4942e7e 100644 --- a/client-sdk/gospice-sdk-sample/README.md +++ b/client-sdk/gospice-sdk-sample/README.md @@ -1,27 +1,33 @@ # Spice with gospice SDK -This recipe demonstrates how to use the gospice SDK to connect to a Spice runtime and query data. +Use the [gospice SDK](https://github.com/spiceai/gospice) to query Spice from Go. -Clone this cookbook repo locally and navigate to the `gospice-sdk-sample` directory: +## What This Sample Includes -```shell -git clone https://github.com/spiceai/cookbook.git -cd cookbook/client-sdk/gospice-sdk-sample/ -``` +- `main.go`: Query a local Spice runtime, including a parameterized query. +- `cloud/main.go`: Query Spice.ai Cloud with inline replacement values. ## Prerequisites -This recipe requires [Go](https://go.dev/) to be installed. +- [Go](https://go.dev/) 1.24+ +- [Spice CLI](https://docs.spiceai.org/getting-started) for local mode + +## Local Quick Start + +```bash +git clone https://github.com/spiceai/cookbook.git +cd cookbook/client-sdk/gospice-sdk-sample +``` -## Start spice runtime +Start Spice runtime in one terminal: -```shell +```bash spice run ``` -Output: +Sample runtime logs: -```shell +```text 2024/11/27 16:24:27 INFO Checking for latest Spice runtime release... 2024/11/27 16:24:27 INFO Spice.ai runtime starting... 2024-11-28T00:24:28.411072Z INFO runtime::init::dataset: Initializing dataset taxi_trips @@ -35,15 +41,15 @@ Output: 2024-11-28T00:24:37.106088Z INFO runtime::accelerated_table::refresh_task: Loaded 2,964,624 rows (419.31 MiB) for dataset taxi_trips in 7s 856ms. ``` -## Run sample application +Run the Go sample in another terminal: -```shell +```bash go run main.go ``` -Results: +Sample output: -```shell +```text === Using Sql === VendorID: 2, tpep_pickup_datetime: 1706465757000000, fare_amount: 15.6 VendorID: 2, tpep_pickup_datetime: 1706466833000000, fare_amount: 14.2 @@ -63,3 +69,26 @@ VendorID: 1, tpep_pickup_datetime: 1706250595000000, fare_amount: 20.5 VendorID: 1, tpep_pickup_datetime: 1706250222000000, fare_amount: 10.7 VendorID: 2, tpep_pickup_datetime: 1706249286000000, fare_amount: 70 ``` + +## Spice.ai Cloud Quick Start + +Set your API key for the commands in this README: + +```bash +export SPICE_API_KEY="your_api_key" +``` + +The cloud snippet keeps an inline API key placeholder by design. Replace the API key placeholder in `cloud/main.go` with `${SPICE_API_KEY}`, then run: + +```bash +go run ./cloud +``` + +Expected output is a list of tables from `show tables;`. + +## Links + +- [gospice SDK](https://github.com/spiceai/gospice) +- [Go package](https://pkg.go.dev/github.com/spiceai/gospice/v6) +- [Spice.ai Cloud](https://spice.ai) +- [Spice.ai documentation](https://docs.spiceai.org) diff --git a/client-sdk/spice-cli-sample/README.md b/client-sdk/spice-cli-sample/README.md new file mode 100644 index 00000000..f90a4572 --- /dev/null +++ b/client-sdk/spice-cli-sample/README.md @@ -0,0 +1,75 @@ +# Spice CLI Cloud Sample + +Use the [Spice CLI](https://docs.spiceai.org/getting-started) to run SQL against [Spice.ai Cloud](https://spice.ai). + +## Links + +- [Spice CLI documentation](https://docs.spiceai.org/cli) +- [Spice CLI installation](https://docs.spiceai.org/getting-started) +- [Spice.ai Cloud](https://spice.ai) +- [Spice OSS GitHub](https://github.com/spiceai/spiceai) + +## Prerequisites + +- [Spice CLI](https://docs.spiceai.org/getting-started) +- A Spice.ai Cloud API key +- A dataset available in your Cloud app + +Install Spice CLI if needed: + +```bash +curl https://install.spiceai.org | /bin/bash +``` + +## Quick Start + +```bash +git clone https://github.com/spiceai/cookbook.git +cd cookbook/client-sdk/spice-cli-sample +``` + +Set your cloud values for the commands in this README: + +```bash +export SPICE_API_KEY="your_api_key" +export SPICE_DATASET="your_dataset" +``` + +The script snippets keep inline placeholders by design. Replace the API key and dataset placeholders in the scripts, then run: + +```bash +bash query_cloud_default.sh +``` + +## Additional URL Examples + +Run with an explicit gRPC endpoint URL: + +```bash +bash query_cloud_grpc.sh +``` + +Run with an explicit HTTP endpoint URL: + +```bash +bash query_cloud_http.sh +``` + +## Manual Commands + +```bash +spice sql \ + --cloud \ + --api-key "${SPICE_API_KEY}" \ + "SELECT * FROM ${SPICE_DATASET} LIMIT 10" + +spice sql \ + --api-key "${SPICE_API_KEY}" \ + --endpoint "grpc+tls://flight.spiceai.io:443" \ + "SELECT * FROM ${SPICE_DATASET} LIMIT 10" + +spice sql \ + --api-key "${SPICE_API_KEY}" \ + --endpoint "https://data.spiceai.io" \ + "SELECT * FROM ${SPICE_DATASET} LIMIT 10" +``` diff --git a/client-sdk/spice-cli-sample/query_cloud_default.sh b/client-sdk/spice-cli-sample/query_cloud_default.sh new file mode 100644 index 00000000..7adb5bb2 --- /dev/null +++ b/client-sdk/spice-cli-sample/query_cloud_default.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +set -euo pipefail + +spice sql \ + --cloud \ + --api-key "" \ + "SELECT * FROM LIMIT 10" \ No newline at end of file diff --git a/client-sdk/spice-cli-sample/query_cloud_grpc.sh b/client-sdk/spice-cli-sample/query_cloud_grpc.sh new file mode 100644 index 00000000..1d8755ce --- /dev/null +++ b/client-sdk/spice-cli-sample/query_cloud_grpc.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +set -euo pipefail + +spice sql \ + --api-key "" \ + --endpoint "grpc+tls://flight.spiceai.io:443" \ + "SELECT * FROM LIMIT 10" diff --git a/client-sdk/spice-cli-sample/query_cloud_http.sh b/client-sdk/spice-cli-sample/query_cloud_http.sh new file mode 100644 index 00000000..834fdb47 --- /dev/null +++ b/client-sdk/spice-cli-sample/query_cloud_http.sh @@ -0,0 +1,7 @@ +#!/usr/bin/env bash +set -euo pipefail + +spice sql \ + --api-key "" \ + --endpoint "https://data.spiceai.io" \ + "SELECT * FROM LIMIT 10" diff --git a/client-sdk/spice-dotnet-sdk-sample/README.md b/client-sdk/spice-dotnet-sdk-sample/README.md index b42688e3..f9266e7d 100644 --- a/client-sdk/spice-dotnet-sdk-sample/README.md +++ b/client-sdk/spice-dotnet-sdk-sample/README.md @@ -1,26 +1,33 @@ # Spice with Dotnet SDK -This recipe shows how to interact with Spice using the [Dotnet SDK](https://github.com/spiceai/spice-dotnet). +Use the [Spice Dotnet SDK](https://github.com/spiceai/spice-dotnet) to query Spice from C#. + +## What This Sample Includes + +- `Program.cs`: Query a local Spice runtime, including a parameterized query. +- `Cloud.cs`: Query Spice.ai Cloud with inline replacement values. ## Prerequisites -- [Spice](https://github.com/spiceai/spiceai) is installed -- [Dotnet](https://dotnet.microsoft.com/en-us/download) +- [.NET SDK](https://dotnet.microsoft.com/en-us/download) compatible with `net10.0` +- [Spice CLI](https://docs.spiceai.org/getting-started) for local mode -## Clone this sample +## Local Quick Start -```shell +```bash git clone https://github.com/spiceai/cookbook.git cd cookbook/client-sdk/spice-dotnet-sdk-sample ``` -## Start the Spice runtime +Start Spice runtime in one terminal: -```shell +```bash spice run ``` -```shell +Sample runtime logs: + +```text 2025-08-28T21:08:10.674387Z INFO spiced: Starting runtime v1.7.0-unstable-build.246c46c4d-dev+models 2025-08-28T21:08:10.675513Z INFO runtime::init::caching: Initialized results cache; max size: 128.00 MiB, item ttl: 1s 2025-08-28T21:08:10.675671Z INFO runtime::init::caching: Initialized search results cache; @@ -34,13 +41,15 @@ spice run 2025-08-28T21:08:20.455383Z INFO runtime: All components are loaded. Spice runtime is ready! ``` -## Run the sample +Run the sample in another terminal: -```shell +```bash dotnet run ``` -```shell +Sample output: + +```text === Using Query === VendorID: 2, tpep_pickup_datetime: 2024-01-09 23:22:13, fare_amount: 7.20 VendorID: 1, tpep_pickup_datetime: 2024-01-09 23:40:08, fare_amount: 18.40 @@ -60,3 +69,20 @@ VendorID: 2, tpep_pickup_datetime: 2024-01-31 09:12:53, fare_amount: 7.90 VendorID: 2, tpep_pickup_datetime: 2024-01-31 09:24:15, fare_amount: 27.50 VendorID: 2, tpep_pickup_datetime: 2024-01-31 09:42:13, fare_amount: 7.90 ``` + +## Spice.ai Cloud Configuration + +Set your API key for the commands in this README: + +```bash +export SPICE_API_KEY="your_api_key" +``` + +The cloud snippet keeps an inline API key placeholder by design. Replace the API key placeholder in `Cloud.cs` with `${SPICE_API_KEY}`. + +## Links + +- [Spice .NET SDK](https://github.com/spiceai/spice-dotnet) +- [NuGet package](https://www.nuget.org/packages/SpiceAI.Client) +- [Spice.ai Cloud](https://spice.ai) +- [Spice.ai documentation](https://docs.spiceai.org) diff --git a/client-sdk/spice-java-sdk-sample/README.md b/client-sdk/spice-java-sdk-sample/README.md index e98b7831..e8a76035 100644 --- a/client-sdk/spice-java-sdk-sample/README.md +++ b/client-sdk/spice-java-sdk-sample/README.md @@ -1,23 +1,34 @@ # Spice with Java SDK -Use [Spice.ai Java SDK](https://github.com/spiceai/spice-java) to query [Spice.ai](https://github.com/spiceai/spiceai) from Java. +Use the [Spice Java SDK](https://github.com/spiceai/spice-java) to query Spice from Java. -## Clone this sample +## What This Sample Includes -```shell +- `App.java`: Query a local Spice runtime. +- `Cloud.java`: Query Spice.ai Cloud with inline replacement values. + +## Prerequisites + +- JDK 17+ +- [Maven](https://maven.apache.org/install.html) +- [Spice CLI](https://docs.spiceai.org/getting-started) for local mode + +## Local Quick Start (Maven) + +```bash git clone https://github.com/spiceai/cookbook.git cd cookbook/client-sdk/spice-java-sdk-sample ``` -## Start spice runtime +Start Spice runtime in one terminal: -[Install Spice.ai OSS](https://docs.spiceai.org/getting-started) and start Spice runtime: - -```shell +```bash spice run ``` -```shell +Sample runtime logs: + +```text Spice.ai runtime starting... 2024-07-16T19:16:34.192387Z INFO spiced: Metrics listening on 127.0.0.1:9090 2024-07-16T19:16:34.195177Z INFO runtime::opentelemetry: Spice Runtime OpenTelemetry listening on 127.0.0.1:50052 @@ -29,34 +40,31 @@ Spice.ai runtime starting... 2024-07-16T19:16:40.494038Z INFO runtime::accelerated_table::refresh_task: Loaded 2,964,624 rows (421.71 MiB) for dataset taxi_trips in 5s 607ms. ``` -## Maven Users - -### Prerequisites - -1. A Java Development Kit (JDK), version 17 or higher - for example [OracleJDK](https://www.oracle.com/java/technologies/downloads/). Installed version can be verified with `java -version`. -1. [Maven](https://maven.apache.org/install.html). Verify the Maven installation with: `mvn -version` +In another terminal, compile and run: -### Build sample - -```shell +```bash mvn clean compile +_JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED" \ + mvn exec:java -Dexec.mainClass="ai.spice.example.App" ``` -```shell +Sample build logs: + +```text [INFO] Scanning for projects... -[INFO] +[INFO] [INFO] ------------------< ai.spice.example:taxi-trips-app >------------------- [INFO] Building taxi-trips-app 1.0-SNAPSHOT [INFO] from pom.xml [INFO] --------------------------------[ jar ]--------------------------------- -[INFO] +[INFO] [INFO] --- clean:3.2.0:clean (default-clean) @ taxi-trips-app --- [INFO] Deleting /Users/sg/spice/samples/client-sdk/spice-java-sdk-sample/target -[INFO] +[INFO] [INFO] --- resources:3.3.1:resources (default-resources) @ taxi-trips-app --- [WARNING] Using platform encoding (UTF-8 actually) to copy filtered resources, i.e. build is platform dependent! [INFO] skip non existing resourceDirectory /Users/sg/spice/samples/client-sdk/spice-java-sdk-sample/src/main/resources -[INFO] +[INFO] [INFO] --- compiler:3.13.0:compile (default-compile) @ taxi-trips-app --- [INFO] Recompiling the module because of changed source code. [WARNING] File encoding has not been set, using platform encoding UTF-8, i.e. build is platform dependent! @@ -73,28 +81,19 @@ mvn clean compile [INFO] Total time: 0.712 s [INFO] Finished at: 2024-07-16T12:43:33-07:00 [INFO] ------------------------------------------------------------------------ - ``` -### Run sample - -> **IMPORTANT:** The Spice SDK uses the Apache Arrow Flight library, which requires the `--add-opens=java.base/java.nio=ALL-UNNAMED` parameter to operate. -> -> Read [Apache Arrow Java Compatibility](https://arrow.apache.org/docs/java/install.html#java-compatibility) for more details. +Sample output: -```shell -_JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED" mvn exec:java -Dexec.mainClass="ai.spice.example.App" -``` - -```shell +```text Picked up _JAVA_OPTIONS: --add-opens=java.base/java.nio=ALL-UNNAMED [INFO] Scanning for projects... -[INFO] +[INFO] [INFO] ------------------< ai.spice.example:taxi-trips-app >------------------- [INFO] Building taxi-trips-app 1.0-SNAPSHOT [INFO] from pom.xml [INFO] --------------------------------[ jar ]--------------------------------- -[INFO] +[INFO] [INFO] --- exec:3.3.0:java (default-cli) @ taxi-trips-app --- [ai.spice.example.App.main()] INFO org.apache.arrow.memory.BaseAllocator - Debug mode disabled. Enable with the VM option -Darrow.memory.debug.allocator=true. [ai.spice.example.App.main()] INFO org.apache.arrow.memory.DefaultAllocationManagerOption - allocation manager type not specified, using netty as the default type @@ -112,20 +111,47 @@ VendorID tpep_pickup_datetime fare_amount 1 2024-01-14T08:17:35 5.1 ``` -## Gradle Users +## Spice.ai Cloud Quick Start + +Set your API key for the commands in this README: + +```bash +export SPICE_API_KEY="your_api_key" +``` + +The cloud snippet keeps an inline API key placeholder by design. Replace the API key placeholder in `src/main/java/ai/spice/example/Cloud.java` with `${SPICE_API_KEY}`, then run: + +```bash +_JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED" \ + mvn exec:java -Dexec.mainClass="ai.spice.example.Cloud" +``` + +## Note on Java Flags + +Apache Arrow Flight requires: + +```bash +_JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED" +``` + +## Advanced: Gradle Workflow + +This sample also supports Gradle. -### Prerequisites +### Gradle Prerequisites -1. A Java Development Kit (JDK), version 17 or higher - for example [OracleJDK](https://www.oracle.com/java/technologies/downloads/). Installed version can be verified with `java -version`. -1. [Gradle Build Tools version 7.0 or later](https://gradle.org/install/). Installed version can be verified with `gradle -v`. +1. JDK 17 or higher. +2. [Gradle](https://gradle.org/install/) 7.0 or later. -### Init gradle wrapper +### Initialize Gradle Wrapper -```shell +```bash gradle wrapper ``` -```shell +Sample output: + +```text Welcome to Gradle 8.9! Here are the highlights of this release: @@ -141,13 +167,15 @@ BUILD SUCCESSFUL in 2s 1 actionable task: 1 executed ``` -### Build recipe +### Build with Gradle -```shell +```bash ./gradlew clean build ``` -```shell +Sample output: + +```text Downloading https://services.gradle.org/distributions/gradle-8.9-bin.zip ............10%.............20%.............30%.............40%.............50%.............60%.............70%.............80%.............90%.............100% Starting a Gradle Daemon, 1 incompatible Daemon could not be reused, use --status for details @@ -156,11 +184,15 @@ BUILD SUCCESSFUL in 40s 6 actionable tasks: 5 executed, 1 up-to-date ``` -### Run recipe +### Run with Gradle -`./gradlew run` +```bash +./gradlew run +``` + +Sample output: -```shell +```text > Task :run [main] INFO org.apache.arrow.memory.BaseAllocator - Debug mode disabled. Enable with the VM option -Darrow.memory.debug.allocator=true. [main] INFO org.apache.arrow.memory.DefaultAllocationManagerOption - allocation manager type not specified, using netty as the default type @@ -177,3 +209,10 @@ VendorID tpep_pickup_datetime fare_amount 2 2024-01-02T14:27:29 44.3 2 2024-01-02T14:54:39 8.6 ``` + +## Links + +- [Spice Java SDK](https://github.com/spiceai/spice-java) +- [Maven Central](https://central.sonatype.com/artifact/ai.spice/spice) +- [Spice.ai Cloud](https://spice.ai) +- [Spice.ai documentation](https://docs.spiceai.org) diff --git a/client-sdk/spice-rs-sdk-sample/README.md b/client-sdk/spice-rs-sdk-sample/README.md index eb9ada33..8c8bb0b4 100644 --- a/client-sdk/spice-rs-sdk-sample/README.md +++ b/client-sdk/spice-rs-sdk-sample/README.md @@ -1,25 +1,28 @@ # Spice with Rust SDK -This recipe demonstrates how to use the Spice Rust SDK to connect to a Spice runtime and query data, including parameterized queries. +Use the [Spice Rust SDK](https://crates.io/crates/spiceai) to query a local Spice runtime. ## Prerequisites -This recipe requires [Rust](https://www.rust-lang.org/) to be installed. +- [Rust](https://www.rust-lang.org/) +- [Spice CLI](https://docs.spiceai.org/getting-started) -## Clone sample application +## Quick Start -```shell +```bash git clone https://github.com/spiceai/cookbook.git cd cookbook/client-sdk/spice-rs-sdk-sample ``` -## Start Spice runtime +Start Spice runtime in one terminal: -```shell +```bash spice run ``` -```shell +Sample runtime logs: + +```text 2024/11/27 12:46:10 INFO Checking for latest Spice runtime release... 2024/11/27 12:46:10 INFO Spice.ai runtime starting... 2024-11-27T20:46:11.343825Z INFO runtime::init::dataset: Initializing dataset taxi_trips @@ -33,21 +36,15 @@ spice run 2024-11-27T20:46:22.751704Z INFO runtime::accelerated_table::refresh_task: Loaded 2,964,624 rows (419.31 MiB) for dataset taxi_trips in 10s 464ms. ``` -## Build sample application - -```shell -cargo build -``` - -## Run sample application +Run the Rust sample in another terminal: -```shell +```bash cargo run ``` -Results: +Sample output: -```console +```text === Using query === VendorID: 2, tpep_pickup_datetime: 2024-01-06 14:41:17, fare_amount: 8.60 VendorID: 2, tpep_pickup_datetime: 2024-01-06 14:56:46, fare_amount: 7.20 @@ -67,3 +64,18 @@ VendorID: 1, tpep_pickup_datetime: 2024-01-26 06:29:55, fare_amount: 20.50 VendorID: 1, tpep_pickup_datetime: 2024-01-26 06:23:42, fare_amount: 10.70 VendorID: 2, tpep_pickup_datetime: 2024-01-26 06:08:06, fare_amount: 70.00 ``` + +## Advanced + +Build the sample without running it: + +```bash +cargo build +``` + +## Links + +- [Spice Rust SDK](https://github.com/spiceai/spice-rs) +- [crates.io](https://crates.io/crates/spiceai) +- [Spice.ai Cloud](https://spice.ai) +- [Spice.ai documentation](https://docs.spiceai.org) diff --git a/client-sdk/spice.js-sdk-sample/README.md b/client-sdk/spice.js-sdk-sample/README.md index ffe0da12..9939f57f 100644 --- a/client-sdk/spice.js-sdk-sample/README.md +++ b/client-sdk/spice.js-sdk-sample/README.md @@ -1,101 +1,76 @@ # Spice.js SDK Sample -A Node.js sample application demonstrating the [`@spiceai/spice`](https://www.npmjs.com/package/@spiceai/spice) package with the NYC taxi_trips dataset. +Use [`@spiceai/spice`](https://www.npmjs.com/package/@spiceai/spice) from Node.js to query `taxi_trips`. -## Features +## What This Sample Includes -- **Dual Mode Support**: Works with both Spice.ai Cloud ☁️ and local Spice runtime 🏠 -- Queries the NYC taxi_trips dataset using both `.sql()` and `.sqlJson()` methods -- Demonstrates four practical analytics queries: - 1. **Most Expensive Trips** - Find the top 10 highest-fare taxi rides - 2. **Trip Statistics** - Calculate average fares, distances, tips, and more - 3. **Popular Pickup Locations** - Identify the busiest pickup spots - 4. **Payment Type Distribution** - Analyze payment methods and tipping patterns +- `index.js`: Main sample with multiple analytics queries. +- `index_cloud.mjs`: Minimal cloud-only query (`show tables;`). ## Prerequisites -- Node.js 20 or higher -- npm or yarn +- Node.js 20+ +- npm +- [Spice CLI](https://docs.spiceai.org/getting-started) for local mode -## Getting Started - -1. Clone the Spice.ai cookbook repository: +## Quick Start ```bash git clone https://github.com/spiceai/cookbook.git cd cookbook/client-sdk/spice.js-sdk-sample -``` - -2. Install dependencies: - -```bash npm install ``` -## Usage - -You can run this sample in two ways: +## Run with Local Spice Runtime -### Option 1: Using Local Spice Runtime 🏠 (Recommended) - -1. Install the Spice CLI (see [Installation Guide](https://spiceai.org/docs/installation)) -2. From the `cookbook/client-sdk/spice.js-sdk-sample` directory, start the Spice runtime: +Start Spice runtime in one terminal: ```bash -# Terminal 1: Start Spice runtime (loads spicepod.yaml) spice run ``` -3. In a separate terminal, run the sample: +Run the Node sample in another terminal: ```bash -# Terminal 2: Run the sample (from the same directory) -node index.js +npm start ``` -The sample will automatically connect to the local runtime at `localhost:50051`. +`index.js` runs against your local runtime by default. -### Option 2: Using Spice.ai Cloud ☁️ +## Run with Spice.ai Cloud -1. Sign up for a free account at [spice.ai](https://spice.ai) -2. Create a new Spice app and manually deploy the `spicepod.yaml` through the web interface - - For detailed instructions, see the [Getting Started Guide](https://docs.spice.ai/getting-started/get-started) -3. Get your API key from the Spice.ai dashboard -4. Create a `.env` file with your API key: +Set your API key for the commands in this README: -```env -# .env file -SPICE_API_KEY=your_api_key_here +```bash +export SPICE_API_KEY="your_api_key" ``` -5. Run the sample: +The cloud snippet keeps an inline API key placeholder by design. Replace the API key placeholder in `index_cloud.mjs` with `${SPICE_API_KEY}`, then run: ```bash -node index.js +node index_cloud.mjs ``` -The sample automatically detects which mode to use based on whether `SPICE_API_KEY` is set. - ## Example Output -The application will display: +The application prints output similar to: -```shell -🌶️ Spice.js initialized - Platform: Node.js v24.9.0 darwin arm64 - Transport: Arrow Flight → HTTP - Endpoint: http://127.0.0.1:8090 - Flight URL: 127.0.0.1:50051 -🚕 NYC Taxi Trips Data Analysis +```text +Spice.js initialized + Platform: Node.js v24.9.0 darwin arm64 + Transport: Arrow Flight -> HTTP + Endpoint: http://127.0.0.1:8090 + Flight URL: 127.0.0.1:50051 +NYC Taxi Trips Data Analysis -📡 Connected to: Local Spice Runtime 🏠 -💡 Tip: Set SPICE_API_KEY in .env to use Spice.ai Cloud +Connected to: Local Spice Runtime +Tip: Use `index_cloud.mjs` with your cloud API key for Spice.ai Cloud Querying taxi_trips dataset... ============================================================ -📊 Query 1: Top 10 Most Expensive Taxi Trips +Query 1: Top 10 Most Expensive Taxi Trips Using .sql() - Apache Arrow Flight (gRPC) for high performance @@ -112,73 +87,73 @@ Found 10 trips: 9. $940.93 - 142.62 miles - 1 passenger(s) 10. $900.00 - 157.25 miles - 1 passenger(s) -⏱️ Execution time: 27.59ms +Execution time: 27.59ms ============================================================ -📈 Query 2: Trip Statistics Summary +Query 2: Trip Statistics Summary Statistics from sample: - • Total trips analyzed: 2964624 - • Average fare: $26.8 - • Average distance: 3.65 miles - • Average tip: $3.34 - • Highest fare: $5000 - • Lowest fare: $-900 + - Total trips analyzed: 2964624 + - Average fare: $26.8 + - Average distance: 3.65 miles + - Average tip: $3.34 + - Highest fare: $5000 + - Lowest fare: $-900 -⏱️ Execution time: 9.25ms +Execution time: 9.25ms ============================================================ -📍 Query 3: Top 10 Popular Pickup Locations +Query 3: Top 10 Popular Pickup Locations Most popular pickup locations: 1. Location ID 132: - 145240 trips | Avg fare: $76.58 | Avg distance: 15.49 miles + 145240 trips | Avg fare: $76.58 | Avg distance: 15.49 miles 2. Location ID 161: - 143471 trips | Avg fare: $23.48 | Avg distance: 2.56 miles + 143471 trips | Avg fare: $23.48 | Avg distance: 2.56 miles 3. Location ID 237: - 142708 trips | Avg fare: $19.45 | Avg distance: 1.7 miles + 142708 trips | Avg fare: $19.45 | Avg distance: 1.7 miles 4. Location ID 236: - 136465 trips | Avg fare: $20 | Avg distance: 1.85 miles + 136465 trips | Avg fare: $20 | Avg distance: 1.85 miles 5. Location ID 162: - 106717 trips | Avg fare: $22.88 | Avg distance: 2.23 miles + 106717 trips | Avg fare: $22.88 | Avg distance: 2.23 miles 6. Location ID 230: - 106324 trips | Avg fare: $26.27 | Avg distance: 2.91 miles + 106324 trips | Avg fare: $26.27 | Avg distance: 2.91 miles 7. Location ID 186: - 104523 trips | Avg fare: $23.64 | Avg distance: 2.27 miles + 104523 trips | Avg fare: $23.64 | Avg distance: 2.27 miles 8. Location ID 142: - 104080 trips | Avg fare: $21 | Avg distance: 2.09 miles + 104080 trips | Avg fare: $21 | Avg distance: 2.09 miles 9. Location ID 138: - 89533 trips | Avg fare: $65.01 | Avg distance: 9.59 miles + 89533 trips | Avg fare: $65.01 | Avg distance: 9.59 miles 10. Location ID 239: - 88474 trips | Avg fare: $20.93 | Avg distance: 2.26 miles + 88474 trips | Avg fare: $20.93 | Avg distance: 2.26 miles -⏱️ Execution time: 9.00ms +Execution time: 9.00ms ============================================================ -💳 Query 4: Payment Type Distribution +Query 4: Payment Type Distribution Using .sqlJson() - HTTP transport for simpler integration Payment type breakdown: 1. Credit card (Type 1): - 2,319,046 trips | Avg amount: $28.26 | Avg tip: $4.17 + 2,319,046 trips | Avg amount: $28.26 | Avg tip: $4.17 2. Cash (Type 2): - 439,191 trips | Avg amount: $22.88 | Avg tip: $0 + 439,191 trips | Avg amount: $22.88 | Avg tip: $0 3. Dispute (Type 4): - 46,628 trips | Avg amount: $1.77 | Avg tip: $0.04 + 46,628 trips | Avg amount: $1.77 | Avg tip: $0.04 4. No charge (Type 3): - 19,597 trips | Avg amount: $8.76 | Avg tip: $0.01 + 19,597 trips | Avg amount: $8.76 | Avg tip: $0.01 -⏱️ Execution time: 17.14ms +Execution time: 17.14ms ============================================================ -🔢 Query 5: Parametrized Query - Trips by Distance Range +Query 5: Parametrized Query - Trips by Distance Range Using .sql() with parameters for safe, dynamic queries @@ -190,77 +165,94 @@ Trips with distance between 5 and 10 miles: 4. 7.93 miles - $297.75 total - $0.00 tip - 1 passenger(s) 5. 7.18 miles - $282.75 total - $5.00 tip - 1 passenger(s) -⏱️ Execution time: 8.91ms +Execution time: 8.91ms -💡 Parameters used: $1=5, $2=10, $3=5 +Parameters used: $1=5, $2=10, $3=5 ============================================================ -📝 Method Comparison: +Method Comparison: -• .sql() - Uses Apache Arrow Flight (gRPC) - ✓ Higher performance and efficiency - ✓ Better for large datasets and high-throughput applications - ✓ Returns Arrow Tables (columnar format) - ✓ Supports parametrized queries ($1, $2, ... placeholders) - ⚠️ Works in true Node.js runtimes (local Node.js, Lambda) +.sql() - Uses Apache Arrow Flight (gRPC) + - Higher performance and efficiency + - Better for large datasets and high-throughput applications + - Returns Arrow Tables (columnar format) + - Supports parametrized queries ($1, $2, ... placeholders) + - Works in true Node.js runtimes (local Node.js, Lambda) -• .sqlJson() - Uses HTTP - ✓ Simpler integration, works everywhere HTTP does - ✓ Better for smaller queries and web applications - ✓ Returns plain JavaScript objects (easier to work with) - ✓ Works in browsers, Vercel, Netlify, and sandbox environments +.sqlJson() - Uses HTTP + - Simpler integration, works everywhere HTTP does + - Better for smaller queries and web applications + - Returns plain JavaScript objects (easier to work with) + - Works in browsers, Vercel, Netlify, and sandbox environments ============================================================ -✅ Analysis complete! +Analysis complete! ``` -## Code Examples +## Optional: Minimal Cloud-Only Script -### Connecting to Spice +```bash +node index_cloud.mjs +``` -```javascript -const { SpiceClient } = require('@spiceai/spice'); +Expected output is a table list from `show tables;`. -// Option 1: Spice.ai Cloud (with API key) -const spiceCloud = new SpiceClient('your_api_key'); +## Advanced and More -// Option 2: Local Spice Runtime (default: localhost:50051) -const spiceLocal = new SpiceClient(); -``` +### Features + +- Dual mode support: local Spice runtime and Spice.ai Cloud. +- Uses both `.sql()` and `.sqlJson()` query methods. +- Includes five analytics query examples over `taxi_trips`. -### Querying Data +### Detailed Cloud Setup -The SDK provides two query methods: +1. Create a free account at [spice.ai](https://spice.ai). +2. Create a Spice.ai Cloud app. +3. Deploy this sample's `spicepod.yaml` to your Cloud app. +4. Set `SPICE_API_KEY`, then replace the API key placeholder in `index_cloud.mjs` with that value. +5. Run `node index_cloud.mjs`. -**`.sql()` - Apache Arrow Flight (gRPC)** +### Code Examples -- Higher performance and efficiency -- Better for large datasets and high-throughput applications -- Returns Apache Arrow Tables (columnar format) -- Works in Node.js, AWS Lambda, and other server environments +Connect to Spice: ```javascript -const result = await spice.sql('SELECT * FROM taxi_trips LIMIT 10'); -const data = result.toArray(); +const { SpiceClient } = require("@spiceai/spice"); + +// Cloud +const spiceCloud = new SpiceClient({ apiKey: process.env.SPICE_API_KEY }); + +// Local (default localhost runtime) +const spiceLocal = new SpiceClient(); ``` -**`.sqlJson()` - HTTP/REST** +Query with `.sql()` (Arrow Flight / gRPC): -- Simpler integration, works everywhere HTTP does -- Better for smaller queries and web applications -- Returns plain JavaScript objects -- Works in browsers, Vercel, Netlify, and edge functions +```javascript +const result = await spice.sql("SELECT * FROM taxi_trips LIMIT 10"); +const rows = result.toArray(); +``` + +Query with `.sqlJson()` (HTTP): ```javascript -const result = await spice.sqlJson('SELECT * FROM taxi_trips LIMIT 10'); -const data = result.data; +const result = await spice.sqlJson("SELECT * FROM taxi_trips LIMIT 10"); +const rows = result.data; ``` -## About the Dataset +### About the Dataset + +This sample uses the NYC `taxi_trips` dataset. + +- Local mode: dataset is defined in `spicepod.yaml` and loads with `spice run`. +- Cloud mode: deploy `spicepod.yaml` to your Cloud app before running queries. -This sample uses the NYC taxi_trips dataset, which contains real taxi trip data including fares, distances, pickup/dropoff times, and locations. +## Links -- **Local**: The dataset is defined in `spicepod.yaml` and will be loaded automatically when you run `spice run` -- **Cloud**: Manually deploy `spicepod.yaml` to Spice Cloud through the web interface. See the [Getting Started Guide](https://docs.spice.ai/getting-started/get-started) for help. +- [spice.js SDK](https://github.com/spiceai/spice.js) +- [npm package](https://www.npmjs.com/package/@spiceai/spice) +- [Spice.ai Cloud](https://spice.ai) +- [Spice.ai documentation](https://docs.spiceai.org) diff --git a/client-sdk/spicepy-sdk-sample/README.md b/client-sdk/spicepy-sdk-sample/README.md index 213236ba..ffed3287 100644 --- a/client-sdk/spicepy-sdk-sample/README.md +++ b/client-sdk/spicepy-sdk-sample/README.md @@ -1,29 +1,38 @@ # Spice with spicepy SDK -This recipe demonstrates how to use the Spice Python SDK to connect to a Spice runtime and query data. +Use [spicepy](https://github.com/spiceai/spicepy) to query Spice from Python. + +## What This Sample Includes + +- `sample.py`: Query a local Spice runtime, including a parameterized query. +- `main_cloud.py`: Query Spice.ai Cloud with inline replacement values. ## Prerequisites -This recipe requires [uv](https://docs.astral.sh/uv/) to be installed. +- [uv](https://docs.astral.sh/uv/) +- [Spice CLI](https://docs.spiceai.org/getting-started) for local mode -- Install `uv` with: - - macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh` - - Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` +Install `uv` if needed: -Navigate to `spicepy-sdk-sample`: +- macOS/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh` +- Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"` -```shell -git clone https://github.com/spiceai/cookbook # skip if already cloned +## Local Quick Start + +```bash +git clone https://github.com/spiceai/cookbook.git cd cookbook/client-sdk/spicepy-sdk-sample ``` -## Start spice runtime +Start Spice runtime in one terminal: -```shell +```bash spice run ``` -```shell +Sample runtime logs: + +```text 2025/01/27 11:53:58 INFO Checking for latest Spice runtime release... 2025/01/27 11:54:01 INFO Spice.ai runtime starting... 2025-01-27T19:54:01.956890Z INFO runtime::init::dataset: Initializing dataset taxi_trips @@ -37,16 +46,15 @@ spice run 2025-01-27T19:54:13.743056Z INFO runtime::accelerated_table::refresh_task: Loaded 2,964,624 rows (399.41 MiB) for dataset taxi_trips in 10s 874ms. ``` -## Run sample application +Run the Python sample in another terminal: -```shell +```bash uv run sample.py ``` -Results: +Sample output: -```shell -➜ uv run sample.py +```text === Using query === VendorID: 1, tpep_pickup_datetime: 2024-01-11 09:37:05, fare_amount: 7.9 VendorID: 1, tpep_pickup_datetime: 2024-01-11 09:50:21, fare_amount: 8.6 @@ -66,3 +74,26 @@ VendorID: 2, tpep_pickup_datetime: 2024-01-25 22:14:50, fare_amount: 31.0 VendorID: 2, tpep_pickup_datetime: 2024-01-25 22:52:11, fare_amount: 21.9 VendorID: 1, tpep_pickup_datetime: 2024-01-25 22:06:02, fare_amount: 13.5 ``` + +## Spice.ai Cloud Quick Start + +Set your API key for the commands in this README: + +```bash +export SPICE_API_KEY="your_api_key" +``` + +The cloud snippet keeps an inline API key placeholder by design. Replace the API key placeholder in `main_cloud.py` with `${SPICE_API_KEY}`, then run: + +```bash +uv run main_cloud.py +``` + +Expected output is a table list from `show tables;`. + +## Links + +- [spicepy SDK](https://github.com/spiceai/spicepy) +- [PyPI package](https://pypi.org/project/spicepy/) +- [Spice.ai Cloud](https://spice.ai) +- [Spice.ai documentation](https://docs.spiceai.org)