[spiceemma]

Summary

This PR documents five changes merged to spiceai/spiceai trunk, in vNext (website/docs/) only. None of the merge commits is an ancestor of v2.4.0 (git merge-base --is-ancestor <sha> v2.4.0 fails for all five), so the version-2.4.x snapshot correctly documents the earlier behavior.

1. SQL and search depth limits (reference/sql/operators, features/search/vector-search): a selected, grouped, or ordered expression, or a VALUES cell, nested more than 512 levels deep fails with its own message. A /v1/search where condition nested more than 512 levels deep is rejected with HTTP 400.
2. Flight SQL prepared statement handles (api/arrow-flight-sql): a handle is valid only on the process that issued it. After a restart, or on another replica, the call fails with InvalidArgument. The runtime's error links to this page, which did not explain it.
3. Iceberg vended storage hosts (components/data-connectors/iceberg): a host name is now resolved when Spice connects, and Spice connects only to the addresses it checked. The new refusal error is documented. The file:// sentence is removed because the guard was deleted.
4. Bedrock reasoning_content (components/models/bedrock): a non-streamed reply now returns the reasoning text in reasoning_content, not in content, and omits redacted reasoning. The link now points at the open streaming enhancement, Enhancement: Streamed chat completions carry the model's reasoning (delta.reasoning_content) spiceai#15595, because #15406 is closed.
5. Encoder-decoder and diffusion GGUFs refused at load (components/models).

Source PRs

• Reject over-deep expressions before they overflow the query stack spiceai#15433 — Reject over-deep expressions before they overflow the query stack
• fix(flight): integrity-protect Flight SQL prepared statement handles spiceai#15347 — fix(flight): integrity-protect Flight SQL prepared statement handles
• fix(iceberg): connect vended storage only to the addresses its DNS check approved spiceai#15430 — fix(iceberg): connect vended storage only to the addresses its DNS check approved
• Bedrock reasoning models: reasoning text goes into content, and ai_* decisions fail with 'more than one JSON object' spiceai#15420 — Bedrock reasoning models: reasoning text goes into content, and ai_* decisions fail with 'more than one JSON object'
• fix(llms): refuse an encoder-decoder or diffusion GGUF at load instead of aborting on its first request spiceai#15569 — fix(llms): refuse an encoder-decoder or diffusion GGUF at load instead of aborting on its first request

Verification

The values below were read on spiceai/spiceai origin/trunk at 814e639e8eb55eacbe3f3fadaad2ec0aaf712c05. Statements about behavior come from reading the code (Unverified, code inspection only), except where a source PR records its own run. The runtime was not run for this docs PR.

crates/runtime-query-engine/src/sql_depth_guard.rs:60   pub const MAX_SQL_EXPR_DEPTH: usize = 512;
crates/runtime-query-engine/src/sql_depth_guard.rs:79   pub const MAX_UNPROTECTED_EXPR_DEPTH: usize = if cfg!(debug_assertions) { 64 } else { MAX_SQL_EXPR_DEPTH };   (release builds: 512)
crates/runtime-query-engine/src/sql_depth_guard.rs:282  "Query rejected: a selected, grouped, ordered, or VALUES expression is nested more than {MAX_UNPROTECTED_EXPR_DEPTH} levels deep. Simplify the expression (for example, compute part of a long chain of +, || or AND in a subquery)."
crates/runtime-query-engine/src/sql_depth_guard.rs:290  "it is nested more than {MAX_UNPROTECTED_EXPR_DEPTH} levels deep. Simplify it (for example, replace a long chain of OR conditions with an IN list)."
crates/runtime-search/src/error.rs:89                   #[snafu(display("Invalid WHERE condition: {}", source.message()))]   WhereConditionTooDeep
crates/runtime-search/src/request.rs:241                ensure_filter_within_depth_limit(&expr).context(WhereConditionTooDeepSnafu)?;
crates/runtime/src/http/v1/search.rs:157                Err(e) => ... return (StatusCode::BAD_REQUEST, e).into_response();

crates/runtime/src/flight/flightsql/prepared_statement_handle.rs  "The key is drawn at random once per process and never persisted"; static HANDLE_KEY: LazyLock<[u8; blake3::KEY_LEN]> = LazyLock::new(rand::random);
  Status::invalid_argument("Invalid prepared statement handle: it was not issued by this Spice runtime, or the runtime has restarted since. Create the prepared statement again and retry. See: https://spiceai.org/docs/api/arrow-flight-sql")

crates/runtime/src/catalogconnector/vended_transport.rs:41  const DNS_RESOLUTION_TIMEOUT: Duration = Duration::from_secs(5);
crates/runtime/src/catalogconnector/vended_transport.rs  "{:?} is or resolves to a private, loopback, or link-local address" / "{:?} could not be resolved to a public address"
  "The Iceberg catalog for {component} directs storage requests to a host that is not allowed: {}, so the request is not sent and the table cannot be read. If this endpoint is trusted, set the `s3_endpoint` parameter to it, or set `{ALLOW_PRIVATE_HOSTS_ENV}=true`. See: https://spiceai.org/docs/components/data-connectors/iceberg"
