Current File : /home/opti/perl5/lib/perl5/MongoDB/DataTypes.pod
# Copyright 2009 - present MongoDB, Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
# PODNAME: MongoDB::DataTypes
# ABSTRACT: Using MongoDB data types with Perl
# vim: set ts=4 sts=4 sw=4 et tw=75:
__END__
=pod
=encoding UTF-8
=head1 NAME
MongoDB::DataTypes - Using MongoDB data types with Perl
=head1 VERSION
version v2.0.2
=head1 DESCRIPTION
MongoDB stores typed data in a data format called BSON
(L<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
L<BSON> library (and optional L<BSON::XS> library) for converting between
Perl data and the MongoDB BSON format.
=head2 Additional information
Additional information about MongoDB documents and types may be found in
the following MongoDB manual pages:
=over 4
=item *
L<Documents|https://docs.mongodb.com/manual/core/document/>
=item *
L<BSON Types|https://docs.mongodb.com/manual/reference/bson-types/>
=back
=head1 ESSENTIAL CONCEPTS
=head2 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.
=head2 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 L<BSON> library, such as L<BSON::OID> and
L<BSON::Time>.
Wrappers for native types are available when necessary to address
limitations in Perl's type system. For example, one can use L<BSON::Doc>
for a ordered hash or L<BSON::Int64> for a 64-bit integer.
The L<BSON> class has attributes that configure how type wrappers are used
during encoding and decoding.
The L<PERL-BSON Type Mapping|BSON/PERL-BSON-TYPE-MAPPING>
documentation has a detailed table of all BSON type conversions.
=head2 String/number type conversion heuristics
Perl's scalar values can have several underlying, internal representations
such as double, integer, or string (see L<perlguts>). When encoding to
BSON, the default behavior is as follows:
=over 4
=item *
If the value has a valid double representation, it will be encoded to BSON as a double.
=item *
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.
=item *
Otherwise, the value will be encoded as a UTF-8 string.
=back
The L<BSON> library provides the C<prefer_numeric> attribute to more
aggressively coerce number-like strings that don't already have a numeric
representation into a numeric form.
=head2 Order sometimes matters a lot
When writing a query document, the order of B<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 L</Documents> section below for
specific guidance.
=head1 THE BSON::TYPES LIBRARY
L<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 L<BSON::Types>
helper functions are loaded.
=head1 NOTES ON SPECIFIC TYPES
=head2 Arrays
BSON arrays encode and decode via Perl array references.
=head2 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 L<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 L<Tie::IxHash> for a more-interactive ordered document,
but at the expense of tied-object overhead.
The L<BSON> encoder has an C<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.
=head2 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 L<wrap_numbers|BSON/wrap_numbers> attribute to always decode
to a BSON type wrapper class with numeric overloading.
=head3 32-bit Platforms
On a 32-bit platform, the L<BSON> library treats L<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 L<Math::BigInt> objects.
=head3 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
=head3 Long doubles
On a perl compiled with long-double support, floating point number
precision will be lost when sending data to MongoDB.
=head3 Decimal128
MongoDB 3.4 adds support for the IEEE 754 Decimal128 type. The
L<BSON::Decimal128> class is used as a proxy for these values for both
inserting and querying documents. Be sure to use B<strings> when
constructing Decimal128 objects.
$item = {
name => "widget",
price => bson_decimal128("4.99"), # 4.99 as a string
currency => "USD",
};
$coll->insert_one($item);
=head2 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
L</Binary Data>, below).
=head2 Booleans
Boolean values are emulated using the L<boolean> package via the
C<boolean::true> and C<boolean::false> functions. Using L<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 L<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 C<true> and
C<false>, but some commands require L<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:
=over 4
=item *
L<JSON::XS>
=item *
L<JSON::PP>
=item *
L<Cpanel::JSON::XS>
=item *
L<Mojo::JSON>
=item *
L<JSON::Tiny>
=back
=head2 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 C<_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 L<BSON::OID> class is the type wrapper for object IDs.
To create a unique id:
$oid = bson_oid();
To create a L<BSON::OID> from an existing 24-character hexadecimal string:
$oid = bson_oid("123456789012345678901234");
=head2 Regular Expressions
Use C<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
L<not fully compatible with
Perl|https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions#Differences_from_Perl>.
$cursor = $collection->find({"name" => qr/[Jj]oh?n/});
Regular expressions will match strings saved in the database.
B<NOTE>: only the following flags are supported: "imsxlu".
You can also save and retrieve regular expressions themselves, but
regular expressions will be retrieved as L<BSON::Regex>
objects for safety (these will round-trip correctly).
From that object, you can attempt to compile a reference to a C<qr{}> using
the C<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";
}
B<SECURITY NOTE>: A regular expression can evaluate arbitrary code if C<use
re 'eval'> is in scope. You are strongly advised never to use untrusted
input as a regular expression.
=head2 Dates
BSON has a datetime type representing signed Int64 milliseconds relative to
the Unix epoch. As of MongoDB v2.0.0, the lightweight L<BSON::Time>
wrapper is now the default wrapper for datetime data.
The C<bson_time()> helper function uses fractional epoch seconds, for
better integration with the L<Time::HiRes> module:
use Time::HiRes 'time';
$later = bson_time( time() + 60 );
For convenience, The default value for the helper is C<Time::HiRes::time>:
$now = bson_time();
L<BSON::Time> has methods for inflating into various popular Perl date
classes, including L<DateTime>, L<Time::Moment> and L<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,
L<DateTime::Tiny> has no time zone or sub-second precision.
=head2 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
L<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 L<BSON::Bytes> wrapper:
# non-utf8 string
$bytes = "\xFF\xFE\xFF";
$collection->insert_one({"photo" => bson_bytes($bytes)});
Binary data will be decoded into a L<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});
=head2 MinKey and MaxKey
L<BSON::MinKey> is "less than" any other value of any type. This can be useful
for always returning certain documents first.
L<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();
=head1 AUTHORS
=over 4
=item *
David Golden <david@mongodb.com>
=item *
Rassi <rassi@mongodb.com>
=item *
Mike Friedman <friedo@friedo.com>
=item *
Kristina Chodorow <k.chodorow@gmail.com>
=item *
Florian Ragwitz <rafl@debian.org>
=back
=head1 COPYRIGHT AND LICENSE
This software is Copyright (c) 2018 by MongoDB, Inc.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
=cut
Mini Shell