1MongoDB::DataTypes(3) User Contributed Perl DocumentationMongoDB::DataTypes(3)
2
3
4

NAME

6       MongoDB::DataTypes - Using MongoDB data types with Perl
7

VERSION

9       version v2.2.2
10

DESCRIPTION

12       MongoDB stores typed data in a data format called BSON
13       (<http://bsonspec.org/>).  This document describes how to work with
14       BSON data types in the MongoDB Perl driver.
15
16       As of the MongoDB Perl driver v2.0.0, the driver relies on the external
17       BSON library (and optional BSON::XS library) for converting between
18       Perl data and the MongoDB BSON format.
19
20   Additional information
21       Additional information about MongoDB documents and types may be found
22       in the following MongoDB manual pages:
23
24       •   Documents <https://docs.mongodb.com/manual/core/document/>
25
26       •   BSON Types <https://docs.mongodb.com/manual/reference/bson-types/>
27

ESSENTIAL CONCEPTS

29   MongoDB records are ordered documents
30       A MongoDB record (i.e. "row") is a BSON document -- a list of key-value
31       pairs, like a Perl hash except that the keys in a BSON document are
32       ordered.  Keys are always strings.  Values can be any of 20+ BSON
33       types.
34
35       Queries and update specifications are also expressed as documents.
36
37   Type wrapper classes provide non-native and disambiguated types
38       In order to represent BSON types that don't natively exist in Perl, we
39       use type wrapper classes from the BSON library, such as BSON::OID and
40       BSON::Time.
41
42       Wrappers for native types are available when necessary to address
43       limitations in Perl's type system. For example, one can use BSON::Doc
44       for a ordered hash or BSON::Int64 for a 64-bit integer.
45
46       The BSON class has attributes that configure how type wrappers are used
47       during encoding and decoding.
48
49       The PERL-BSON Type Mapping documentation has a detailed table of all
50       BSON type conversions.
51
52   String/number type conversion heuristics
53       Perl's scalar values can have several underlying, internal
54       representations such as double, integer, or string (see perlguts).
55       When encoding to BSON, the default behavior is as follows:
56
57       •   If the value has a valid double representation, it will be encoded
58           to BSON as a double.
59
60       •   Otherwise, if the value has a valid integer interpretation, it will
61           be encoded as either Int32 or Int64; the smallest type that the
62           value fits will be used; a value that overflows will error.
63
64       •   Otherwise, the value will be encoded as a UTF-8 string.
65
66       The BSON library provides the "prefer_numeric" attribute to more
67       aggressively coerce number-like strings that don't already have a
68       numeric representation into a numeric form.
69
70   Order sometimes matters a lot
71       When writing a query document, the order of top level keys doesn't
72       matter, but the order of keys in any embedded documents does matter.
73
74           $coll->insert_one({
75               name => { first => "John", last => "Doe" },
76               age => 42,
77               color => "blue",
78           });
79
80           # Order doesn't matter here
81           $coll->find( { age => 42, color => "blue" } );     # MATCH
82           $coll->find( { color => "blue", age => 42 } );     # MATCH
83
84           # Order *does* matter here
85           $coll->find(
86               { name => { first => "John", last => "Doe" } } # MATCH
87           );
88           $coll->find(
89               { name => { last => "Doe", first => "John" } } # NO MATCH
90           );
91
92       When specifying a sort order or the order of keys for an index, order
93       matters whenever there is more than one key.
94
95       Because of Perl's hash order randomization, be very careful using
96       native hashes with MongoDB.  See the "Documents" section below for
97       specific guidance.
98

THE BSON::TYPES LIBRARY

100       BSON::Types is a library with helper subroutines to easily create BSON
101       type wrappers.  Use of this library is highly recommended.
102
103           use BSON::Types ':all';
104
105           $int64   = bson_int64(42);         # force encoding more bits
106           $decimal = bson_decimal("24.01");  # Decimal128 type
107           $time    = bson_time();            # now
108
109       Examples in the rest of this document assume that all BSON::Types
110       helper functions are loaded.
111

NOTES ON SPECIFIC TYPES

113   Arrays
114       BSON arrays encode and decode via Perl array references.
115
116   Documents
117       Because Perl's hashes guarantee key-order randomness, using hash
118       references as documents will lead to BSON documents with a different
119       key order.  For top-level keys, this shouldn't cause problems, but it
120       may cause problems for embedded documents when querying, sorting or
121       indexing on the embedded document.
122
123       For sending data to the server, the BSON::Doc class provides a very
124       lightweight wrapper around ordered key-value pairs, but it's opaque.
125
126           $doc = bson_doc( name => "Larry", color => "purple" );
127
128       You can also use Tie::IxHash for a more-interactive ordered document,
129       but at the expense of tied-object overhead.
130
131       The BSON encoder has an "ordered" attribute that, if enabled, returns
132       all documents as order-preserving tied hashes.  This is slow, but is
133       the only way to ensure that documents can roundtrip preserving key
134       order.
135
136   Numbers
137       By default, the BSON decoder decodes doubles and integers into a Perl-
138       native form.  To maximize fidelity during a roundtrip, the decoder
139       supports the wrap_numbers attribute to always decode to a BSON type
140       wrapper class with numeric overloading.
141
142       32-bit Platforms
143
144       On a 32-bit platform, the BSON library treats Math::BigInt as the
145       "native" type for integers outside the (signed) 32-bit range.  Values
146       that are encoded as 64-bit integers will be decoded as Math::BigInt
147       objects.
148
149       64-bit Platforms
150
151       On a 64-bit platform, (signed) Int64 values are supported, but, by
152       default, numbers will be stored in the smallest BSON size needed.  To
153       force a 64-bit representation for numbers in the signed 32-bit range,
154       use a type wrapper:
155
156           $int64 = bson_int64(0); # 64 bits of 0
157
158       Long doubles
159
160       On a perl compiled with long-double support, floating point number
161       precision will be lost when sending data to MongoDB.
162
163       Decimal128
164
165       MongoDB 3.4 adds support for the IEEE 754 Decimal128 type.  The
166       BSON::Decimal128 class is used as a proxy for these values for both
167       inserting and querying documents.  Be sure to use strings when
168       constructing Decimal128 objects.
169
170           $item = {
171               name => "widget",
172               price => bson_decimal128("4.99"), # 4.99 as a string
173               currency => "USD",
174           };
175
176           $coll->insert_one($item);
177
178   Strings
179       String values are expected to be character-data (not bytes).  They are
180       encoded as UTF-8 before being sent to the database and decoded from
181       UTF-8 when received.  If a string can't be decoded, an error will be
182       thrown.
183
184       To save or query arbitrary, non-UTF8 bytes, use a binary type wrapper
185       (see "Binary Data", below).
186
187   Booleans
188       Boolean values are emulated using the boolean package via the
189       "boolean::true" and "boolean::false" functions.  Using boolean objects
190       in documents will ensure the documents have the BSON boolean type in
191       the database.  Likewise, BSON boolean types in the database will be
192       returned as boolean objects.
193
194       An example of inserting boolean values:
195
196           use boolean;
197
198           $collection->insert_one({"okay" => true, "name" => "fred"});
199
200       An example of using boolean values for query operators (only returns
201       documents where the name field exists):
202
203           $cursor = $collection->find({"name" => {'$exists' => true}});
204
205       Often, you can just use 1 or 0 in query operations instead of "true"
206       and "false", but some commands require boolean objects and the database
207       will return an error if integers 1 or 0 are used.
208
209       Boolean objects from the following JSON libraries will also be encoded
210       correctly in the database:
211
212       •   JSON::XS
213
214       •   JSON::PP
215
216       •   Cpanel::JSON::XS
217
218       •   Mojo::JSON
219
220       •   JSON::Tiny
221
222   Object IDs
223       The BSON object ID type (aka "OID") is a 12 byte identifier that
224       ensures uniqueness by mixing a timestamp and counter with host and
225       process-specific bytes.
226
227       All MongoDB documents have an "_id" field as a unique identifier.  This
228       field does not have to be an object ID, but if the field does not
229       exist, an object ID is created automatically for it when the document
230       is inserted into the database.
231
232       The BSON::OID class is the type wrapper for object IDs.
233
234       To create a unique id:
235
236           $oid = bson_oid();
237
238       To create a BSON::OID from an existing 24-character hexadecimal string:
239
240           $oid = bson_oid("123456789012345678901234");
241
242   Regular Expressions
243       Use "qr/.../" to use a regular expression in a query, but be sure to
244       limit your regular expression to syntax and features supported by PCRE,
245       which are not fully compatible with Perl
246       <https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions#Differences_from_Perl>.
247
248           $cursor = $collection->find({"name" => qr/[Jj]oh?n/});
249
250       Regular expressions will match strings saved in the database.
251
252       NOTE: only the following flags are supported: "imsxlu".
253
254       You can also save and retrieve regular expressions themselves, but
255       regular expressions will be retrieved as BSON::Regex objects for safety
256       (these will round-trip correctly).
257
258       From that object, you can attempt to compile a reference to a "qr{}"
259       using the "try_compile" method. However, due to PCRE differences, this
260       could fail to compile or could have different match behavior than
261       intended.
262
263           $collection->insert_one({"regex" => qr/foo/i});
264           $obj = $collection->find_one;
265           if ("FOO" =~ $obj->{regex}->try_compile) { # matches
266               print "hooray\n";
267           }
268
269       SECURITY NOTE: A regular expression can evaluate arbitrary code if "use
270       re 'eval'" is in scope.  You are strongly advised never to use
271       untrusted input as a regular expression.
272
273   Dates
274       BSON has a datetime type representing signed Int64 milliseconds
275       relative to the Unix epoch.  As of MongoDB v2.0.0, the lightweight
276       BSON::Time wrapper is now the default wrapper for datetime data.
277
278       The bson_time() helper function uses fractional epoch seconds, for
279       better integration with the Time::HiRes module:
280
281           use Time::HiRes 'time';
282
283           $later = bson_time( time() + 60 );
284
285       For convenience, The default value for the helper is
286       "Time::HiRes::time":
287
288           $now = bson_time();
289
290       BSON::Time has methods for inflating into various popular Perl date
291       classes, including DateTime, Time::Moment and DateTime::Tiny.  The BSON
292       encoder can also encode objects of these types, with limitations on
293       precision and timezone based on the underlying class.  For example,
294       DateTime::Tiny has no time zone or sub-second precision.
295
296   Binary Data
297       By default, all database strings are UTF-8.  To store images, binaries,
298       and other non-UTF-8 data, one can use the BSON binary data type via the
299       BSON::Bytes wrapper.
300
301       The BSON binary type includes the notion of a "subtype" attribute,
302       which can be any integer between 0 and 255.  The meaning of subtypes
303       from 0 to 127 are reserved for definition by MongoDB; values 128 to 255
304       are user-defined.  Binary data values will only match in a MongoDB
305       query if both the binary bytes and the subtypes are the same.  The
306       default subtype is 0 (a.k.a. "generic binary data") and generally
307       should not be modified.
308
309       To roundtrip binary data, use the BSON::Bytes wrapper:
310
311           # non-utf8 string
312           $bytes = "\xFF\xFE\xFF";
313
314           $collection->insert_one({"photo" => bson_bytes($bytes)});
315
316       Binary data will be decoded into a BSON::Bytes object.  It stringifies
317       as the underlying bytes for convenience.
318
319       One can also store binary data by using a string reference.
320
321           $collection->insert_one({"photo" => \$bytes});
322
323   MinKey and MaxKey
324       BSON::MinKey is "less than" any other value of any type.  This can be
325       useful for always returning certain documents first.
326
327       BSON::MaxKey is "greater than" any other value of any type.  This can
328       be useful for always returning certain documents last.
329
330       There is a helper function for each:
331
332           $min = bson_minkey();
333           $max = bson_maxkey();
334

AUTHORS

336       •   David Golden <david@mongodb.com>
337
338       •   Rassi <rassi@mongodb.com>
339
340       •   Mike Friedman <friedo@friedo.com>
341
342       •   Kristina Chodorow <k.chodorow@gmail.com>
343
344       •   Florian Ragwitz <rafl@debian.org>
345
347       This software is Copyright (c) 2020 by MongoDB, Inc.
348
349       This is free software, licensed under:
350
351         The Apache License, Version 2.0, January 2004
352
353
354
355perl v5.38.0                      2023-07-20             MongoDB::DataTypes(3)
Impressum