docs(snapshots): per-dataset snapshot settings; deprecate top-level snapshots and runtime.scheduler state settings

[spiceemma]

spiceai/spiceai#15136 adds three per-dataset acceleration fields, snapshots_location, snapshots_params, and snapshots_bootstrap_on_failure_behavior, and deprecates the top-level snapshots section and runtime.scheduler.state_location/params in favor of runtime.state. Each deprecated setting still works and logs one startup warning that shows the replacement configuration. The PR also routes SQS snapshot notifications so a queue on the whole runtime.state prefix works: notifications for other state folders are deleted silently, and locations that name the same queue share one consumer. Before this change, the docs presented the top-level snapshots section and runtime.scheduler.state_location as the primary configuration, and the acceleration.snapshots reference said the top-level section was required.

Pages changed

• website/docs/features/data-acceleration/snapshots.md: snapshot storage now leads with runtime.state; new "Override the snapshot location per dataset" and "Migrate from the top-level snapshots section" subsections; Failure behavior names the new dataset field; examples moved to runtime.state.
• website/docs/features/data-acceleration/refresh-modes/snapshot.md: reader examples set acceleration.snapshots_location (read-only access, no runtime.state startup check), with a note on the runtime.state alternative; s3_queue_url placement, shared queue consumers, notification filters for every location on a queue, sibling state folder notifications, and the unread-queue warning on a scheduler.
• website/docs/features/data-acceleration/data-refresh.md: snapshot refresh example sets acceleration.snapshots_location.
• website/docs/reference/spicepod/datasets.md: acceleration.snapshots requirement corrected; three new field sections.
• website/docs/reference/spicepod/index.md: deprecation notice on snapshots and precedence of the dataset fields.
• website/docs/reference/spicepod/runtime.md: runtime.scheduler.state_location/params marked deprecated, with the startup warning cases; runtime.state feature table and state location parameters updated; s3_queue_url in runtime.state.params.
• website/docs/features/distributed-query/index.md, website/docs/cli/reference/query.md: scheduler state examples and prerequisites use runtime.state.location.

These edits avoid the lines that open docs PR #2379 (snapshot roll back and pin) changes.

Versioned docs

vNext only. The merge commit 4a99926b4abde0c7bb303113ea3b488856752dc7 is in no release tag and is not on release/2.4, so v2.4.0-rc.1 and v2.4.0-rc.2 do not have the new fields or the warnings. Testers of rc.1 and rc.2 who set runtime.scheduler.state_location or the top-level snapshots section see a deprecation warning after upgrading; the migration subsection and the runtime.scheduler warning table cover this. No versioned docs are changed.

Verification

Trunk SHA: 9a25991b0384c7fc6b25fc838d6d71ce6f65ea57.

