Fundamentals: Warnings

samtSQL surfaces advisory warnings to help you discover anti-patterns such as repeated AI calls or unguarded LIMIT clauses. Such warnings are shown in the web interface or returned in the JSON response when using the REST API.

Warnings are stable, structured objects with a code, a message, and a context payload. They appear in the JSON / empty response body under the warnings field, and in the X-SAMT-Warnings HTTP header for csv and zip downloads.

For background on why these patterns matter, see Partial Query Results.

REPEATED_AI_CALL

The same AI call (identical post-qualification SQL) appears more than once in the query. Each occurrence is computed and billed independently. The context field lists the offending calls and how many times each appears. Recommended fix: keep the AI call to a single occurrence by materializing it in a subquery / CTE alias and reusing that alias.

LIMIT_WITHOUT_COMPLETENESS_GUARD

The query has an explicit LIMIT and at least one AI call that lives in the outer SELECT in a non-filter position (typically the projection or ORDER BY). The engine's row-count termination may stop before any row is fully processed. The context field's unguarded_calls array lists the calls that should be wrapped in a subquery / CTE and filtered by alias in the outer query.

The warning is intentionally scoped to the outer SELECT. AI calls that already live inside an inner SELECT (CTE body or subquery) are not flagged: the outer LIMIT operates on the alias produced by that inner scope, not on the AI call directly, so the recommended subquery / CTE pattern is recognized as safe.