.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MongoDB::DataTypes 3pm"
.TH MongoDB::DataTypes 3pm "2022-06-30" "perl v5.34.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
MongoDB::DataTypes \- Using MongoDB data types with Perl
.SH "VERSION"
.IX Header "VERSION"
version v2.2.2
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
MongoDB stores typed data in a data format called \s-1BSON\s0
(<http://bsonspec.org/>).  This document describes how to work with \s-1BSON\s0
data types in the MongoDB Perl driver.
.PP
As of the MongoDB Perl driver v2.0.0, the driver relies on the external
\&\s-1BSON\s0 library (and optional \s-1BSON::XS\s0 library) for converting between
Perl data and the MongoDB \s-1BSON\s0 format.
.SS "Additional information"
.IX Subsection "Additional information"
Additional information about MongoDB documents and types may be found in
the following MongoDB manual pages:
.IP "\(bu" 4
Documents <https://docs.mongodb.com/manual/core/document/>
.IP "\(bu" 4
\&\s-1BSON\s0 Types <https://docs.mongodb.com/manual/reference/bson-types/>
.SH "ESSENTIAL CONCEPTS"
.IX Header "ESSENTIAL CONCEPTS"
.SS "MongoDB records are ordered documents"
.IX Subsection "MongoDB records are ordered documents"
A MongoDB record (i.e. \*(L"row\*(R") is a \s-1BSON\s0 document \*(-- a list of key-value
pairs, like a Perl hash except that the keys in a \s-1BSON\s0 document are
ordered.  Keys are always strings.  Values can be any of 20+ \s-1BSON\s0 types.
.PP
Queries and update specifications are also expressed as documents.
.SS "Type wrapper classes provide non-native and disambiguated types"
.IX Subsection "Type wrapper classes provide non-native and disambiguated types"
In order to represent \s-1BSON\s0 types that don't natively exist in Perl, we use
type wrapper classes from the \s-1BSON\s0 library, such as \s-1BSON::OID\s0 and
BSON::Time.
.PP
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.
.PP
The \s-1BSON\s0 class has attributes that configure how type wrappers are used
during encoding and decoding.
.PP
The PERL-BSON Type Mapping
documentation has a detailed table of all \s-1BSON\s0 type conversions.
.SS "String/number type conversion heuristics"
.IX Subsection "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
\&\s-1BSON,\s0 the default behavior is as follows:
.IP "\(bu" 4
If the value has a valid double representation, it will be encoded to \s-1BSON\s0 as a double.
.IP "\(bu" 4
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.
.IP "\(bu" 4
Otherwise, the value will be encoded as a \s-1UTF\-8\s0 string.
.PP
The \s-1BSON\s0 library provides the \f(CW\*(C`prefer_numeric\*(C'\fR attribute to more
aggressively coerce number-like strings that don't already have a numeric
representation into a numeric form.
.SS "Order sometimes matters a lot"
.IX Subsection "Order sometimes matters a lot"
When writing a query document, the order of \fBtop\fR level keys doesn't
matter, but the order of keys in any embedded documents does matter.
.PP
.Vb 5
\&    $coll\->insert_one({
\&        name => { first => "John", last => "Doe" },
\&        age => 42,
\&        color => "blue",
\&    });
\&
\&    # Order doesn\*(Aqt 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
\&    );
.Ve
.PP
When specifying a sort order or the order of keys for an index, order
matters whenever there is more than one key.
.PP
Because of Perl's hash order randomization, be very careful using
native hashes with MongoDB.  See the \*(L"Documents\*(R" section below for
specific guidance.
.SH "THE BSON::TYPES LIBRARY"
.IX Header "THE BSON::TYPES LIBRARY"
BSON::Types is a library with helper subroutines to easily create \s-1BSON\s0
type wrappers.  Use of this library is highly recommended.
.PP
.Vb 1
\&    use BSON::Types \*(Aq:all\*(Aq;
\&
\&    $int64   = bson_int64(42);         # force encoding more bits
\&    $decimal = bson_decimal("24.01");  # Decimal128 type
\&    $time    = bson_time();            # now
.Ve
.PP
Examples in the rest of this document assume that all BSON::Types
helper functions are loaded.
.SH "NOTES ON SPECIFIC TYPES"
.IX Header "NOTES ON SPECIFIC TYPES"
.SS "Arrays"
.IX Subsection "Arrays"
\&\s-1BSON\s0 arrays encode and decode via Perl array references.
.SS "Documents"
.IX Subsection "Documents"
Because Perl's hashes guarantee key-order randomness, using hash references
as documents will lead to \s-1BSON\s0 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.
.PP
For sending data to the server, the BSON::Doc class provides a very
lightweight wrapper around ordered key-value pairs, but it's opaque.
.PP
.Vb 1
\&    $doc = bson_doc( name => "Larry", color => "purple" );
.Ve
.PP
You can also use Tie::IxHash for a more-interactive ordered document,
but at the expense of tied-object overhead.
.PP
The \s-1BSON\s0 encoder has an \f(CW\*(C`ordered\*(C'\fR 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.
.SS "Numbers"
.IX Subsection "Numbers"
By default, the \s-1BSON\s0 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 \s-1BSON\s0 type wrapper class with numeric overloading.
.PP
\fI32\-bit Platforms\fR
.IX Subsection "32-bit Platforms"
.PP
On a 32\-bit platform, the \s-1BSON\s0 library treats Math::BigInt as the
\&\*(L"native\*(R" type for integers outside the (signed) 32\-bit range.  Values that
are encoded as 64\-bit integers will be decoded as Math::BigInt objects.
.PP
\fI64\-bit Platforms\fR
.IX Subsection "64-bit Platforms"
.PP
On a 64\-bit platform, (signed) Int64 values are supported, but, by default,
numbers will be stored in the smallest \s-1BSON\s0 size needed.  To force a 64\-bit
representation for numbers in the signed 32\-bit range, use a type wrapper:
.PP
.Vb 1
\&    $int64 = bson_int64(0); # 64 bits of 0
.Ve
.PP
\fILong doubles\fR
.IX Subsection "Long doubles"
.PP
On a perl compiled with long-double support, floating point number
precision will be lost when sending data to MongoDB.
.PP
\fIDecimal128\fR
.IX Subsection "Decimal128"
.PP
MongoDB 3.4 adds support for the \s-1IEEE 754\s0 Decimal128 type.  The
BSON::Decimal128 class is used as a proxy for these values for both
inserting and querying documents.  Be sure to use \fBstrings\fR when
constructing Decimal128 objects.
.PP
.Vb 5
\&    $item = {
\&        name => "widget",
\&        price => bson_decimal128("4.99"), # 4.99 as a string
\&        currency => "USD",
\&    };
\&
\&    $coll\->insert_one($item);
.Ve
.SS "Strings"
.IX Subsection "Strings"
String values are expected to be character-data (not bytes).  They are
encoded as \s-1UTF\-8\s0 before being sent to the database and decoded from \s-1UTF\-8\s0
when received.  If a string can't be decoded, an error will be thrown.
.PP
To save or query arbitrary, non\-UTF8 bytes, use a binary type wrapper (see
\&\*(L"Binary Data\*(R", below).
.SS "Booleans"
.IX Subsection "Booleans"
Boolean values are emulated using the boolean package via the
\&\f(CW\*(C`boolean::true\*(C'\fR and \f(CW\*(C`boolean::false\*(C'\fR functions.  Using boolean objects
in documents will ensure the documents have the \s-1BSON\s0 boolean type in the
database.  Likewise, \s-1BSON\s0 boolean types in the database will be returned
as boolean objects.
.PP
An example of inserting boolean values:
.PP
.Vb 1
\&    use boolean;
\&
\&    $collection\->insert_one({"okay" => true, "name" => "fred"});
.Ve
.PP
An example of using boolean values for query operators (only returns documents
where the name field exists):
.PP
.Vb 1
\&    $cursor = $collection\->find({"name" => {\*(Aq$exists\*(Aq => true}});
.Ve
.PP
Often, you can just use 1 or 0 in query operations instead of \f(CW\*(C`true\*(C'\fR and
\&\f(CW\*(C`false\*(C'\fR, but some commands require boolean objects and the database
will return an error if integers 1 or 0 are used.
.PP
Boolean objects from the following \s-1JSON\s0 libraries will also be encoded
correctly in the database:
.IP "\(bu" 4
\&\s-1JSON::XS\s0
.IP "\(bu" 4
\&\s-1JSON::PP\s0
.IP "\(bu" 4
Cpanel::JSON::XS
.IP "\(bu" 4
Mojo::JSON
.IP "\(bu" 4
JSON::Tiny
.SS "Object IDs"
.IX Subsection "Object IDs"
The \s-1BSON\s0 object \s-1ID\s0 type (aka \*(L"\s-1OID\*(R"\s0) is a 12 byte identifier that ensures
uniqueness by mixing a timestamp and counter with host and
process-specific bytes.
.PP
All MongoDB documents have an \f(CW\*(C`_id\*(C'\fR field as a unique identifier.  This
field does not have to be an object \s-1ID,\s0 but if the field does not exist, an
object \s-1ID\s0 is created automatically for it when the document is inserted
into the database.
.PP
The \s-1BSON::OID\s0 class is the type wrapper for object IDs.
.PP
To create a unique id:
.PP
.Vb 1
\&    $oid = bson_oid();
.Ve
.PP
To create a \s-1BSON::OID\s0 from an existing 24\-character hexadecimal string:
.PP
.Vb 1
\&    $oid = bson_oid("123456789012345678901234");
.Ve
.SS "Regular Expressions"
.IX Subsection "Regular Expressions"
Use \f(CW\*(C`qr/.../\*(C'\fR to use a regular expression in a query, but be sure to limit
your regular expression to syntax and features supported by \s-1PCRE,\s0 which are
not fully compatible with
Perl <https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions#Differences_from_Perl>.
.PP
.Vb 1
\&    $cursor = $collection\->find({"name" => qr/[Jj]oh?n/});
.Ve
.PP
Regular expressions will match strings saved in the database.
.PP
\&\fB\s-1NOTE\s0\fR: only the following flags are supported: \*(L"imsxlu\*(R".
.PP
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).
.PP
From that object, you can attempt to compile a reference to a \f(CW\*(C`qr{}\*(C'\fR using
the \f(CW\*(C`try_compile\*(C'\fR method. However, due to \s-1PCRE\s0 differences, this could fail
to compile or could have different match behavior than intended.
.PP
.Vb 5
\&    $collection\->insert_one({"regex" => qr/foo/i});
\&    $obj = $collection\->find_one;
\&    if ("FOO" =~ $obj\->{regex}\->try_compile) { # matches
\&        print "hooray\en";
\&    }
.Ve
.PP
\&\fB\s-1SECURITY NOTE\s0\fR: A regular expression can evaluate arbitrary code if \f(CW\*(C`use
re \*(Aqeval\*(Aq\*(C'\fR is in scope.  You are strongly advised never to use untrusted
input as a regular expression.
.SS "Dates"
.IX Subsection "Dates"
\&\s-1BSON\s0 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.
.PP
The \f(CW\*(C`bson_time()\*(C'\fR helper function uses fractional epoch seconds, for
better integration with the Time::HiRes module:
.PP
.Vb 1
\&    use Time::HiRes \*(Aqtime\*(Aq;
\&
\&    $later = bson_time( time() + 60 );
.Ve
.PP
For convenience, The default value for the helper is \f(CW\*(C`Time::HiRes::time\*(C'\fR:
.PP
.Vb 1
\&    $now = bson_time();
.Ve
.PP
BSON::Time has methods for inflating into various popular Perl date
classes, including DateTime, Time::Moment and DateTime::Tiny.  The
\&\s-1BSON\s0 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.
.SS "Binary Data"
.IX Subsection "Binary Data"
By default, all database strings are \s-1UTF\-8.\s0  To store images, binaries, and
other non\-UTF\-8 data, one can use the \s-1BSON\s0 binary data type via the
BSON::Bytes wrapper.
.PP
The \s-1BSON\s0 binary type includes the notion of a \*(L"subtype\*(R" 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. \*(L"generic binary data\*(R") and generally should not be modified.
.PP
To roundtrip binary data, use the BSON::Bytes wrapper:
.PP
.Vb 2
\&    # non\-utf8 string
\&    $bytes = "\exFF\exFE\exFF";
\&
\&    $collection\->insert_one({"photo" => bson_bytes($bytes)});
.Ve
.PP
Binary data will be decoded into a BSON::Bytes object.  It stringifies
as the underlying bytes for convenience.
.PP
One can also store binary data by using a string reference.
.PP
.Vb 1
\&    $collection\->insert_one({"photo" => \e$bytes});
.Ve
.SS "MinKey and MaxKey"
.IX Subsection "MinKey and MaxKey"
BSON::MinKey is \*(L"less than\*(R" any other value of any type.  This can be useful
for always returning certain documents first.
.PP
BSON::MaxKey is \*(L"greater than\*(R" any other value of any type.  This can be useful
for always returning certain documents last.
.PP
There is a helper function for each:
.PP
.Vb 2
\&    $min = bson_minkey();
\&    $max = bson_maxkey();
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
David Golden <david@mongodb.com>
.IP "\(bu" 4
Rassi <rassi@mongodb.com>
.IP "\(bu" 4
Mike Friedman <friedo@friedo.com>
.IP "\(bu" 4
Kristina Chodorow <k.chodorow@gmail.com>
.IP "\(bu" 4
Florian Ragwitz <rafl@debian.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by MongoDB, Inc.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Apache License, Version 2.0, January 2004
.Ve