Sign in to the Portal with GitHub

Create a Spice app

Add a dataset and query it

Add an AI Model and chat with it

The Spice.ai Cloud Platform is an AI application and agent cloud; an AI-backend-as-a-service comprising of composable, ready-to-use AI and agent building blocks including high-speed SQL query, LLM inference, Vector Search, and RAG built-on cloud-scale, managed Spice.ai OSS.

With the Spice.ai Cloud Platform, powered by Spice.ai OSS, you can:

1. Query and accelerate data: Run high-performance SQL queries across multiple data sources with results optimized for AI applications and agents.

2. Use AI Models: Perform large language model (LLM) inference with major providers including OpenAI, Anthropic, and Grok for chat, completion, and generative AI workflows.

3. Collaborate on : Share, fork, and manage datasets, models, embeddings, evals, and tools in a collaborative, community-driven hub indexed by .

Use-Cases

• Fast, virtualized data views: Build specialized “small data” warehouses to serve fast, virtualized views across large datasets for applications, APIs, dashboards, and analytics.

• Performance and reliability: Manage replicas of hot data, cache SQL queries and AI results, and load-balance AI services to improve resiliency and scalability.

• Production-grade AI workflows: Use Spice.ai Cloud as a data and AI proxy for secure, monitored, and compliant production environments, complete with advanced observability and performance management.

Take it for a spin by starting with the .

Once , you will be redirected to the new application page. Set a name, add a model provider, and optionally select one of ready to use datasets.

1. Enter a name for the application.

2. Optionally choose a model provider, such as OpenAI, and provide an API key.

3. Optionally select one or more of the available datasets. Datasets can also be added later.

Learn more about building AI applications and agents with the Spice.ai Cloud Platform.

From the Spice.ai website

What's the difference between the Spice.ai Cloud Platform and Spice.ai OSS?

Spice.ai OSS is an open-source project created by the Spice AI team that provides a unified SQL query interface to locally materialize, accelerate, and query data tables sourced from any database, data warehouse, or data lake.

The Spice.ai Cloud Platform is a data and AI application platform that provides a set of building-blocks to create AI and agentic applications. Building blocks include a cloud-data-warehouse, ML model training and inference, and a cloud-scale, managed Spice.ai OSS cloud-hosted service.

How much does Spice.ai Cloud cost?

It's free to to use the .

Customers who need resource limits, service-level guarantees, or priority support we offer based on usage.

What level of support do you offer?

We offer enterprise-grade support with an SLA .

For standard plans we offer in Discord.

What's your approach to security and compliance?

See . The Spice.ai Cloud Platform is SOC 2 Type II compliant.

What SQL query engine/dialect do you support?

Spice.ai OSS is built on and uses the PostgreSQL dialect.

To add a dataset to the Spice app, navigate to the tab.

Use the Components sidebar on the right to select from available Data Connectors, Model Providers, and ready-to-use Datasets.

Adding a ready-to-use Dataset

Vector similarity search across disparate and legacy data systems

Enterprises face the challenge of accessing data from various disparate and legacy systems to provide AI with comprehensive context. Speed is crucial for this process to be effective.

Spice offers a fast knowledge index into both structured and unstructured data, enabling efficient vector similarity search across multiple data sources. This ensures that AI applications have access to the necessary data for accurate and timely responses.

Adding a Model Provider

1. Navigate to Code tab.

2. In Components sidebar, click Model Providers tab, and select OpenAI.

3. Enter the Model name.

4. Enter the Model ID, (e.g. gpt-4o).

5. Set the OpenAI API Key secret

   1. API keys and other secrets are securely stored and encrypted.

1. Insert tools: auto in the params section of the gpt-4o Model to automatically connect datasets to the model. The final Spicepod configuration in the editor should be as follows:

1. Click Save in the code toolbar and then Deploy in the popup card that appears in the bottom right to deploy the changes.

2. Navigate to Playground and select AI Chat in the sidebar.

3. Ask a question about the NYC Taxi Trips dataset in the chat. For example:

[Optional] Call chat completions API using cURL

1. Replace [API-KEY] in the sample below with the app API Key and execute in a terminal.

🎉 Congratulations, you've now added an OpenAI model and can use it to ask questions of the NYC Taxi Trips dataset.

Continue to to explore use-cases to do more with the Spice.ai Cloud Platform.

The In-Memory Arrow Data Accelerator is the default data accelerator in Spice. It uses Apache Arrow to store data in-memory for fast access and query performance.

Configuration

To use the In-Memory Arrow Data Accelerator, no additional configuration is required beyond enabling acceleration.

Example:

However Arrow can be specified explicitly using arrow as the engine for acceleration.

