Quickstart

Get up and running with Spice in minutes using the taxi_trips example dataset

Overview

This quickstart guide will walk you through installing Spice, initializing a new app, starting the runtime, and querying your first dataset.

Prerequisites

• macOS, Linux, or Windows operating system
• Terminal or command-line interface

For detailed installation instructions for your platform, see the Installation guide.

Quick Install

macOS/Linux

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

Getting Started

1. Initialize a new Spice app

   Create a new Spice app using the spice init command:

   spice init spice_qs
   

   This creates a spicepod.yaml file in the spice_qs directory. Navigate to that directory:

   cd spice_qs
   
2. Start the Spice runtime

   Start the Spice runtime using the spice run command:

   spice run
   

   You should see output similar to:

   2025/01/20 11:26:10 INFO Spice.ai runtime starting...
   2025-01-20T19:26:10.679068Z  INFO runtime::init::dataset: No datasets were configured. If this is unexpected, check the Spicepod configuration.
   2025-01-20T19:26:10.679716Z  INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
   2025-01-20T19:26:10.679786Z  INFO runtime::metrics_server: Spice Runtime Metrics listening on 127.0.0.1:9090
   2025-01-20T19:26:10.680140Z  INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
   2025-01-20T19:26:10.879126Z  INFO runtime::init::results_cache: Initialized sql results cache; max size: 128.00 MiB, item ttl: 1s
   

   The runtime is now started and ready for queries on:

   • HTTP: 127.0.0.1:8090
   • Arrow Flight: 127.0.0.1:50051
   • Metrics: 127.0.0.1:9090
3. Add a dataset

   In a new terminal window, 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:

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

   The spiceai/quickstart Spicepod adds a taxi_trips data table to the runtime. In your runtime terminal, you’ll see:

   2025-01-20T19:26:30.011633Z  INFO runtime::init::dataset: Dataset taxi_trips registered (s3://spiceai-demo-datasets/taxi_trips/2024/), acceleration (arrow), results cache enabled.
   2025-01-20T19:26:30.013002Z  INFO runtime::accelerated_table::refresh_task: Loading data for dataset taxi_trips
   2025-01-20T19:26:40.312839Z  INFO runtime::accelerated_table::refresh_task: Loaded 2,964,624 rows (399.41 MiB) for dataset taxi_trips in 10s 299ms
   
4. Query the dataset

   Start the Spice SQL REPL:

   spice sql
   

   You’ll see the SQL REPL interface:

   Welcome to the Spice.ai SQL REPL! Type 'help' for help.
   
   show tables; -- list available tables
   sql>
   

   List the available tables:

   show tables;
   

   Output:

   +---------------+--------------+---------------+------------+
   | table_catalog | table_schema | table_name    | table_type |
   +---------------+--------------+---------------+------------+
   | spice         | public       | taxi_trips    | BASE TABLE |
   | spice         | runtime      | query_history | BASE TABLE |
   | spice         | runtime      | metrics       | BASE TABLE |
   +---------------+--------------+---------------+------------+
   
   Time: 0.022671708 seconds. 3 rows.
   

   Query the longest taxi trips:

   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.
   

Runtime Container Deployment

Spice can also be deployed as a container for production use.

Docker Pull

docker pull spiceai/spiceai

Next Steps

Explore the Cookbook

Over 45 quickstarts and samples showing how to use Spice with various data sources and AI models.

Documentation

Comprehensive documentation covering all features, connectors, and APIs.

Data Connectors

Learn about the 30+ supported data connectors including PostgreSQL, MySQL, S3, Databricks, and more.

Data Accelerators

Understand how to accelerate your queries with Arrow, DuckDB, SQLite, PostgreSQL, or Cayenne.

Using Spice.ai Cloud Platform

Spice also integrates with the Spice.ai Cloud Platform for hosted datasets and models. Create a free account at spice.ai and use the spice login command to authenticate.