feat: DynamoDB vector index support

.github/workflows/benchmark-regression.yml

@@ -26,7 +26,7 @@ jobs:
         # is tee's, so a bench that dies partway leaves a truncated file and
         # still reports success.
         shell: bash
-        run: cd benchmarks && cargo bench --bench embedded_micro -- --output-format bencher | tee criterion_output.txt
+        run: cd benchmarks && rm -rf target/criterion && cargo bench --bench embedded_micro -- --output-format bencher | tee criterion_output.txt
 
       - name: Compare against recent baselines
         id: compare

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- **Breaking (Rust API):** the `StorageBackend` trait gained four required methods for vector index support: `create_vector_table` and `drop_vector_table` manage a vector index's physical shadow table, `update_vector_index_definitions` writes a table's stored vector index definitions, and `insert_vector_items` bulk-inserts backfill rows (taking the new public `VectorItemRow` struct). Backend implementations outside the crate must add all four; the bundled rusqlite and wasm backends already have them. The DynamoDB wire API and the CLI/server/MCP surfaces are unaffected.
+
 ## [0.13.0] - 2026-07-30
 
 ### Added

benchmarks/benches/iai_core.rs

@@ -10,6 +10,8 @@
 #[cfg(feature = "iai-callgrind")]
 use dynoxide::Database;
 #[cfg(feature = "iai-callgrind")]
+use dynoxide::actions::create_table::CreateTableRequest;
+#[cfg(feature = "iai-callgrind")]
 use dynoxide::actions::delete_item::DeleteItemRequest;
 #[cfg(feature = "iai-callgrind")]
 use dynoxide::actions::get_item::GetItemRequest;
@@ -62,6 +64,45 @@ fn setup_put_item_large() -> (Database, PutItemRequest) {
     (db, request)
 }
 