The Memory Data Connector enables configuring an in-memory dataset for tables used, or produced by the Spice runtime. Only certain tables, with predefined schemas, can be defined by the connector. These are:

• store: Defines a table that LLMs, with , can store data in. Requires mode: read_write.

To use a model hosted on the , specify the spice.ai path in the from field.

Example:

Specific model versions can be referenced using a version label or Training Run ID.

from Format

The from key must conform to the following regex format:

The health API can be called to confirm the overall availability of the API service.

Get API Health

GET https://data.spiceai.io/health

This endpoint gets the health of the API.

Chat Completions

Spice provides an OpenAI compatible chat completion AI at . Authorize with the endpoint using an .

The App requires a configured and deployed model to respond to chat completion requests.

For more information about using chat completions, refer to the .

Accessing data across multiple, disparate data sources

Perform across databases, data warehouses, and data lakes using .

Enhancing data application performance

Colocate a local working set of hot data with data applications and frontends to serve more concurrent requests and users with faster page loads and data updates.

Create New Deployment

Navigate to the Spicepod tab and click on Create Deployment.

A light or dark mode portal theme can be set:

1. Click the profile picture on the top right corner of the portal interface.

2. Select Light, Dark, or System mode using the theme toggle.

Each new app deployment automatically retrieves the most recent stable Spice OSS release. Visit the or to check for the latest runtime updates.

Migrate Exiting Apps

All Spice Apps are now powered by the latest, next-generation Spice.ai Open Source data and AI engine. Existing apps have been migrated but require a manual setup step to connect datasets and/or model providers.

Learn More: Read the blog post for details on this upgrade, and visit the for over 50 quickstarts and examples.

Use Spice to access data across various data sources for Retrieval-Augmented-Generation (RAG).

Spice enables developers to combine structured data via SQL queries and unstructured data through built-in vector similarity search. This combined data can then be fed to large language models (LLMs) through a native AI gateway, enhancing the models' ability to generate accurate and contextually relevant responses.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Connect to any Flight SQL compatible server (e.g. Influx 3.0, CnosDB, other Spice runtimes!) as a connector for federated SQL queries.

- from: flightsql:my_catalog.good_schemas.cool_dataset
  name: cool_dataset
  params:
    flightsql_endpoint: http://127.0.0.1:50051
    flightsql_username: spicy
    flightsql_password: ${secrets:my_flightsql_pass}

Configuration

from

The from field takes the form flightsql:dataset where dataset is the fully qualified name of the dataset to read from.

name

The dataset name. This will be used as the table name within Spice.

params

Spice supports federated queries, enabling you to join and combine data from multiple sources, including databases (PostgreSQL, MySQL), data warehouses (Databricks, Snowflake, BigQuery), and data lakes (S3, MinIO). For a full list of supported sources, see Data Connectors.

SQL Query

Playground SQL Explorer

The Playground SQL Explorer is the fastest way to get started with federated queries, debugging queries, and iterating quickly. The SQL Query Editor be accessed by clicking on the SQL Explorer tab after selecting Playground in the app navigation bar.

See for further documentation on using the SQL Query Editor.

Apache Arrow Flight API

For production applications, leveraging the high-performance endpoint is recommended. The Spice SDKs always query using Arrow Flight.

See for further documentation on using Apache Arrow Flight APIs.

HTTP API

SQL Query is also accessible via a standard HTTP API.

See for further documentation on using the HTTP SQL API.

To use a language model hosted on Azure OpenAI, specify the azure path in the from field and the following parameters from the Azure OpenAI Model Deployment page:

Only one of azure_api_key or azure_entra_token can be provided for model configuration.

Example:

Refer to the for more details on available models and configurations.

Follow the to try Azure OpenAI models for vector-based search and chat functionalities with structured (taxi trips) and unstructured (GitHub files) data.

Spice provides a high-performance, OpenAI API-compatible AI Gateway optimized for managing and scaling large language models (LLMs). Additionally, Spice offers tools for Enterprise Retrieval-Augmented Generation (RAG), such as SQL query across federated datasets and an advanced search feature (see Search).

Spice supports full OpenTelemetry observability, enabling detailed tracking of data flows and requests for full transparency and easier debugging.

Supported Models​

Spice supports a variety of LLMs, including OpenAI, Azure OpenAI, Anthropic, Groq, Hugging Face, and more (see Model Providers for all supported models).

Core Features

• Custom Tools: Equip models with tools to interact with the Spice runtime.

• System Prompts: Customize system prompts and override defaults for .

For detailed configuration and API usage, refer to the .

Example: Configuring an OpenAI Compatible Model

To use a language model hosted on OpenAI (or compatible), specify the openai path and model ID in from.

Example spicepod.yml:

