DynamoDB tables can carry vector indexes for real-time approximate nearest-neighbor search. ddbsh exposes the whole lifecycle — declare the index, write vectors, and run a nearest-neighbor query — as additive SQL-like syntax that maps to the SearchVectors API.
Declaring a vector index
A vector index is declared on CREATE TABLE or added with ALTER TABLE. The clause lead accepts three synonyms: VSI (...), VECTOR (...), or VECTOR INDEX (...). It names the vector attribute with ON <attr> (the vector attribute is not declared in the top-level attribute list), its DIMENSIONS, a DISTANCE function (COSINE | EUCLIDEAN | DOT_PRODUCT), an optional SEARCH KEY schema, and a projection:
CREATE TABLE docs ( id string, category string ) PRIMARY KEY ( id hash ) VSI ( embidx ON embedding DIMENSIONS 1536 DISTANCE COSINE SEARCH KEY ( category FILTER ) PROJECTING ALL );ALTER TABLE docs ( category string ) CREATE VSI embidx ON embedding DIMENSIONS 1536 DISTANCE COSINE SEARCH KEY ( category FILTER ) PROJECTING ALL;ALTER TABLE docs DROP VSI embidx; -- create/drop only; no in-place update
The SEARCH KEY schema names the attributes a search filter may reference — attr HASH or attr FILTER. Vector indexes are create/drop only; there is no in-place update.
Writing vectors
A vector value is written as a bare numeric list. INSERT and UPDATE store it as a DynamoDB list of numbers — no special ceremony:
INSERT INTO docs ( id, embedding ) VALUES ( "d1", [0.12, -0.34, 0.56] );UPDATE docs SET embedding = [0.9, 0.1] WHERE id = "d1";
Searching
A nearest-neighbor query is a SELECT against <table>.<vectorindex> with a NEAREST <n> TO [ ... ] clause. It plans to a SearchVectors call — never GetItem, Query, or Scan. <n> is the TopK; the bracketed numeric list is the query vector, and its length must equal the index’s DIMENSIONS. A WHERE clause becomes the search filter and may reference only the index’s HASH / FILTER search-key attributes:
SELECT * FROM docs.embidx WHERE category = "news" NEAREST 5 TO [0.1, 0.2, 0.3];
Each result row is printed with a trailing score <n> — the similarity score the service returns for that match.
Returning the vector (or not)
The stored vector is treated like any other attribute. SELECT * does not request it — ddbsh sends no ProjectionExpression, and the service omits the vector unless asked. Name the vector attribute in the projection and it comes back, in the same SearchVectors call, at no extra API cost:
-- vector omittedSELECT * FROM docs.embidx NEAREST 3 TO [0.1, 0.2, 0.3];-- vector returned: name it explicitlySELECT id, category, embedding FROM docs.embidx NEAREST 3 TO [0.1, 0.2, 0.3];
Notes
Vector search requires the AWS SDK for C++ ≥ 1.11.916 — the first release exposing SearchVectors. As with every ddbsh extension, the syntax is opt-in and changes no existing command: a table without a vector index behaves exactly as before, and SELECT without NEARESTstill plans through the usual GetItem/Query/Scan matrix.