• Reproduced: acceleration.snapshots_location field: crates/spicepod/src/acceleration/mod.rs:674: pub snapshots_location: Option<String>,
• Reproduced: acceleration.snapshots_params field: crates/spicepod/src/acceleration/mod.rs:682: pub snapshots_params: Option<Params>,
• Reproduced: acceleration.snapshots_bootstrap_on_failure_behavior field: crates/spicepod/src/acceleration/mod.rs:688: pub snapshots_bootstrap_on_failure_behavior: Option<BootstrapOnFailureBehavior>,
• Reproduced: top-level section deprecation text: crates/runtime-acceleration/src/snapshot/section_deprecation.rs:68: "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`."`
• Reproduced: scheduler deprecation text: crates/runtime-state-location/src/scheduler_deprecation.rs:75: "{settings} deprecated and will be removed in a future release. The scheduler keeps its state in the \cluster/` folder of `runtime.state.location`."`
• Reproduced: scheduler folder name: crates/spicepod/src/component/runtime.rs:1730: pub const SCHEDULER_STATE_FOLDER: &str = "cluster";
• Unverified, code inspection only: shared queue consumer reads with the first location's credentials: crates/runtime-acceleration/src/snapshot/notifications.rs:831: "... A queue has one consumer, so it is read with the credentials of '{opened_for}'. ..."
• Reproduced: rc.2 rejects unknown acceleration fields: v2.4.0-rc.2:crates/spicepod/src/acceleration/mod.rs:515: #[serde(deny_unknown_fields)] (on pub struct Acceleration at line 516).
• Observed, not isolated: resolution order, every warning case, queue routing for sibling state folders, and the scheduler migration to runtime.state.location finding existing objects were tested in the source PR on LocalStack and with unit tests: feat(snapshots): per-dataset snapshot settings; deprecate top-level snapshots and runtime.scheduler state settings spiceai#15136
• Unverified, code inspection only: location, params, and failure behavior resolution (dataset field, then top-level section, then runtime.state; a snapshots_location without snapshots_params uses no params), from App::dataset_snapshots and snapshot_params_setting in crates/app/src/lib.rs.
• Unverified, code inspection only: executors do not log the deprecation warnings, and schedulers do not log the unread-queue warning (crates/runtime/src/init/dataset.rs:293 and :312).
• Unverified, code inspection only: runtime.state.params accept s3_queue_url for the scheduler, rate control, and warmup without a warning (crates/runtime-state-location/src/lib.rs:226-227); a feature's own params still warn.
• Unverified, code inspection only: the scheduler warning cases in the runtime.scheduler table, from crates/runtime-state-location/src/scheduler_deprecation.rs.
• Unverified, code inspection only: an instance with runtime.state is not ready until the startup check passes (crates/runtime/src/state_location.rs:160), so read-only reader examples use snapshots_location instead.
• Unverified, code inspection only: a queue message is left on the queue only when its object is outside every location served by that queue and every runtime.state root (route() in crates/runtime-acceleration/src/snapshot/notifications.rs).
• build: npm run build in website/ passed locally ([SUCCESS] Generated static files in "build"., exit 0; no broken links or anchors reported)

[github-actions]

✅ Pull with Spice Passed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected
• ✅ Has at least one assignee: spiceemma

[github-actions]

🔍 Pull with Spice Failed

Passing checks:

• ✅ Title meets minimum length requirement (10 characters)
• ✅ Has at least one of the required labels: area/blog, area/docs, area/cookbook, dependencies
• ✅ No banned labels detected

Failed checks:

• ❌ At least one assignee is required for this pull request.

Please address these issues and update your pull request.

[Copilot]

🟡 Changes recommended

Reader examples omit a write-access prerequisite that can prevent read-only deployments from becoming ready.

3 open findings

• Document runtime.state write access and snapshot-only reader configuration · New
• Document notification filters for all locations sharing a queue · New
• Include deprecated snapshots.location as a supported location source · New

What changed in this PR

Updates vNext documentation for per-dataset snapshot settings and shared runtime state, while documenting migration from deprecated configuration.

Changes:

• Adds per-dataset snapshot fields and migration guidance.
• Moves snapshot and scheduler examples to runtime.state.
• Explains shared SQS consumers and notification routing.

File	Description
website/​docs/​reference/​spicepod/​runtime.md	Documents scheduler deprecations and state parameters.
website/​docs/​reference/​spicepod/​index.md	Marks top-level snapshots deprecated and explains precedence.
website/​docs/​reference/​spicepod/​datasets.md	Adds per-dataset snapshot settings.
website/​docs/​features/​distributed-query/​index.md	Updates scheduler configuration examples.
website/​docs/​features/​data-acceleration/​snapshots.md	Adds storage overrides and migration guidance.
website/​docs/​features/​data-acceleration/​refresh-modes/​snapshot.md	Updates reader examples and queue guidance.
website/​docs/​features/​data-acceleration/​data-refresh.md	Uses shared state in the snapshot example.
website/​docs/​cli/​reference/​query.md	Updates scheduler state prerequisites.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

🚀 deployed to https://d0bcb7a4.spiceai-org-website.pages.dev

[Copilot]

🟢 Approved

The documentation changes address prior feedback, with no unresolved blocking issues.

0 open findings

3 resolved since last review

• Include deprecated snapshots.location as a supported location source
• Document notification filters for all locations sharing a queue
• Document runtime.state write access and snapshot-only reader configuration

🧠 Review effort: Balanced

[github-actions]

🚀 deployed to https://38092b01.spiceai-org-website.pages.dev