1---
2title: 'Getting Started with Spice.ai OSS'
3sidebar_label: 'Getting started'
4sidebar_position: 1
5description: 'Get started with Spice.ai in 5 minutes. Install the CLI, connect to datasets, run SQL queries, and use AI models with OpenAI-compatible APIs.'
6keywords: [spice.ai, getting started, quickstart, tutorial, install, cli, sql, ai, openai]
7image: /img/og/getting-started.png
8pagination_next: null
9---
10
11import Tabs from '@theme/Tabs'
12import TabItem from '@theme/TabItem'
13
14<div style={{ display: 'flex', justifyContent: 'center', marginBottom: '15px' }}>
15  <iframe
16    width='640'
17    height='360'
18    src='https://www.youtube.com/embed/yAIyjb1RxX4'
19    frameBorder='0'
20    allow='accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture'
21    allowFullScreen
22  />
23</div>
24
25### Follow these steps to get started with Spice
26
27Download the latest version of Spice, connect to a dataset in S3, and ask questions about the data using AI, in less than 5 minutes.
28
29**Step 1.** Install the Spice CLI:
30
31<Tabs>
32  <TabItem value="default" label="macOS, Linux, and WSL" default>
33    ### Install Script
34
35    ```bash
36    curl https://install.spiceai.org | /bin/bash
37    ```
38
39    ### Homebrew
40
41    ```bash
42    brew install spiceai/spiceai/spice
43    ```
44
45  </TabItem>
46  <TabItem value="windows" label="Windows" default>
47    ### PowerShell Install Script
48
49    ```bash
50    iex ((New-Object System.Net.WebClient).DownloadString("https://install.spiceai.org/Install.ps1"))
51    ```
52
53  </TabItem>
54</Tabs>
55
56**Step 2.** Initialize a new Spice app with the `spice init` command:
57
58```bash
59spice init spice_qs
60```
61
62A `spicepod.yaml` file is created in the `spice_qs` directory. Change to that directory:
63
64```bash
65cd spice_qs
66```
67
68**Step 3.** Add the `spiceai/quickstart` Spicepod. A Spicepod is a package of configuration defining datasets and ML models.
69
70```bash
71spice add spiceai/quickstart
72```
73
74The `spicepod.yaml` file will be updated with the `spiceai/quickstart` dependency. This Spicepod includes a `taxi_trips` dataset sourced from S3.
75
76```yaml
77version: v1
78kind: Spicepod
79name: spice_qs
80dependencies:
81  - spiceai/quickstart
82```
83
84**Step 4.** Add an [OpenAI] model to the Spicepod with tools enabled, so the model can query the `taxi_trips` dataset directly:
85
86[OpenAI]: /docs/components/models/openai
87
88```yaml
89models:
90  - from: openai:gpt-4o-mini
91    name: openai_model
92    params:
93      openai_api_key: ${ env:OPENAI_API_KEY }
94      tools: auto
95```
96
97Add your OpenAI API key to a `.env` file that Spice automatically loads at startup:
98
99```bash
100echo "OPENAI_API_KEY=sk-..." > .env
101```
102
103Start the Spice runtime:
104
105```bash
106spice run
107```
108
109The runtime starts and loads the `taxi_trips` dataset. Wait for the dataset to finish loading before querying:
110
111```bash
112Spice.ai runtime starting...
1132024-08-05T13:02:40.247484Z  INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
1142024-08-05T13:02:40.247949Z  INFO runtime: Initialized results cache; max size: 128.00 MiB, item ttl: 1s
1152024-08-05T13:02:40.248611Z  INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
116```
117
118**Step 5.** Start the Spice Chat REPL and ask a question:
119
120```bash
121$ spice chat
122Using model: openai_model
123chat> How many taxi trips were taken?
124A total of 2,964,624 trips were taken according to the dataset.
125```
126
127The OpenAI model was automatically provided with the `taxi_trips` dataset and was able to answer the question.
128
129**Step 6.** Start the Spice SQL REPL:
130
131```bash
132spice sql
133```
134
135The SQL REPL inferface will be shown:
136
137```
138Welcome to the Spice.ai SQL REPL! Type 'help' for help.
139
140show tables; -- list available tables
141sql>
142```
143
144Enter `show tables;` to display the available tables for query:
145
146```
147sql> show tables
148+---------------+--------------+---------------+------------+
149| table_catalog | table_schema | table_name    | table_type |
150+---------------+--------------+---------------+------------+
151| spice         | public       | taxi_trips    | BASE TABLE |
152| spice         | runtime      | task_history  | BASE TABLE |
153| spice         | runtime      | metrics       | BASE TABLE |
154+---------------+--------------+---------------+------------+
155
156Time: 0.022671708 seconds. 3 rows.
157```
158
159Enter a query to display the longest taxi trips:
160
161```
162sql> SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;
163```
164
165Output:
166
167```
168+---------------+--------------+
169| trip_distance | total_amount |
170+---------------+--------------+
171| 312722.3      | 22.15        |
172| 97793.92      | 36.31        |
173| 82015.45      | 21.56        |
174| 72975.97      | 20.04        |
175| 71752.26      | 49.57        |
176| 59282.45      | 33.52        |
177| 59076.43      | 23.17        |
178| 58298.51      | 18.63        |
179| 51619.36      | 24.2         |
180| 44018.64      | 52.43        |
181+---------------+--------------+
182
183Time: 0.045150667 seconds. 10 rows.
184```
185
186## Next Steps
187
188Now that Spice is running, explore the key capabilities:
189
190import DocCardList from '@theme/DocCardList'
191
192<DocCardList
193  items={[
194    {
195      type: 'link',
196      label: 'Spicepods',
197      href: '/docs/getting-started/spicepods',
198      description: 'Understand the Spicepod configuration format that defines datasets, models, and secrets.'
199    },
200    {
201      type: 'link',
202      label: 'Data Connectors',
203      href: '/docs/components/data-connectors',
204      description: 'Connect to PostgreSQL, MySQL, S3, Snowflake, Databricks, and more.'
205    },
206    {
207      type: 'link',
208      label: 'Data Acceleration',
209      href: '/docs/features/data-acceleration',
210      description: 'Materialize and cache datasets locally for sub-second query performance.'
211    },
212    {
213      type: 'link',
214      label: 'Large Language Models',
215      href: '/docs/features/large-language-models',
216      description: 'Configure AI models with OpenAI-compatible APIs, local serving, and tool use.'
217    },
218    {
219      type: 'link',
220      label: 'Search',
221      href: '/docs/features/search',
222      description: 'Vector, full-text, and hybrid search across structured and unstructured data.'
223    },
224    {
225      type: 'link',
226      label: 'Cookbook',
227      href: 'https://github.com/spiceai/cookbook',
228      description: 'Over 65 recipes demonstrating federated queries, RAG, text-to-SQL, and more.'
229    }
230  ]}
231/>
232

