Query Modes

​

Execute Mode

• Consumes DynamoDB RCUs charged to your AWS account.
• Required scope: query
• Returns a data payload with rows, column metadata, and timing fields.

​

Plan Mode

• Does NOT consume DynamoDB RCUs.
• Required scope: query
• Returns a human-readable plan tree, an optimizer weight (cost estimate), and the normalized SQL string.

• 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

​

planTime

​

execTime

​

Example

{
  "sql": "SELECT id, total FROM myschema.orders WHERE status = 'pending' LIMIT 10",
  "mode": "plan"
}

{
  "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
  }
}

{
  "sql": "SELECT id, total FROM myschema.orders WHERE status = 'pending' LIMIT 10",
  "mode": "execute"
}

{
  "success": true,
  "data": {
    "columns": ["id", "total"],
    "data": [
      ["ord-001", 59.99],
      ["ord-002", 120.00]
    ],
    "firstRowIdx": 0,
    "planTime": 3,
    "execTime": 47
  }
}