For details, see .

A semantic model is a structured representation of data that captures the meaning and relationships between elements in a dataset.

In Spice, semantic models transform raw data into meaningful business concepts by defining metadata, descriptions, and relationships at both the dataset and column level. This makes the data more interpretable for both AI language models and human analysis.

Use-Cases

Large Language Models (LLMs)

The semantic model is automatically used by as context to produce more accurate and context-aware AI responses.

Defining a Semantic Model

Semantic data models are defined within the spicepod.yaml file, specifically under the datasets section. Each dataset supports description, metadata, and a columns field where individual columns are described with metadata and features for utility and clarity.

Example Configuration

Example spicepod.yaml:

Dataset Metadata

Datasets can be defined with the following metadata:

• instructions: Optional. Instructions to provide to a language model when using this dataset.

• reference_url_template: Optional. A URL template for citation links.

For detailed metadata configuration, see the Spice OSS

Column Definitions

Each column in the dataset can be defined with the following attributes:

• description: Optional. A description of the column's contents and purpose.

• embeddings: Optional. Vector embeddings configuration for this column.

For detailed columns configuration, see the Spice OSS

To use a language model hosted on xAI, specify xai path in the from field and the associated xai_api_key parameter:

Example:

models:
- from: xai:grok2-latest
  name: xai
  params:
    xai_api_key: ${secrets:SPICE_GROK_API_KEY}

Refer to the for more details on available models and configurations.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Apache Spark as a connector for federated SQL query against a Spark Cluster using Spark Connect

datasets:
  - from: spark:spiceai.datasets.my_awesome_table
    name: my_table
    params:
      spark_remote: sc://my-spark-endpoint

Configuration

• spark_remote: A spark remote connection URI. Refer to spark connect client connection string for parameters in URI.

Limitations

• Correlated scalar subqueries are only supported in filters, aggregations, projections, and UPDATE/MERGE/DELETE commands.

• The Spark connector does not yet support streaming query results from Spark.

To use a language model hosted on Anthropic, specify anthropic in the from field.

To use a specific model, include its model ID in the from field (see example below). If not specified, the default model is claude-3-5-sonnet-latest.

The following parameters are specific to Anthropic models:

Example spicepod.yml configuration:

See for a list of supported model names.

In addition to the built-in runtime.task_history SQL table, Spice can export the observability traces it collects into Zipkin.

Enabling Zipkin Export

Zipkin export is defined in the spicepod.yaml under the runtime.tracingsection:

runtime:
  tracing:
    zipkin_enabled: true
    zipkin_endpoint: http://localhost:9411/api/v2/spans

• zipkin_enabled: Optional. Default false. Enables or disables the Zipkin trace export.

• zipkin_endpoint: Required if zipkin_enabledis true. The path to the /api/v2/spansendpoint on the Zipkin instance to export to.

The Localpod Data Connector enables setting up a parent/child relationship between datasets in the current Spicepod. This can be used for configuring multiple/tiered accelerations for a single dataset, and ensuring that the data is only downloaded once from the remote source. For example, you can use the localpod connector to create a child dataset that is accelerated in-memory, while the parent dataset is accelerated to a file.

The dataset created by the localpod connector will logically have the same data as the parent dataset.

Synchronized Refreshes

The localpod connector supports synchronized refreshes, which ensures that the child dataset is refreshed from the same data as the parent dataset. Synchronized refreshes require that both the parent and child datasets are accelerated with refresh_mode: full (which is the default).

When synchronization is enabled, the following logs will be emitted:

Examples

Public Spice Apps can be forked, added as a dependency or connected to using Spice OSS Spice.ai connector.

Making the app public

To make your app public, go to your app settings and click Make public.

After that, the app will be visible to all users at https://spice.ai/<org-name>/<app-name> and searchable at .

Data may be queried by posting SQL to the /v1/sql API and /v1/firesql API for Firecached data. For documentation on the Spice Firecache see .

See Tables for a list of tables to query or browse the example queries listed in the menu.

Requirements and limitations

• An API key is required for all SQL queries.

• Results are limited to 500 rows. Use the to fetch up to 1M rows in a single query or the to fetch results with paging.

• Requests are limited to 90 seconds.

The @spiceai/spice SDK supports streaming partial results as they become available.

This can be used to enable more efficient pipelining scenarios where processing each row of the result set can happen independently.

The Client.query function takes an optional onData callback that will be passed partial results as they become available.

public async query(
    queryText: string,
    onData: ((data: Table) => void) | undefined = undefined
  ): Promise<Table>

In this example, we retrieve all 10,000 suppliers from the TPCH Suppliers table. This query retrieves all suppliers in a single call:

