Skip to main content
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:execute
  • 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:plan
  • 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: 
{
  "sql": "SELECT id, total FROM myschema.orders WHERE status = 'pending' LIMIT 10",
  "mode": "plan"
}
Plan mode response: 
{
  "success": true,
  "data": {
    "plan": "Limit(10)\n  Scan(myschema.orders)\n    Filter(status = 'pending')",
    "weight": 0,
    "normalizedSql": "SELECT id, total FROM myschema.orders WHERE status = 'pending' LIMIT 10",
    "planTime": 3
  }
}
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.
Execute mode request (same query): 
{
  "sql": "SELECT id, total FROM myschema.orders WHERE status = 'pending' LIMIT 10",
  "mode": "execute"
}
Execute mode response: 
{
  "success": true,
  "data": {
    "columns": ["id", "total"],
    "data": [
      ["ord-001", 59.99],
      ["ord-002", 120.00]
    ],
    "firstRowIdx": 0,
    "planTime": 3,
    "execTime": 47
  }
}