1---
2title: 'Getting Started with Spice.ai OSS'
3sidebar_label: 'Getting started'
4sidebar_position: 1
5description: 'Get started with Spice.ai in 5 minutes. Install the CLI, connect to datasets, run SQL queries, and use AI models with OpenAI-compatible APIs.'
6keywords: [spice.ai, getting started, quickstart, tutorial, install, cli, sql, ai, openai]
7image: /img/og/getting-started.png
8pagination_next: null
9---
10
11import Tabs from '@theme/Tabs'
12import TabItem from '@theme/TabItem'
13
14<div style={{ display: 'flex', justifyContent: 'center', marginBottom: '15px' }}>
15  <iframe
16    width='640'
17    height='360'
18    src='https://www.youtube.com/embed/yAIyjb1RxX4'
19    frameBorder='0'
20    allow='accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture'
21    allowFullScreen
22  />
23</div>
24
25### Follow these steps to get started with Spice
26
27Download the latest version of Spice, connect to a dataset in S3, and ask questions about the data using AI, in less than 5 minutes.
28
29**Step 1.** Install the Spice CLI:
30
31<Tabs>
32  <TabItem value="default" label="macOS, Linux, and WSL" default>
33    ### Install Script
34
35    ```bash
36    curl https://install.spiceai.org | /bin/bash
37    ```
38
39    ### Homebrew
40
41    ```bash
42    brew install spiceai/spiceai/spice
43    ```
44
45  </TabItem>
46  <TabItem value="windows" label="Windows" default>
47    ### PowerShell Install Script
48
49    ```bash
50    iex ((New-Object System.Net.WebClient).DownloadString("https://install.spiceai.org/Install.ps1"))
51    ```
52
53  </TabItem>
54</Tabs>
55
56**Step 2.** Initialize a new Spice app with the `spice init` command:
57
58```bash
59spice init spice_qs
60```
61
62A `spicepod.yaml` file is created in the `spice_qs` directory. Change to that directory:
63
64```bash
65cd spice_qs
66```
67
68**Step 3.** Add the `spiceai/quickstart` Spicepod. A Spicepod is a package of configuration defining datasets and ML models.
69
70```bash
71spice add spiceai/quickstart
72```
73
74The `spicepod.yaml` file will be updated with the `spiceai/quickstart` dependency. This Spicepod includes a `taxi_trips` dataset sourced from S3.
75
76```yaml
77version: v1
78kind: Spicepod
79name: spice_qs
80dependencies:
81  - spiceai/quickstart
82```
83
84**Step 4.** Add an [OpenAI] model to the Spicepod with tools enabled, so the model can query the `taxi_trips` dataset directly:
85
86[OpenAI]: /docs/components/models/openai
87
88```yaml
89models:
90  - from: openai:gpt-4o-mini
91    name: openai_model
92    params:
93      openai_api_key: ${ env:OPENAI_API_KEY }
94      tools: auto
95```
96
97Add your OpenAI API key to a `.env` file that Spice automatically loads at startup:
98
99```bash
100echo "OPENAI_API_KEY=sk-..." > .env
101```
102
103Start the Spice runtime:
104
105```bash
106spice run
107```
108
109The runtime starts and loads the `taxi_trips` dataset. Wait for the dataset to finish loading before querying:
110
111```bash
112Spice.ai runtime starting...
1132024-08-05T13:02:40.247484Z  INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
1142024-08-05T13:02:40.247949Z  INFO runtime: Initialized results cache; max size: 128.00 MiB, item ttl: 1s
1152024-08-05T13:02:40.248611Z  INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
116```
117
118**Step 5.** Start the Spice Chat REPL and ask a question:
119
120```bash
121$ spice chat
122Using model: openai_model
123chat> How many taxi trips were taken?
124A total of 2,964,624 trips were taken according to the dataset.
125```
126
127The OpenAI model was automatically provided with the `taxi_trips` dataset and was able to answer the question.
128
129**Step 6.** Start the Spice SQL REPL:
130
131```bash
132spice sql
133```
134
135The SQL REPL inferface will be shown:
136
137```
138Welcome to the Spice.ai SQL REPL! Type 'help' for help.
139
140show tables; -- list available tables
141sql>
142```
143
144Enter `show tables;` to display the available tables for query:
145
146```
147sql> show tables
148+---------------+--------------+---------------+------------+
149| table_catalog | table_schema | table_name    | table_type |
150+---------------+--------------+---------------+------------+
151| spice         | public       | taxi_trips    | BASE TABLE |
152| spice         | runtime      | task_history  | BASE TABLE |
153| spice         | runtime      | metrics       | BASE TABLE |
154+---------------+--------------+---------------+------------+
155
156Time: 0.022671708 seconds. 3 rows.
157```
158
159Enter a query to display the longest taxi trips:
160
161```
162sql> SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;
163```
164
165Output:
166
167```
168+---------------+--------------+
169| trip_distance | total_amount |
170+---------------+--------------+
171| 312722.3      | 22.15        |
172| 97793.92      | 36.31        |
173| 82015.45      | 21.56        |
174| 72975.97      | 20.04        |
175| 71752.26      | 49.57        |
176| 59282.45      | 33.52        |
177| 59076.43      | 23.17        |
178| 58298.51      | 18.63        |
179| 51619.36      | 24.2         |
180| 44018.64      | 52.43        |
181+---------------+--------------+
182
183Time: 0.045150667 seconds. 10 rows.
184```
185
186## Next Steps
187
188Now that Spice is running, explore the key capabilities:
189
190import DocCardList from '@theme/DocCardList'
191
192<DocCardList
193  items={[
194    {
195      type: 'link',
196      label: 'Spicepods',
197      href: '/docs/getting-started/spicepods',
198      description: 'Understand the Spicepod configuration format that defines datasets, models, and secrets.'
199    },
200    {
201      type: 'link',
202      label: 'Data Connectors',
203      href: '/docs/components/data-connectors',
204      description: 'Connect to PostgreSQL, MySQL, S3, Snowflake, Databricks, and more.'
205    },
206    {
207      type: 'link',
208      label: 'Data Acceleration',
209      href: '/docs/features/data-acceleration',
210      description: 'Materialize and cache datasets locally for sub-second query performance.'
211    },
212    {
213      type: 'link',
214      label: 'Large Language Models',
215      href: '/docs/features/large-language-models',
216      description: 'Configure AI models with OpenAI-compatible APIs, local serving, and tool use.'
217    },
218    {
219      type: 'link',
220      label: 'Search',
221      href: '/docs/features/search',
222      description: 'Vector, full-text, and hybrid search across structured and unstructured data.'
223    },
224    {
225      type: 'link',
226      label: 'Cookbook',
227      href: 'https://github.com/spiceai/cookbook',
228      description: 'Over 65 recipes demonstrating federated queries, RAG, text-to-SQL, and more.'
229    }
230  ]}
231/>
232