Skip to main content

Spice v2.3.1 (Sep 15, 2026)

· 14 min read
Phillip LeBlanc
Phillip LeBlanc
Co-Founder and CTO of Spice AI

Spice v2.3.1 is now available! 🛠️

Spice v2.3.1 is a patch release that improves performance of filtered Vortex scans, cache eviction, and query planning. It also improves installation reliability, subquery fallback, numeric conversion, and Cayenne writes. The MCP server and client support the 2026-07-28 revision of the Model Context Protocol.

Highlights in v2.3.1 include:

  • Ordered Full Refreshes — Cayenne applies sort_columns when a full refresh replaces a table
  • CTE Materialization — Cayenne computes a multi-reference CTE once under runtime.query.cte_materialization: auto
  • Faster Vortex Scans — selective filters read fewer bytes, and zones skip unrelated scan splits
  • Faster IN Lists — Vortex uses a set probe for large constant lists
  • Reusable Parameterized Plans — all parameter values use the same cached plan without sharing results
  • Reliable Cache Eviction — declared keys and timestamp ties do not prevent eviction
  • Installer and Container Reliability — the installer validates each archive, and scratch images provide a writable temporary directory
  • Cayenne Memory-Mode DML — DELETE, UPDATE, and INSERT is now supported when the acceleration uses the default in-memory mode
  • MCP 2026-07-28 — the MCP server and client speak the new revision, and legacy initialize clients keep working
  • Connector Fixes — SMB share roots load on Samba, regexp_match answers faithfully on DuckDB, and S3 retry warnings read as one line

What's New in v2.3.1​

Cayenne Applies sort_columns During Full Refreshes​

Cayenne previously applied sort_columns only during compaction. A dataset with refresh_mode: full replaces its table, so it did not run that compaction. Cayenne now sorts the replacement stream before it writes the refreshed table, and the ordered files let min/max statistics exclude unrelated files from selective queries.

In the reported TPC-H SF1 benchmark, point-lookup p50 latency improved by 16%, and the same query used 37% less CPU. The sort adds work to each full refresh, so only datasets that configure sort_columns pay this cost. See Full Refresh for full-refresh configuration.

Cayenne Materializes Multi-Reference CTEs​

DataFusion inlines a WITH body when it binds a query, so it plans and executes a twice-referenced CTE twice. This release adds the setting runtime.query.cte_materialization, which accepts disabled and auto. The default is disabled, and it keeps the previous behavior.

Under auto, Cayenne computes an expensive multi-reference CTE once into a memory-accounted buffer, and each reference reads that buffer. A CTE body counts as expensive when it contains an aggregation, a join, a window function, a distinct, a sort, an unnest, or a union. A pass-through CTE stays inlined, so projection pushdown can still prune its columns. The setting has no effect on a query that does not scan a Cayenne-accelerated dataset.

runtime:
  query:
    cte_materialization: auto # disabled (default) | auto

See the Runtime reference for the other query settings.

Faster Vortex Scans​

Vortex now waits for a pushed-down filter before it prepares projected column readers, so a split with no matching rows does not prepare those readers. Selective queries in the reported benchmarks read 45% to 58% fewer bytes, and bandwidth-constrained storage showed the largest latency improvements.

Vortex also checks each scan split against its zone statistics, and it returns an empty stream when the split cannot contain a matching row. In the reported TPC-H SF1 benchmark, point-lookup p50 latency improved by 12%, and CPU use per query fell by 53%. Nonselective scans do not use these shortcuts and remain unchanged within the reported run-to-run variation.

Large IN Lists Run Faster​

Vortex previously evaluated a constant IN list once for every row and every list item, so runtime grew with both dimensions. Vortex now builds a set once and probes it in one pass, and it uses value intervals to reject files before a scan.

A 32,768-value list over 1,048,576 rows fell from 44.57 seconds to 225 milliseconds in the reported benchmark. Small lists keep their existing evaluation path.

Parameterized Queries Reuse Logical Plans​

The logical-plan cache previously included each bound parameter value in its key, so each value tuple created another entry for the same SQL text. The cache now stores an unbound plan for each SQL statement, and Spice binds the current values after it reads the plan. The SQL results cache still includes parameter values in its keys, so a result only matches a query with the same values.

The reported point-lookup benchmark improved p50 latency by 12.4% and p99 latency by 31.7%, and parameterized traffic creates fewer duplicate entries. Indexed primary-key lookups now report an exact row count to the query planner, so DataFusion can avoid an unnecessary repartition for a single-row probe.

Caching Accelerations Evict Reliably​

A refresh_mode: caching dataset can use size and row-count limits, and two defects could let the cache exceed these limits. A declared primary_key could expand the eviction key to the entire stored row, and an index marked as unique had the same fault. A Map column in the expanded key then made every sweep fail. Spice now keeps the group key limited to the request columns, and a refreshed entry also removes rows that disappeared from its latest response.

