/amazon-dynamodb

Cost model JSON schema

The cost calculator at ${SKILL_DIR}/scripts/calculate_costs.py reads a JSON file describing the data model and access patterns, and writes a monthly-cost report in Markdown. This document specifies the JSON shape. (${SKILL_DIR} is defined in SKILL.md "Resolving the skill's own paths" — substitute the absolute path of the directory containing SKILL.md.)

The agent generates this JSON from its own in-context design — it is not authored by hand. Everything the calculator needs (RPS, item size, operation, consistency, GSI projection) is already part of a properly produced access-pattern list and schema (per Mechanics #2 and #18). Assembling the JSON is a serialization step, not a separate design exercise.

Top-level shape

{
  "tables": [ /* Table[] */ ],
  "access_patterns": [ /* AccessPattern[] */ ]
}

Only these two arrays are required. Everything else is optional and has sensible defaults.

Table

{
  "table_name": "Orders",
  "table_class": "STANDARD",
  "global_tables": false,
  "key_schema": {
    "partition_key": "customer_id",
    "sort_key": "order_id"
  },
  "entities": [ /* Entity[] */ ],
  "gsis": [ /* Gsi[] */ ],
  "vector_indexes": [ /* VectorIndex[] */ ]
}

Entity

{
  "entity_name": "Order",
  "estimated_item_size_bytes": 2048,
  "estimated_item_count": 500000,
  "attributes": [
    { "name": "order_id", "type": "S" },
    { "name": "status", "type": "S" },
    { "name": "total_cents", "type": "N" }
  ]
}

Entities are used mainly when access patterns specify a projection list. The calculator caps Query/Scan items_per_request at the 900 KB page limit based on the sum of projected attribute sizes. If you never use projection, the entity list is only consulted for the storage fallback.

Key attribute types are load-bearing for live deploy. DynamoDB types only key attributes (PK/SK on the table and every GSI); non-key attributes are schemaless. The deploy builds each table's AttributeDefinitions by looking up every key attribute's type in entities[].attributes[] and the table-level attribute_definitions block (the latter wins on conflict), defaulting to S for any it can't find. A key declared (or defaulted) to the wrong type is the one schema error DynamoDB enforces at write time: a numeric epoch sort key left as S accepts the seed but rejects real integer writes with ValidationException. So whenever a key is an epoch timestamp, a numeric id, or binary, declare it N/B — in either place — and the benchmark/seed path (which reads the same two sources) will generate matching values automatically.

GSI

{
  "index_name": "OrdersByCustomer",
  "partition_key": "customer_id",
  "sort_key": "created_at",
  "projection": {
    "type": "ALL"
  }
}

With an INCLUDE projection:

{
  "index_name": "OrdersByStatusSparse",
  "partition_key": "status_active",
  "sort_key": "created_at",
  "projection": {
    "type": "INCLUDE",
    "attributes": ["order_id", "customer_id", "total_cents"]
  }
}

Projection ratios (applied to base item size):

• ALL → 1.0 (full item written to index; full base-table storage footprint)
• INCLUDE → 0.3 (conservative default when the include list is unknown)
• KEYS_ONLY → 0.1 (keys + SK only)

GSI sparseness (write amplification AND storage). A DynamoDB item is written to — and stored in — a GSI only if it carries that GSI's key (the partition key, plus the sort key if the GSI is composite). This is verified live against ReturnConsumedCapacity=INDEXES: an item missing a composite GSI's sort key fired zero writes to it. In a single-table design with heterogeneous entities, each GSI is keyed on an attribute only some entities have, so most items belong to only one or two of the table's GSIs — not all of them. The calculator models this: write amplification uses entities_written (above) to bill only the member indexes; GSI storage is sized by the byte-share of entities that carry the index's key, not the whole base table. When the model doesn't declare enough to establish membership (no entities_written, or a GSI key declared on no entity), the calculator stays at the conservative full-fan-out / full-size upper bound rather than guessing low.

Vector index

{
  "index_name": "ProductEmbeddingIndex",
  "vector_attribute": "Embedding",
  "dimensions": 1024,
  "distance_function": "COSINE",
  "projection": { "type": "INCLUDE", "attributes": ["Title"] },
  "search_schema": { "partition_key": "Category", "inline_filters": ["Brand"] },
  "estimated_indexed_items": 40000000
}

The calculator rejects a model where a vector-index table declares provisioned_capacity, where dimensions or top_k are out of range, where more than 5 vector indexes are declared on one table, or where indexes on the same attribute disagree on dimensions. These are service constraints, so a violation means the design cannot be deployed — better to fail than to price something impossible.

Vector capacity is metered in BYTES, and the projection is the lever

Vector indexes are billed on three dimensions, separately from base-table RCU/WCU. Rates are from the AWS Pricing API (us-east-1 Standard); Standard-IA is 125% on requests, 40% on storage. Rates change and vary by region: these are the values the calculator ships with, and before quoting a dollar figure to a user in another region — or a long time after this was written — confirm them against aws pricing get-products --service-code AmazonDynamoDB or the DynamoDB pricing page. The shape of the model below is what matters and does not change with the rates.

Write cost, measured semantics (controlled probe: two indexes on the same attribute and dimensions, projection the only variable):

• KEYS_ONLY is flat — dimensions × 4 plus ~35 B of key overhead, and independent of item size. Measured 4,105 / 4,104 / 4,104 B on a 1024-dim index across a minimal item, a +10 KB item, and an item carrying a second vector.
• ALL adds the entire rest of the item to every vector write, including other vector attributes (carried in base-table form, ~5.5 B per number rather than 4). A 10 KB payload added 10,246 B.
• So on a minimal item holding only keys and the vector, ALL costs exactly the same as KEYS_ONLY. The projection only costs what the rest of the item costs. Choose it on item size, not on the vector.
• The 1 KB per-request minimum only binds below 256 dimensions (256 × 4 = 1024 B), so it is moot for every real embedding model.

estimated_item_size_bytes EXCLUDES the vector attributes. Declare the size of the item without its embeddings; the calculator adds each vector's own footprint from dimensions. This matters only for ALL (and INCLUDE naming a vector), where the model is dimensions × 4 + key overhead + the rest of the item — if the declared size already counted the embedding, the vector is billed twice and an ALL index looks roughly twice as expensive as it is. The convention is this way round because dimensions is exact and an item-size estimate is not, so deriving the vector's bytes from dimensions is strictly more accurate than trusting it to be included. A 1024-dim embedding is ~4 KB in the index and ~5.5 KB in base-table form, so on a small item this is the difference between a right answer and a doubled one.

Search cost is deliberately not priced. It bills on the vector data a search examines inside the index plus the data returned, and the examined fraction varies by an order of magnitude with index configuration (measured: 12.8% of all vector bytes on a 60-item unpartitioned index against 1.3% on a 200-item partitioned one). A calibration fitted across configurations came out 51–69% low at 256/1536/3072 dimensions — exactly where real embedding models sit. The report gives the measured drivers instead: TopK is exactly linear, the projection is a ~170× multiplier on bytes returned per result (~89 B for KEYS_ONLY against the whole item for ALL; a TopK=100 search on an ALL index measured 1.52 MB), cost is linear in dimensions at fixed configuration, and index size is not a linear driver because ANN prunes — measured between 10 and 200 vectors in the searched partition. That is not the same as "population never matters": an empty 1024-dimension index measured about twice a populated one, so do not extrapolate the shape down to a sparse or freshly-created index. Obtain the real figure from ReturnConsumedCapacity or the VectorSearchRequestBytes CloudWatch metric — a live validation run measures it for you.

Access pattern

{
  "pattern_id": "Q8",
  "description": "Get order by ID",
  "operation": "GetItem",
  "table": "Orders",
  "index": null,
  "peak_rps": 800,
  "estimated_item_size_bytes": 2048,
  "items_per_request": 1,
  "consistency": "strong"
}

A SearchVectors pattern is shaped a little differently: it targets a vector index by name, carries top_k instead of items_per_request, and takes no consistency (vector search is always eventually consistent, and consumes no RCU).

{
  "pattern_id": "V1",
  "description": "Find similar products",
  "operation": "SearchVectors",
  "table": "Products",
  "index": "ProductEmbeddingIndex",
  "peak_rps": 40,
  "top_k": 10
}

The index MUST name a vector index declared in that table's vector_indexes, or the calculator refuses the model rather than silently costing nothing.

Optional fields that tighten the estimate:

Minimal working example

A tiny Orders table with two patterns — GetItem by id (strong), Query by customer (eventual) — and one GSI:

{
  "tables": [
    {
      "table_name": "Orders",
      "key_schema": {
        "partition_key": "customer_id",
        "sort_key": "order_id"
      },
      "gsis": [
        {
          "index_name": "OrdersByCustomer",
          "partition_key": "customer_id",
          "sort_key": "created_at",
          "projection": { "type": "ALL" }
        }
      ]
    }
  ],
  "access_patterns": [
    {
      "pattern_id": "Q8",
      "description": "Get order by ID",
      "operation": "GetItem",
      "table": "Orders",
      "peak_rps": 800,
      "estimated_item_size_bytes": 2048,
      "consistency": "strong"
    },
    {
      "pattern_id": "Q9",
      "description": "List user orders",
      "operation": "Query",
      "table": "Orders",
      "index": "OrdersByCustomer",
      "peak_rps": 400,
      "estimated_item_size_bytes": 2048,
      "items_per_request": 20,
      "consistency": "eventual"
    }
  ]
}

How it maps to what the skill already produces

The access-pattern list described in SKILL.md already carries the data the calculator needs — the JSON is a literal translation of that table plus the schema:

If a field you would need is not yet in the design, the design itself has a gap — filling the JSON is how you find out.

Running the calculator

python3 ${SKILL_DIR}/scripts/calculate_costs.py --model /path/to/dynamodb_data_model.json --output /path/to/cost_report.md

The calculator prints where it wrote the report and how many patterns and tables it analyzed. Pricing uses DynamoDB Standard table-class, on-demand public rates; rates vary by region, so confirm the figure against the AWS DynamoDB pricing page (or aws pricing get-products --service-code AmazonDynamoDB) for the region you will deploy in before quoting it. Read the disclaimer at the top of the generated report before sharing the number.