import { SpiceClient } from "@spiceai/spice";

const spiceClient = new SpiceClient(process.env.API_KEY);
const query = `
SELECT s_suppkey, s_name
FROM tpch.supplier
`
const allSuppliers = await spiceClient.query(query)
allSuppliers.toArray().forEach((row) => {
    processSupplier(row.toJSON())
});

This call will wait for the promise returned by query() to complete, returning all 10,000 suppliers.

Alternatively, data can be processed as it is streamed to the SDK. Provide a callback function to the onData parameter, which will be called with every partial set of data streamed to the SDK:

Navigate to Settings -> Runtime to configure the runtime settings for your Spice application.

Runtime Version

The runtime version determines the Spice.ai Open Source version for your Spice application. Each new deployment automatically adopts the latest stable version of the Spice runtime to ensure access to the most recent features and optimizations.

Runtime Region

The runtime region specifies the geographic location of the data center hosting your Spice application. Region selection optimizes latency, compliance, and performance based on your business needs.

• Availability: Region selection is exclusive to Enterprise plan customers.

• Supported Regions:

  • North America:

Compute

Compute settings define the resource allocation for your Spice application, balancing performance and cost.

Standard Compute Instances:

• Developer: 2 CPU / 4 GB

• Pro for Teams: 4 CPU / 8 GB

• Enterprise: Dedicated Instances with multiple high-availability replicas

Storage

Provides a persistent storage for the runtime to save data acceleration files. Data remains intact across restarts and redeployments.

• Availability: Storage is exclusive to Enterprise plan customers.

• Mount Path: /data.

• Size: Configured per request. Contact your account executive to set or update capacity.

The HTTP(s) Data Connector enables federated SQL query across stored at an HTTP(s) endpoint.

Configuration

from

Observability in Spice enables task tracking and performance monitoring through a built-in distributed tracing system that can or be viewed via the SQL table.

Spice records detailed information about runtime operations through trace IDs, timings, and labels - from SQL queries to AI completions. This task history system helps operators monitor performance, debug issues, and understand system behavior across individual requests and overall patterns.

Use-Cases

Apps are self-contained instances of Spice OSS Runtime, running in Spice.ai Cloud Platform.

Each app has a unique API Key and owned by individual accounts or .

Learn how to:

To use SQLite as Data Accelerator, specify sqlite as the engine for acceleration.

Configuration

The connection to SQLite can be configured by providing the following params:

The SQL Query API provides powerful capabilities for querying data managed by the Spice.ai Cloud Data Warehouse and connected external data sources using federated SQL queries. Results can be fetched through either the high-performance Apache Arrow Flight API or a standard HTTP API.

Production Query Endpoints

To use a language model hosted on Perplexity, specify perplexity in the from field.

To use a specific model, include its model ID in the from field (see example below). If not specified, the default model is sonar.

The following parameters are specific to Perplexity models:

Each Spice app have two pre-generated API keys, which can be used with , the or the .

• Select Spice app and navigate to Settings -> General.

• Click the API Key 1 or API Key 2 field to copy the key value.

Edit app spicepod not connected to GitHub

To update Spice App spicepod.yaml, navigate to Code tab. Use Components sidebar to add data connectors, model providers and preconfigured datasets, or manually edit spicepod.yaml in code editor.

After saving the spicepod changes, a new deployment must be triggered. Learn more about .

You can transfer an App's ownership to another .

Learn more about .

The spicepy SDK supports streaming partial results as they become available.

This can be used to enable more efficient pipelining scenarios where processing each row of the result set can happen independently.

spicepy enables streaming through the use of the .

The object returned from spicepy.Client.query() is a .

Calling to_pandas() on the FlightStreamReader will wait for the stream to return all of the data before returning a pandas DataFrame.

Open the SQL editor by navigating to an App Playground and clicking SQL Query in the sidebar.

SQL table, column, and keyword suggestions

The Spice.ai Query Editor will suggest table and column names along with keywords as you type. You can manually prompt for a suggestion by pressing ctrl+space.

SpiceClient(params)

The top-level object that connects to Spice.ai

• params.api_key (string, optional): API key to authenticate with the endpoint

The Data Connector enables federated SQL query across datasets in the . Access to these datasets requires a free .

Configuration

Parameters

Under the Monitoring tab, track your app requests, their status codes, and duration, in addition to the existing usage monitoring metrics dashboard.

Overview

Monitor the success, failures, and durations of SQL queries, AI completions, Vector Searches, Embedding calculations, and accelerated dataset refreshes.

App Secrets are key-value pairs that are passed to the Spice Runtime instance as environment secrets. Secrets are securely encrypted and accessible only through the app in which they were created.