Many responses can share the same one-second fetch timestamp. The previous eviction predicate could then remove only 512 entries when this tie crossed the survivor boundary. The eviction sweep now combines a timestamp range with named boundary entries. The range removes the older bulk, so eviction converges under sustained ingestion.

Federation and Runtime Improvements​

  • DuckDB and SQLite accelerations now handle more subqueries with on_zero_results: use_source. This includes mixed fallback policies and ANY or ALL comparisons.
  • Decimal-to-float casts now preserve the expected rounded value after a federated aggregate. For example, a PostgreSQL average of 47.5 returns 47.5.
  • Cayenne uses asynchronous filesystem calls from its asynchronous code. A slow data directory does not block the Tokio runtime at these call sites.

Installer and Container Reliability​

The runtime installer now retries unsuccessful HTTP responses and invalid archives, and it accepts an archive only when it contains a regular spiced executable. The installer sends a configured token to GitHub release requests, and it does not send that token to runtime download hosts. On native Windows, spice upgrade now rejects the unsupported runtime upgrade instead of continuing with a partial upgrade.

The scratch-based standard and release images now provide a writable temporary directory at /app/tmp, which supports operations such as acceleration snapshot uploads.

Cayenne Memory-Mode DML Works as Expected​

A Cayenne acceleration uses mode: memory by default. Before this release, filtered DML statements did not change its in-memory rows as requested.

  • A filtered DELETE reported zero affected rows and left each matching row in place.
  • An UPDATE could create a duplicate live row for the same primary key.
  • An INSERT over an existing primary key could keep both versions of the row.

DELETE, UPDATE, and INSERT now update the in-memory tier. The append path also enforces each declared primary_key according to its on_conflict setting. The SQL DML reference lists the supported statements.

Cayenne Uses Less Memory for Primary-Key Work​

Cayenne now releases the keyset bytes that an abandoned primary-key checkout counted. A cancelled validation stream, or an apply that fails before the store, previously left a phantom reservation behind. That reservation counted against the table's memory account and the keyset ceiling until the next publish replaced the figure. Sibling tables then received a smaller keyset budget than their real use warranted. Cayenne always discarded the keys themselves, so no query returned wrong rows.

Cayenne also allocates less during primary-key validation and deletion filtering:

  • The membership set for incoming keys holds only the precomputed digests.
  • Conflict and bloom checks borrow the encoded row. Cayenne copies the key bytes only for a row that it retains.
  • A scan reuses its row-encoding buffers between batches. The runtime charges each retained buffer to the query memory pool.

MCP Specification 2026-07-28​

Spice supports revision 2026-07-28 of the Model Context Protocol on /v1/mcp. A modern client calls server/discover and sends per-request _meta, and it can call tools/list and tools/call without a prior initialize request. These requests carry no session, so the runtime mints no Mcp-Session-Id. A legacy client keeps its current behavior. It sends initialize and notifications/initialized, receives an Mcp-Session-Id, and sends that header on each later request. GET /v1/mcp and DELETE /v1/mcp stay legacy-only.

The runtime accepts every revision from 2024-11-05 to 2026-07-28, and it advertises 2026-07-28. An unknown version returns JSON-RPC error -32022, and data.supported lists the accepted revisions. A Streamable HTTP header that does not match the request body returns HTTP 400 and error -32020. The MCP client for stdio and Streamable HTTP catalogs prefers server/discover with 2026-07-28. It falls back to initialize with 2025-03-26 when the server does not support the new revision.

/v1/mcp now checks the browser Origin header. Read Breaking Changes before you upgrade a remote browser client.

Chunked Search Indexes Drop Superseded Chunks​

A chunked search index stores one entry for each text chunk of a source row. A write upserts the chunks that the current text produces. Before this release, a row whose new text produced fewer chunks kept the extra chunks of the previous text. A search could return a row for text that the dataset no longer holds, and the runtime reported no error. An index that can enumerate its own entries now deletes the chunks that a shortened row no longer produces. A co-located index needs no cleanup, because its entries live in the accelerated row.

Connector Bug Fixes​

  • SMB: A dataset whose from: names the share root failed to load on Samba with SMB error 0xC000000D. The connector sent a CREATE request with an empty dynamic buffer, and Samba rejects a frame that declares dynamic bytes and carries none. The connector now pads an empty buffer with one zero byte, and the error message names <share root> for an empty path.
  • DuckDB: A federated regexp_match call returned the whole match instead of the capture groups. A row with no match returned [''] instead of NULL, so IS NULL answered false. The DuckDB dialect rewrote the call to regexp_extract, which answers a different question. Spice now evaluates regexp_match above the federated scan with the DataFusion implementation.
  • S3: A connection that closed before the response headers arrived printed a multi-line OpenDAL diagnostic at WARN level. The runtime now prints one line that names the file, the scheduled retry, the cause, and the action to take. Set opendal::layers::retry=debug for the full diagnostic. The retry policy is unchanged.

