View Source Dynamo.Repo behaviour (Dynamo v0.2.0)
Defines a repository: a supervised process tree that owns the DynamoDB client (region, endpoint, credentials, retry policy) and exposes the operations.
defmodule MyApp.Dynamo do
use Dynamo.Repo, otp_app: :my_app
end
# config/runtime.exs
config :my_app, MyApp.Dynamo,
region: System.get_env("AWS_REGION", "eu-central-1"),
endpoint: System.get_env("DYNAMO_ENDPOINT") # e.g. http://localhost:8000 for DynamoDB Local
# application.ex
children = [MyApp.Dynamo]Configuration
Read from Application.get_env(otp_app, MyRepo) and overridable via
init/1:
:region(required unless:endpointis given – then defaults to"us-east-1"):endpoint– custom URL (DynamoDB Local, VPC endpoint):search_endpoint– URL forSearchVectors(defaulthttps://search-dynamodb.<region>.amazonaws.com):access_key_id,:secret_access_key,:session_token– static credentials (otherwise env → ECS → IMDS, seeDynamo.Credentials):max_retries,:base_backoff_ms,:max_backoff_ms,:receive_timeout,:connect_timeout,:req_options,:telemetry_prefix– seeDynamo.Client:batch_retries– how many times unprocessed batch items are retried (default 5)
Operations
Every function returns {:ok, result} | {:error, %Dynamo.Error{}} and has a
bang variant that raises the error.
put/2,get/2,delete/2,update/3query/2,scan/2→%Dynamo.Page{};query_all/2,scan_all/2→ list (bounded by:limit);stream/2(seeDynamo.Stream)batch_write/2,batch_get/2– automatically chunked and unprocessed items retried with backofftransaction/2–TransactWriteItemssearch_vectors/4–SearchVectorson avector_indexrequest/2– raw action escape hatch
Options are documented on Dynamo.Request.
Summary
Functions
BatchGetItem for any number of structs of one schema. Chunks into 100,
retries UnprocessedKeys. Returns {:ok, %{items: [struct], unprocessed_keys: [key_map]}}.
Items are returned in arbitrary order (DynamoDB does not preserve order).
BatchWriteItem for any number of structs / {:delete, struct} tuples.
Chunks into 25, retries UnprocessedItems with backoff up to
:batch_retries times. Returns {:ok, %{unprocessed: [raw_requests]}} –
unprocessed is empty on full success. Any non-retryable error aborts and
is returned.
DeleteItem. {:ok, nil} or, with return_values: :all_old, {:ok, old_struct | nil}.
GetItem. {:ok, struct} or {:ok, nil} when not found.
PutItem. Returns the struct; with return_values: :all_old returns the previous item (or nil).
Query one page.
Query all pages into a list. :limit bounds the total number of items
returned (pages are requested until that many items are collected or the
data is exhausted). Without :limit this loads the whole partition.
Raw escape hatch.
Scan one page.
Scan all pages into a list (bounded by :limit). Expensive – prefer stream/2.
Vector similarity search on a schema's vector_index. Returns the top-k
items as {struct, score} pairs, most similar first. Score semantics follow
the index distance function: lower is closer for :cosine/:euclidean,
higher for :dot_product.
TransactWriteItems. See Dynamo.Request.transact_write/2 for operation shapes.
On cancellation the returned error has type: :transaction_canceled and
cancellation_reasons (one per operation, in order).
UpdateItem. Returns {:ok, nil} unless return_values: asks for attributes.
Types
@type result(t) :: {:ok, t} | {:error, Dynamo.Error.t()}
Callbacks
Functions
@spec batch_get(module(), [struct()], keyword()) :: result(%{items: [struct()], unprocessed_keys: [map()]})
BatchGetItem for any number of structs of one schema. Chunks into 100,
retries UnprocessedKeys. Returns {:ok, %{items: [struct], unprocessed_keys: [key_map]}}.
Items are returned in arbitrary order (DynamoDB does not preserve order).
@spec batch_write(module(), [struct() | {:delete, struct()}], keyword()) :: result(%{unprocessed: [map()]})
BatchWriteItem for any number of structs / {:delete, struct} tuples.
Chunks into 25, retries UnprocessedItems with backoff up to
:batch_retries times. Returns {:ok, %{unprocessed: [raw_requests]}} –
unprocessed is empty on full success. Any non-retryable error aborts and
is returned.
DeleteItem. {:ok, nil} or, with return_values: :all_old, {:ok, old_struct | nil}.
GetItem. {:ok, struct} or {:ok, nil} when not found.
PutItem. Returns the struct; with return_values: :all_old returns the previous item (or nil).
@spec query(module(), struct(), keyword()) :: result(Dynamo.Page.t())
Query one page.
Query all pages into a list. :limit bounds the total number of items
returned (pages are requested until that many items are collected or the
data is exhausted). Without :limit this loads the whole partition.
Raw escape hatch.
@spec scan(module(), module(), keyword()) :: result(Dynamo.Page.t())
Scan one page.
Scan all pages into a list (bounded by :limit). Expensive – prefer stream/2.
@spec search_vectors(module(), module(), String.t(), [number()], keyword()) :: result(%{results: [{struct(), number()}], consumed_capacity: map() | nil})
Vector similarity search on a schema's vector_index. Returns the top-k
items as {struct, score} pairs, most similar first. Score semantics follow
the index distance function: lower is closer for :cosine/:euclidean,
higher for :dot_product.
{:ok, %{results: [{%Doc{} = doc, 0.12}, ...], consumed_capacity: cc}} =
MyRepo.search_vectors(Doc, "Semantic", embedding, top_k: 5, filter: [lang: "en"])The vector index is eventually consistent; a freshly written item may not be found immediately. Projection determines which fields are populated on the returned structs (others keep their defaults).
TransactWriteItems. See Dynamo.Request.transact_write/2 for operation shapes.
On cancellation the returned error has type: :transaction_canceled and
cancellation_reasons (one per operation, in order).
UpdateItem. Returns {:ok, nil} unless return_values: asks for attributes.