Use QueryPlan mode by default
QueryPlan mode is the recommended executor mode because a structured request is easier to validate conservatively.
A QueryPlan describes the intended query using structured fields such as source table, selected columns, filters, grouping, ordering, and limit.
The Gateway validates the plan against the published scope and generates provider-specific SQL only after the request passes policy checks.
Use SQL mode for advanced cases
SQL mode is available for advanced or conservative workflows where teams intentionally allow SQL candidates.
SQL mode still validates before execution. It should not be treated as direct database access, and it is not published together with QueryPlan mode for the same scope.
Mode comparison
A scope should publish one executor mode at a time.
| Mode | Best fit | Gateway behavior |
|---|---|---|
| QueryPlan | Default, structured, repeatable database access. | Validate plan fields, then generate provider SQL. |
| SQL mode | Advanced workflows with explicit SQL candidates. | Validate SQL conservatively before execution. |
Common questions
Can QueryPlan and SQL mode be published together?
No. A database scope publishes either QueryPlan executor tools or SQL executor tools, never both at the same time.
Why is QueryPlan recommended?
A structured plan gives the Gateway clearer fields to validate against published tables, columns, relationships, limits, and read-only policy.
Does SQL mode skip validation?
No. SQL mode is still validated by the Gateway before execution.