NAME

MongoDB::DataTypes - the data types used with MongoDB

DESCRIPTION

This goes over the types you can save to the database and use for queries.

TYPES

Strings

All strings must be valid UTF-8 to be sent to the database. If a string is not valid, it will not be saved. If you need to save a non-UTF-8 string, you can save it as a binary blob (see the Binary Data section below).

All strings returned from the database have the UTF-8 flag set.

Unfortunately, due to Perl weirdness, UTF-8 is not very pretty. For example, suppose we have a UTF-8 string:

my $str = 'Åland Islands';

Now, let's print it:

print "$str\n";

You can see in the output:

"\x{c5}land Islands"

Lovely, isn't it? This is how Perl prints UTF-8. To make it "pretty," you can do one of two things:

my $pretty_str = utf8::encode($str);

which, unintuitively, clears the UTF-8 flag. You can also just run

binmode STDOUT, ':utf8';

and then the string (and all future UTF-8 strings) will print "correctly."

Dates

The DateTime package can be used insert and query for dates. Dates stored in the database will be returned as instances of DateTime.

An example of storing and retrieving a date:

use DateTime;

my $now = DateTime->now;
$collection->insert({'ts' => $now});

my $obj = $collection->find_one;
print "Today is ".$obj->{'ts'}->ymd."\n";

An example of querying for a range of dates:

my $start = DateTime->from_epoch( epoch => 100000 );
my $end = DateTime->from_epoch( epoch => 500000 );

my $cursor = $collection->query({event => {'$gt' => $start, '$lt' => $end}});

Regular Expressions

Use qr/.../ to use a regular expression in a query:

my $cursor = $collection->query({"name" => qr/[Jj]oh?n/});

Regular expressions will match strings saved in the database.

You can also save and retrieve regular expressions themselves:

$collection->insert({"regex" => qr/foo/i});
$obj = $collection->find_one;
if ("FOO" =~ $obj->{'regex'}) { # matches
    print "hooray\n";
}

Note for Perl 5.8 users: flags are lost when regular expressions are retrieved from the database (this does not affect queries or Perl 5.10+).

Booleans

Use the boolean pachage to get boolean values. boolean::true and boolean::false are the only parts of the package used, currently.

An example of inserting boolean values:

use boolean;

$collection->insert({"okay" => true, "name" => "fred"});

An example using boolean values for query operators (only returns documents where the name field exists):

my $cursor = $collection->query({"name" => {'$exists' => boolean::true}});

Most of the time, you can just use 1 or 0 instead of true and false, such as for specifying fields to return. boolean is the only way to save booleans to the database, though.

Numbers

By default, numbers with a decimal point will be saved as doubles (64-bit).

32-bit Platforms

Numbers without decimal points will be saved as 32-bit integers. To save a number as a 64-bit integer, use bigint:

use bigint;

$collection->insert({"user_id" => 28347197234178})

The driver will die if you try to insert a number beyond the signed 64-bit range: -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807.

Numbers that are saved as 64-bit integers will be decoded as doubles.

64-bit Platforms

Numbers without a decimal point will be saved and returned as 64-bit integers.

Keep in mind that this can cause some weirdness to ensue if some machines are 32-bit and others are 64-bit. Take the following example:

• Programmer 1 saves an int on a 32-bit platform.

• Programmer 2 retrieves the document on a 64-bit platform and re-saves it, effectively converting it to a 64-bit int.

• Programmer 1 retrieves the document on their 32-bit machine, which decodes the 64-bit int as a double.

Nothing drastic, but good to be aware of.

MongoDB::OID

"OID" stands for "Object ID", and is a unique id that is automatically added to documents if they do not already have an _id field before they are saved to the database. They are 12 bytes which are guarenteed to be unique. Their string form is a 24-character string of hexidecimal digits.

To create a unique id:

my $oid = MongoDB::OID->new;

To create a MongoDB::OID from an existing 24-character hexidecimal string:

my $oid = MongoDB::OID->new("123456789012345678901234");

Binary Data

By default, all database strings are UTF8. To save images, binaries, and other non-UTF8 data, you can pass the string as a reference to the database. For example:

# non-utf8 string
my $string = "\xFF\xFE\xFF";

$collection->insert({"photo" => \$string});

This will save the variable as binary data, bypassing the UTF8 check.

Binary data can be matched exactly by the database, so this query will match the object we inserted above:

$collection->find({"photo" => \$string});

Comparisons (e.g., $gt, $lt) may not work as you expect with binary data, so it is worth experimenting.

MongoDB::Code

MongoDB::Code is used to represent JavaScript code and, optionally, scope. To create one:

use MongoDB::Code;

my $code = MongoDB::Code->new("code" => "function() { return 'hello, world'; }");

Or, with a scope:

my $code = MongoDB::Code->new("code" => "function() { return 'hello, '+name; }",
    "scope" => "Fred");

Which would then return "hello, Fred" when run.

MongoDB::MinKey

MongoDB::MinKey is "less than" any other value of any type. This can be useful for always returning certain documents first (or last).

MongoDB::MinKey has no methods, fields, or string form. To create one, it is sufficient to say:

bless $minKey, "MongoDB::MinKey";

MongoDB::MaxKey

MongoDB::MaxKey is "greater than" any other value of any type. This can be useful for always returning certain documents last (or first).

MongoDB::MaxKey has no methods, fields, or string form. To create one, it is sufficient to say:

bless $minKey, "MongoDB::MaxKey";

cpanm MongoDB

perl -MCPAN -e shell
install MongoDB