diff --git a/website/docs/api/arrow-flight-sql/index.md b/website/docs/api/arrow-flight-sql/index.md index cd4b0d4fe..2f4654897 100644 --- a/website/docs/api/arrow-flight-sql/index.md +++ b/website/docs/api/arrow-flight-sql/index.md @@ -57,6 +57,14 @@ For point lookups and other small Flight SQL responses, fixed per-query costs (p - **Prepared statements**, for a lookup that runs often with different parameter values. `PREPARE` the statement, then `EXECUTE` it with bound parameters ([prepared statements](../reference/sql/prepared_statements)). Preparing saves parsing and planning work on each call, not queueing: `EXECUTE` still takes a [`max_concurrent_queries`](../reference/spicepod/runtime#runtimequerymax_concurrent_queries) slot. Repeated SQL text also hits the [logical plan cache](../features/caching#logical-plan-cache). - **A low [`target_partitions`](../reference/performance-tuning#query-parallelism)** for a lookup that does not scan in parallel. Confirm the plan with [`EXPLAIN`](../reference/sql/explain). +A Flight SQL prepared statement handle is valid only on the Spice process that created it. After that process restarts, or when a load balancer without session affinity sends a later call to another replica, the call fails with `InvalidArgument`: + +```text +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 +``` + +Create the prepared statement again and retry. No setting changes this. + JDBC, ODBC, and ADBC clients connect to Spice over Flight SQL. Set the connection pool size to the sum of [`max_concurrent_queries`](../reference/spicepod/runtime#runtimequerymax_concurrent_queries) across the Spice replicas behind the load balancer, divided by the number of application instances that share them — see [Client connection pools](../reference/performance-tuning#client-connection-pools). ## Long `DoGet` streams diff --git a/website/docs/components/data-connectors/iceberg.md b/website/docs/components/data-connectors/iceberg.md index f27dc8ab2..42a233d22 100644 --- a/website/docs/components/data-connectors/iceberg.md +++ b/website/docs/components/data-connectors/iceberg.md @@ -245,7 +245,13 @@ The IAM role or user needs the following permissions to access Iceberg tables in ## Storage endpoints supplied by a REST catalog -An Iceberg REST catalog can return storage settings with a table, such as `s3.endpoint` or `client.region`. Spice does not send storage requests, or the credentials that go with them, to a private, loopback, or link-local address only because the catalog named it. Before reading a table, Spice checks each storage endpoint the catalog returns (`s3.endpoint`, `gcs.service.host`, `adls.authority-host`, `oss.endpoint`, and `hf.endpoint`) and the S3 region, using the host the S3 client actually connects to after the bucket and region are applied. A host name is resolved first, with a 5-second limit. A table whose endpoint resolves to an internal address, or whose host cannot be resolved, is refused before any storage request is sent. A `file://` table location outside the `file://` `iceberg_warehouse` is also refused. When storage redirects a request from a catalog-supplied endpoint, Spice refuses a redirect to an internal address, and drops the `Authorization`, `Cookie`, and `Proxy-Authorization` headers when the redirect changes origin. +An Iceberg REST catalog can return storage settings with a table, such as `s3.endpoint` or `client.region`. Spice does not send storage requests, or the credentials that go with them, to a private, loopback, or link-local address only because the catalog named it. Before reading a table, Spice checks each storage endpoint the catalog returns (`s3.endpoint`, `gcs.service.host`, `adls.authority-host`, `oss.endpoint`, and `hf.endpoint`) and the S3 region, using the host the S3 client actually connects to after the bucket and region are applied. A literal internal address is refused before any storage request is sent. A host name is resolved when Spice connects to it, with a 5-second limit, and Spice connects only to the addresses that passed the check. A request to a host that resolves to an internal address, or that cannot be resolved, is not sent, and the query fails with an error such as: + +```text +The Iceberg catalog for dataset 'my_table' directs storage requests to a host that is not allowed: "" is or resolves to a private, loopback, or link-local address, 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 `SPICE_URL_TABLE_ALLOW_PRIVATE_HOSTS=true`. See: https://spiceai.org/docs/components/data-connectors/iceberg +``` + +When storage redirects a request from a catalog-supplied endpoint, Spice refuses a redirect to an internal address, and drops the `Authorization`, `Cookie`, and `Proxy-Authorization` headers when the redirect changes origin. An endpoint or region is checked only when its value differs from the one set in the Spicepod. A private S3-compatible store, such as MinIO served alongside a local REST catalog, keeps working when the Spicepod sets its endpoint and region: diff --git a/website/docs/components/models/bedrock.md b/website/docs/components/models/bedrock.md index 8a473323c..cd9fcb84e 100644 --- a/website/docs/components/models/bedrock.md +++ b/website/docs/components/models/bedrock.md @@ -99,7 +99,7 @@ Spice finds the family from the model ID, which can be a base model ID, a cross- - **Sampling parameters are sent as set.** Spice does not remove `temperature` or `top_p` when it sends `reasoning_effort`, and AWS rejects some combinations: Claude extended thinking is not compatible with `temperature`, `top_p`, or `top_k` changes ([Extended thinking](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-extended-thinking.html)), and Nova 2 Lite at `high` effort requires `temperature`, `topP`, and `maxTokens` to be unset ([Nova 2 extended thinking](https://docs.aws.amazon.com/nova/latest/nova2-userguide/extended-thinking.html)). Leave `bedrock_temperature`, `bedrock_top_p`, and, for Nova 2 Lite at `high`, `bedrock_max_completion_tokens` unset on a model that reasons. - **Other models**, such as Claude 3.5, Nova 1, or an application inference profile ARN, which does not name its model, receive nothing, and Spice logs a warning for each request. -A streamed response carries the answer but not the model's reasoning text. A response that is not streamed returns the reasoning text in `content`, after the answer, rather than in `reasoning_content` ([spiceai/spiceai#15406](https://github.com/spiceai/spiceai/issues/15406)). With Claude 3.7 to 4.5, a multi-turn tool call with `reasoning_effort` can fail with a Bedrock validation error, because Spice does not send the model's earlier `thinking` blocks back with the tool results, as AWS requires for [extended thinking with tool use](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-extended-thinking.html). +A streamed response carries the answer but not the model's reasoning text. A response that is not streamed returns the answer in `content` and the reasoning text in `reasoning_content`, and omits redacted reasoning. Streamed reasoning is tracked in [spiceai/spiceai#15595](https://github.com/spiceai/spiceai/issues/15595). With Claude 3.7 to 4.5, a multi-turn tool call with `reasoning_effort` can fail with a Bedrock validation error, because Spice does not send the model's earlier `thinking` blocks back with the tool results, as AWS requires for [extended thinking with tool use](https://docs.aws.amazon.com/bedrock/latest/userguide/claude-messages-extended-thinking.html). ## Examples diff --git a/website/docs/components/models/index.md b/website/docs/components/models/index.md index 86512b3f9..e02840dba 100644 --- a/website/docs/components/models/index.md +++ b/website/docs/components/models/index.md @@ -137,7 +137,7 @@ A GGUF model loads when llama.cpp supports its architecture, the `general.archit `afmoe`, `apertus`, `arcee`, `arctic`, `arwkv7`, `baichuan`, `bailingmoe`, `bailingmoe2`, `bailingmoe3`, `beam`, `bitnet`, `bloom`, `chameleon`, `chatglm`, `codeshell`, `cogvlm`, `cohere2`, `cohere2moe`, `command-r`, `dbrx`, `deci`, `deepseek`, `deepseek2`, `deepseek2-ocr`, `deepseek32`, `deepseek4`, `dots1`, `dots3note`, `ernie4_5`, `ernie4_5-moe`, `exaone`, `exaone-moe`, `exaone4`, `falcon`, `falcon-h1`, `flint`, `gemma`, `gemma2`, `gemma3`, `gemma3n`, `gemma4`, `glm-dsa`, `glm4`, `glm4moe`, `glm5-next`, `gpt2`, `gptj`, `gptneox`, `granite`, `granite_swa`, `granitehybrid`, `granitemoe`, `graniteswitch`, `grok`, `grovemoe`, `hrm_text`, `hunyuan-dense`, `hunyuan-moe`, `hunyuan_vl`, `hy_v3`, `hy_v4`, `internlm2`, `jais`, `jais2`, `jamba`, `k2-horizon`, `kimi-k3`, `kimi-linear`, `kolibri1`, `laguna`, `lfm2`, `lfm2moe`, `llama`, `llama4`, `maincoder`, `maion-coder`, `mamba`, `mamba2`, `maple`, `mellum`, `mimo2`, `minicpm`, `minicpm3`, `minimax-01`, `minimax-m2`, `minimax-m3`, `mistral3`, `mistral4`, `mpt`, `muse-glimmer`, `muse-spark`, `nanbeige`, `nemotron`, `nemotron_h`, `nemotron_h_moe`, `olmo`, `olmo2`, `olmoe`, `openelm`, `orion`, `paddleocr`, `pangu-embedded`, `phi2`, `phi3`, `phimoe`, `plamo`, `plamo2`, `plamo3`, `plm`, `qwen`, `qwen2`, `qwen2moe`, `qwen2vl`, `qwen3`, `qwen35`, `qwen35moe`, `qwen3moe`, `qwen3next`, `qwen3vl`, `qwen3vlmoe`, `qwen4exp`, `refact`, `rwkv6`, `rwkv6qwen2`, `rwkv7`, `seed_oss`, `sensenova_u1`, `smallthinker`, `smollm3`, `spark2_5`, `stablelm`, `starcoder`, `starcoder2`, `step35`, `talkie`, `xverse`. -The list omits the architectures llama.cpp provides for embedding, audio, scoring and speculative-draft models, which are not chat models. It omits `t5`, an encoder-decoder architecture, and the diffusion architectures `dream`, `llada`, `llada-moe` and `rnd1`: the engine generates one token at a time with a decoder alone, and runs no encoder pass and no diffusion sampling. It also omits `gpt-oss`: a gpt-oss GGUF is refused at load with the message below, because the engine does not yet read its Harmony replies. A GGUF whose architecture llama.cpp does not know fails to load with: +The list omits the architectures llama.cpp provides for embedding, audio, scoring and speculative-draft models, which are not chat models. It omits `t5`, an encoder-decoder architecture, and the diffusion architectures `dream`, `llada`, `llada-moe` and `rnd1`: the engine generates one token at a time with a decoder alone, and runs no encoder pass and no diffusion sampling. A GGUF of an encoder-decoder or diffusion architecture is refused at load with the message below. It also omits `gpt-oss`: a gpt-oss GGUF is refused at load with the same message, because the engine does not yet read its Harmony replies. A GGUF whose architecture llama.cpp does not know fails to load with: ```text Architecture '' in is not supported by this Spice release. Upgrade Spice, or use a GGUF of a supported architecture: https://spiceai.org/docs/components/models#gguf-architectures diff --git a/website/docs/features/search/vector-search.md b/website/docs/features/search/vector-search.md index baefbf087..1fda1d4e9 100644 --- a/website/docs/features/search/vector-search.md +++ b/website/docs/features/search/vector-search.md @@ -84,6 +84,12 @@ The optional `keywords` field narrows the candidates to rows whose searched colu Search request rejected: 513 keywords were provided, and at most 512 are accepted. Shorten the `keywords` list. ``` +The `where` condition has the same 512-level nesting limit as a [SQL expression](../../reference/sql/operators.md#logical-operators). A condition nested deeper, such as a long chain of `AND` or `OR` terms, is rejected with HTTP `400` before any search runs: + +```text +Invalid WHERE condition: it is nested more than 512 levels deep. Simplify it (for example, replace a long chain of OR conditions with an IN list). +``` + ## Retrieving Full Documents If the dataset uses chunking, Spice returns relevant chunks. To retrieve entire documents, include the embedding column in `additional_columns`: diff --git a/website/docs/reference/sql/operators.md b/website/docs/reference/sql/operators.md index 4f6c59d20..183df802e 100644 --- a/website/docs/reference/sql/operators.md +++ b/website/docs/reference/sql/operators.md @@ -356,6 +356,12 @@ Spice rejects a SQL statement whose expression tree is nested more than 512 leve Query rejected: an expression is nested more than 512 levels deep. Simplify the query (for example, replace a long chain of OR/AND conditions with an IN list or a join). ``` +A selected, grouped, or ordered expression, or a `VALUES` cell, has the same 512-level limit and its own message. Compute part of a long chain of `+`, `||`, or `AND` in a subquery to bring it under the limit: + +```text +Query rejected: a selected, grouped, ordered, or VALUES expression is nested more than 512 levels deep. Simplify the expression (for example, compute part of a long chain of +, || or AND in a subquery). +``` + ### `AND` Logical And