Upgrade Guide from v1.x to v2.x | Changelog | Spice.ai Cloud Documentation

For the complete documentation index, see llms.txt. This page is also available as Markdown.

Most v1 spicepods continue to work on v2.0 — v1 remains supported and deprecated fields auto-migrate at load time — so many deployments can upgrade by updating the image alone. The steps below cover the breaking changes that may require manual action. Review each before upgrading a production deployment. For the full v2.0 changelog, see the OSS release notes.

1. Adopt Spicepod v2 (recommended)

spice init now creates version: v2 spicepods. v1 spicepods remain supported with automatic migration, but v1beta1 is no longer accepted. To move to v2, set version: v2 and update the following fields — each auto-migrates from v1, but updating now clears the deprecation:

2. Update changed configuration

• DuckDB parameter rename: partitioned_write_flush_threshold → partitioned_write_flush_threshold_rows.
• Default query memory limit raised from 70% to 90%. If you relied on the previous default to leave headroom for other processes on the host, set it explicitly via runtime.query.memory_limit.

3. Update queries and API clients

• S3 metadata columns renamed: location, last_modified, size → _location, _last_modified, _size. Update any queries that reference these columns.
• /v1/search always returns an array in matches, even for a single result. Update clients that assumed a scalar value.
• /v1/evals API removed. Remove integrations that depend on it.

4. Update model providers

• Perplexity model provider removed. Re-point affected models to another provider.
• x.ai models use the /v1/responses endpoint exclusively. Ensure x.ai integrations target the Responses API.

5. Update observability

• Metric renames: accelerated_refresh → acceleration_refresh, and the last_refresh_time gauge is renamed to include the milliseconds unit. Update dashboards and alerts that reference these metric names.

Last updated 1 month ago