Once a secret is saved, its value cannot be retrieved through Spice Cloud. If you need to update the secret value, you must delete the existing secret and create a new one.

Create a new secret

1. Select your app.

Organizations enable you to share apps, datasets, users, billing, and settings with your team. Organization administrators can set who has access to their organization's resources and data.

When you create an account on Spice.ai, a single member organization of the same name as your username is created for you and you are automatically added as a member and the owner of the organization.

Creating an organization

Spice.ai organizations are created by connecting an existing GitHub organization to Spice.ai.

1. Click on the organization dropdown icon in the application selector. Next, select the Create Org option from the menu.

1. Check to accept the terms and conditions for the new organization, then proceed by clicking the Connect GitHub organization button.

1. A window will pop up from GitHub where you can select the organization to install the Spice.ai app into.

1. On the confirmation page proceed by clicking the Install button.

1. Upon successful connection, you will be automatically redirected to the newly created Spice.ai organization.

View Organizations

To view your organizations, click the dropdown icon from the application selector.

All organizations you have access to are listed.

Organization Management

Click on the first tab to access the details of your current organization or select another organization from the menu to view its information. On this page, you will see all the applications that have been created within the selected organization.

Click the Settings tab to view information about the organization, including members and billing information.

Adding organization members

To add an existing Spice.ai user to an organization:

1. Navigate to the organization's settings.

2. Click the Add Member button.

3. Enter the Spice.ai username of the user you wish to add to the organization.

4. Click the Add Member button to confirm.

The user will be added to the organization and they will receive an email notifying them of the new membership.

To invite GitHub user to a Spice.ai organization:

Enter the GitHub username of the user you wish to invite to the organization and select the user from the search results. Only users with public email address can be invited.

The invited user will receive an invitation link. Once they accept the invitation, they will be granted access to the organization.

To invite anyone by email

Enter the email address of the user you want to invite to the organization, then click Send invite.

Removing organization members

To remove a member from an organization:

1. Navigate to the organization's settings.

2. Locate the user you wish to remove from the list of members.

3. Click the ellipsis on the right of the user's card.

4. Confirm the removal by clicking the Remove member from organization

Build intelligent autonomous agents that act contextually by grounding AI models in secure, full-knowledge datasets with fast, iterative feedback loops.

Spice.ai helps in building intelligent autonomous agents by leveraging several key features:

Federated SQL Query

Spice.ai enables federated querying across databases, data warehouses, and lakes. With advanced query push-down optimizations, it ensures efficient retrieval and processing of data across disparate sources, reducing latency and operational complexity. Learn more about Federated SQL Query. For practical implementation, refer to the Federated SQL Query recipe.

Data Acceleration & Materialization with Change Data Capture (CDC)

Spice.ai materializes application-specific datasets close to the point of use, reducing query and thus retrieval times, and infrastructure costs. It supports Change Data Capture (CDC), keeping materialized data sets up-to-date with minimal overhead and enabling real-time, reliable data access. . See the for an example.

AI Gateway

Integrate AI into your applications with Spice.ai’s AI Gateway. It supports hosted models like OpenAI and Anthropic and local models such as OSS Llama and NVIDIA NIM. Fine-tuning and model distillation are simplified, helping faster cycles of development and deployment. . Refer to the for details.

Search with Vector Similarity Search (VSS)

Spice.ai provides advanced search capabilities, including vector similarity search (VSS), enabling efficient retrieval of unstructured data, embeddings, and AI model outputs. This is critical for applications like RAG and intelligent search systems. . For implementation, see the .

Semantic Model for AI

Built-in semantic models allow Spice.ai to align AI operations with enterprise data, ensuring that applications are grounded in contextual, full-knowledge datasets. This enhances the accuracy and reliability of AI outputs while reducing risks of irrelevant or untrustworthy results. .

Monitoring and Observability

Spice.ai includes robust monitoring and observability tools tailored for AI applications. These tools provide end-to-end visibility into data flows and AI workflows, LLM-specific observability to monitor model performance, track usage, and manage drift, and security and compliance auditing for data and model interactions. .

Prepare the repository

Before connecting:

• Admin access: Ensure you have administrative access to the GitHub repository. This level of access is required to install the Spice.ai GitHub app.

• Matching repository name: The Spice.ai app and the GitHub repository names must match. For example:

  • Spice.ai app:

  • GitHub repository:

To quickly set up a new repository, use the as a starting point:

Connect

1. Ensure the repository is set up as per instructions above.

2. In the context of the Spice app to connect, navigate to Settings, then click the Connect repository button.

1. Follow GitHub App installation instructions.

Ensure that you select all repositories or specifically the repository you intend to connect.

1. Finally, link the repository to your Spice.ai app.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