+#[cfg(feature = "iai-callgrind")]
+fn setup_put_item_vector() -> (Database, PutItemRequest) {
+    let db = Database::memory().unwrap();
+    // A small deterministic vector-indexed fixture: one on-demand table with a
+    // single 8-dimension index, so the measurement covers the put plus its
+    // shadow-row fan-out.
+    let create: CreateTableRequest = serde_json::from_value(serde_json::json!({
+        "TableName": "VectorBench",
+        "KeySchema": [{"AttributeName": "pk", "KeyType": "HASH"}],
+        "AttributeDefinitions": [{"AttributeName": "pk", "AttributeType": "S"}],
+        "BillingMode": "PAY_PER_REQUEST",
+        "VectorIndexes": [{
+            "IndexName": "vix",
+            "VectorAttribute": {"AttributeName": "embedding"},
+            "Dimensions": 8,
+            "DistanceFunction": "COSINE",
+            "Projection": {"ProjectionType": "ALL"}
+        }]
+    }))
+    .unwrap();
+    db.create_table(create).unwrap();
+    let mut item = HashMap::new();
+    item.insert("pk".to_string(), AttributeValue::S("vec#000000".to_string()));
+    item.insert(
+        "embedding".to_string(),
+        AttributeValue::L(
+            (0..8)
+                .map(|i| AttributeValue::N(format!("0.{i}")))
+                .collect(),
+        ),
+    );
+    let request = PutItemRequest {
+        table_name: "VectorBench".to_string(),
+        item,
+        ..Default::default()
+    };
+    (db, request)
+}
+
 #[cfg(feature = "iai-callgrind")]
 fn setup_get_item() -> (Database, GetItemRequest) {
     let db = setup_database(1000, ItemSize::Medium);
@@ -155,6 +196,13 @@ fn bench_put_item((db, request): (Database, PutItemRequest)) {
     black_box(db.put_item(request).unwrap());
 }
 
+#[cfg(feature = "iai-callgrind")]
+#[library_benchmark]
+#[bench::vector_indexed(setup_put_item_vector())]
+fn bench_put_item_vector((db, request): (Database, PutItemRequest)) {
+    black_box(db.put_item(request).unwrap());
+}
+
 #[cfg(feature = "iai-callgrind")]
 #[library_benchmark]
 #[bench::by_key(setup_get_item())]
@@ -201,7 +249,8 @@ library_benchmark_group!(
         bench_query,
         bench_scan,
         bench_update_item,
-        bench_delete_item
+        bench_delete_item,
+        bench_put_item_vector
 );
 
 #[cfg(feature = "iai-callgrind")]

src/actions/batch_write_item.rs

@@ -191,15 +191,16 @@ pub async fn execute<S: StorageBackend>(
     // Collect unique (table, pk_str, pk_attr, pk_value) for deferred metrics computation
     let mut affected_partitions: Vec<(String, String, String, AttributeValue)> = Vec::new();
 
-    // OPTIMISATION: maintain_gsis_after_write/maintain_lsis_after_write each
-    // deserialise GSI/LSI definitions from JSON on every call. For batch writes
-    // of 25 items against one table, that's 50 redundant deserialise calls.
-    // A future improvement would hoist parse_gsi_defs/parse_lsi_defs to this
-    // level and pass pre-parsed defs into the maintenance functions.
-
     for (table_name, write_requests) in &mut request.request_items {
         let meta = helpers::require_table_for_item_op(storage, table_name).await?;
         let key_schema = helpers::parse_key_schema(&meta)?;
+        // Parse the index definitions once per table: the maintain helpers'
+        // meta-accepting forms deserialise the JSON on every call, which for
+        // a 25-item batch against one table would repeat the work per item.
+        let gsi_defs = super::gsi::parse_gsi_defs(&meta)?;
+        let lsi_defs = super::lsi::parse_lsi_defs(&meta)?;
+        let vector_defs = super::vector_index::parse_vector_defs(&meta)?;
+        let attr_defs = super::vector_index::parse_attr_defs(&meta)?;
 
         for wr in write_requests {
             if let Some(ref mut put_req) = wr.put_request {
@@ -237,28 +238,40 @@ pub async fn execute<S: StorageBackend>(
                     let old_json = storage
                         .put_item_with_hash(table_name, &pk, &sk, &item_json, size, &hash_prefix)
                         .await?;
-                    let gsi_units = super::gsi::maintain_gsis_after_write(
+                    let gsi_units = super::gsi::maintain_gsis_after_write_with_defs(
                         storage,
                         table_name,
-                        &meta,
+                        &gsi_defs,
                         &pk,
                         &sk,
                         &put_req.item,
                         &key_schema.partition_key,
                         key_schema.sort_key.as_deref(),
                     )
                     .await?;
-                    super::lsi::maintain_lsis_after_write(
+                    super::lsi::maintain_lsis_after_write_with_defs(
                         storage,
                         table_name,
-                        &meta,
+                        &lsi_defs,
                         &pk,
                         &sk,
                         &put_req.item,
                         &key_schema.partition_key,
                         key_schema.sort_key.as_deref(),
                     )
                     .await?;
+                    super::vector_index::maintain_vector_indexes_after_write_with_defs(
+                        storage,
+                        table_name,
+                        &vector_defs,
+                        &attr_defs,
+                        &pk,
+                        &sk,
+                        &put_req.item,
+                        &key_schema,
+                        false,
+                    )
+                    .await?;
                     let old_item: Option<Item> =
                         old_json.and_then(|j| serde_json::from_str(&j).ok());
                     crate::streams::record_stream_event(
@@ -301,12 +314,22 @@ pub async fn execute<S: StorageBackend>(
                     let old_json = storage.delete_item(table_name, &pk, &sk).await?;
                     let old_item: Option<Item> =
                         old_json.as_ref().and_then(|j| serde_json::from_str(j).ok());
-                    let gsi_units = super::gsi::maintain_gsis_after_delete(
-                        storage, table_name, &meta, &pk, &sk,
+                    let gsi_units = super::gsi::maintain_gsis_after_delete_with_defs(
+                        storage, table_name, &gsi_defs, &pk, &sk,
+                    )
+                    .await?;
+                    super::lsi::maintain_lsis_after_delete_with_defs(
+                        storage, table_name, &lsi_defs, &pk, &sk,
+                    )
+                    .await?;
+                    super::vector_index::maintain_vector_indexes_after_delete_with_defs(
+                        storage,
+                        table_name,
+                        &vector_defs,
+                        &pk,
+                        &sk,
                     )
                     .await?;
-                    super::lsi::maintain_lsis_after_delete(storage, table_name, &meta, &pk, &sk)
-                        .await?;
                     if old_item.is_some() {
                         crate::streams::record_stream_event(
                             storage,