ExAws v1.0.0 ExAws.Dynamo
Operations on the AWS Dynamo service.
NOTE: When Mix.env in [:test, :dev] dynamo clients will run by default against Dynamodb local.
Basic usage
defmodule User do
@derive [ExAws.Dynamo.Encodable]
defstruct [:email, :name, :age, :admin]
end
alias ExAws.Dynamo
# Create a users table with a primary key of email [String]
# and 1 unit of read and write capacity
Dynamo.create_table("Users", "email", %{email: :string}, 1, 1)
|> ExAws.request!
user = %User{email: "bubba@foo.com", name: "Bubba", age: 23, admin: false}
# Save the user
Dynamo.put_item("Users", user) |> ExAws.request!
# Retrieve the user by email and decode it as a User struct.
result = Dynamo.get_item("Users", %{email: user.email})
|> ExAws.request!
|> Dynamo.Decoder.decode(as: User)
assert user == resultGeneral notes
All options are handled as underscored atoms instead of camelcased binaries as specified
in the Dynamo API. IE IndexName would be :index_name. Anywhere in the API that requires
dynamo type annotation ({"S":"mystring"}) is handled for you automatically. IE
ExAws.Dynamo.scan("Users", expression_attribute_values: [api_key: "foo"])Transforms into a query of
%{"ExpressionAttributeValues" => %{api_key: %{"S" => "foo"}}, "TableName" => "Users"}Consult the function documentation to see precisely which options are handled this way.
If you wish to avoid this kind of automatic behaviour you are free to specify the types yourself. IE:
ExAws.Dynamo.scan("Users", expression_attribute_values: [api_key: %{"B" => "Treated as binary"}])Becomes:
%{"ExpressionAttributeValues" => %{api_key: %{"B" => "Treated as binary"}}, "TableName" => "Users"}Alternatively, if what’s being encoded is a struct, you’re always free to implement ExAws.Dynamo.Encodable for that struct.
http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Operations.html
Summary
Functions
Get up to 100 items (16mb)
Put or delete up to 25 items (16mb)
Create table with secondary indices
Decode an item returned from Dynamo. This will handle items wrapped in the ordinary
get_item response map of %{"Item" => item}
Delete item in table
Delete Table
Describe table
Get item from table
List tables
Put item in table
Query Table
Scan table
Update item in table
Update Table
Types
batch_get_item_opts() :: [{:return_consumed_capacity, return_consumed_capacity_vals}]
batch_write_item_opts() :: [return_consumed_capacity: return_consumed_capacity_vals, return_item_collection_metrics: return_item_collection_metrics_vals]
delete_item_opts() :: [condition_expression: binary, expression_attribute_names: expression_attribute_names_vals, expression_attribute_values: expression_attribute_values_vals, return_consumed_capacity: return_consumed_capacity_vals, return_item_collection_metrics: return_item_collection_metrics_vals, return_values: return_values_vals]
dynamo_type_names :: :blob | :boolean | :blob_set | :list | :map | :number_set | :null | :number | :string | :string_set
exclusive_start_key_vals :: [{atom, binary}] | %{optional(atom) => binary}
expression_attribute_names_vals() :: %{optional(binary) => binary}
expression_attribute_values_vals :: [{atom, binary}] | %{optional(atom) => binary}
get_item_opts() :: [consistent_read: boolean, expression_attribute_names: expression_attribute_names_vals, projection_expression: binary, return_consumed_capacity: return_consumed_capacity_vals]
put_item_opts() :: [condition_expression: binary, expression_attribute_names: expression_attribute_names_vals, expression_attribute_values: expression_attribute_values_vals, return_consumed_capacity: return_consumed_capacity_vals, return_item_collection_metrics: return_item_collection_metrics_vals, return_values: return_values_vals]
query_opts() :: [consistent_read: boolean, exclusive_start_key: exclusive_start_key_vals, expression_attribute_names: expression_attribute_names_vals, expression_attribute_values: expression_attribute_values_vals, filter_expression: binary, index_name: binary, key_condition_expression: binary, limit: pos_integer, projection_expression: binary, return_consumed_capacity: return_consumed_capacity_vals, scan_index_forward: boolean, select: select_vals]
return_values_vals :: :none | :all_old | :updated_old | :all_new | :updated_new
scan_opts() :: [exclusive_start_key: exclusive_start_key_vals, expression_attribute_names: expression_attribute_names_vals, expression_attribute_values: expression_attribute_values_vals, filter_expression: binary, index_name: binary, limit: pos_integer, projection_expression: binary, return_consumed_capacity: return_consumed_capacity_vals, segment: non_neg_integer, select: select_vals, total_segments: pos_integer]
select_vals :: :all_attributes | :all_projected_attributes | :specific_attributes | :count
update_item_opts() :: [condition_expression: binary, expression_attribute_names: expression_attribute_names_vals, expression_attribute_values: expression_attribute_values_vals, return_consumed_capacity: return_consumed_capacity_vals, return_item_collection_metrics: return_item_collection_metrics_vals, return_values: return_values_vals, update_expression: binary]
write_item() :: [[{:delete_request, [{:key, primary_key}]}] | [{:put_request, [{:item, %{}}]}]]
Functions
batch_get_item(%{optional(table_name) => get_item}, opts :: batch_get_item_opts) :: ExAws.Operation.JSON.t
Get up to 100 items (16mb)
Map of table names to request parameter maps. http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html
Parameters with keys that are automatically annotated with dynamo types are:
[:keys]
Dynamo.batch_get_item(%{
"Users" => [
consistent_read: true,
keys: [
[api_key: "key1"],
[api_key: "api_key2"]
]
],
"Subscriptions" => %{
keys: [
%{id: "id1"}
]
}
})As you see you’re largely free to use either keyword args or maps in the body. A map is required for the argument itself because the table names are most often binaries, and I refuse to inflict proplists on anyone.
batch_write_item(%{optional(table_name) => [write_item]}, opts :: batch_write_item_opts) :: ExAws.Operation.JSON.t
Put or delete up to 25 items (16mb)
Map of table names to request parameter maps. http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html
Parameters with keys that are automatically annotated with dynamo types are:
[:keys]
create_table(table_name :: binary, key_schema :: binary | atom | key_schema, key_definitions :: key_definitions, read_capacity :: pos_integer, write_capacity :: pos_integer) :: ExAws.Operation.JSON.t
Create table
key_schema can be a simple binary or atom indicating a simple hash key
create_table(table_name :: binary, key_schema :: key_schema, key_definitions :: key_definitions, read_capacity :: pos_integer, write_capacity :: pos_integer, global_indexes :: [Map.t], local_indexes :: [Map.t]) :: ExAws.ExAws.Operation.JSON.t
Create table with secondary indices
Each index should follow the format outlined here: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CreateTable.html
For convenience, the keys in each index map are allowed to be atoms. IE:
"KeySchema" in the aws docs can be key_schema:
Note that both the global_indexes and local_indexes arguments expect a list of such indices.
Examples
secondary_index = [%{
index_name: "my-global-index",
key_schema: [%{
attribute_name: "email",
attribute_type: "HASH",
}],
provisioned_throughput: %{
read_capacity_units: 1,
write_capacity_units: 1,
},
projection: %{
projection_type: "KEYS_ONLY",
}
}]
create_table("TestUsers", [id: :hash], %{id: :string}, 1, 1, secondary_index, [])Decode an item returned from Dynamo. This will handle items wrapped in the ordinary
get_item response map of %{"Item" => item}.
Example
Dynamo.get_item("users", %{id: "asdf"})
|> ExAws.request!
|> Dynamo.decode_item(as: User)delete_item(table_name :: table_name, primary_key :: primary_key, opts :: delete_item_opts) :: ExAws.Operation.JSON.t
Delete item in table
Delete Table
Describe table
get_item(table_name :: table_name, primary_key :: primary_key, opts :: get_item_opts) :: ExAws.Operation.JSON.t
Get item from table
List tables
put_item(table_name :: table_name, record :: %{}, opts :: put_item_opts) :: ExAws.Operation.JSON.t
Put item in table
query(table_name :: table_name, opts :: query_opts) :: ExAws.Operation.JSON.t
Query Table
Please read: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html
Dynamo.query("Users",
limit: 1,
expression_attribute_values: [desired_api_key: "adminkey"],
key_condition_expression: "api_key = :desired_api_key")Parameters with keys that are automatically annotated with dynamo types are:
[:exclusive_start_key, :expression_attribute_names]
Scan table
Please read http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html
Dynamo.scan("Users"
limit: 1,
expression_attribute_values: [desired_api_key: "adminkey"],
expression_attribute_names: %{"#asdf" => "api_key"},
filter_expression: "#asdf = :desired_api_key")Generally speaking you won’t need to use :expression_attribute_names. It exists
to alias a column name if one of the columns you want to search against is a reserved dynamo word,
like Percentile. In this case it’s totally unnecessary as api_key is not a reserved word.
Parameters with keys that are automatically annotated with dynamo types are:
[:exclusive_start_key, :expression_attribute_names]
update_item(table_name :: table_name, primary_key :: primary_key, opts :: update_item_opts) :: ExAws.Operation.JSON.t
Update item in table
For update_args format see http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html
update_table(name :: binary, attributes :: Keyword.t) :: ExAws.Operation.JSON.t
Update Table