The Snowflake Data Connector enables federated SQL queries across datasets in the Snowflake Cloud Data Warehouse.

Configuration

from

A Snowflake fully qualified table name (database.schema.table). For instance snowflake:SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM or snowflake:TAXI_DATA."2024".TAXI_TRIPS

name

The dataset name. This will be used as the table name within Spice.

params

Auth

The connector supports password-based and authentication. Login requires the account identifier ('orgname-accountname' format) - use instructions.

Example

To use DuckDB as Data Accelerator, specify duckdb as the engine for acceleration.

datasets:
  - from: spice.ai:path.to.my_dataset
    name: my_dataset
    acceleration:
      engine: duckdb

Configuration

Spice.ai currently only supports mode: memory for DuckDB accelerator.

Configuration params are provided in the acceleration section for a data store. Other common acceleration fields can be configured for DuckDB, see see .

The Dotnet SDK spiceai is the easiest way to query Spice.ai from Dotnet.

It uses Apache Arrow Flight to efficiently stream data to the client and Apache Arrow Records as data frames.

Requirements

• .Net 6.0+ or .Net Standard 2.0+

Installation

Add Spice SDK

Usage

1. Create a SpiceClient by providing your API key to SpiceClientBuilder. Get your free API key at .

1. Execute a query and get back an Apache Arrow .

1. Iterate through the reader to access the records.

Usage with local Spice runtime

Follow the to install and run spice locally.

Contributing

Contribute to or file an issue with the spice-dotnet library at:

Create custom dashboards and visualizations using the FlightSQL or Infinity Grafana Plugins:

• FlightSQL Grafana Plugin

• Infinity Grafana Plugin

Setup with FlightSQL Grafana Plugin

Installing FlightSQL Grafana Plugin

Use the for an installation reference.

In the Grafana installation, navigate to Administration -> Plugins and data -> Plugins. Select "State: All" and search for "FlightSQL" in the Search box. Select "FlightSQL" in the list of plugins.

Click the "Install" button to install the plugin. Once installed, a new data source can be added.

Adding Spice as a data source

Click the "Add new data source" button from the FlightSQL plugin menu.

In the data source menu, provide the following options:

• Host:Port - set to flight.spiceai.io:443 to connect to the Spice.ai Cloud Platform

• Auth Type - set to token

• Token - set to your .

Once these options are set, click "Save & Test". Grafana should report "OK" if the configuration is correct.

Creating visualizations

Create a visualization using the FlightSQL Spice.AI data source. Select the configured datasource from the list of datasources in the visualization creator.

Create your query using the SQL builder, or switch to a plain SQL editor by clicking the "Edit SQL" button. In this example, the query retrieves the latest query execution times from the configured App instance and displays them as a line graph.

Grafana may not automatically update the visualization when changes are made to the query. To force the visualization to update with new query changes, click the "Query Inspector" button, and click "Refresh".

The Java SDK is the easiest way to query the Spice Cloud Platform from Java.

It uses Apache Arrow Flight to efficiently stream data to the client and Apache Arrow Records as data frames.

Supported Java Versions

This library supports the following Java implementations:

• OpenJDK 11

• OpenJDK 17

• OpenJDK 21

• OracleJDK 11

• OracleJDK 17

• OracleJDK 21

• OracleJDK 22

Installation

Usage

1. Import the package.

2. Create a SpiceClient by providing your API key. Get your free API key at .

3. Execute a query and get back a .

5. Iterate through the FlightStream to access the records.

Check to learn more.

Usage with local Spice.ai OSS runtime

Follow the to install and run spice locally.

Or using custom flight address:

Check or to learn more

Connection retry

The SpiceClient implements connection retry mechanism (3 attempts by default). The number of attempts can be configured with withMaxRetries:

Retries are performed for connection and system internal errors. It is the SDK user's responsibility to properly handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429).

Contributing

Contribute to or file an issue with the spice-rs library at:

Every Spice app is powered by a managed instance of the Spice OSS Runtime deployed to the platform.

A Spicepod is a package that encapsulates application-centric datasets and machine learning (ML) models.

Spicepods are analogous to code packaging systems, like NPM, however differ by expanding the concepts to data and ML models.

Structure​

A Spicepod is described by a YAML manifest file, typically named spicepod.yaml, which includes the following key sections:

• Metadata: Basic information about the Spicepod, such as its name and version.

• Datasets: Definitions of datasets that are used or produced within the Spicepod.

• Catalogs: Definitions of catalogs that are used within the Spicepod.

• Models: Definitions of ML models that the Spicepod manages, including their sources and associated datasets.

Example Manifest

Key Components

Datasets

