Every request to POST /v1/query runs in one of two modes, controlled by the mode field in the request body.
Execute Mode
"mode": "execute" is the default. The engine parses, plans, optimizes, and then runs the query — fetching rows from DynamoDB and returning them in the response.
- Consumes DynamoDB RCUs charged to your AWS account.
- Required scope:
query
- Returns a
data payload with rows, column metadata, and timing fields.
Plan Mode
"mode": "plan" parses and optimizes the query without fetching any data.
- Does NOT consume DynamoDB RCUs.
- Required scope:
query
- Returns a human-readable plan tree, an optimizer weight (cost estimate), and the normalized SQL string.
Plan mode is useful for:
- Debugging slow queries — check whether the optimizer selected an index or fell back to a scan.
- Validating SQL in CI/CD — catch syntax errors and unsupported features without consuming capacity.
- Previewing query structure — understand how the engine will execute a query before running it against production tables.
Understanding the Response Fields
weight
The optimizer’s relative cost estimate. Lower is cheaper. A weight of 0 means no cost estimate was computed — for example, when the query has no index candidates and the optimizer produces a simple scan plan.
planTime
Present in both modes. Covers parse + plan + optimize only. It does not include any DynamoDB I/O.
execTime
Present in execute mode only. Total elapsed time from request receipt to response, including all DynamoDB I/O. Always >= planTime.
Example
Plan mode request:
Plan mode response:
The plan tree shows the engine will perform a full Scan with a Filter applied — no index was matched. If you have a GSI on status, check that the schema metadata is registered correctly in the portal so the optimizer can see it.
If you see Scan(...) in the plan for a query that should use an index, run the query in plan mode first and inspect the tree before paying DynamoDB RCU costs for a scan.
