MongoDB::DataTypes - phpMan

NAME
    MongoDB::DataTypes - Using MongoDB data types with Perl

VERSION
    version v2.2.2

DESCRIPTION
    MongoDB stores typed data in a data format called BSON
    (<http://bsonspec.org/>). This document describes how to work with BSON
    data types in the MongoDB Perl driver.

    As of the MongoDB Perl driver v2.0.0, the driver relies on the external
    BSON library (and optional BSON::XS library) for converting between Perl
    data and the MongoDB BSON format.

  Additional information
    Additional information about MongoDB documents and types may be found in
    the following MongoDB manual pages:

    *   Documents <https://docs.mongodb.com/manual/core/document/>

    *   BSON Types <https://docs.mongodb.com/manual/reference/bson-types/>

ESSENTIAL CONCEPTS
  MongoDB records are ordered documents
    A MongoDB record (i.e. "row") is a BSON document -- a list of key-value
    pairs, like a Perl hash except that the keys in a BSON document are
    ordered. Keys are always strings. Values can be any of 20+ BSON types.

    Queries and update specifications are also expressed as documents.

  Type wrapper classes provide non-native and disambiguated types
    In order to represent BSON types that don't natively exist in Perl, we
    use type wrapper classes from the BSON library, such as BSON::OID and
    BSON::Time.

    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
    Perl's scalar values can have several underlying, internal
    representations such as double, integer, or string (see perlguts). When
    encoding to BSON, the default behavior is as follows:

    *   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
    When writing a query document, the order of top level keys doesn't
    matter, but the order of keys in any embedded documents does matter.

        $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.

THE BSON::TYPES LIBRARY
    BSON::Types is a library with helper subroutines to easily create BSON
    type wrappers. Use of this library is highly recommended.

        use BSON::Types ':all';

        $int64   = bson_int64(42);         # force encoding more bits
        $decimal = bson_decimal("24.01");  # Decimal128 type
        $time    = bson_time();            # now

    Examples in the rest of this document assume that all BSON::Types helper
    functions are loaded.

NOTES ON SPECIFIC TYPES
  Arrays
    BSON arrays encode and decode via Perl array references.

  Documents
    Because Perl's hashes guarantee key-order randomness, using hash
    references as documents will lead to BSON documents with a different key
    order. For top-level keys, this shouldn't cause problems, but it may
    cause problems for embedded documents when querying, sorting or indexing
    on the embedded document.

    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
    By default, the BSON decoder decodes doubles and integers into a
    Perl-native form. To maximize fidelity during a roundtrip, the decoder
    supports the wrap_numbers attribute to always decode to a BSON type
    wrapper class with numeric overloading.

   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
    String values are expected to be character-data (not bytes). They are
    encoded as UTF-8 before being sent to the database and decoded from
    UTF-8 when received. If a string can't be decoded, an error will be
    thrown.

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

  Booleans
    Boolean values are emulated using the boolean package via the
    "boolean::true" and "boolean::false" functions. Using boolean objects in
    documents will ensure the documents have the BSON boolean type in the
    database. Likewise, BSON boolean types in the database will be returned
    as boolean objects.

    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
    The BSON object ID type (aka "OID") is a 12 byte identifier that ensures
    uniqueness by mixing a timestamp and counter with host and
    process-specific bytes.

    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
    Use "qr/.../" to use a regular expression in a query, but be sure to
    limit your regular expression to syntax and features supported by PCRE,
    which are not fully compatible with Perl
    <https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions#Diffe
    rences_from_Perl>.

        $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
    BSON has a datetime type representing signed Int64 milliseconds relative
    to the Unix epoch. As of MongoDB v2.0.0, the lightweight BSON::Time
    wrapper is now the default wrapper for datetime data.

    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
    By default, all database strings are UTF-8. To store images, binaries,
    and other non-UTF-8 data, one can use the BSON binary data type via the
    BSON::Bytes wrapper.

    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::MinKey is "less than" any other value of any type. This can be
    useful for always returning certain documents first.

    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();

AUTHORS
    *   David Golden <david AT mongodb.com>

    *   Rassi <rassi AT mongodb.com>

    *   Mike Friedman <friedo AT friedo.com>

    *   Kristina Chodorow <k.chodorow AT gmail.com>

    *   Florian Ragwitz <rafl AT debian.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2020 by MongoDB, Inc.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004