# Connecting Data

## Overview

Spice.ai supports [federated SQL queries](https://github.com/spicehq/docs/blob/trunk/features/federated-sql-query.md) across a wide range of data sources. Data connectors let you query external data directly or replicate it into Spice for accelerated access.

For the full list of connectors and configuration options, see [Data Connectors](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/README.md).

## Supported Data Sources

| Category                 | Connectors                                                                                                                                                                                                                                                                                                                                                                                               |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Relational databases** | [PostgreSQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/postgres.md), [MySQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/mysql.md), [MSSQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/mssql.md), [ClickHouse](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/clickhouse.md) |
| **Data warehouses**      | [Snowflake](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/snowflake.md), [Databricks](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/databricks.md), [Dremio](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/dremio.md)                                                                                             |
| **Data lakes & formats** | [S3](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/s3.md), [Delta Lake](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/delta-lake.md), [ABFS](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/abfs.md)                                                                                                               |
| **APIs & other**         | [GraphQL](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/graphql.md), [GitHub](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/github.md), [SharePoint](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/sharepoint.md)                                                                                                 |
| **Streaming**            | [Debezium CDC](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/debezium.md)                                                                                                                                                                                                                                                                                                   |
| **Embedded / local**     | [DuckDB](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/duckdb.md), [SQLite](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/ftp.md)                                                                                                                                                                                                              |

## Adding a Data Source

### 1. Store credentials as secrets

Data source credentials should be stored as [secrets](https://github.com/spicehq/docs/blob/trunk/portal/apps/secrets.md) in your app. In the Portal, go to your app → **Secrets** and create entries for connection strings, access keys, or tokens.

{% hint style="info" %}
Secret values are write-only and cannot be retrieved after saving.
{% endhint %}

### 2. Configure the dataset in your Spicepod

Add a dataset entry to your app's `spicepod.yaml` referencing the connector and secrets:

```yaml
datasets:
  - from: postgres:my_schema.my_table
    name: my_table
    params:
      pg_host: my-database.example.com
      pg_port: "5432"
      pg_db: my_database
      pg_user: "${secrets:PG_USER}"
      pg_pass: "${secrets:PG_PASS}"
```

### 3. Deploy

Commit and deploy your app to make the dataset available for querying.

## Data Acceleration

For faster queries, enable [data acceleration](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/README.md) to cache datasets in a local engine:

```yaml
datasets:
  - from: postgres:my_schema.my_table
    name: my_table
    acceleration:
      engine: arrow  # or duckdb, sqlite, postgres
      refresh_interval: 10m
```

Available acceleration engines:

* [Arrow](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/in-memory-arrow-data-accelerator.md) — In-memory, fastest performance.
* [DuckDB](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/duckdb-data-accelerator.md) — Embedded analytical engine.
* [SQLite](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/sqlite-data-accelerator.md) — Lightweight, persistent.
* [PostgreSQL](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/postgresql-data-accelerator.md) — Full-featured relational engine.

## Common Issues

### Table not found

Spice normalizes unquoted SQL identifiers to **lowercase** (PostgreSQL-style). If your source uses mixed-case table or column names, double-quote them:

```sql
SELECT "ColumnName" FROM "MySchema"."MyTable"
```

### Object store file format errors

When connecting to object stores (S3, ABFS):

* **Folder paths** require an explicit `file_format` (e.g., `parquet`, `csv`).
* **Single file paths** auto-detect the format from the file extension.

### Schema changes break data refresh

Spice infers the schema at deployment time. If the source schema changes, refresh will fail. **Redeploy the app** to pick up the new schema.

### Connection failures

* Confirm the data source is network-accessible from Spice.ai Cloud (firewalls, IP allowlists).
* Verify secrets are correct and referenced with `${secrets:SECRET_NAME}` syntax.
* Check connector-specific docs for required parameters.

## Further Reading

* [Data Connectors reference](https://github.com/spicehq/docs/blob/trunk/building-blocks/data-connectors/README.md)
* [Data Acceleration](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/README.md)
* [Federated SQL Query](https://github.com/spicehq/docs/blob/trunk/features/federated-sql-query.md)
* [Catalogs](https://github.com/spicehq/docs/blob/trunk/building-blocks/catalogs/index.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spice.ai/help/connecting-data.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.