DOCSEARCHbyAlgolia
Submit Docs

Spice.ai Open Source

website·Indexed 33 days ago

https://spiceai.org

Documentation for the Spice.ai open source project, including the Spice CLI and runtime. Features technical specifications for ADBC, JDBC, ODBC, and Arrow Flight SQL, as well as API references for Iceberg configuration, Model Context Protocol (MCP) streams, and Text-to-SQL (NSQL). Includes guides for integrating with Zipkin, DBeaver, and Microsoft Power BI.

Tokens
406.7K
Snippets
1.8K
Records
2.9K
Agent score
70%

What's inside Spice.ai

  1. Overview of the SMB Data Connector

    The SMB Data Connector enables federated SQL queries across supported file formats stored on SMB/CIFS network shares. It specifically requires the SMB 3.1.1 dialect and is compatible with Windows Server 2016+, Samba 4.x, Azure Files, and NAS devices (e.g., Synology, QNAP) configured for SMB 3.1.1. The connector is read-only; write operations like put, delete, and copy are not supported.

  2. Overview of Spice dataset refresh modes

    Spice supports five modes to refresh accelerated datasets. The default mode is full.

    • full: Replaces/overwrites the entire dataset on each refresh. Best for general tables (e.g., a table of users).
    • append: Adds new data to the dataset on each refresh. Best for append-only, immutable datasets like time-series or log data.
    • changes: Applies incremental inserts, updates, and deletes. Best for lifecycle tables (e.g., customer orders).
    • caching: Read-through caching for HTTP-based datasets. Best for API search results.
    • snapshot: Reloads exclusively from the snapshot store. Best for read-only replicas bootstrapped from centralized snapshots.

  3. Overview of Spice Cayenne Data Accelerator

    Spice Cayenne is a data acceleration engine designed for high-performance, scalable queries on large-scale datasets. It is built on Vortex (a high-performance columnar file format) and combines columnar storage with in-process metadata management to support datasets larger than 1TB.

  4. Overview of Spice Distributed Query Architecture

    Spice uses Apache Ballista to coordinate distributed queries across multiple nodes, which is particularly useful for large, partitioned datasets in formats like Parquet, Delta Lake, or Iceberg. The architecture consists of two primary components:

    • Scheduler: Plans distributed queries, manages the work queue for executors, and manages async query jobs (if scheduler.state_location is configured).
    • Executors: Nodes that execute the physical query plans. They connect to the scheduler to receive work and fetch the Spicepod configuration.

  5. Overview of Spice Data Acceleration

    Data Acceleration allows datasets and views to be pulled from any Data Connector and stored locally in a Data Accelerator. This eliminates network latency and reduces query times, especially for large results. Data can be kept up-to-date via real-time updates or a refresh schedule. Key features include indexing for speed, primary key constraints for data integrity, acceleration snapshots for fast bootstrapping from object storage (e.g., S3), and partitioning to reduce scan sizes for large datasets.

  6. Overview of Spice.ai Open Source

    Spice is a SQL query, search, and LLM-inference engine written in Rust, designed for data-driven applications and AI agents. It provides a lightweight, portable runtime (single ~140 MB binary) that combines data query and AI inference in a single engine to ground AI responses in real data. It is built on Apache DataFusion, Apache Arrow, Arrow Flight, SQLite, and DuckDB.

  7. Overview of Cluster-Sidecar Deployment Architecture

    The Cluster-Sidecar architecture is designed to handle two distinct data access patterns: large analytical queries (handled by a centralized Spice cluster) and hot operational queries (handled by local application sidecars).

    Key architectural properties:

    • Sidecars as Edge Nodes: Sidecars act as a 'CDN for data,' providing sub-millisecond reads for a scoped working set of data materialized locally.
    • Cluster as Origin: A centralized Spice cluster (or Spice Cloud Platform) handles data ingestion, acceleration, and distributed compute for heavy queries via Apache Ballista and Spice Cayenne.
    • Transparent Delegation: When a sidecar cannot answer a query from its local working set, it transparently delegates the request to the cluster over Arrow Flight and caches the result for future use.
    • Isolation: The sidecar serves as a sandbox, ensuring applications never have direct credentials to origin data systems (Postgres, Snowflake, etc.) and cannot access data not explicitly declared in their configuration.

  8. Overview of Spice.ai Runtime Components

    Spice.ai runtime components are the building blocks used to configure data access, acceleration, AI models, embeddings, and secrets. These components are defined within the spicepod.yaml manifest. The core components include:

    • Data Connectors: Enable federated SQL queries by connecting to databases, warehouses, lakes, and file systems (e.g., PostgreSQL, MySQL, S3, Snowflake, Databricks, DuckDB).
    • Data Accelerators: Materialize datasets locally in memory or on disk for performance. Options include Arrow (in-memory), DuckDB, SQLite, PostgreSQL, or Cayenne.
    • Catalog Connectors: Integrate with catalogs like Apache Iceberg, Unity Catalog, AWS Glue, and DuckLake to discover and register datasets.
    • Models: Configure LLM providers for AI inference via an OpenAI-compatible API, supporting both hosted models (OpenAI, Anthropic, xAI) and local models with CUDA/Metal acceleration.
    • Embeddings: Generate vector representations of text for semantic search and RAG using built-in or external providers.
    • Tools: Define callable functions for LLMs, including Model Context Protocol (MCP) integrations.
    • Vector Engines: Index embedding columns for nearest-neighbour search, backed by DuckDB, Elasticsearch, or Amazon S3 Vectors.
    • Secret Stores: Manage credentials via environment variables, files, or external managers like AWS Secrets Manager and Azure Key Vault.

  9. Overview of the Tool Registry

    The Tool Registry is a runtime capability designed to manage large numbers of tools available to an LLM. Instead of injecting every tool's full JSON schema into every chat turn—which increases token costs, latency, and reduces model accuracy—the registry replaces individual tool definitions with two meta-tools: tool_search and tool_invoke.

    list_datasets is always exposed directly alongside these meta-tools to allow the model to orient itself without needing a registry search first.

    The registry indexes all callable tools, including:

    • Built-in Spice runtime tools (e.g., sql, list_datasets, table_schema, search, random_sample)
    • MCP tools (connected via sse or stdio)
    • Functions declared in the Spicepod with as_tool: true
    • Tools defined in the tools: section with as_sql: true

  10. Overview of JSON support in Spice

    Spice provides JSON support via datafusion-functions-json, allowing users to extract, query, and manipulate JSON data stored as strings.

    Limitations:

    • JSON functions and operators are only supported during DataFusion (Arrow) execution.
    • Federated or accelerated (non-Arrow) sources may not support all JSON functions.
    • Advanced features for JSON creation, modification, or complex path expressions are not supported.

  11. Overview of Acceleration Snapshots

    Acceleration snapshots allow Spice to reuse a pre-built acceleration file on startup instead of performing a full refresh. This is applicable when a dataset uses a file-mode acceleration engine (DuckDB, SQLite, Cayenne, or Turso). If the local acceleration file is missing (e.g., on first boot or when using ephemeral NVMe storage), Spice downloads the most recent snapshot from object storage to move the dataset immediately to a ready state.

    Key constraints:

    • Available only in the Enterprise edition.
    • Every accelerated dataset must write to its own dedicated file (e.g., /nvme/my_dataset.db); sharing a single file across multiple datasets is not supported.
    • Snapshots are organized using Hive-style partitioning in the storage backend.

  12. Overview of Spice.ai Cluster-Sidecar Deployment

    The Cluster-Sidecar deployment model is a Kubernetes-native architecture designed for high-performance data retrieval. It uses a centralized cluster (self-managed or Spice Cloud) to handle data ingestion, acceleration (via Spice Cayenne), and complex distributed queries, while deploying lightweight sidecars alongside application pods to provide sub-millisecond reads via local caching on loopback.

    Key architectural benefits include:

    • Structural Isolation: Sidecars expose a scoped catalog and hold no origin database credentials, preventing pods from having direct access to source systems.
    • Transparent Query Delegation: Queries that exceed the sidecar's local cached working set are automatically routed to the central cluster via Arrow Flight.
    • Reduced Source Load: The cluster ingests data once from the source, and sidecars synchronize from the cluster, preventing multiple application instances from overloading upstream databases.
    • Resilience: Sidecars can serve cached data even if the central cluster is temporarily unavailable.
    • Security: Communication between sidecars and the cluster is encrypted via mTLS; data is encrypted at rest and in transit.