title: 'YAML syntax for Spicepod manifests' sidebar_position: 1 sidebar_label: 'Spicepod specification' description: 'Detailed documentation on the Spicepod manifest syntax (spicepod.yaml)' tags:

• reference
• spicepod
• yaml
• manifest

Spicepod manifests use YAML syntax. By default they are stored in the root directory of the application and named spicepod.yaml or spicepod.yml — when the runtime is given a directory path, it looks for one of those two filenames. The runtime also accepts any YAML file path directly (e.g. spiced ./configs/my-app.yaml); files passed by path must declare kind: Spicepod and a recognized version and are otherwise rejected with an explicit error.

:::info[Tip]

Readers who are new to YAML can find a primer in "Learn YAML in Y minutes (opens in a new tab)."

:::

version

The version of the Spicepod manifest. The current version is v2.

kind

The kind of Spicepod manifest. The kind is Spicepod.

name

The name of the Spicepod.

secrets

The secrets section in the Spicepod manifest is optional and is used to configure how secrets are stored and accessed by the Spicepod. For more information, see Secret Stores (opens in a new tab).

secrets.from

The from field is a string that represents the Uniform Resource Identifier (URI) for the secret store. This URI is composed of two parts: a prefix indicating the Secret Store to use, and an optional selector that specifies the secret to retrieve.

The syntax for the from field is as follows:

from: <secret_store>:<selector>

from: <secret_store>:<selector>

Where:

• <secret_store>: The Secret Store to use

  Currently supported secret stores:

  • env (opens in a new tab)
  • kubernetes (opens in a new tab)
  • keyring (opens in a new tab)
  • aws-secrets-manager (opens in a new tab)

  If no secret stores are explicitly specified, it defaults to env.

• <selector>: The secret within the secret store to load.

The type of secret store for reading secrets.

Example

secrets:
  - from: env
    name: env

secrets:
  - from: env
    name: env

secrets.name

The name of the secret store. This is used to reference the store in the secret replacement syntax, ${<secret_store_name>:<key_name>}.

runtime

The runtime section specifies configuration settings for the Spice runtime. For detailed documentation, see the Runtime YAML reference (opens in a new tab).

metadata

An optional map of metadata.

Example

metadata:
  epoch_time: 1605312000
  period: 72h
  interval: 1m
  granularity: 10s
  episodes: 10

metadata:
  epoch_time: 1605312000
  period: 72h
  interval: 1m
  granularity: 10s
  episodes: 10

datasets

A Spicepod can contain one or more datasets (opens in a new tab) referenced by relative path.

Example

A datasets referenced by relative path.

datasets:
  - ref: datasets/uniswap_v2_eth_usdc

datasets:
  - ref: datasets/uniswap_v2_eth_usdc

A dataset defined inline.

datasets:
  - from: spice.ai/spiceai/quickstart/datasets/taxi_trips
    name: taxi_trips
    acceleration:
      enabled: true
      refresh_mode: full
      refresh_check_interval: 1h

datasets:
  - from: spice.ai/spiceai/quickstart/datasets/taxi_trips
    name: taxi_trips
    acceleration:
      enabled: true
      refresh_mode: full
      refresh_check_interval: 1h

catalogs

A Spicepod can contain one or more catalogs (opens in a new tab), each of which connects to an external data catalog and exposes its schemas and tables without a dataset entry per table.

Example

catalogs:
  - from: spice.ai:demo-org/tpch # The `tpch` app of the `demo-org` organization
    name: marketplace
    params:
      spiceai_api_key: ${secrets:SPICEAI_API_KEY}
      spiceai_region: us-east-1
    include:
      - 'tpch.*' # Include only the "tpch" tables.

catalogs:
  - from: spice.ai:demo-org/tpch # The `tpch` app of the `demo-org` organization
    name: marketplace
    params:
      spiceai_api_key: ${secrets:SPICEAI_API_KEY}
      spiceai_region: us-east-1
    include:
      - 'tpch.*' # Include only the "tpch" tables.

