docs(v2.4): backport docs for PRs cherry-picked into release/2.4

website/versioned_docs/version-2.4.x/api/HTTP/post-search.RequestSchema.json

@@ -1 +1 @@
-{"title":"Body","body":{"description":"Search request parameters","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["text"],"properties":{"additional_columns":{"type":"array","items":{"type":"string"},"description":"Additional columns to return from the dataset. If the column is a primary key, it will be\n returned within the response under `.primary_key`, not `.data`."},"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"The datasets to search for similarity. If None, search across all datasets. For available datasets, use the `list_datasets` tool and ensure `can_search_documents==true`."},"limit":{"type":["integer","null"],"description":"Number of documents to return for each dataset","minimum":0},"text":{"type":"string","description":"The text to search documents for similarity"},"where":{"type":["string","null"],"description":"An SQL filter predicate to apply. Format: 'WHERE `where_cond`'."}},"title":"SearchRequestBaseJson"},{"type":"object","properties":{"keywords":{"type":["array","null"],"items":{"type":"string"}}}}],"description":"HTTP request schema is separate from AI requests, so that keywords can be supplied as an optional field for HTTP calls.\n`schemars` doesn't allow setting `#[serde(default)]` as well as `#[schemars(required)]` - the field does not become required.\nWhen the field is not required, the model ignores it.","title":"SearchRequestHTTPJson"},"example":{"datasets":["app_messages"],"text":"Tokyo plane tickets","where":"user=1234321","additional_columns":["timestamp"],"limit":3,"keywords":["plane","tickets"]}}},"required":true}}
+{"title":"Body","body":{"description":"Search request parameters","content":{"application/json":{"schema":{"allOf":[{"type":"object","required":["text"],"properties":{"additional_columns":{"type":"array","items":{"type":"string"},"description":"Additional columns to return from the dataset. If the column is a primary key, it will be\n returned within the response under `.primary_key`, not `.data`."},"datasets":{"type":["array","null"],"items":{"type":"string"},"description":"The datasets to search for similarity. If None, search across all datasets. For available datasets, use the `list_datasets` tool and ensure `can_search_documents==true`."},"limit":{"type":["integer","null"],"description":"Number of documents to return for each dataset","minimum":0},"text":{"type":"string","description":"The text to search documents for similarity. Must contain at least one non-whitespace character."},"where":{"type":["string","null"],"description":"An SQL filter predicate to apply. Format: 'WHERE `where_cond`'."}},"title":"SearchRequestBaseJson"},{"type":"object","properties":{"keywords":{"type":["array","null"],"items":{"type":"string"}}}}],"description":"HTTP request schema is separate from AI requests, so that keywords can be supplied as an optional field for HTTP calls.\n`schemars` doesn't allow setting `#[serde(default)]` as well as `#[schemars(required)]` - the field does not become required.\nWhen the field is not required, the model ignores it.","title":"SearchRequestHTTPJson"},"example":{"datasets":["app_messages"],"text":"Tokyo plane tickets","where":"user=1234321","additional_columns":["timestamp"],"limit":3,"keywords":["plane","tickets"]}}},"required":true}}

website/versioned_docs/version-2.4.x/api/HTTP/post-search.api.mdx

@@ -5,7 +5,7 @@ description: "Perform a vector similarity search (VSS) operation on a dataset."
 sidebar_label: "Search"
 hide_title: true
 hide_table_of_contents: true
-api: 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
+api: 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
 sidebar_class_name: "post api-method"
 info_path: docs/api/HTTP/runtime
 custom_edit_url: null

website/versioned_docs/version-2.4.x/cli/reference/query.md

@@ -84,5 +84,5 @@ Time: 5.10000000 seconds. 1 rows.
 Query IDs can be abbreviated if they uniquely identify a query within the tracked session.
 
 :::note
