SimpleDB::Class FAQ

The following are some of the questions people have asked about how to use the SimpleDB::Class.

How do I search by primary key?

In SimpleDB, the primary key (aka id or ItemName) is not actually part of the data stored in the item, so you can't use it in a where clause or order by clause. However, there is a special fucntion called itemName() that allows you to do just that. Assuming you were searching a domain here's what that might look like:

 $books->search(where => { 'itemName()' => ['in','x','y','z'] });

The above statement says to return any items that have an id of x, y, or z. This can be useful if you just want to retreive a specific set of items in a single request. Or if you actually specifiy the ids at creation time, and have some sort of logic in them, you may be able to do other things.

You can also use it in an order by clause like this:

 $books->search( where => { color => 'green' }, 'itemName()');

That says return all items where color is green ordered by id. If you're using the auto-generated ids that SimpleDB::Class::Item provides for you, this is a way to produce a semi-random ordered result set.

How do I instantiate an item without inserting it into the database?

As you might notice when you call

 $domain->insert(\%attributes);

it creates the item and inserts it into the database. Sometimes you want to create the item in advance, play around with it, and then decide whether to insert it into the database. This is fairly easy, but not entirely intuitive. Let's assume you have a SimpleDB::Class::Item subclass called Book that you've created. Do the following:

 my $item = Book->new(simpledb=>$simpledb)->update(\%attributes);

or

 my $item = Book->new(simpledb=>$simpledb);
 $item->some_attribute($value);

Then when you're ready to insert it:

 $item->put;

That's all there is to it. Some people are so used to using

 my $books = $simpledb->domain('books');
 my $book = $books->find($id);
 my $book = $books->insert(\%attributes);

that they forget that you can create an object directly using the class.

How can I store multiple objects in the same domain?

Use "recast_using" in SimpleDB::Class::Item. It works like this. First you have a base class like so:

 package StellarBody;

 use Moose;
 extends 'SimpleDB::Class::Item';

 __PACKAGE__->set_domain_name('bodies');
 --PACKAGE__->add_attributes(
    name        => { isa=>'Str' },
    star_id     => { isa=>'Str' },
    class_name  => { isa=>'Str' },
    );
 
 __PACKAGE__->recast_using('class_name');

 1;

The recast_using command sets up the ability to then dynamically load multiple object types depending upon what's in the class_name field. For example:

 package GasGiant;

 use Moose;
 extends 'Planet';

 1;

So now when an object is loaded from SimpleDB with a class_name field of GasGiant, that object will be loaded instead of StellarBody.

How can I shard objects across multiple domains?

Given the previous example of using recast_using to store multiple object types in the same domain, you can do something similar to make sure that some object types get stored in a different domain. You simply add a new set_domain_name command to the subclass:

 package GasGiant;

 use Moose;
 extends 'Planet';

 __PACKAGE__->set_domain_name('gas_giants');

Does the version number have meaning?

Yes. In a version number like 1.0402 there are three pieces of information that can be gleened.

The first is the number before the decimal (1). That is the API version number, and only changes if the API or data storage mechanisms change in an incompatible way to previous releases. Therefore if you write code against version 1.0001 and then sometime later 1.5702 comes out, you can be reasonably sure your code will still function as you expect it to on 1.5702. However, if 2.0000 comes out, all bets are off.

The second number (04) is the feature release. That number is changed every time a new feature is added to the system and released. It gets reset to 00 if the API version number changes.

The third number (02) is the bug fix number. That number is changed every time a new release comes out that only contains bug fixes. It gets reset to 00 if the feature release number is incremented.

 1;

Now all GasGiant objects will be stored in the gas_giants domain, but all other StellarBody objects and subclasses will be stored in the bodies domain.

cpanm SimpleDB::Class

perl -MCPAN -e shell
install SimpleDB::Class