Overview

Module erlcloud_ddb2

• Description
• Data Types
• Function Index
• Function Details

Authors: Ransom Richardson (ransom@ransomr.net).

Description

An Erlang interface to Amazon's DynamoDB.

http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/operationlist.html

erlcloud_ddb2 implements the entire 20120810 API.

Method names match DynamoDB operations converted to lower_case_with_underscores. The one exception is query, which is an Erlang reserved word. The q method implements Query.

Required parameters are passed as function arguments. In addition all methods take an options proplist argument which can be used to pass optional parameters. See function documentation for examples.

Table names, key names, attribute names and any other input strings except attribute values must be binary strings.

Attribute values may be either {Type, Value} or Value. If only Value is provided then the type is inferred. Lists (iolists are handled), binaries and atoms are assumed to be strings. The following are equivalent: {s, <<"value">>}, <<"value">>, "value", value. Numbers are assumed to be numbers. The following are equivalent: {n, 42}, 42. To specify the AWS binary or set types an explicit Type must be provided. For example: {b, <<1,2,3>>} or {ns, [4,5,6]}. Note that binary values will be base64 encoded and decoded automatically. Since some atoms (such as true, false, not_null, null, undefined, delete, etc) have special meanings in some cases, use them carefully.

Output is in the form of {ok, Value} or {error, Reason}. The format of Value is controlled by the out option, which defaults to simple. The possible values are:

* simple - The most interesting part of the output. For example get_item will return the item.

* record - A record containing all the information from the DynamoDB response except field types. This is useful if you need more detailed information than what is returned with simple. For example, with scan and query the record will contain the last evaluated key which can be used to continue the operation.

* typed_record - A record containing all the information from the DynamoDB response. All field values are returned with type information.

* json - The output from DynamoDB as processed by jsx:decode but with no further manipulation. This would rarely be useful, unless the DynamoDB API is updated to include data that is not yet parsed correctly.

Items will be returned as a list of {Name, Value}. In most cases the output will have type information removed. For example: [{<<"String Attribute">>, <<"value">>}, {<<"Number Attribute">>, 42}, {<<"BinaryAttribute">>, <<1,2,3>>}]. The exception is for output fields that are intended to be passed to a subsequent call, such as unprocessed_keys and last_evaluated_key. Those will contain typed attribute values so that they may be correctly passed to subsequent calls.

DynamoDB errors are return in the form {error, {ErrorCode, Message}} where ErrorCode and 'Message' are both binary strings. List of error codes: http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ErrorHandling.html. So to handle conditional check failures, match {error, {<<"ConditionalCheckFailedException">>, _}}.

erlcloud_ddb_util provides a higher level API that implements common operations that may require multiple DynamoDB API calls.

Data Types

attr_defs()

attr_defs() = maybe_list({attr_name(), attr_type()})

attr_name()

attr_name() = binary()

attr_type()

attr_type() = s | n | b | bool | null | ss | ns | bs | l | m

attributes_to_get_opt()

attributes_to_get_opt() = {attributes_to_get, [attr_name()]}

batch_get_item_opt()

batch_get_item_opt() = return_consumed_capacity_opt() | out_opt()

batch_get_item_opts()

batch_get_item_opts() = [batch_get_item_opt()]

batch_get_item_request_item()

batch_get_item_request_item() = {table_name(), [key(), ...], batch_get_item_request_item_opts()} | {table_name(), [key(), ...]}

batch_get_item_request_item_opt()

batch_get_item_request_item_opt() = expression_attribute_names_opt() | projection_expression_opt() | attributes_to_get_opt() | consistent_read_opt()

batch_get_item_request_item_opts()

batch_get_item_request_item_opts() = [batch_get_item_request_item_opt()]

batch_get_item_request_items()

batch_get_item_request_items() = maybe_list(batch_get_item_request_item())

batch_get_item_return()

