Additional information

• Documents <https://docs.mongodb.com/manual/core/document/>
• BSON Types <https://docs.mongodb.com/manual/reference/bson-types/>

MongoDB records are ordered documents

Queries and update specifications are also expressed as documents.

Type wrapper classes provide non-native and disambiguated types

Wrappers for native types are available when necessary to address limitations in Perl's type system. For example, one can use BSON::Doc for a ordered hash or BSON::Int64 for a 64-bit integer.

The BSON class has attributes that configure how type wrappers are used during encoding and decoding.

The PERL-BSON Type Mapping documentation has a detailed table of all BSON type conversions.

String/number type conversion heuristics

• If the value has a valid double representation, it will be encoded to BSON as a double.
• Otherwise, if the value has a valid integer interpretation, it will be encoded as either Int32 or Int64; the smallest type that the value fits will be used; a value that overflows will error.
• Otherwise, the value will be encoded as a UTF-8 string.

The BSON library provides the "prefer_numeric" attribute to more aggressively coerce number-like strings that don't already have a numeric representation into a numeric form.

Order sometimes matters a lot

    $coll->insert_one({
        name => { first => "John", last => "Doe" },
        age => 42,
        color => "blue",
    });

    # Order doesn't matter here
    $coll->find( { age => 42, color => "blue" } );     # MATCH
    $coll->find( { color => "blue", age => 42 } );     # MATCH

    # Order *does* matter here
    $coll->find(
        { name => { first => "John", last => "Doe" } } # MATCH
    );
    $coll->find(
        { name => { last => "Doe", first => "John" } } # NO MATCH
    );

When specifying a sort order or the order of keys for an index, order matters whenever there is more than one key.

Because of Perl's hash order randomization, be very careful using native hashes with MongoDB. See the "Documents" section below for specific guidance.

Arrays

Documents

For sending data to the server, the BSON::Doc class provides a very lightweight wrapper around ordered key-value pairs, but it's opaque.

    $doc = bson_doc( name => "Larry", color => "purple" );

You can also use Tie::IxHash for a more-interactive ordered document, but at the expense of tied-object overhead.

The BSON encoder has an "ordered" attribute that, if enabled, returns all documents as order-preserving tied hashes. This is slow, but is the only way to ensure that documents can roundtrip preserving key order.

Numbers

32-bit Platforms

On a 32-bit platform, the BSON library treats Math::BigInt as the "native" type for integers outside the (signed) 32-bit range. Values that are encoded as 64-bit integers will be decoded as Math::BigInt objects.

64-bit Platforms

On a 64-bit platform, (signed) Int64 values are supported, but, by default, numbers will be stored in the smallest BSON size needed. To force a 64-bit representation for numbers in the signed 32-bit range, use a type wrapper:

    $int64 = bson_int64(0); # 64 bits of 0

Long doubles

On a perl compiled with long-double support, floating point number precision will be lost when sending data to MongoDB.

Decimal128

MongoDB 3.4 adds support for the IEEE 754 Decimal128 type. The BSON::Decimal128 class is used as a proxy for these values for both inserting and querying documents. Be sure to use strings when constructing Decimal128 objects.

    $item = {
        name => "widget",
        price => bson_decimal128("4.99"), # 4.99 as a string
        currency => "USD",
    };

    $coll->insert_one($item);

Strings

To save or query arbitrary, non-UTF8 bytes, use a binary type wrapper (see "Binary Data", below).

Booleans

An example of inserting boolean values:

    use boolean;

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

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

    $cursor = $collection->find({"name" => {'$exists' => true}});

Often, you can just use 1 or 0 in query operations instead of "true" and "false", but some commands require boolean objects and the database will return an error if integers 1 or 0 are used.

Boolean objects from the following JSON libraries will also be encoded correctly in the database:

• JSON::XS
• JSON::PP
• Cpanel::JSON::XS
• Mojo::JSON
• JSON::Tiny

Object IDs

All MongoDB documents have an "_id" field as a unique identifier. This field does not have to be an object ID, but if the field does not exist, an object ID is created automatically for it when the document is inserted into the database.

The BSON::OID class is the type wrapper for object IDs.

To create a unique id:

    $oid = bson_oid();

To create a BSON::OID from an existing 24-character hexadecimal string:

    $oid = bson_oid("123456789012345678901234");

Regular Expressions

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

Regular expressions will match strings saved in the database.

NOTE: only the following flags are supported: "imsxlu".

You can also save and retrieve regular expressions themselves, but regular expressions will be retrieved as BSON::Regex objects for safety (these will round-trip correctly).

From that object, you can attempt to compile a reference to a "qr{}" using the "try_compile" method. However, due to PCRE differences, this could fail to compile or could have different match behavior than intended.

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

SECURITY NOTE: A regular expression can evaluate arbitrary code if "use re 'eval'" is in scope. You are strongly advised never to use untrusted input as a regular expression.

Dates

The "bson_time()" helper function uses fractional epoch seconds, for better integration with the Time::HiRes module:

    use Time::HiRes 'time';

    $later = bson_time( time() + 60 );

For convenience, The default value for the helper is "Time::HiRes::time":

    $now = bson_time();

BSON::Time has methods for inflating into various popular Perl date classes, including DateTime, Time::Moment and DateTime::Tiny. The BSON encoder can also encode objects of these types, with limitations on precision and timezone based on the underlying class. For example, DateTime::Tiny has no time zone or sub-second precision.

Binary Data

The BSON binary type includes the notion of a "subtype" attribute, which can be any integer between 0 and 255. The meaning of subtypes from 0 to 127 are reserved for definition by MongoDB; values 128 to 255 are user-defined. Binary data values will only match in a MongoDB query if both the binary bytes and the subtypes are the same. The default subtype is 0 (a.k.a. "generic binary data") and generally should not be modified.

To roundtrip binary data, use the BSON::Bytes wrapper:

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

    $collection->insert_one({"photo" => bson_bytes($bytes)});

Binary data will be decoded into a BSON::Bytes object. It stringifies as the underlying bytes for convenience.

One can also store binary data by using a string reference.

    $collection->insert_one({"photo" => \$bytes});

MinKey and MaxKey

BSON::MaxKey is "greater than" any other value of any type. This can be useful for always returning certain documents last.

There is a helper function for each:

    $min = bson_minkey();
    $max = bson_maxkey();