Dependency Updates​

Compared with v2.3.0, this release changes the following versions:

Dependency / Componentv2.3.0v2.3.1
rmcpv1.5.0v3.3.0

DataFusion remains at v54.1.0, Arrow remains at v58.3.0, and Vortex remains at v0.79.0. Spice updates the Arrow and DataFusion fork revisions for the Decimal-to-Float rounding fix and the scan improvements described above.

Contributors​

Breaking Changes​

/v1/mcp now checks the browser Origin header against runtime.cors.allowed_origins. A request with an Origin that is not on the list receives HTTP 403. The default value ["*"], and an empty list, expand to the localhost origins. A client that sends no Origin header, or a localhost Origin, still passes, so most desktop MCP clients are unaffected.

If a remote browser client calls /v1/mcp, set an explicit list before you upgrade:

runtime:
  cors:
    enabled: true
    allowed_origins:
      - 'https://app.example.com'

CORS on the other HTTP endpoints is unchanged. runtime.mcp.allowed_hosts: ["*"] still disables the Host check.

A modern MCP client must send the headers MCP-Protocol-Version, Mcp-Method, and, for tools/call, Mcp-Name. It must also send per-request _meta. An argument that carries the x-mcp-header annotation needs a matching Mcp-Param-* header. These requirements come from the 2026-07-28 specification. A legacy client that sends initialize needs no change.

Cookbook Updates​

No new cookbook recipes.

The Spice Cookbook includes more than 104 recipes to help you get started with Spice quickly and easily.

Upgrading​

To upgrade to v2.3.1, use one of the following methods:

CLI:

spice upgrade

Homebrew:

brew upgrade spiceai/spiceai/spice

Docker:

Pull the spiceai/spiceai:2.3.1 image:

docker pull spiceai/spiceai:2.3.1

For available tags, see DockerHub.

Helm:

helm repo update
helm upgrade spiceai spiceai/spiceai --version 2.3.1

AWS Marketplace:

Spice is available in the AWS Marketplace.

What's Changed​

Changelog​

  • fix(duckdb): deny the regexp built-ins DuckDB cannot answer faithfully (fixes #13809) by @claudespice in #13871
  • feat(cayenne): materialize multi-reference CTEs on the query path by @lukekim in #13918
  • fix(cayenne): release the keyset bytes an abandoned PK checkout accounted (fixes #13668) by @grokspice in #13925
  • fix(search): drop the chunks a shortened row no longer produces from a chunked index (refs #13717) by @claudespice in #13960
  • fix(arrow): report an exact row count from the indexed point-lookup scan by @krinart in #13972
  • fix(caching): keep a declared key from disabling eviction and stranding stale rows (fixes #13976) by @bjchambers in #13992
  • Reduce Cayenne allocations during primary-key validation and filtering by @lukekim in #14009
  • fix(deps): bump arrow-rs to correctly-rounded Decimal→Float cast (closes #13978) by @Jeadie in #14012
  • fix(caching): partition doomed entries at the survivor cutoff so eviction converges (closes #13994) by @Jeadie in #14021
  • Fix subqueries with use_source acceleration by @phillipleblanc in #14022
  • fix: restore OSS installer, CLI and test workflow coverage by @phillipleblanc in #14025
  • perf(vortex): defer projection setup on filtered scans until the filter resolves by @bjchambers in #14035
  • fix: clarify OpenDAL S3 retry warnings by @lukekim in #14040
  • feat(mcp): support MCP specification 2026-07-28 (dual-era) by @lukekim in #14043
  • fix(cayenne): make DELETE, UPDATE and INSERT work on a mode: memory acceleration (fixes #12008) by @bjchambers in #14047
  • fix(deps): bump arrow-rs fork pin for Decimal->Float rounding fix by @Jeadie in #14049
  • fix(smb): pad an empty CREATE buffer so Samba lists the share root (fixes #13293) by @grokspice in #14050
  • perf(vortex): answer a constant IN list by probing a set, and falsify it by interval by @bjchambers in #14061
  • fix(cayenne): apply sort_columns with refresh_mode: full by @peasee in #14063
  • perf(vortex): skip a scan split whose zones cannot satisfy the filter by @peasee in #14064
  • perf(cache): key the logical-plan cache on SQL text, not parameter values by @bjchambers in #14069
  • fix(cayenne): move accelerator filesystem I/O off Tokio workers by @lukekim in #14073
  • fix: Provide temporary directory in docker images by @Jeadie in #14089

Full Changelog: https://github.com/spiceai/spiceai/compare/v2.3.0...v2.3.1