The snapshot refresh mode creates a read-only acceleration that reloads exclusively from the snapshot store (opens in a new tab). The federated 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.
Use snapshot when:
To read snapshots published to S3 without naming the original federated source, an engine, or a top-level snapshots section, set the dataset's from to the snapshot location and file_format: snapshot. See Serve a dataset from published snapshots (opens in a new tab).
This reader sets acceleration.snapshots_location (opens in a new tab) to the folder the writer publishes to, so it needs only read access to the snapshots. It could instead set runtime.state (opens in a new tab) to the writer's state location, whose snapshots/ folder holds the snapshots. An instance with runtime.state checks the location at startup, which needs write access under _spice/, and does not report ready until the check (opens in a new tab) passes, even though snapshot reads do not wait for it.
acceleration.snapshots must be enabled or bootstrap_only. Snapshot mode is a snapshot consumer only, so the two behave identically here: creation is skipped for the mode entirely and the dataset never publishes new snapshots — a separate writer must produce them.bootstrap_on_failure_behavior is set to. Spice logs Snapshot acceleration for dataset 'my_table' is waiting for its first snapshot, checks the location every refresh_check_interval, and restores the first snapshot once a writer publishes it.refresh_check_interval (default: 60s) for newer snapshots.from source, although it does not query that source. When the source is unavailable from startup, for example because its table does not exist or its credentials are rejected, the connection is not created, and the dataset keeps serving the snapshot it bootstrapped from without loading newer snapshots until the source becomes reachable. An outage that starts after the connection was created does not block polling. A dataset whose from is the snapshot location (file_format: snapshot) is not affected. Starting in v2.5, the refresh polls the snapshot store without waiting for the source.ETag recorded by the previous poll in If-None-Match. When the store reports that the metadata is unchanged, the poll ends without downloading it.:::tip
Use refresh_mode: snapshot for read-only replicas that should not access the federated source — for example, edge nodes that receive snapshots from a centralized writer.
:::
A reader that only polls loads a new snapshot up to one refresh_check_interval after a writer publishes it. When the snapshot location is on Amazon S3, set s3_queue_url in the location's params (runtime.state.params, or a dataset's snapshots_params (opens in a new tab)) to an Amazon SQS queue that receives the location's S3 event notifications (opens in a new tab), and refresh_mode: snapshot datasets reload as soon as a new snapshot is published:
A writer makes a snapshot current by rewriting the location's metadata.json, so an ObjectCreated notification for that object triggers the reload. Spice reads metadata.json once for each batch of such notifications it receives and reloads only the datasets whose current snapshot changed, with the same snapshot id, schema, and checksum checks as a poll. Notifications for snapshot files and for removed objects are deleted from the queue without a reload. A reader that is still waiting for its first snapshot restores it when the notification arrives.
Set up the queue as follows:
refresh_mode: snapshot datasets in one process share that process's queue. Snapshot locations in one process that name the same queue share one consumer, which reads the queue with the credentials of the first location. A location that names the queue with other credentials logs a warning that names both locations.snapshots/ folder of runtime.state.location, the notification can cover the whole runtime.state prefix: notifications for the other runtime state folders (opens in a new tab), such as the scheduler's cluster/ folder, are deleted from the queue without a log.s3_key and s3_secret when both are set, otherwise the default AWS credential chain. The region comes from the queue URL. Grant sqs:ReceiveMessage and sqs:DeleteMessage on the queue.Datasets keep checking the location every refresh_check_interval, which covers notifications that never arrive. When Spice cannot reach SQS, it logs a warning when the outage starts, an error if it lasts five minutes, and an info message when it recovers. Datasets reload on refresh_check_interval in the meantime.
A queue URL that is empty, is an ARN, or is not an SQS queue URL, and a snapshot location that is not s3://, fail the dataset at load with an error that names s3_queue_url. When s3_queue_url is set but no dataset uses refresh_mode: snapshot, Spice logs a warning that names the setting that holds the queue, such as runtime.state.params.s3_queue_url, and does not read the queue. A cluster scheduler, which loads no accelerations, does not log this warning. A dataset that reads snapshots with file_format: snapshot (opens in a new tab) does not accept s3_queue_url and checks for new snapshots every refresh_check_interval.
bootstrap_on_failure_behavior: retry (opens in a new tab), a failed download retries the whole poll. Each attempt reads the metadata again and validates the snapshot before downloading it, so a snapshot published to replace a broken one is picked up.ETag, so the next poll reads the metadata in full. This applies when bootstrap_on_failure_behavior: warn skipped a failed download or fallback loaded an older snapshot, and when the store's current snapshot id is older than the loaded one.Ready and keeps serving the loaded snapshot. The poll increments dataset_acceleration_refresh_errors (opens in a new tab) with reason="snapshot_not_found" or reason="snapshot_older_than_loaded" and logs a warning that begins Dataset '<name>' cannot refresh from its snapshot location, so it keeps serving snapshot <id>.bootstrap_on_failure_behavior is set to: the dataset stays Ready and keeps serving the loaded snapshot, the poll increments dataset_acceleration_refresh_errors with reason="snapshot_download_failed" and logs the same warning, and the next poll tries again. A snapshot file that has not yet reached the location, because metadata.json arrived first, is checked every 10 seconds for up to 90 seconds before the poll reports it. A file that fails verification is reported at once.INSERT, UPDATE, DELETE, and TRUNCATE statements are all rejected with an error since the acceleration is driven exclusively from snapshots.