/ 
Net-Amazon-DynamoDB-v0.1.6
River stage zero No dependents
/ Net::Amazon::DynamoDB

NAME

Net::Amazon::DynamoDB - Simple interface for Amazon DynamoDB

DESCRIPTION

Simple to use interface for Amazon DynamoDB

If you want an ORM-like interface with real objects to work with, this is implementation is not for you. If you just want to access DynamoDB in a simple/quick manner - you are welcome.

See https://github.com/ukautz/Net-Amazon-DynamoDB for latest release.

SYNOPSIS

my $ddb = Net::Amazon::DynamoDB->new(
    access_key => $my_access_key,
    secret_key => $my_secret_key,
    tables     => {
        
        # table with only hash key
        sometable => {
            hash_key   => 'id',
            attributes => {
                id   => 'N',
                name => 'S'
            }
        },
        
        # table with hash and reange key key
        othertable => {
            hash_key   => 'id',
            range_key  => 'range_id',
            attributes => {
                id       => 'N',
                range_id => 'N',
                attrib1  => 'S',
                attrib2  => 'S'
            }
        }
    }
);

# create both tables with 10 read and 5 write unites
$ddb->exists_table( $_ ) || $ddb->create_table( $_, 10, 5 )
    for qw/ sometable othertable /;

# insert something into tables
$ddb->put_item( sometable => {
    id   => 5,
    name => 'bla'
} ) or die $ddb->error;
$ddb->put_item( sometable => {
    id        => 5,
    range_key => 7,
    attrib1   => 'It is now '. localtime(),
    attrib1   => 'Or in unix timstamp '. time(),
} ) or die $ddb->error;

CLASS ATTRIBUTES

tables

The table definitions

lwp

Contains LWP::UserAgent instance.

json

Contains JSON instance for decoding/encoding json.

host

DynamoDB API Hostname

Default: dynamodb.us-east-1.amazonaws.com

access_key

AWS API access key

secret_key

AWS API secret key

read_consistent

Whether reads (get_item) consistent per default or not. This does not affcect batch_get_item or scan_items or query_items, which are always eventually consistent.

Default: 0 (eventually consistent)

namespace

Table prefix, prepended before table name on usage

Default: ''

raise_error

Whether database errors (eg 4xx Response from DynamoDB) raise errors or not.

Default: 0

max_retries

Amount of retries a query will be tries if ProvisionedThroughputExceededException is raised until final error.

Default: 0 (do only once, no retries)

retry_timeout

Wait period in seconds between tries. Float allowed.

Default: 0.1 (100ms)

METHODS

create_table $table_name, $read_amount, $write_amount

Create a new Table. Returns description of the table

my $desc_ref = $ddb->create_table( 'table_name', 10, 5 )
$desc_ref = {
    count           => 123,         # amount of "rows"
    status          => 'CREATING',  # or 'ACTIVE' or 'UPDATING' or some error state?
    created         => 1328893776,  # timestamp
    read_amount     => 10,          # amount of read units
    write_amount    => 5,           # amount of write units
    hash_key        => 'id',        # name of the hash key attribute
    hash_key_type   => 'S',         # or 'N',
    #range_key      => 'id',        # name of the hash key attribute (optional)
    #range_key_type => 'S',         # or 'N' (optional)
}

delete_table $table

Delete an existing (and defined) table.

Returns bool whether table is now in deleting state (succesfully performed)

describe_table $table

Returns table information

my $desc_ref = $ddb->describe_table( 'my_table' );
$desc_ref = {
    existing        => 1,
    size            => 123213,      # data size in bytes
    count           => 123,         # amount of "rows"
    status          => 'ACTIVE',    # or 'DELETING' or 'CREATING' or 'UPDATING' or some error state
    created         => 1328893776,  # timestamp
    read_amount     => 10,          # amount of read units
    write_amount    => 5,           # amount of write units
    hash_key        => 'id',        # name of the hash key attribute
    hash_key_type   => 'S',         # or 'N',
    #range_key      => 'id',        # name of the hash key attribute (optional)
    #range_key_type => 'S',         # or 'N' (optional)
}

If no such table exists, return is

{
    existing => 0
}

update_table $table, $read_amount, $write_amount

Update read and write amount for a table

exists_table $table

Returns bool whether table exists or not

list_tables

Returns tables names as arrayref (or array in array context)

put_item $table, $item_ref, [$where_ref], [$return_old]

Write a single item to table. All primary keys are required in new item.

# just write
$ddb->put_item( my_table => {
    id => 123,
    some_attrib => 'bla',
    other_attrib => 'dunno'
} );

# write conditionally
$ddb->put_item( my_table => {
    id => 123,
    some_attrib => 'bla',
    other_attrib => 'dunno'
}, {
    some_attrib => { # only update, if some_attrib has the value 'blub'
        value => 'blub'
    },
    other_attrib => { # only update, if a value for other_attrib exists
        exists => 1
    }
} );

  • $table

    Name of the table

  • $item_ref

    Hashref containing the values to be inserted

  • $where_ref [optional]

    Filter containing expected values of the (existing) item to be updated

    {}