Datasets in a Spicepod can be sourced from various locations, including local files or remote databases. They can be materialized and accelerated using different engines such as DuckDB, SQLite, or PostgreSQL to optimize performance ().

Catalogs

Catalogs in a Spicepod can contain multiple schemas. Each schema, in turn, contains multiple tables where the actual data is stored.

Models

ML models are integrated into the Spicepod similarly to datasets. The models can be specified using paths to local files or remote locations. ML inference can be performed using the models and datasets defined within the Spicepod.

To learn more, please refer to the full .

ClickHouse is a fast, open-source columnar database management system designed for online analytical processing (OLAP) and real-time analytics. This connector enables federated SQL queries from a ClickHouse server.

Configuration

from

FTP (File Transfer Protocol) and SFTP (SSH File Transfer Protocol) are network protocols used for transferring files between a client and server, with FTP being less secure and SFTP providing encrypted file transfer over SSH.

The FTP/SFTP Data Connector enables federated/accelerated SQL query across stored in FTP/SFTP servers.

Configuration

is a data lake engine that enables high-performance SQL queries directly on data lake storage. It provides a unified interface for querying and analyzing data from various sources without the need for complex data movement or transformation.

This connector enables using Dremio as a data source for federated SQL queries.

Configuration

Datasets can be locally accelerated by the Spice runtime, pulling data from any and storing it locally in a for faster access. The data can be kept up-to-date in real-time or on a refresh schedule, ensuring users always have the latest data locally for querying.

Supported Data Accelerators

Dataset acceleration is enabled by setting the acceleration configuration. Spice currently supports In-Memory Arrow, DuckDB, SQLite, PostgreSQL as accelerators. For engine specific configuration, see

The spicepy is the easiest way to use and query in Python.

The Python SDK uses to efficiently stream data to the client and Records as data frames which are then easily converted to Pandas data frames.

Requirements

To use a model hosted on HuggingFace, specify the huggingface.co path in the from field and, when needed, the files to include.

Configuration

from

The from key takes the form of huggingface:model_path. Below shows 2 common example of from key configuration.

• huggingface:username/modelname: Implies the latest version of modelname hosted by username.

• huggingface:huggingface.co/username/modelname:revision: Specifies a particular revision of modelname by username, including the optional domain.

The from key follows the following regex format.

The from key consists of five components:

1. Prefix: The value must start with huggingface:.

2. Domain (Optional): Optionally includes huggingface.co/ immediately after the prefix. Currently no other Huggingface compatible services are supported.

3. Organization/User: The HuggingFace organization (org).

name

The model name. This will be used as the model ID within Spice and Spice's endpoints (i.e. https://data.spiceai.io/v1/models). This can be set to the same value as the model ID in the from field.

params

files

The specific file path for Huggingface model. For example, GGUF model formats require a specific file path, other varieties (e.g. .safetensors) are inferred.

Example

Access Tokens

Access tokens can be provided for Huggingface models in two ways:

1. In the Huggingface token cache (i.e. ~/.cache/huggingface/token). Default.

2. Via .

Examples

Load a ML model to predict taxi trips outcomes

Load a LLM model to generate text

Load a private model

For more details on authentication, see .

To use a language model hosted on OpenAI (or compatible), specify the openai path in the from field.

For a specific model, include it as the model ID in the from field (see example below). The default model is gpt-4o-mini.

Configuration

from

The from field takes the form openai:model_id where model_id is the model ID of the OpenAI model, valid model IDs are found in the {endpoint}/v1/models API response.

Example:

name

The model name. This will be used as the model ID within Spice and Spice's endpoints (i.e. https://data.spiceai.io/v1/models). This can be set to the same value as the model ID in the from field.

params

See for additional configuration options.

Supported OpenAI Compatible Providers

Spice supports several OpenAI compatible providers. Specify the appropriate endpoint in the params section.

Azure OpenAI

Follow instructions.

Groq

Groq provides OpenAI compatible endpoints. Use the following configuration:

NVidia NIM

NVidia NIM models are OpenAI compatible endpoints. Use the following configuration:

View the Spice cookbook for an example of setting up NVidia NIM with Spice .

Parasail

Parasail also offers OpenAI compatible endpoints. Use the following configuration:

Refer to the respective provider documentation for more details on available models and configurations.

Spice Models enable the training and use of ML models natively on the Spice platform.

The platform currently supports time-series forecasting models, with other categories of models planned.

Hosted models have first-class access to co-located data for training and inferencing including: Spice managed datasets, user managed datasets, and custom datasets and views. Additionally, Spice Firecache can be leveraged to train and infer up to 10x faster.

Defining a Model

Models are defined using a YAML file. Model details such as data requirements, architecture, training parameters, and other important hyperparameters are defined in the model.yaml.