spiceai/spiceai#15430 diff removes "refuses `file://` table and metadata locations" (body: "The `file://` guard is removed because the REST catalog's S3 and GCS storage never read local files.")

crates/llms/src/bedrock/chat/util.rs:99-102  ReasoningContent(ReasoningText) => ResponseBlock::Reasoning; ReasoningContent(RedactedContent) => ResponseBlock::Empty
crates/llms/src/bedrock/chat/mod.rs:623      reasoning_content: (!reasoning.is_empty()).then(|| reasoning.join("\n")),
$ gh issue view 15410 --repo spiceai/spiceai -> CLOSED; open enhancement: spiceai/spiceai#15595 "Streamed chat completions carry the model's reasoning (delta.reasoning_content)"

crates/llms-llamacpp/src/lib.rs:760  if model.has_encoder() || model.is_diffusion() { ... ChatError::UnsupportedArchitecture { ... } }   (same message as the gpt-oss refusal)

The source PRs ran their own reproductions. spiceai/spiceai#15430 ran an E2E against spiced built from trunk and from the branch. With the fix, the query fails with directs storage requests to a host that is not allowed, and the internal listener received no requests.

Later revert, removal, or retune: searching merged spiceai/spiceai PRs for MAX_UNPROTECTED_EXPR_DEPTH, prepared_statement_handle, vended_transport, ResponseBlock::Reasoning, and is_diffusion returned only the source PRs.

Known limitations, each stated on the page: a handle cannot be reused after a restart or on another replica (the "Breaking Changes" section of spiceai/spiceai#15347). Streamed Bedrock replies still carry no reasoning text (spiceai/spiceai#15595, open).

Merge-commit ancestry:

15433 d63258bb798a2460e8c8f6a2176ca499ce8caf42 not-in-v2.4.0
15347 2ee86e2b73b6b6ee318b157114ba676d01fcdc16 not-in-v2.4.0
15430 44306cc78d110304a30cd1146addccf630065e28 not-in-v2.4.0
15420 428695afe11faac153c8a27c4fbbc7bd7e886260 not-in-v2.4.0
15569 2f0d4ced935e903e6b10248fed914e52e93e17ed not-in-v2.4.0

Files changed (6):

website/docs/api/arrow-flight-sql/index.md
website/docs/components/data-connectors/iceberg.md
website/docs/components/models/bedrock.md
website/docs/components/models/index.md
website/docs/features/search/vector-search.md
website/docs/reference/sql/operators.md

Build: NODE_OPTIONS=--max-old-space-size=12288 npm run build (in website/):

[SUCCESS] Generated static files in "build".
exit=0

The style grep (docs-pr-hygiene.md §"Local Docusaurus build gate") over the added lines found nothing. The new link ../../reference/sql/operators.md#logical-operators resolves to ## Logical Operators at operators.md:348.

Test plan

• cd website && npm run build passes (output above)
• Versioned-docs propagation checked: vNext only (ancestry above)
• Files updated: 6 (list above)

Review gate

• Adversarial review: skipped — codex not installed (receipt: attempt=codex result=not-installed, engine=none)
• /security-review: not run — docs-only Markdown diff; the same review on the sibling docs-only PR docs: request-context metric labels, HTTPS redirect guard, ORC metadata limit, scalar function memory, OTLP log record size #2440 found nothing
• /simplify: not run — docs-only diff, no code

[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]

🟢 Approved

No active review issues block the documentation-only updates to vNext runtime guidance.

No open issues 🎉

What changed in this PR

This documentation-only PR updates vNext guidance for five runtime changes merged into spiceai/spiceai. The version 2.4.x documentation remains unchanged because these changes postdate v2.4.0.

Changes:

• Documents SQL and search expression-depth limits and process-specific Flight SQL prepared statement handles.
• Updates Iceberg storage-host validation behavior and refusal errors.
• Clarifies Bedrock reasoning response fields and load-time rejection of unsupported GGUF architectures.

File	Description
website/​docs/​reference/​sql/​operators.md	Documents the depth-limit error for selected, grouped, ordered, and VALUES expressions.
website/​docs/​features/​search/​vector-search.md	Documents the where nesting limit and HTTP 400 response.
website/​docs/​components/​models/​index.md	Clarifies load-time rejection of encoder-decoder and diffusion GGUFs.
website/​docs/​components/​models/​bedrock.md	Corrects non-streamed reasoning fields and links the streaming issue.
website/​docs/​components/​data-connectors/​iceberg.md	Explains connection-time host validation and removes the obsolete file:// restriction.
website/​docs/​api/​arrow-flight-sql/​index.md	Documents prepared statement handle validity across restarts and replicas.

_{Review effort: Balanced}

[github-actions]

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