Debugging with explain()

dkmio provides an explain() method on query and scan builders. This method returns the parameters that would be sent to DynamoDB without actually executing the operation.

This is extremely useful for:

1. Verifying that the generated ExpressionAttributeNames and ExpressionAttributeValues are correct.
2. Checking the KeyConditionExpression and FilterExpression.
3. Understanding how dkmio maps your fluent API calls to raw DynamoDB parameters.

Usage

Simply call .explain() at the end of your query or scan chain.

params = (
    orders.by_status
    .query(status="PENDING")
    .filter(total__gte=100)
    .select("user_id", "total")
    .explain()
)

Example Output

The output is a dictionary containing all the relevant operation parameters:

{
    "operation": "Query",
    "table": "orders",
    "index": "gsi-status-date",
    "key_condition": "#status = :v0",
    "filter": "#total >= :v1",
    "projection": "#user_id, #total",
    "expression_attribute_names": {
        "#status": "status", 
        "#total": "total",
        "#user_id": "user_id"
    },
    "expression_attribute_values": {
        ":v0": "PENDING", 
        ":v1": 100
    },
}

Logging

dkmio uses the standard Python logging module. You can enable debug logging to see detailed information about operations and retries.

import logging

# Get the dkmio logger
logger = logging.getLogger("dkmio")
logger.setLevel(logging.DEBUG)

# Add a handler to see output in console
handler = logging.StreamHandler()
logger.addHandler(handler)

• DEBUG: Logs raw parameters and successful operations.
• WARNING: Logs retries on batch operations or throttling events.