Add a model.yaml file to the repository path /models/[model_name]/model.yaml of a , replacing [model_name] with the desired model name. For example, the uses the path /models/gas-fees/model.yaml.

Refer to the for all available configuration options.

For example model manifests, see the .

Training a Model

In the , navigate to the Models tab of the Spice app.

model.yaml files committed to the connected repository will be automatically detected and imported as Spice Models.

Navigating to a specific Model will show detailed information as defined in the model.yaml.

A training run can be started using the Train button.

Training runs in progress will be shown and updated, along with historical training runs.

The Training Status will be updated to Complete for successfully completed training runs. Details and the Training Report, are available on the Training Run page.

Running Model Predictions

A successfully trained model can be used to make predictions.

The lookback data (inferencing data) is automatically provided by the platform and wired up to the inference, enabling a prediction to be made using a simple API call.

AI Predictions in the Playground

Navigate to AI Predictions in the Playground.

Successfully trained models will be available for selection from the model selector drop down on the right.

Clicking Predict will demonstrate calling the predictions API using lookback data within the Spice platform. A graph of the predicted value(s) along with the lookback data will be displayed.

Predictions by API

The Training Runs page provides training details including a copyable curl command to make a prediction from the command line.

For details on the API, see .

Microsoft SQL Server is a relational database management system developed by Microsoft.

The Microsoft SQL Server Data Connector enables federated/accelerated SQL queries on data stored in MSSQL databases.

Configuration

from

The from field takes the form mssql:database.schema.table where database.schema.table is the fully-qualified table name in the SQL server.

name

The dataset name. This will be used as the table name within Spice.

Example:

params

The data connector supports the following params. Use the to load the secret from a secret store, e.g. ${secrets:my_mssql_conn_string}.

Example

SQL query results can be served via a high-performance Apache Arrow Flight endpoint. Arrow Flight uses the gRPC protocol for efficient data transfer.

This setup enables high-speed access to your data in Python, Go, C++, C#, Rust, Java, and C# and makes it easy to use libraries like Pandas and NumPy.

SDKs

It's recommended to use the Spice.ai SDKs to connect and query the Arrow Flight endpoint. SDKs are available for , , , , , and .

In Python, query results can be easily converted to Pandas or NumPy formats.

You may also use Apache's pyarrow library directly.

Connecting to the Endpoint

• Endpoint URL: grpc+tls://flight.spiceai.io

• Basic Authentication:

  • Username can be set to an empty string

Requirements

• names must be fully-qualified. For example spiceai.quickstart

Samples

Find code samples in Python in .

Troubleshooting

Mac/Windows Certificate issue

If you get this error:

Could not get default pem root certs

Install the .

The Go SDK gospice is the easiest way to query Spice.ai from Go.

It uses Apache Arrow Flight to efficiently stream data to the client and Apache Arrow Records as data frames.

GoDocs are available at: pkg.go.dev/github.com/spiceai/gospice.

Requirements

• (or later)

Installation

Get the gospice package.

Usage

1. Import the package.

2. Create a SpiceClient by providing your API key. Get your free API key at .

3. Initialize the SpiceClient.

4. Execute a query and get back an .

5. Iterate through the reader to access the records.

Usage with local Spice runtime

Follow the to install and run spice locally.

Or using custom flight address:

Check to learn more.

Example

Run go run . to execute a sample query and print the results to the console.

Connection retry

The SpiceClient implements connection retry mechanism (3 attempts by default). The number of attempts can be configured via SetMaxRetries:

Retries are performed for connection and system internal errors. It is the SDK user's responsibility to properly handle other errors, for example RESOURCE_EXHAUSTED (HTTP 429).

Contributing

Contribute to or file an issue with the gospice library at:

The SharePoint Data Connector enables federated SQL queries on documents stored in SharePoint.

Example

Returns

DuckDB is an in-process SQL OLAP (Online Analytical Processing) database management system designed for analytical query workloads. It is optimized for fast execution and can be embedded directly into applications, providing efficient data processing without the need for a separate database server.

This connector supports DuckDB as a data source for federated SQL queries.

Configuration

The makes it easy to access and chat with external data in GitHub Copilot, enhancing AI-assisted research, Q&A, code, and documentation suggestions for greater accuracy.

Access structured and unstructured data from any Spice data source like GitHub, PostgreSQL, MySQL, Snowflake, Databricks, GraphQL, data lakes (S3, Delta Lake, OneLake), HTTP(s), SharePoint, and even FTP.

Some example prompts:

• @spiceai What documentation is relevant to this file?

The spice-rs is the easiest way to query from Rust.

It uses to efficiently stream data to the client and Records as data frames.

Requirements