docs: Document refresh_mode: snapshot

Add documentation for the new snapshot refresh mode that creates
read-only accelerations driven exclusively from the snapshot store.

Also remove the Cayenne single-dataset-per-spicepod snapshot limitation,
which was lifted by per-dataset metastore slices.

Source: spiceai/spiceai#10651

Author: claudespice

website/docs/features/data-acceleration/data-refresh.md

@@ -21,14 +21,15 @@ Acceleration data can be refreshed (updated) by:
 
 ## Refresh Modes
 
-Spice supports four modes to refresh/update local data from a connected data source. `full` is the default mode.
+Spice supports five modes to refresh/update local data from a connected data source. `full` is the default mode.
 
-| Mode      | Description                                          | Example                                                          |
-| --------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
-| `full`    | Replace/overwrite the entire dataset on each refresh | A table of users                                                 |
-| `append`  | Append/add data to the dataset on each refresh       | Append-only, immutable datasets, such as time-series or log data |
-| `changes` | Apply incremental changes                            | Customer order lifecycle table                                   |
-| `caching` | Read-through caching for SQL queries                 | API search results or dynamic content endpoints                  |
+| Mode       | Description                                          | Example                                                          |
+| ---------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| `full`     | Replace/overwrite the entire dataset on each refresh | A table of users                                                 |
+| `append`   | Append/add data to the dataset on each refresh       | Append-only, immutable datasets, such as time-series or log data |
+| `changes`  | Apply incremental changes                            | Customer order lifecycle table                                   |
+| `caching`  | Read-through caching for SQL queries                 | API search results or dynamic content endpoints                  |
+| `snapshot` | Reload exclusively from the snapshot store           | Read-only replicas bootstrapped from centralized snapshots       |
 
 Learn more about each mode:
 
@@ -136,6 +137,48 @@ The `caching` refresh mode is designed for HTTP-based datasets where request met
 
 See [Caching Mode](./refresh-modes/caching) for detailed documentation and examples.
 
+### Snapshot
+
+The `snapshot` refresh mode creates a read-only acceleration that reloads exclusively from the [snapshot store](./snapshots). The federated data source is never queried for refreshes — instead, the runtime polls the snapshot store on a configurable interval and atomically swaps in newer snapshots when available.
+
+```yaml
+snapshots:
+  enabled: true
+  location: s3://my-bucket/snapshots/
+  params:
+    s3_auth: iam_role
+
+datasets:
+  - from: postgres:public.my_table
+    name: my_table
+    acceleration:
+      enabled: true
+      engine: duckdb
+      mode: file
+      refresh_mode: snapshot
+      refresh_check_interval: 30s  # Poll interval; defaults to 1m
+      snapshots: enabled
+      params:
+        duckdb_file: /nvme/my_table.db
+```
+
+**Requirements:**
+
+- `acceleration.snapshots` must be `enabled` or `bootstrap_only`
+- The acceleration engine must be a snapshot-capable file-based engine: **DuckDB**, **SQLite**, **Cayenne**, or **Turso**
+
+**Behavior:**
+
+- On startup, the runtime bootstraps from the most recent snapshot (same as other snapshot-enabled modes)
+- After bootstrap, the runtime polls the snapshot store at `refresh_check_interval` (default: 60 seconds) for newer snapshots
+- When a newer snapshot is found, its schema is validated against the current acceleration schema before downloading
+- The accelerator file is swapped atomically — queries continue to be served from the previous snapshot until the swap completes
+- `INSERT INTO` statements are rejected with an error since the acceleration is driven exclusively from snapshots
+
+:::tip
+Use `refresh_mode: snapshot` for read-only replicas that don't need direct access to the federated source — for example, edge nodes that receive snapshots from a centralized writer.
+:::
+
 ## Ready State
 
 |                             |           |

website/docs/features/data-acceleration/snapshots.md

@@ -290,6 +290,5 @@ For the full reference, see [`snapshots` in the Spicepod specification](../../re
 :::warning[Limitations]
 
 - Only datasets are supported for snapshots. Views are not supported.
-- When using Cayenne accelerations, snapshots are supported only when one dataset is configured per spicepod.
 
 :::

website/docs/reference/spicepod/datasets.md

@@ -23,7 +23,7 @@ datasets:
       mode: memory # / file
       engine: arrow # / cayenne / duckdb / sqlite / postgres / turso
       refresh_check_interval: 1h
-      refresh_mode: full / append # / changes / caching
+      refresh_mode: full / append # / changes / caching / snapshot
 ```
 
 `spicepod.yaml`
@@ -39,7 +39,7 @@ datasets:
       mode: memory # / file
       engine: arrow # / cayenne / duckdb / sqlite / postgres / turso
       refresh_check_interval: 1h
-      refresh_mode: full / append # / changes / caching
+      refresh_mode: full / append # / changes / caching / snapshot
 ```
 
 Relative path example:
@@ -436,6 +436,7 @@ Optional. How to refresh the dataset. The following values are supported:
 - `append` - Append new data to the dataset. When `time_column` is specified, new records are fetched from the latest timestamp in the accelerated data at the `acceleration.refresh_check_interval`.
 - `changes` - Apply change data capture (CDC) events to incrementally update the dataset.
 - `caching` - Cache data based on request metadata (HTTP requests). Uses row-level replacement based on cache keys. See [Caching Mode](../../features/data-acceleration/refresh-modes/caching) for details.
+- `snapshot` - Reload exclusively from the [snapshot store](../../features/data-acceleration/snapshots). The federated source is never queried; the runtime polls for newer snapshots at `refresh_check_interval` (default: 60s). Requires `acceleration.snapshots: enabled` or `bootstrap_only` and a snapshot-capable file-based engine (DuckDB, SQLite, Cayenne, or Turso). Writes (`INSERT INTO`) are rejected. See [Snapshot Refresh Mode](../../features/data-acceleration/data-refresh#snapshot).
 
 ## `acceleration.refresh_check_interval`