update_item $table, $update_ref, $where_ref, [$return_old]

Update existing item in database. All primary keys are required in where clause

# update existing
$ddb->update_item( my_table => {
    id => 123,
    some_attrib => 'bla',
    other_attrib => 'dunno'
} );

# write conditionally
$ddb->update_item( my_table => {
    id => 123,
    some_attrib => 'bla',
    other_attrib => 'dunno'
}, {
    some_attrib => { # only update, if some_attrib has the value 'blub'
        value => 'blub'
    },
    other_attrib => { # only update, if a value for other_attrib exists
        exists => 1
    }
} );

  • $table

    Name of the table

  • $update_ref

    Hashref containing the updates.

    • delete a single values

      { attribname => undef }

    • replace a values

      { 
    attribname1 => 'somevalue',
    attribname2 => [ 1, 2, 3 ]
}

    • add values (arrays only)

      { attribname => \[ 4, 5, 6 ] }

  • $where_ref [optional]

    Filter

get_item $table, $pk_ref, [$args_ref]

Read a single item by hash (and range) key.

# only with hash key
my $item1 = $ddb->get_item( my_table => { id => 123 } );
print "Got $item1->{ some_key }\n";

# with hash and range key, also consistent read and only certain attributes in return
my $item2 = $ddb->get_item( my_other_table =>, {
    id    => $hash_value, # the hash value
    title => $range_value # the range value
}, {
    consistent => 1,
    attributes => [ qw/ attrib1 attrib2 ]
} );
print "Got $item2->{ attrib1 }\n";

batch_get_item

Read multiple items (possible accross multiple tables) identified by their hash and range key (if required).

my $res = $ddb->batch_get_item( {
    table_name => [
        { $hash_key => $value1 },
        { $hash_key => $value2 },
        { $hash_key => $value3 },
    ],
    other_table_name => {
        keys => [
            { $hash_key => $value1, $range_key => $rvalue1 },
            { $hash_key => $value2, $range_key => $rvalue2 },
            { $hash_key => $value3, $range_key => $rvalue3 },
        ],
        attributes => [ qw/ attrib1 attrib2 / ]
    ]
} );

foreach my $table( keys %$res ) {
    foreach my $item( @{ $res->{ $table } } ) {
        print "$item->{ some_attrib }\n";
    }
}

delete_item

Deletes a single item by primary key (hash or hash+range key).

# only with hash key

query_items $table, $where, $args

Search in a table with hash AND range key.

my ( $count, $items_ref, $next_start_keys_ref )
    = $ddb->qyery_items( some_table => { id => 123, my_range_id => { GT => 5 } } );
print "Found $count items, where last id is ". $items_ref->[-1]->{ id }. "\n";

# iterate through al all "pages"
my $next_start_keys_ref;
do {
    ( my $count, my $items_ref, $next_start_keys_ref )
        = $ddb->qyery_items( some_table => { id => 123, my_range_id => { GT => 5 } }, {
            start_key => $next_start_keys_ref
        } );
} while( $next_start_keys_ref );

  • $table

    Name of the table

  • $where

    Search condition. Has to contain a value of the primary key and a search-value for the range key.

    Search-value for range key can be formated in two ways

  • $args

    {
    limit => 5,
    consistent => 0,
    backward => 0,
    #start_key =>  { .. }
    attributes => [ qw/ attrib1 attrib2 / ],
    #count => 1
}

    HASHREF containing:

    • limit

      Amount of items to return

      Default: unlimited

    • consistent

      If set to 1, consistent read is performed

      Default: 0

    • backward

      Whether traverse index backward or forward.

      Default: 0 (=forward)

    • start_key

      Contains start key, as return in LastEvaluatedKey from previous query. Allows to iterate above a table in pages.

      { $hash_key => 5, $range_key => "something" }

    • attributes

      Return only those attributes

      [ qw/ attrib attrib2 / ]

    • count

      Instead of returning the actual result, return the count.

      Default: 0 (=return result)

    • all

      Iterate through all pages (see link to API above) and return them all.

      Can take some time. Also: max_retries might be needed to set, as a scan/query create lot's of read-units, and an immediate reading of the next "pages" lead to an Exception due to too many reads.

      Default: 0 (=first "page" of items)

scan_items $table, $filter, $args

Performs scan on table. The result is eventually consistent. Non hash or range keys are allowed in the filter.

See query_items for argument description.

Main difference to query_items: A whole table scan is performed, which is much slower. Also the amount of data scanned is limited in size; see http://docs.amazonwebservices.com/amazondynamodb/latest/developerguide/API_Scan.html

request

Arbitrary request to DynamoDB API

error [$str]

Get/set last error

AUTHOR

COPYRIGHT

Copyright (c) 2012 the "AUTHOR" as listed above

LICENCSE

Same license as Perl itself.

2 POD Errors

The following errors were encountered while parsing the POD:

Around line 634:

You forgot a '=back' before '=head2'

Around line 816:

You forgot a '=back' before '=head2'