Skip to main content
Version: Latest (v2.3)

Getting Started with Spice.ai OSS

Follow these steps to get started with Spice​

Download the latest version of Spice, connect to a dataset in S3, and query it with SQL, in less than 5 minutes. No AI model or model provider API key is required. An optional section at the end shows how to add an AI model and chat with the data using an OpenAI, Anthropic, or xAI API key.

Step 1. Install the Spice CLI:

Install Script​

curl https://install.spiceai.org | /bin/bash

Homebrew​

brew install spiceai/spiceai/spice

Step 2. Initialize a new Spice app with the spice init command:

spice init spice_qs

A spicepod.yaml file is created in the spice_qs directory. Change to that directory:

cd spice_qs

Step 3. Add the spiceai/quickstart Spicepod. A Spicepod is a package of configuration defining datasets and ML models.

spice add spiceai/quickstart

The spicepod.yaml file will be updated with the spiceai/quickstart dependency. This Spicepod includes a taxi_trips dataset sourced from S3.

version: v1
kind: Spicepod
name: spice_qs
dependencies:
  - spiceai/quickstart

Step 4. Start the Spice runtime:

spice run

The runtime starts and loads the taxi_trips dataset. Wait for the dataset to finish loading before querying:

Spice.ai runtime starting...
2024-08-05T13:02:40.247484Z  INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
2024-08-05T13:02:40.247949Z  INFO runtime: Initialized results cache; max size: 128.00 MiB, item ttl: 1s
2024-08-05T13:02:40.248611Z  INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090

Step 5. In a second terminal, start the Spice SQL REPL:

spice sql

The SQL REPL interface will be shown:

Welcome to the Spice.ai SQL REPL! Type 'help' for help.

show tables; -- list available tables
sql>

Enter show tables; to display the available tables for query:

sql> show tables
+---------------+--------------+---------------+------------+
| table_catalog | table_schema | table_name    | table_type |
+---------------+--------------+---------------+------------+
| spice         | public       | taxi_trips    | BASE TABLE |
| spice         | runtime      | task_history  | BASE TABLE |
| spice         | runtime      | metrics       | BASE TABLE |
+---------------+--------------+---------------+------------+

Time: 0.022671708 seconds. 3 rows.

Enter a query to display the longest taxi trips:

sql> SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;

Output:

+---------------+--------------+
| trip_distance | total_amount |
+---------------+--------------+
| 312722.3      | 22.15        |
| 97793.92      | 36.31        |
| 82015.45      | 21.56        |
| 72975.97      | 20.04        |
| 71752.26      | 49.57        |
| 59282.45      | 33.52        |
| 59076.43      | 23.17        |
| 58298.51      | 18.63        |
| 51619.36      | 24.2         |
| 44018.64      | 52.43        |
+---------------+--------------+

Time: 0.045150667 seconds. 10 rows.

Spice is now running and the taxi_trips dataset can be queried with SQL. Continue to Next Steps, or add an AI model to ask questions about the data.

Add an AI model and chat with your data (optional)​

This section is optional. It requires an API key from OpenAI, Anthropic, or xAI. With tools enabled, the model can query the taxi_trips dataset directly to answer questions in the Spice Chat REPL.

Step 6. Add a model to spicepod.yaml for the provider that matches your key, and add the key to a .env file that Spice automatically loads at startup:

models:
  - from: openai:gpt-4o-mini
    name: assistant
    params:
      openai_api_key: ${ env:OPENAI_API_KEY }
      tools: auto
echo "OPENAI_API_KEY=sk-..." > .env

See the OpenAI, Anthropic, and xAI model documentation for the full list of parameters for each provider.

Step 7. Restart the Spice runtime so it loads the .env file and the model. Press Ctrl+C in the terminal running spice run, then start it again:

spice run

Step 8. Start the Spice Chat REPL and ask a question:

$ spice chat
Using model: assistant
chat> How many taxi trips were taken?
A total of 2,964,624 trips were taken according to the dataset.

The model was automatically provided with the taxi_trips dataset and was able to answer the question. The Using model line shows the name of the model from the Spicepod.

Next Steps​

Now that Spice is running, explore the key capabilities: