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
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.** Start the Spice runtime:
85
86```bash
87spice run
88```
89
90The runtime starts and loads the `taxi_trips` dataset. Wait for the dataset to finish loading before querying:
91
92```bash
93Spice.ai runtime starting...
942024-08-05T13:02:40.247484Z  INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
952024-08-05T13:02:40.247949Z  INFO runtime: Initialized results cache; max size: 128.00 MiB, item ttl: 1s
962024-08-05T13:02:40.248611Z  INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
97```
98
99**Step 5.** In a second terminal, start the Spice SQL REPL:
100
101```bash
102spice sql
103```
104
105The SQL REPL interface will be shown:
106
107```
108Welcome to the Spice.ai SQL REPL! Type 'help' for help.
109
110show tables; -- list available tables
111sql>
112```
113
114Enter `show tables;` to display the available tables for query:
115
116```
117sql> show tables
118+---------------+--------------+---------------+------------+
119| table_catalog | table_schema | table_name    | table_type |
120+---------------+--------------+---------------+------------+
121| spice         | public       | taxi_trips    | BASE TABLE |
122| spice         | runtime      | task_history  | BASE TABLE |
123| spice         | runtime      | metrics       | BASE TABLE |
124+---------------+--------------+---------------+------------+
125
126Time: 0.022671708 seconds. 3 rows.
127```
128
129Enter a query to display the longest taxi trips:
130
131```
132sql> SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;
133```
134
135Output:
136
137```
138+---------------+--------------+
139| trip_distance | total_amount |
140+---------------+--------------+
141| 312722.3      | 22.15        |
142| 97793.92      | 36.31        |
143| 82015.45      | 21.56        |
144| 72975.97      | 20.04        |
145| 71752.26      | 49.57        |
146| 59282.45      | 33.52        |
147| 59076.43      | 23.17        |
148| 58298.51      | 18.63        |
149| 51619.36      | 24.2         |
150| 44018.64      | 52.43        |
151+---------------+--------------+
152
153Time: 0.045150667 seconds. 10 rows.
154```
155
156Spice 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.
157
158## Add an AI model and chat with your data (optional) {#add-an-ai-model}
159
160This 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.
161
162**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:
163
164<Tabs>
165  <TabItem value="openai" label="OpenAI" default>
166    ```yaml
167    models:
168      - from: openai:gpt-4o-mini
169        name: assistant
170        params:
171          openai_api_key: ${ env:OPENAI_API_KEY }
172          tools: auto
173    ```
174
175    ```bash
176    echo "OPENAI_API_KEY=sk-..." > .env
177    ```
178
179  </TabItem>
180  <TabItem value="anthropic" label="Anthropic">
181    ```yaml
182    models:
183      - from: anthropic:claude-sonnet-4-6
184        name: assistant
185        params:
186          anthropic_api_key: ${ env:ANTHROPIC_API_KEY }
187          tools: auto
188    ```
189
190    ```bash
191    echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
192    ```
193
194  </TabItem>
195  <TabItem value="xai" label="xAI">
196    ```yaml
197    models:
198      - from: xai:grok-4.3
199        name: assistant
200        params:
201          xai_api_key: ${ env:XAI_API_KEY }
202          tools: auto
203    ```
204
205    ```bash
206    echo "XAI_API_KEY=xai-..." > .env
207    ```
208
209  </TabItem>
210</Tabs>
211
212See the [OpenAI], [Anthropic], and [xAI] model documentation for the full list of parameters for each provider.
213
214[OpenAI]: /docs/components/models/openai
215[Anthropic]: /docs/components/models/anthropic
216[xAI]: /docs/components/models/xai
217
218**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:
219
220```bash
221spice run
222```
223
224**Step 8.** Start the Spice Chat REPL and ask a question:
225
226```bash
227$ spice chat
228Using model: assistant
229chat> How many taxi trips were taken?
230A total of 2,964,624 trips were taken according to the dataset.
231```
232
233The 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.
234
235## Next Steps
236
237Now that Spice is running, explore the key capabilities:
238
239import DocCardList from '@theme/DocCardList'
240
241<DocCardList
242  items={[
243    {
244      type: 'link',
245      label: 'Spicepods',
246      href: '/docs/getting-started/spicepods',
247      description:
248        'Understand the Spicepod configuration format that defines datasets, models, and secrets.'
249    },
250    {
251      type: 'link',
252      label: 'Data Connectors',
253      href: '/docs/components/data-connectors',
254      description: 'Connect to PostgreSQL, MySQL, S3, Snowflake, Databricks, and more.'
255    },
256    {
257      type: 'link',
258      label: 'Data Acceleration',
259      href: '/docs/features/data-acceleration',
260      description: 'Materialize and cache datasets locally for sub-second query performance.'
261    },
262    {
263      type: 'link',
264      label: 'Large Language Models',
265      href: '/docs/features/large-language-models',
266      description: 'Configure AI models with OpenAI-compatible APIs, local serving, and tool use.'
267    },
268    {
269      type: 'link',
270      label: 'Search',
271      href: '/docs/features/search',
272      description: 'Vector, full-text, and hybrid search across structured and unstructured data.'
273    },
274    {
275      type: 'link',
276      label: 'Cookbook',
277      href: 'https://github.com/spiceai/cookbook',
278      description: 'Over 65 recipes demonstrating federated queries, RAG, text-to-SQL, and more.'
279    }
280  ]}
281/>
282

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
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.** Start the Spice runtime:
85
86```bash
87spice run
88```
89
90The runtime starts and loads the `taxi_trips` dataset. Wait for the dataset to finish loading before querying:
91
92```bash
93Spice.ai runtime starting...
942024-08-05T13:02:40.247484Z  INFO runtime::flight: Spice Runtime Flight listening on 127.0.0.1:50051
952024-08-05T13:02:40.247949Z  INFO runtime: Initialized results cache; max size: 128.00 MiB, item ttl: 1s
962024-08-05T13:02:40.248611Z  INFO runtime::http: Spice Runtime HTTP listening on 127.0.0.1:8090
97```
98
99**Step 5.** In a second terminal, start the Spice SQL REPL:
100
101```bash
102spice sql
103```
104
105The SQL REPL interface will be shown:
106
107```
108Welcome to the Spice.ai SQL REPL! Type 'help' for help.
109
110show tables; -- list available tables
111sql>
112```
113
114Enter `show tables;` to display the available tables for query:
115
116```
117sql> show tables
118+---------------+--------------+---------------+------------+
119| table_catalog | table_schema | table_name    | table_type |
120+---------------+--------------+---------------+------------+
121| spice         | public       | taxi_trips    | BASE TABLE |
122| spice         | runtime      | task_history  | BASE TABLE |
123| spice         | runtime      | metrics       | BASE TABLE |
124+---------------+--------------+---------------+------------+
125
126Time: 0.022671708 seconds. 3 rows.
127```
128
129Enter a query to display the longest taxi trips:
130
131```
132sql> SELECT trip_distance, total_amount FROM taxi_trips ORDER BY trip_distance DESC LIMIT 10;
133```
134
135Output:
136
137```
138+---------------+--------------+
139| trip_distance | total_amount |
140+---------------+--------------+
141| 312722.3      | 22.15        |
142| 97793.92      | 36.31        |
143| 82015.45      | 21.56        |
144| 72975.97      | 20.04        |
145| 71752.26      | 49.57        |
146| 59282.45      | 33.52        |
147| 59076.43      | 23.17        |
148| 58298.51      | 18.63        |
149| 51619.36      | 24.2         |
150| 44018.64      | 52.43        |
151+---------------+--------------+
152
153Time: 0.045150667 seconds. 10 rows.
154```
155
156Spice 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.
157
158## Add an AI model and chat with your data (optional) {#add-an-ai-model}
159
160This 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.
161
162**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:
163
164<Tabs>
165  <TabItem value="openai" label="OpenAI" default>
166    ```yaml
167    models:
168      - from: openai:gpt-4o-mini
169        name: assistant
170        params:
171          openai_api_key: ${ env:OPENAI_API_KEY }
172          tools: auto
173    ```
174
175    ```bash
176    echo "OPENAI_API_KEY=sk-..." > .env
177    ```
178
179  </TabItem>
180  <TabItem value="anthropic" label="Anthropic">
181    ```yaml
182    models:
183      - from: anthropic:claude-sonnet-4-6
184        name: assistant
185        params:
186          anthropic_api_key: ${ env:ANTHROPIC_API_KEY }
187          tools: auto
188    ```
189
190    ```bash
191    echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
192    ```
193
194  </TabItem>
195  <TabItem value="xai" label="xAI">
196    ```yaml
197    models:
198      - from: xai:grok-4.3
199        name: assistant
200        params:
201          xai_api_key: ${ env:XAI_API_KEY }
202          tools: auto
203    ```
204
205    ```bash
206    echo "XAI_API_KEY=xai-..." > .env
207    ```
208
209  </TabItem>
210</Tabs>
211
212See the [OpenAI], [Anthropic], and [xAI] model documentation for the full list of parameters for each provider.
213
214[OpenAI]: /docs/components/models/openai
215[Anthropic]: /docs/components/models/anthropic
216[xAI]: /docs/components/models/xai
217
218**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:
219
220```bash
221spice run
222```
223
224**Step 8.** Start the Spice Chat REPL and ask a question:
225
226```bash
227$ spice chat
228Using model: assistant
229chat> How many taxi trips were taken?
230A total of 2,964,624 trips were taken according to the dataset.
231```
232
233The 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.
234
235## Next Steps
236
237Now that Spice is running, explore the key capabilities:
238
239import DocCardList from '@theme/DocCardList'
240
241<DocCardList
242  items={[
243    {
244      type: 'link',
245      label: 'Spicepods',
246      href: '/docs/getting-started/spicepods',
247      description:
248        'Understand the Spicepod configuration format that defines datasets, models, and secrets.'
249    },
250    {
251      type: 'link',
252      label: 'Data Connectors',
253      href: '/docs/components/data-connectors',
254      description: 'Connect to PostgreSQL, MySQL, S3, Snowflake, Databricks, and more.'
255    },
256    {
257      type: 'link',
258      label: 'Data Acceleration',
259      href: '/docs/features/data-acceleration',
260      description: 'Materialize and cache datasets locally for sub-second query performance.'
261    },
262    {
263      type: 'link',
264      label: 'Large Language Models',
265      href: '/docs/features/large-language-models',
266      description: 'Configure AI models with OpenAI-compatible APIs, local serving, and tool use.'
267    },
268    {
269      type: 'link',
270      label: 'Search',
271      href: '/docs/features/search',
272      description: 'Vector, full-text, and hybrid search across structured and unstructured data.'
273    },
274    {
275      type: 'link',
276      label: 'Cookbook',
277      href: 'https://github.com/spiceai/cookbook',
278      description: 'Over 65 recipes demonstrating federated queries, RAG, text-to-SQL, and more.'
279    }
280  ]}
281/>
282