snapshots {#snapshots}

:::warning[Deprecated] The top-level snapshots section is deprecated and will be removed in a future release. Snapshots are stored in the snapshots/ folder of runtime.state.location (opens in a new tab). A dataset overrides the location, params, and failure behavior with acceleration.snapshots_location (opens in a new tab), acceleration.snapshots_params (opens in a new tab), and acceleration.snapshots_bootstrap_on_failure_behavior (opens in a new tab). A Spicepod that sets the section logs a startup warning that shows the replacement configuration. See Migrate from the top-level snapshots section (opens in a new tab). :::

Optional. Configure managed acceleration snapshots that Spice can use to bootstrap file-based accelerations. When enabled, datasets that opt in with acceleration.snapshots (opens in a new tab) will download database files from the snapshot location if the local file is missing, and will optionally write new snapshots after each refresh. DuckDB, SQLite, Cayenne, and Turso accelerations running in mode: file are supported, and each dataset must write to its own file path.

snapshots:
  enabled: true
  location: s3://my_bucket/snapshots/
  bootstrap_on_failure_behavior: warn # warn | retry | fallback
  params:
    s3_auth: iam_role

snapshots:
  enabled: true
  location: s3://my_bucket/snapshots/
  bootstrap_on_failure_behavior: warn # warn | retry | fallback
  params:
    s3_auth: iam_role

snapshots.enabled

Enable or disable snapshot management globally. Defaults to true.

snapshots.location

The folder where snapshots are stored. Supports S3 bucket URIs (s3://bucket/prefix/), Azure ADLS Gen2 URIs (abfss://container@account.dfs.core.windows.net/path/), Google Cloud Storage URIs (gs://bucket/prefix/), and local filesystem URIs (file:///path/to/folder/). The value must be a URI with a scheme: a bare filesystem path such as /var/spice/snapshots is not a valid URI, so it fails to parse and snapshots are disabled with an error logged. The location must resolve to a single folder; Spice creates per-dataset folders underneath using Hive-style partitions (month=YYYY-MM/day=YYYY-MM-DD/dataset=<name>).

When location is not set and the Spicepod sets runtime.state (opens in a new tab), snapshots go to <runtime.state.location>/snapshots/. A location that is set takes precedence over runtime.state, and a dataset's acceleration.snapshots_location takes precedence over location. See Store snapshots under runtime.state (opens in a new tab).

The location's store must enforce conditional writes (create only if absent, update only at the version read), because every publisher updates the location's shared metadata.json with them. Amazon S3, Azure ADLS Gen2, Google Cloud Storage, and local file:// directories do. Each Spice instance probes the store before it creates a dataset's first snapshot, and refuses a store that does not enforce them. The probe creates, updates, and then deletes a .spice-conditional-write-probe-<id> object under the location. The credentials of every instance that publishes snapshots need permission to create and update that object. Permission to delete it is needed only for cleanup: a failed delete does not change the probe result and leaves the probe object behind. See Conditional writes on the snapshot location (opens in a new tab).

Keep a cloud location on standard S3, GCS, or ADLS so bucket or object replication and readers in another region can use the prefix. Each snapshot written there is a complete copy of the acceleration file. This location is separate from Cayenne's S3 Express One Zone data tier (cayenne_file_path, cayenne_s3_*), which does not substitute for the snapshot bucket. See Snapshots (opens in a new tab).

snapshots.bootstrap_on_failure_behavior

Controls what happens when Spice cannot load the most recent snapshot on startup, for datasets that do not set acceleration.snapshots_bootstrap_on_failure_behavior. Valid values:

• warn (default) – Log a warning and continue with an empty acceleration.
• retry – Retry the newest snapshot until it loads successfully.
• fallback – Attempt older snapshots in the same dataset folder until one works.

snapshots.params

Optional key-value map passed to the snapshot storage layer. When location points to S3, params accepts these S3 parameters (opens in a new tab): s3_region, s3_endpoint, s3_auth (iam_role or key; default iam_role), s3_key, s3_secret, s3_session_token, s3_queue_url, client_timeout, and allow_http. Spice ignores other keys and logs a warning for each. Snapshots default to s3_auth: iam_role, which differs from the S3 dataset default of public. With s3_auth: key, both s3_key and s3_secret must be set, or the snapshot location is not used and Spice logs an error. Azure ADLS locations also accept the Azure connector parameters, and GCS locations the GCS connector parameter names (such as gcs_service_account_key), for explicit credential overrides; when no overrides are supplied, Spice reads standard environment variables for each cloud provider. Values can reference secrets with ${secrets:<name>} for all three. An invalid S3 parameter value, such as s3_auth: public, disables snapshots for the dataset with an error; Spice does not fall back to default parameters. When s3_queue_url is set, the dataset fails to register with the parameter error instead.

For snapshots stored under runtime.state, params replaces runtime.state.params as a whole. When params is not set, those snapshots use runtime.state.params. A dataset that sets acceleration.snapshots_params uses those instead, and a dataset that sets acceleration.snapshots_location without snapshots_params uses no params.

models

A Spicepod can contain one or more models (opens in a new tab) referenced by relative path.

Example

A model referenced by path.

models:
  - from: models/drive_stats

models:
  - from: models/drive_stats

A model defined inline.

models:
  - from: spice.ai:openai/gpt-4o
    name: cloud_llm
    params:
      spiceai_api_key: ${secrets:SPICEAI_API_KEY}

models:
  - from: spice.ai:openai/gpt-4o
    name: cloud_llm
    params:
      spiceai_api_key: ${secrets:SPICEAI_API_KEY}

embeddings

A Spicepod can contain one or more embeddings (opens in a new tab) referenced by relative path.

Example

An embeddings model referenced by path.

embeddings:
  - from: embeddings/openai_text_embedding_3

embeddings:
  - from: embeddings/openai_text_embedding_3

An embedding defined inline.

embeddings:
  - name: hf_baai_bge
    from: huggingface:huggingface.co/BAAI/bge-small-en-v1.5

embeddings:
  - name: hf_baai_bge
    from: huggingface:huggingface.co/BAAI/bge-small-en-v1.5

dependencies

A list of dependent Spicepods.

dependencies:
  - lukekim/demo
  - spicehq/nfts

dependencies:
  - lukekim/demo
  - spicehq/nfts

views {#views}

A Spicepod can contain one or more views which are virtual tables defined by SQL queries.

Example

views:
  - name: rankings
    sql: |
      WITH a AS (
        SELECT products.id, SUM(count) AS count
        FROM orders
        INNER JOIN products ON orders.product_id = products.id
        GROUP BY products.id
      )
      SELECT name, count
      FROM products
      LEFT JOIN a ON products.id = a.id
      ORDER BY count DESC
      LIMIT 5

views:
  - name: rankings
    sql: |
      WITH a AS (
        SELECT products.id, SUM(count) AS count
        FROM orders
        INNER JOIN products ON orders.product_id = products.id
        GROUP BY products.id
      )
      SELECT name, count
      FROM products
      LEFT JOIN a ON products.id = a.id
      ORDER BY count DESC
      LIMIT 5

workers

A Spicepod can contain one or more workers (opens in a new tab) defining configurable units of compute.

Example

workers:
  - name: round-robin
    description: |
      Distributes requests between 'llama3_2' and 'gpt4_1' models in a round-robin fashion.
    load_balance:
      routing:
        - from: llama3_2
        - from: gpt4_1
  - name: fallback
    description: |
      Attempts 'gpt4_1' first, then 'llama3_2', then 'anth_haiku' if previous models fail.
    load_balance:
      routing:
        - from: llama3_2
          order: 2
        - from: gpt4_1
          order: 1
        - from: anth_haiku
          order: 3
  - name: weighted
    description: |
      Routes 80% of traffic to 'llama3_2'.
    load_balance:
      routing:
        - from: llama3_2
          weight: 4
        - from: gpt4_1
          weight: 1

workers:
  - name: round-robin
    description: |
      Distributes requests between 'llama3_2' and 'gpt4_1' models in a round-robin fashion.
    load_balance:
      routing:
        - from: llama3_2
        - from: gpt4_1
  - name: fallback
    description: |
      Attempts 'gpt4_1' first, then 'llama3_2', then 'anth_haiku' if previous models fail.
    load_balance:
      routing:
        - from: llama3_2
          order: 2
        - from: gpt4_1
          order: 1
        - from: anth_haiku
          order: 3
  - name: weighted
    description: |
      Routes 80% of traffic to 'llama3_2'.
    load_balance:
      routing:
        - from: llama3_2
          weight: 4
        - from: gpt4_1
          weight: 1

For a complete specification of worker configuration, see the Workers Reference (opens in a new tab).

rerankers

A Spicepod can contain one or more reranker models, which reorder search results by relevance. See Reranking (opens in a new tab) for the supported providers and how to use a reranker in a query.

Example

rerankers:
  - from: cohere:rerank-v3.5
    name: cohere_rr
    params:
      api_key: ${secrets:COHERE_API_KEY}

rerankers:
  - from: cohere:rerank-v3.5
    name: cohere_rr
    params:
      api_key: ${secrets:COHERE_API_KEY}

tools

A Spicepod can contain one or more tools (opens in a new tab) that the runtime or a language model can call, such as tools served by an MCP server.

Example

tools:
  - name: my_mcp_tool
    from: mcp:http://localhost:8090/v1/mcp
    description: 'An MCP tool.'

tools:
  - name: my_mcp_tool
    from: mcp:http://localhost:8090/v1/mcp
    description: 'An MCP tool.'

functions

A Spicepod can contain one or more functions (opens in a new tab), user-defined scalar or table functions that Spice registers in its SQL engine. The functions section is used only when runtime.functions.enabled (opens in a new tab) is true.

Example

runtime:
  functions:
    enabled: true

functions:
  - name: double_it
    from: sql
    description: Double a 64-bit integer.
    volatility: immutable
    signature:
      args:
        - { name: x, type: int64 }
      returns: int64
    body: 'x * 2'

runtime:
  functions:
    enabled: true

functions:
  - name: double_it
    from: sql
    description: Double a 64-bit integer.
    volatility: immutable
    signature:
      args:
        - { name: x, type: int64 }
      returns: int64
    body: 'x * 2'

management

Optional. Connects a self-hosted runtime to the Spice Cloud Platform (opens in a new tab), which receives the runtime's task history. api_key and params.region are required: the connection to Spice Cloud fails without a region.

Example

management:
  api_key: ${secrets:SPICEAI_API_KEY}
  params:
    region: us-east-1 # The Spice Cloud region of the target app

management:
  api_key: ${secrets:SPICEAI_API_KEY}
  params:
    region: us-east-1 # The Spice Cloud region of the target app