Match the symptom to one check
Keep the raw service error code and request ID. A transport or SigV4 failure occurs before an adapter decision can be inferred. A validation or conditional error is an origin-facing result; a report can add recorded decisions but does not turn the failed operation into a success. A report receipt means an explanation was admitted, not that the operation or later work completed.
Begin with a non-mutating table and item check
Use the installed DynamoDB origin endpoint, signing Region, and existing IAM workload profile for the same application identity. Set these placeholders from that install and client configuration;DYNAMODB_ENDPOINT_URL is distinct from the report service’s T9_ENDPOINT_URL. Replace the example key with the actual table’s complete key. Do not use a different Region or account to make a failed lookup appear successful.
DescribeTable first and construct a key from its actual schema. These ordinary metadata and item reads still follow the adapter’s configured Explain default; a 409 ExplainedNotPerformed preview is not evidence that the resource is missing. For a missing item, an empty GetItem result is different from a missing table. ConsistentRead is meaningful only where the selected mapping supports that read mode. AWS allows strong reads on tables and local secondary indexes, but not on global secondary indexes; target mappings can make different documented choices. Consult the exact service profile before attributing a read difference to propagation. AWS read consistency explains the origin contract.
For Query, preserve the original LastEvaluatedKey and pass it as ExclusiveStartKey on the next request with the same key condition. Do not treat an empty filtered page as the end of the result. Check whether the named index was declared and deployed for this backend. A local index, a global index, and a base-table query can take different target paths. AWS pagination describes the continuation behavior; the service profile describes each mapping’s index support.
Worked case: a conditional update that times out
Suppose an order update setsversion from 4 to 5 when version = 4. The SDK times out after sending UpdateItem. The timeout does not tell you whether the write committed. Save the request ID, exact table and key, condition, endpoint, Region, and report receipt if one was returned. Read that one item with the supported consistency option. If it now has version 5, investigate whether this update or another writer made the change before deciding what to retry. If it remains 4, the original request may still be unresolved; use the application’s idempotency and reconciliation rules. Never send an unconditional replacement just to produce a report.
If the SDK received ConditionalCheckFailedException, preserve the exact submitted condition and investigate competing writers. The item read afterward shows only its current value; it cannot reconstruct the condition’s inputs or item value at the earlier evaluation time. If a transaction was involved, keep the ClientRequestToken and the exact action list. AWS documents a bounded idempotency window for TransactWriteItems; the selected adapter’s transaction behavior must also be checked in its profile. AWS transaction semantics explain the origin token.
To understand the request before another execution, use a signed explicit Explain control on an isolated, representative request, after checking support for that operation and installed version. A completed preview returns 409 ExplainedNotPerformed and a receipt; it does not update the item. Unsupported capture can return a refusal instead. ExecuteAndExplain and the shorthand x-t9-explain: true execute the operation. Preserve the native SDK response and retrieve the report separately with signed T9CloudAdapter.GetExplanation on the install’s published t9 endpoint. Use signing service t9, the published signing Region, and the original report owner’s IAM credentials, including the session token. A different assumed-role session cannot read that owner’s report. See Explaining SDK Requests and Reading an Explanation.
An explanation may show an adapter validation decision, a target operation attempt, an observed state, or a declared gap. Read its assurance and lifecycle before drawing a conclusion. PostgreSQL plans are planned, operation-specific evidence: a full plan may include physical relation names and bound constants, is visible only to the report owner, and estimates a separate committed-state observation. It does not prove that this update committed or that the native execution used that exact plan. Keep it with the report under your normal customer-data controls.
Worked comparison: the same item on PostgreSQL and Cosmos DB
SupposeGetItem for the orders table is slow. The origin request and response can look identical across backends, while the target work differs. Check the installed table mapping first: the catalog includes PostgreSQL profiles, Google Cloud SQL for PostgreSQL, Azure Cosmos DB provisioned and serverless profiles, Firestore, Spanner and Bigtable. Operation support and evidence coverage remain specific to the selected profile and adapter version.
PostgreSQL plan reporting is planned, October 25, 2026. Owner: Tensor9 Cloud Adapter team. The examples below explain the reporting contract and the operation paths being qualified; they do not establish availability in your installed release. The paths being qualified include the
GetItem keyed lookup, PutItem upsert, and filtered, paginated Query and Scan on the base table and a declared secondary index. This does not establish plan coverage for UpdateItem, transactions, every index, or every statement within a conditional write. A missing or unavailable fact must remain explicit.Retrieve the report from the request you already made
Keep the native DynamoDB result and the receipt from that same attempt. A successfulGetItem still returns its ordinary Item; a completed explicit preview returns 409 ExplainedNotPerformed without reading the item through the native execution path. Neither response contains a PostgreSQL plan.
Use the install’s published report endpoint and signing Region, with the same report owner’s IAM session that made the captured request:
T9CloudAdapter.GetExplanation for service t9 and prints the rendered report. It does not replay GetItem or acknowledge the report. A direct SDK client instead decodes the outer AWS JSON response’s body string before inspecting facts. If collection is still in progress, poll the same report with bounded backoff; omit minimumVersion until you have a positive revision. Reads do not extend the fixed expiry in x-t9-explain-expires-at; the default retention is 24 hours. See existing-report retrieval.
PostgreSQL: read the keyed lookup estimate
This is an illustrative assertion excerpt, not a captured production measurement or a complete report. Names, costs and values are example data. An actual fact preserves PostgreSQL’s full JSON, including nested nodes and predicates.item by the physical pk and sk. The example index condition matches both encoded string keys; the physical relation and index names need not match orders. Plan Rows: 1 is an estimate of rows emitted by this node, not proof that the item exists. Total Cost: 8.31 is a PostgreSQL planner cost, not milliseconds. Compare the index condition with any residual Filter and nested Plans; a Seq Scan can be reasonable on a small table and is not automatically a defect.
For the initial PutItem path, look for statementCode: "dynamodb.put-item.upsert" and statementOrdinal: 2. It describes the keyed INSERT ... ON CONFLICT ... DO UPDATE statement. A plan can contain a ModifyTable root and its input node; estimated rows at a write node do not count committed items. An ExecuteAndExplain response and a separate item read establish the write result. A preview plan does not perform that insert or update.
planningContext: "committed-state-observation" means the observer planned the actual SQL and encoded parameters on a separate authenticated, read-only connection. It uses EXPLAIN (FORMAT JSON) without ANALYZE; it does not share the original transaction snapshot or report actual execution time. Early revisions can precede the plan, and an unsupported route or unavailable observer can produce a declared limitation instead. Do not treat absence as evidence that no SQL ran.
Cosmos DB: compare the item path, not a PostgreSQL index
On the provisioned or serverless Cosmos DB profile, the equivalent keyed lookup resolves the item to a Cosmos partition and document ID, then performs a point read. Inspect the report’s recorded validation, route and operation evidence where available, and compare it with the nativeItem or error. For instrumented table dispatch, backend.target-kind identifies the selected backend; an unknown target or declared gap is not permission to infer a route.
There should be no PostgreSQL plan for that Cosmos item operation. PostgreSQL costs and Index Cond do not explain Cosmos request units or throttling. Compare the independently observed Cosmos request charge, throttling and partition behavior for the same interval; those target metrics are separate evidence, not fields promised in every Explain report. The provisioned and serverless profiles also have different index support: a DynamoDB GSI requires the provisioned mapping, while the serverless profile supports local indexes only. Return to the exact backend comparison before changing a query or capacity setting.
A full PostgreSQL plan can contain application literals, physical relation names and predicates. It remains private to the exact report owner in Human, Agent and JSON formats. Review a copy before sharing it; removing the item payload from a support bundle does not sanitize values embedded in a plan.