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 a dataset, and run SQL queries. Optionally add an OpenAI, Anthropic, or xAI model to chat with your data.'
6keywords: [spice.ai, getting started, quickstart, tutorial, install, cli, sql, ai, openai, anthropic, xai]
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 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](#add-an-ai-model) using an OpenAI, Anthropic, or xAI API key.
28
29**Step 1.** Install the Spice CLI:
30
31Requires macOS 14+, Linux with glibc 2.39+ (e.g. Ubuntu 24.04+), or Windows via WSL 2, and `curl`. See [System Requirements](../reference/system_requirements.md).
32
33<Tabs>
34 <TabItem value="default" label="macOS, Linux, and WSL" default>
35 ### Install Script
36
37 ```bash
38 curl https://install.spiceai.org | /bin/bash
39 ```
40
41 ### Homebrew
42
43 ```bash
44 brew install spiceai/spiceai/spice
45 ```
46
47 </TabItem>
48 <TabItem value="windows" label="Windows" default>
49 Use [WSL 2](https://learn.microsoft.com/windows/wsl/install) with Ubuntu 24.04+, and run in the WSL terminal:
50
51 ```bash
52 curl https://install.spiceai.org | /bin/bash
53 ```
54
55 </TabItem>
56</Tabs>
57
58**Step 2.** Initialize a new Spice app with the `spice init` command:
59
60```bash
61spice init spice_qs
62```
63
64A `spicepod.yaml` file is created in the `spice_qs` directory. Change to that directory:
65
66```bash
67cd spice_qs
68```
69
70**Step 3.** Add the `spiceai/quickstart` Spicepod. A Spicepod is a package of configuration defining datasets and ML models.
71
72```bash
73spice add spiceai/quickstart
74```
75
76The `spicepod.yaml` file will be updated with the `spiceai/quickstart` dependency. This Spicepod includes a `taxi_trips` dataset sourced from S3.
77
78```yaml
79version: v2
80kind: Spicepod
81name: spice_qs
82dependencies:
83 - spiceai/quickstart
84```
85
86**Step 4.** Start the Spice runtime:
87
88```bash
89spice run
90```
91
92The runtime starts and loads the `taxi_trips` dataset. Wait for the dataset to finish loading before querying:
93
94```bash
95Spice.ai runtime starting...
962024-08-05T13:02:40.247484Z INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
972024-08-05T13:02:40.247949Z INFO runtime: Initialized results cache; max size: 128.00 MiB, item ttl: 1s
982024-08-05T13:02:40.248611Z INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
99```
100
101**Step 5.** In a second terminal, start the Spice SQL REPL:
102
103```bash
104spice sql
105```
106
107The SQL REPL interface will be shown:
108
109```
110Welcome to the Spice.ai SQL REPL! Type `help` or `?` for commands.
111
112Examples:
113 show tables; -- list available tables
114 describe <table_name>; -- show column types
115 nql <question> -- natural language to SQL (requires a model)
116
117sql>
118```
119
120Enter `show tables;` to display the available tables for query:
121
122```
123sql> show tables;
124+---------------+--------------+--------------+------------+
125| table_catalog | table_schema | table_name | table_type |
126| varchar | varchar | varchar | varchar |
127+---------------+--------------+--------------+------------+
128| spice | runtime | task_history | BASE TABLE |
129| spice | public | taxi_trips | BASE TABLE |
130+---------------+--------------+--------------+------------+
131
132Time: 0.001012917 seconds. 2 rows.
133```
134
135Enter a query to display the longest taxi trips:
136
137```
138sql> SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;
139```
140
141Output:
142
143```
144+---------------+--------------+
145| trip_distance | total_amount |
146| float64 | float64 |
147+---------------+--------------+
148| 312722.3 | 22.15 |
149| 97793.92 | 36.31 |
150| 82015.45 | 21.56 |
151| 72975.97 | 20.04 |
152| 71752.26 | 49.57 |
153| 59282.45 | 33.52 |
154| 59076.43 | 23.17 |
155| 58298.51 | 18.63 |
156| 51619.36 | 24.2 |
157| 44018.64 | 52.43 |
158+---------------+--------------+
159
160Time: 0.001865625 seconds. 10 rows.
161```
162
163Spice is now running and the `taxi_trips` dataset can be queried with SQL. Continue to [Next Steps](#next-steps), or add an AI model to ask questions about the data.
164
165## Add an AI model and chat with your data (optional) {#add-an-ai-model}
166
167This section is optional. It requires an API key from [OpenAI](https://platform.openai.com/), [Anthropic](https://platform.claude.com/), or [xAI](https://console.x.ai/). With tools enabled, the model can query the `taxi_trips` dataset directly to answer questions in the Spice Chat REPL.
168
169**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:
170
171<Tabs>
172 <TabItem value="openai" label="OpenAI" default>
173 ```yaml
174 models:
175 - from: openai:gpt-4o-mini
176 name: assistant
177 params:
178 openai_api_key: ${ env:OPENAI_API_KEY }
179 tools: auto
180 ```
181
182 ```bash
183 echo "OPENAI_API_KEY=sk-..." > .env
184 ```
185
186 </TabItem>
187 <TabItem value="anthropic" label="Anthropic">
188 ```yaml
189 models:
190 - from: anthropic:claude-sonnet-4-6
191 name: assistant
192 params:
193 anthropic_api_key: ${ env:ANTHROPIC_API_KEY }
194 tools: auto
195 ```
196
197 ```bash
198 echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
199 ```
200
201 </TabItem>
202 <TabItem value="xai" label="xAI">
203 ```yaml
204 models:
205 - from: xai:grok-4.3
206 name: assistant
207 params:
208 xai_api_key: ${ env:XAI_API_KEY }
209 tools: auto
210 ```
211
212 ```bash
213 echo "XAI_API_KEY=xai-..." > .env
214 ```
215
216 </TabItem>
217</Tabs>
218
219See the [OpenAI], [Anthropic], and [xAI] model documentation for the full list of parameters for each provider.
220
221[OpenAI]: /docs/components/models/openai
222[Anthropic]: /docs/components/models/anthropic
223[xAI]: /docs/components/models/xai
224
225**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:
226
227```bash
228spice run
229```
230
231**Step 8.** Start the Spice Chat REPL and ask a question:
232
233```bash
234$ spice chat
235Using model: assistant
236chat> How many taxi trips were taken?
237A total of 2,964,624 trips were taken according to the dataset.
238```
239
240The 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.
241
242## Next Steps
243
244Now that Spice is running, explore the key capabilities:
245
246import DocCardList from '@theme/DocCardList'
247
248<DocCardList
249 items={[
250 {
251 type: 'link',
252 label: 'Spicepods',
253 href: '/docs/getting-started/spicepods',
254 description:
255 'Understand the Spicepod configuration format that defines datasets, models, and secrets.'
256 },
257 {
258 type: 'link',
259 label: 'Data Connectors',
260 href: '/docs/components/data-connectors',
261 description: 'Connect to PostgreSQL, MySQL, S3, Snowflake, Databricks, and more.'
262 },
263 {
264 type: 'link',
265 label: 'Data Acceleration',
266 href: '/docs/features/data-acceleration',
267 description: 'Materialize and cache datasets locally for sub-second query performance.'
268 },
269 {
270 type: 'link',
271 label: 'Large Language Models',
272 href: '/docs/features/large-language-models',
273 description: 'Configure AI models with OpenAI-compatible APIs, local serving, and tool use.'
274 },
275 {
276 type: 'link',
277 label: 'Search',
278 href: '/docs/features/search',
279 description: 'Vector, full-text, and hybrid search across structured and unstructured data.'
280 },
281 {
282 type: 'link',
283 label: 'Cookbook',
284 href: 'https://github.com/spiceai/cookbook',
285 description: 'Over 100 recipes demonstrating federated queries, RAG, text-to-SQL, and more.'
286 }
287 ]}
288/>
289
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 a dataset, and run SQL queries. Optionally add an OpenAI, Anthropic, or xAI model to chat with your data.'
6keywords: [spice.ai, getting started, quickstart, tutorial, install, cli, sql, ai, openai, anthropic, xai]
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 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](#add-an-ai-model) using an OpenAI, Anthropic, or xAI API key.
28
29**Step 1.** Install the Spice CLI:
30
31Requires macOS 14+, Linux with glibc 2.39+ (e.g. Ubuntu 24.04+), or Windows via WSL 2, and `curl`. See [System Requirements](../reference/system_requirements.md).
32
33<Tabs>
34 <TabItem value="default" label="macOS, Linux, and WSL" default>
35 ### Install Script
36
37 ```bash
38 curl https://install.spiceai.org | /bin/bash
39 ```
40
41 ### Homebrew
42
43 ```bash
44 brew install spiceai/spiceai/spice
45 ```
46
47 </TabItem>
48 <TabItem value="windows" label="Windows" default>
49 Use [WSL 2](https://learn.microsoft.com/windows/wsl/install) with Ubuntu 24.04+, and run in the WSL terminal:
50
51 ```bash
52 curl https://install.spiceai.org | /bin/bash
53 ```
54
55 </TabItem>
56</Tabs>
57
58**Step 2.** Initialize a new Spice app with the `spice init` command:
59
60```bash
61spice init spice_qs
62```
63
64A `spicepod.yaml` file is created in the `spice_qs` directory. Change to that directory:
65
66```bash
67cd spice_qs
68```
69
70**Step 3.** Add the `spiceai/quickstart` Spicepod. A Spicepod is a package of configuration defining datasets and ML models.
71
72```bash
73spice add spiceai/quickstart
74```
75
76The `spicepod.yaml` file will be updated with the `spiceai/quickstart` dependency. This Spicepod includes a `taxi_trips` dataset sourced from S3.
77
78```yaml
79version: v2
80kind: Spicepod
81name: spice_qs
82dependencies:
83 - spiceai/quickstart
84```
85
86**Step 4.** Start the Spice runtime:
87
88```bash
89spice run
90```
91
92The runtime starts and loads the `taxi_trips` dataset. Wait for the dataset to finish loading before querying:
93
94```bash
95Spice.ai runtime starting...
962024-08-05T13:02:40.247484Z INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
972024-08-05T13:02:40.247949Z INFO runtime: Initialized results cache; max size: 128.00 MiB, item ttl: 1s
982024-08-05T13:02:40.248611Z INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
99```
100
101**Step 5.** In a second terminal, start the Spice SQL REPL:
102
103```bash
104spice sql
105```
106
107The SQL REPL interface will be shown:
108
109```
110Welcome to the Spice.ai SQL REPL! Type `help` or `?` for commands.
111
112Examples:
113 show tables; -- list available tables
114 describe <table_name>; -- show column types
115 nql <question> -- natural language to SQL (requires a model)
116
117sql>
118```
119
120Enter `show tables;` to display the available tables for query:
121
122```
123sql> show tables;
124+---------------+--------------+--------------+------------+
125| table_catalog | table_schema | table_name | table_type |
126| varchar | varchar | varchar | varchar |
127+---------------+--------------+--------------+------------+
128| spice | runtime | task_history | BASE TABLE |
129| spice | public | taxi_trips | BASE TABLE |
130+---------------+--------------+--------------+------------+
131
132Time: 0.001012917 seconds. 2 rows.
133```
134
135Enter a query to display the longest taxi trips:
136
137```
138sql> SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;
139```
140
141Output:
142
143```
144+---------------+--------------+
145| trip_distance | total_amount |
146| float64 | float64 |
147+---------------+--------------+
148| 312722.3 | 22.15 |
149| 97793.92 | 36.31 |
150| 82015.45 | 21.56 |
151| 72975.97 | 20.04 |
152| 71752.26 | 49.57 |
153| 59282.45 | 33.52 |
154| 59076.43 | 23.17 |
155| 58298.51 | 18.63 |
156| 51619.36 | 24.2 |
157| 44018.64 | 52.43 |
158+---------------+--------------+
159
160Time: 0.001865625 seconds. 10 rows.
161```
162
163Spice is now running and the `taxi_trips` dataset can be queried with SQL. Continue to [Next Steps](#next-steps), or add an AI model to ask questions about the data.
164
165## Add an AI model and chat with your data (optional) {#add-an-ai-model}
166
167This section is optional. It requires an API key from [OpenAI](https://platform.openai.com/), [Anthropic](https://platform.claude.com/), or [xAI](https://console.x.ai/). With tools enabled, the model can query the `taxi_trips` dataset directly to answer questions in the Spice Chat REPL.
168
169**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:
170
171<Tabs>
172 <TabItem value="openai" label="OpenAI" default>
173 ```yaml
174 models:
175 - from: openai:gpt-4o-mini
176 name: assistant
177 params:
178 openai_api_key: ${ env:OPENAI_API_KEY }
179 tools: auto
180 ```
181
182 ```bash
183 echo "OPENAI_API_KEY=sk-..." > .env
184 ```
185
186 </TabItem>
187 <TabItem value="anthropic" label="Anthropic">
188 ```yaml
189 models:
190 - from: anthropic:claude-sonnet-4-6
191 name: assistant
192 params:
193 anthropic_api_key: ${ env:ANTHROPIC_API_KEY }
194 tools: auto
195 ```
196
197 ```bash
198 echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
199 ```
200
201 </TabItem>
202 <TabItem value="xai" label="xAI">
203 ```yaml
204 models:
205 - from: xai:grok-4.3
206 name: assistant
207 params:
208 xai_api_key: ${ env:XAI_API_KEY }
209 tools: auto
210 ```
211
212 ```bash
213 echo "XAI_API_KEY=xai-..." > .env
214 ```
215
216 </TabItem>
217</Tabs>
218
219See the [OpenAI], [Anthropic], and [xAI] model documentation for the full list of parameters for each provider.
220
221[OpenAI]: /docs/components/models/openai
222[Anthropic]: /docs/components/models/anthropic
223[xAI]: /docs/components/models/xai
224
225**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:
226
227```bash
228spice run
229```
230
231**Step 8.** Start the Spice Chat REPL and ask a question:
232
233```bash
234$ spice chat
235Using model: assistant
236chat> How many taxi trips were taken?
237A total of 2,964,624 trips were taken according to the dataset.
238```
239
240The 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.
241
242## Next Steps
243
244Now that Spice is running, explore the key capabilities:
245
246import DocCardList from '@theme/DocCardList'
247
248<DocCardList
249 items={[
250 {
251 type: 'link',
252 label: 'Spicepods',
253 href: '/docs/getting-started/spicepods',
254 description:
255 'Understand the Spicepod configuration format that defines datasets, models, and secrets.'
256 },
257 {
258 type: 'link',
259 label: 'Data Connectors',
260 href: '/docs/components/data-connectors',
261 description: 'Connect to PostgreSQL, MySQL, S3, Snowflake, Databricks, and more.'
262 },
263 {
264 type: 'link',
265 label: 'Data Acceleration',
266 href: '/docs/features/data-acceleration',
267 description: 'Materialize and cache datasets locally for sub-second query performance.'
268 },
269 {
270 type: 'link',
271 label: 'Large Language Models',
272 href: '/docs/features/large-language-models',
273 description: 'Configure AI models with OpenAI-compatible APIs, local serving, and tool use.'
274 },
275 {
276 type: 'link',
277 label: 'Search',
278 href: '/docs/features/search',
279 description: 'Vector, full-text, and hybrid search across structured and unstructured data.'
280 },
281 {
282 type: 'link',
283 label: 'Cookbook',
284 href: 'https://github.com/spiceai/cookbook',
285 description: 'Over 100 recipes demonstrating federated queries, RAG, text-to-SQL, and more.'
286 }
287 ]}
288/>
289