batch_get_item_return() = ddb_return(#ddb2_batch_get_item{}, [out_item()])

batch_write_item_delete()

batch_write_item_delete() = {delete, key()}

batch_write_item_opt()

batch_write_item_opt() = return_consumed_capacity_opt() | return_item_collection_metrics_opt() | out_opt()

batch_write_item_opts()

batch_write_item_opts() = [batch_write_item_opt()]

batch_write_item_put()

batch_write_item_put() = {put, in_item()}

batch_write_item_request()

batch_write_item_request() = batch_write_item_put() | batch_write_item_delete()

batch_write_item_request_item()

batch_write_item_request_item() = {table_name(), [batch_write_item_request()]}

batch_write_item_request_items()

batch_write_item_request_items() = maybe_list(batch_write_item_request_item())

batch_write_item_return()

batch_write_item_return() = ddb_return(#ddb2_batch_write_item{}, #ddb2_batch_write_item{})

boolean_opt()

boolean_opt(Name) = Name | {Name, boolean()}

comparison_op()

comparison_op() = eq | ne | le | lt | ge | gt | not_null | null | contains | not_contains | begins_with | in | between

condition()

condition() = {attr_name(), not_null | null} | {attr_name(), in_attr_value()} | {attr_name(), in_attr_value(), comparison_op()} | {attr_name(), {in_attr_value(), in_attr_value()}, between} | {attr_name(), [in_attr_value(), ...], in}

condition_expression_opt()

condition_expression_opt() = {condition_expression, expression()}

conditional_op()

conditional_op() = '\'and\'' | '\'or\''

conditional_op_opt()

conditional_op_opt() = {conditional_op, conditional_op()}

conditions()

conditions() = maybe_list(condition())

consistent_read_opt()

consistent_read_opt() = boolean_opt(consistent_read)

create_table_opt()

create_table_opt() = {local_secondary_indexes, local_secondary_indexes()} | {global_secondary_indexes, global_secondary_indexes()} | {stream_specification, stream_specification()}

create_table_opts()

create_table_opts() = [create_table_opt()]

create_table_return()

create_table_return() = ddb_return(#ddb2_create_table{}, #ddb2_table_description{})

ddb_opts()

ddb_opts() = [out_opt()]

ddb_return()

ddb_return(Record, Simple) = {ok, jsx:json_term() | Record | Simple} | {error, term()}

delete_item_opt()

delete_item_opt() = expression_attribute_names_opt() | expression_attribute_values_opt() | condition_expression_opt() | conditional_op_opt() | expected_opt() | {return_values, none | all_old} | return_consumed_capacity_opt() | return_item_collection_metrics_opt() | out_opt()

delete_item_opts()

delete_item_opts() = [delete_item_opt()]

delete_item_return()

delete_item_return() = ddb_return(#ddb2_delete_item{}, out_item())

delete_table_return()

delete_table_return() = ddb_return(#ddb2_delete_table{}, #ddb2_table_description{})

describe_limits_return()

describe_limits_return() = ddb_return(#ddb2_describe_limits{}, #ddb2_describe_limits{})

describe_table_return()

describe_table_return() = ddb_return(#ddb2_describe_table{}, #ddb2_table_description{})

describe_time_to_live_return()

describe_time_to_live_return() = ddb_return(#ddb2_describe_time_to_live{}, #ddb2_time_to_live_description{})

expected_opt()

expected_opt() = {expected, in_expected()}

expression()

expression() = binary()

expression_attribute_names()

expression_attribute_names() = [{binary(), attr_name()}]

expression_attribute_names_opt()

expression_attribute_names_opt() = {expression_attribute_names, expression_attribute_names()}

expression_attribute_values()

expression_attribute_values() = [{binary(), in_attr_value()}]

expression_attribute_values_opt()

expression_attribute_values_opt() = {expression_attribute_values, expression_attribute_values()}

get_item_opt()

get_item_opt() = expression_attribute_names_opt() | projection_expression_opt() | attributes_to_get_opt() | consistent_read_opt() | return_consumed_capacity_opt() | out_opt()

get_item_opts()

get_item_opts() = [get_item_opt()]

get_item_return()

get_item_return() = ddb_return(#ddb2_get_item{}, out_item())

global_secondary_index_def()

global_secondary_index_def() = {index_name(), key_schema(), projection(), read_units(), write_units()}

global_secondary_index_update()

global_secondary_index_update() = {index_name(), read_units(), write_units()} | {index_name(), delete} | global_secondary_index_def()

global_secondary_index_updates()

global_secondary_index_updates() = maybe_list(global_secondary_index_update())

global_secondary_indexes()

global_secondary_indexes() = maybe_list(global_secondary_index_def())

hash_key_name()

hash_key_name() = attr_name()

in_attr()

in_attr() = {attr_name(), in_attr_value()}

in_attr_value()

in_attr_value() = in_string_value() | in_number_value() | {s, in_string_value()} | {n, in_number_value()} | {b, in_binary_value()} | {bool, boolean()} | {null, true} | {ss, [in_string_value(), ...]} | {ns, [in_number_value(), ...]} | {bs, [in_binary_value(), ...]} | {l, [in_attr_value()]} | {m, [in_attr()]}

in_binary_value()

in_binary_value() = binary() | [byte()]

non-empty

in_expected()

in_expected() = maybe_list(in_expected_item())

in_expected_item()

in_expected_item() = {attr_name(), false} | {attr_name(), true, in_attr_value()} | condition()

in_item()

in_item() = [in_attr()]

in_number_value()

in_number_value() = number()

in_string_value()

in_string_value() = binary() | iolist() | atom()

non-empty

in_update()

in_update() = {attr_name(), in_attr_value(), update_action()} | in_attr() | {attr_name(), delete}

in_updates()

in_updates() = maybe_list(in_update())

index_name()

index_name() = binary()

key()

key() = maybe_list(in_attr())

key_schema()

key_schema() = hash_key_name() | {hash_key_name(), range_key_name()}

list_tables_opt()

list_tables_opt() = {limit, pos_integer()} | {exclusive_start_table_name, table_name() | undefined} | out_opt()

list_tables_opts()

list_tables_opts() = [list_tables_opt()]

list_tables_return()

list_tables_return() = ddb_return(#ddb2_list_tables{}, [table_name()])

local_secondary_index_def()

local_secondary_index_def() = {index_name(), range_key_name(), projection()}

local_secondary_indexes()

local_secondary_indexes() = maybe_list(local_secondary_index_def())

maybe_list()

maybe_list(T) = T | [T]

ok_return()

ok_return(T) = {ok, T} | {error, term()}

out_attr()

out_attr() = {attr_name(), out_attr_value()}

out_attr_value()

out_attr_value() = binary() | number() | boolean() | undefined | [binary()] | [number()] | [out_attr_value()] | [out_attr()]

out_item()

out_item() = [out_attr() | in_attr()]

in_attr in the case of typed_record

out_opt()

out_opt() = {out, out_type()}

out_type()

out_type() = json | record | typed_record | simple

projection()

projection() = keys_only | {include, [attr_name()]} | all

projection_expression_opt()

projection_expression_opt() = {projection_expression, expression()}

put_item_opt()

put_item_opt() = expression_attribute_names_opt() | expression_attribute_values_opt() | condition_expression_opt() | conditional_op_opt() | expected_opt() | {return_values, none | all_old} | return_consumed_capacity_opt() | return_item_collection_metrics_opt() | out_opt()

put_item_opts()

put_item_opts() = [put_item_opt()]

put_item_return()

put_item_return() = ddb_return(#ddb2_put_item{}, out_item())

q_opt()

q_opt() = expression_attribute_names_opt() | expression_attribute_values_opt() | projection_expression_opt() | attributes_to_get_opt() | consistent_read_opt() | {filter_expression, expression()} | conditional_op_opt() | {query_filter, conditions()} | {limit, pos_integer()} | {exclusive_start_key, key() | undefined} | boolean_opt(scan_index_forward) | {index_name, index_name()} | {select, select()} | return_consumed_capacity_opt() | out_opt()

q_opts()

q_opts() = [q_opt()]

q_return()

q_return() = ddb_return(#ddb2_q{}, [out_item()])

range_key_name()

range_key_name() = attr_name()

read_units()

read_units() = pos_integer()

return_consumed_capacity()

return_consumed_capacity() = none | total | indexes

return_consumed_capacity_opt()

return_consumed_capacity_opt() = {return_consumed_capacity, return_consumed_capacity()}

return_item_collection_metrics()

return_item_collection_metrics() = none | size

return_item_collection_metrics_opt()

return_item_collection_metrics_opt() = {return_item_collection_metrics, return_item_collection_metrics()}

return_value()

return_value() = none | all_old | updated_old | all_new | updated_new

scan_opt()

scan_opt() = expression_attribute_names_opt() | expression_attribute_values_opt() | projection_expression_opt() | attributes_to_get_opt() | consistent_read_opt() | {filter_expression, expression()} | conditional_op_opt() | {scan_filter, conditions()} | {limit, pos_integer()} | {exclusive_start_key, key() | undefined} | {segment, non_neg_integer()} | {total_segments, pos_integer()} | {index_name, index_name()} | {select, select()} | return_consumed_capacity_opt() | out_opt()

scan_opts()

scan_opts() = [scan_opt()]

scan_return()

scan_return() = ddb_return(#ddb2_scan{}, [out_item()])

select()

select() = all_attributes | all_projected_attributes | count | specific_attributes

stream_specification()

stream_specification() = false | {true, stream_view_type()}

stream_view_type()

stream_view_type() = keys_only | new_image | old_image | new_and_old_images

table_name()

table_name() = binary()

time_to_live_status()

time_to_live_status() = enabled | disabled | enabling | disabling

update_action()

update_action() = put | add | delete

update_item_opt()

update_item_opt() = expression_attribute_names_opt() | expression_attribute_values_opt() | condition_expression_opt() | conditional_op_opt() | expected_opt() | {return_values, return_value()} | return_consumed_capacity_opt() | return_item_collection_metrics_opt() | out_opt()

update_item_opts()

update_item_opts() = [update_item_opt()]

update_item_return()

update_item_return() = ddb_return(#ddb2_update_item{}, out_item())

update_table_opt()

update_table_opt() = {provisioned_throughput, {read_units(), write_units()}} | {attribute_definitions, attr_defs()} | {global_secondary_index_updates, global_secondary_index_updates()} | {stream_specification, stream_specification()} | out_opt()

update_table_opts()

update_table_opts() = [update_table_opt()]

update_table_return()

update_table_return() = ddb_return(#ddb2_update_table{}, #ddb2_table_description{})

update_time_to_live_opt()

update_time_to_live_opt() = {attribute_name, attr_name()} | {enabled, boolean()}

update_time_to_live_opts()

update_time_to_live_opts() = [update_time_to_live_opt()]

update_time_to_live_return()

update_time_to_live_return() = ddb_return(#ddb2_update_time_to_live{}, #ddb2_time_to_live_specification{})

write_units()

write_units() = pos_integer()

Function Index

Function Details

batch_get_item/1

batch_get_item/2

batch_get_item/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html

Example

Get 4 items total from 2 tables.

{ok, Record} = erlcloud_ddb2:batch_get_item( [{<<"Forum">>, [{<<"Name">>, {s, <<"Amazon DynamoDB">>}}, {<<"Name">>, {s, <<"Amazon RDS">>}}, {<<"Name">>, {s, <<"Amazon Redshift">>}}], [{projection_expression, <<"Name, Threads, Messages, Views">>}]}, {<<"Thread">>, [[{<<"ForumName">>, {s, <<"Amazon DynamoDB">>}}, {<<"Subject">>, {s, <<"Concurrent reads">>}}]], [{projection_expression, <<"Tags, Message">>}]}], [{return_consumed_capacity, total}, {out, record}]),

batch_write_item/1

batch_write_item/2

batch_write_item/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html

Example

Put 4 items in the "Forum" table.

configure/2

configure/3

configure/4

configure/5

create_table/5

create_table/6

create_table/7

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_CreateTable.html

Example

Create a table with hash key "ForumName" and range key "Subject" with a local secondary index on "LastPostDateTime" and a global secondary index on "Subject" as hash key and "LastPostDateTime" as range key, read and write capacity 10, projecting all fields

delete_item/2

delete_item/3

delete_item/4

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteItem.html

Example

Delete an item from the "Thread" table if it doesn't have a "Replies" attribute.

{ok, Item} = erlcloud_ddb2:delete_item( <<"Thread">>, [{<<"ForumName">>, {s, <<"Amazon DynamoDB">>}}, {<<"Subject">>, {s, <<"How do I update multiple items?">>}}], [{return_values, all_old}, {condition_expression, <<"attribute_not_exists(Replies)">>}]),

The ConditionExpression option can also be used in place of the legacy ConditionalOperator or Expected parameters.

delete_table/1

delete_table/2

delete_table/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DeleteTable.html

Example

Delete "Reply" table.

describe_limits/0

describe_limits/1

describe_limits/2

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeLimits.html

Example

Describe the current provisioned-capacity limits for your AWS account.

describe_table/1

describe_table/2

describe_table/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTable.html

Example

Describe "Thread" table.

describe_time_to_live/1

describe_time_to_live/2

describe_time_to_live/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_DescribeTimeToLive.html

Example

get_item/2

get_item/3

get_item/4

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html

Example

Get selected attributes from an item in the "Thread" table.

list_tables/0

list_tables/1

list_tables/2

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_ListTables.html

Example

Get the next 3 table names after "Forum".

new/2

new/3

new/4

new/5

put_item/2

put_item/3

put_item/4

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html

Example

Put an item in the "Thread" table if it does not already exist.

{ok, []} = erlcloud_ddb2:put_item( <<"Thread">>, [{<<"LastPostedBy">>, <<"fred@example.com">>}, {<<"ForumName">>, <<"Amazon DynamoDB">>}, {<<"LastPostDateTime">>, <<"201303190422">>}, {<<"Tags">>, {ss, [<<"Update">>, <<"Multiple Items">>, <<"HelpMe">>]}}, {<<"Subject">>, <<"How do I update multiple items?">>}, {<<"Message">>, <<"I want to update multiple items in a single API call. What is the best way to do that?">>}], [{condition_expression, <<"ForumName <> :f and Subject <> :s">>}, {expression_attribute_values, [{<<":f">>, <<"Amazon DynamoDB">>}, {<<":s">>, <<"How do I update multiple items?">>}]}]),

The ConditionExpression option can be used in place of the legacy Expected parameter.

q/2

q/3

q/4

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html

KeyConditions are treated as a required parameter, which appears to be the case despite what the documentation says.

Example

Get up to 3 itesm from the "Thread" table with "ForumName" of "Amazon DynamoDB" and "LastPostDateTime" between specified value. Use the "LastPostIndex".

scan/1

scan/2

scan/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html

Example

Return all items in the "Reply" table.

update_item/3

update_item/4

update_item/5

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateItem.html

AttributeUpdates is treated as a required parameter because callers will almost always provide it. If no updates are desired, You can pass [] for that argument.

Example

Update specific item in the "Thread" table by setting "LastPostBy" if it has the expected previous value.

update_table/2

update_table/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateTable.html

Example

  erlcloud_ddb2:update_table(
    <<"Thread">>,
    [{provisioned_throughput, {10, 10}},
     {global_secondary_index_updates, [{<<"SubjectIdx">>, 10, 10}]}])

update_table/4

update_table/5

update_time_to_live/2

update_time_to_live/3

DynamoDB API: http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_UpdateTimeToLive.html

Example

  erlcloud_ddb2:update_time_to_live(
    <<"SessionData">>,
    [{attribute_name, <<"ExpirationTime">>},
     {enabled, true}])

update_time_to_live/4

Overview

Generated by EDoc