-The `spice query` command requires the runtime to be running in [cluster mode](/docs/features/distributed-query) with `--role scheduler` and a scheduler state location configured (`runtime.scheduler.state_location`, or [`runtime.state.location`](../../reference/spicepod/runtime#runtimestate)).
+The `spice query` command requires the runtime to be running in [cluster mode](/docs/features/distributed-query) with `--role scheduler` and a scheduler state location configured ([`runtime.state.location`](../../reference/spicepod/runtime#runtimestate), or the deprecated `runtime.scheduler.state_location`).
 :::

website/versioned_docs/version-2.4.x/components/data-accelerators/arrow/index.md

@@ -5,6 +5,12 @@ description: 'In-Memory Arrow Data Accelerator Documentation'
 sidebar_position: 2
 ---
 
+:::warning[Deprecated]
+
+The `arrow` acceleration engine is deprecated in v2.4 and will be removed in v2.5. A Spicepod with a dataset or view that uses it logs one warning at startup, and one on each hot reload that adds or changes such a component, naming those datasets and views. A cluster executor does not log it. Runtimes up to and including v2.4.0-rc.3 do not log this warning. Move these accelerations to [Spice Cayenne](../cayenne/index.md) before upgrading to v2.5. On Windows, where `arrow` is the default engine, an acceleration that sets no `engine` uses `arrow` and is included in the warning; Cayenne is not available on native Windows, so run Spice in Docker or WSL to use it; see [Migrating to Spice Cayenne](../cayenne/migration.md).
+
+:::
+
 The In-Memory Arrow Data Accelerator uses Apache Arrow to store data in-memory for fast access and query performance. It is the default data accelerator on Windows. On Linux and macOS, the default is [Spice Cayenne](../cayenne/index.md); see [Default Engine](../index.md#default-engine).
 
 ## Configuration

website/versioned_docs/version-2.4.x/components/data-accelerators/cayenne/index.md

@@ -96,7 +96,7 @@ Set under a dataset's `acceleration.params`:
 | `cayenne_compaction_trigger_protected_snapshots` | Number of protected snapshots before snapshot-maintenance compaction runs. Separate from `cayenne_compaction_trigger_files` so small-file tuning does not silently change scan amplification behavior. Defaults to `4` for `refresh_mode: caching` / `changes`, or `append` with `refresh_check_interval` ≤ 5m; `8` otherwise. A value of `1` is clamped to a minimum of `2`. |
 | `cayenne_compaction_trigger_snapshot_age_ms` | Maximum age in milliseconds of the oldest protected snapshot before snapshot-maintenance compaction runs. Set to `0` to disable the age trigger. Defaults to `60000` for `refresh_mode: caching` / `changes`, or `append` with `refresh_check_interval` ≤ 5m; `300000` otherwise. |
 | `cayenne_compaction_max_levels`   | Maximum number of consecutive compaction passes per trigger. Bounds write amplification when promotion keeps producing new candidates. Defaults to `3`. |
-| `cayenne_compaction_max_files_per_pick` | Maximum number of eligible file paths retained in one compaction candidate. For a table eligible for **subset** compaction — key-based deletes (`cayenne_deletion_mode: key`, including append-only tables), no configured `sort_columns`, and no protected snapshots — the runner rewrites only the picked candidate and carries the unpicked settled files into the new snapshot by hardlink (local filesystem) or copy (S3 or cross-device), so this value does bound rewrite IO and memory. A table using position deletes, a configured `sort_columns` (whose subset hardlinks would break the global sort attestation), or carrying protected snapshots (which the rewrite has to fold) still rewrites the whole current snapshot, and this value then only affects trigger selection and observability. Defaults to `32`. |
+| `cayenne_compaction_max_files_per_pick` | Maximum number of eligible file paths retained in one compaction candidate. For a table eligible for **subset** compaction — key-based deletes (`cayenne_deletion_mode: key`, including append-only tables) or a table without a primary key that holds no position deletes, no configured `sort_columns` or `cayenne_cluster_by`, and no protected snapshots — the runner rewrites only the picked candidate and carries the unpicked settled files into the new snapshot by hardlink (local filesystem) or copy (S3 or cross-device), so this value does bound rewrite IO and memory on a key-delete table. A table without a primary key extends the candidate with its tier's next-smallest files up to one sixteenth of `cayenne_target_file_size_mb` (16 MiB at a 256 MB target), so its merge is bounded by bytes rather than by this value, and its small-file tier also qualifies once it holds this many small files (or `cayenne_compaction_trigger_files`, if larger), whatever their total size. Such a table holds writers off only to commit the pass, not while it encodes. A table that holds position deletes, has a configured `sort_columns` or `cayenne_cluster_by` (whose subset hardlinks would break the global sort attestation), or carries protected snapshots (which the rewrite has to fold) still rewrites the whole current snapshot, and this value then only affects trigger selection and observability. Defaults to `32`. |
 | `cayenne_compaction_background_interval_ms` | Background compaction interval in milliseconds. The accelerator runs a per-table background task at this interval. Set to `0` to disable the background task — inline compaction on writes still runs. Defaults to `10000` for `refresh_mode: caching` / `changes`, or `append` with `refresh_check_interval` ≤ 5m; `0` for `refresh_mode: full`, where each refresh replaces the whole table and leaves nothing for the background task to consolidate (set the parameter explicitly to turn it back on for a table that also takes `INSERT`s); `30000` otherwise. When `refresh_mode` is left unset the connector fills it in — `debezium` and `cdc` resolve to `changes`, `sink` to `disabled`, every other connector to `full` — so an unannotated dataset takes the `full` default here. |
 | `cayenne_cdc_durability`          | Durability mode for the inline CDC write path. Accepts `memory` (default) or `file`. `memory` appends batches to an in-RAM tier and defers the source-slot acknowledgement to a periodic or cap-triggered checkpoint, collapsing per-batch durability cost; on crash the un-checkpointed tail is replayed from the source slot, and because the apply is primary-key-idempotent this remains exactly-once. The in-memory path is eligibility-gated — it applies only to the small-write / CDC profile on non-partitioned tables, and other profiles always use `file`. `file` persists each CDC batch durably before advancing the source slot and is the conservative opt-out. |
 | `cayenne_cdc_mem_tier_max_bytes`  | Per-table RAM-tier byte cap that forces a spill (checkpoint) and source-slot advance, in `cayenne_cdc_durability: memory` mode only. Auto-derived from host memory (~1/64 of RAM, clamped to 256 MiB–1 GiB; 256 MiB on hosts at or under 16 GiB). A process-global byte budget also bounds aggregate resident memory across all tables; whichever cap is breached first triggers the spill. Set to `0` to disable the per-table cap (the global budget still applies). |

website/versioned_docs/version-2.4.x/components/data-accelerators/cayenne/performance.md

@@ -333,7 +333,7 @@ Compaction consolidates the small files that appends and CDC produce into files
 | `cayenne_compaction_trigger_protected_snapshots`  | `4` / `8`                                                                                 | Protected snapshots before snapshot-maintenance compaction runs                                                              |
 | `cayenne_compaction_trigger_snapshot_age_ms`      | `60000` / `300000`                                                                        | Age of the oldest protected snapshot before maintenance runs; `0` disables the age trigger                                    |
 | `cayenne_compaction_max_levels`                   | `3`                                                                                       | Consecutive passes per trigger, bounding write amplification                                                                 |
-| `cayenne_compaction_max_files_per_pick`           | `32`                                                                                      | Files rewritten per pass on tables eligible for subset compaction; the rest are carried forward by hardlink                  |
+| `cayenne_compaction_max_files_per_pick`           | `32`                                                                                      | Files rewritten per pass on key-delete tables eligible for subset compaction; the rest are carried forward by hardlink. A table without a primary key adds more small files to each pass, up to one sixteenth of the target file size |
 | `runtime.params.cayenne_compaction_memory_fraction` | `0.2`                                                                                     | Share of the query memory pool carved out for the dedicated compaction pool                                                  |
 
 Compaction is where the storage tier shows most clearly. A pass reads a file set and writes a new one, so on a network volume it consumes the same bandwidth ingest and queries need; on the `ebs` tier Cayenne writes the output with `O_DIRECT` so the rewritten bytes do not evict hot query data from the page cache, and the tuner lengthens the compaction interval when the table is I/O-bound. Guidance:

website/versioned_docs/version-2.4.x/components/data-accelerators/duckdb/index.md

@@ -5,6 +5,12 @@ description: 'DuckDB Data Accelerator Documentation'
 sidebar_position: 3
 ---
 
+:::warning[Deprecated]
+
+The `duckdb` acceleration engine is deprecated in v2.4 and will be removed in v2.5. A Spicepod with a dataset or view that uses it logs one warning at startup, and one on each hot reload that adds or changes such a component, naming those datasets and views. A cluster executor does not log it. Runtimes up to and including v2.4.0-rc.3 do not log this warning. Move these accelerations to [Spice Cayenne](../cayenne/index.md) before upgrading to v2.5; see [Migrating to Spice Cayenne](../cayenne/migration.md).
+
+:::
+
 The DuckDB Data Accelerator helps improve query performance by using [DuckDB](https://duckdb.org/), an embedded analytical database engine optimized for efficient data processing.
 
 It supports in-memory and file-based operation modes, enabling workloads that exceed available memory and optionally providing persistent storage for datasets.