1MongoDB::DataTypes(3) User Contributed Perl DocumentationMongoDB::DataTypes(3)
2
6 MongoDB::DataTypes - Using MongoDB data types with Perl
7
9 version v2.2.2
10
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 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 Additional information
21 Additional information about MongoDB documents and types may be found
22 in the following MongoDB manual pages:
23 • Documents <https://docs.mongodb.com/manual/core/document/>
25 • BSON Types <https://docs.mongodb.com/manual/reference/bson-types/>
27
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 Queries and update specifications are also expressed as documents.
36 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 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 The BSON class has attributes that configure how type wrappers are used
47 during encoding and decoding.
48 The PERL-BSON Type Mapping documentation has a detailed table of all
50 BSON type conversions.
51 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 • If the value has a valid double representation, it will be encoded
58 to BSON as a double.
59 • 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 • Otherwise, the value will be encoded as a UTF-8 string.
65 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 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 $coll->insert_one({
75 name => { first => "John", last => "Doe" },
76 age => 42,
77 color => "blue",
78 });
79 # Order doesn't matter here
81 $coll->find( { age => 42, color => "blue" } ); # MATCH
82 $coll->find( { color => "blue", age => 42 } ); # MATCH
83 # 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 When specifying a sort order or the order of keys for an index, order
93 matters whenever there is more than one key.
94 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
100 BSON::Types is a library with helper subroutines to easily create BSON
101 type wrappers. Use of this library is highly recommended.
102 use BSON::Types ':all';
104 $int64 = bson_int64(42); # force encoding more bits
106 $decimal = bson_decimal("24.01"); # Decimal128 type
107 $time = bson_time(); # now
108 Examples in the rest of this document assume that all BSON::Types
110 helper functions are loaded.
111
113 Arrays
114 BSON arrays encode and decode via Perl array references.
115 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 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 $doc = bson_doc( name => "Larry", color => "purple" );
127 You can also use Tie::IxHash for a more-interactive ordered document,
129 but at the expense of tied-object overhead.
130 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 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 32-bit Platforms
143 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 64-bit Platforms
150 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 $int64 = bson_int64(0); # 64 bits of 0
157 Long doubles
159 On a perl compiled with long-double support, floating point number
161 precision will be lost when sending data to MongoDB.
162 Decimal128
164 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 $item = {
171 name => "widget",
172 price => bson_decimal128("4.99"), # 4.99 as a string
173 currency => "USD",
174 };
175 $coll->insert_one($item);
177 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 To save or query arbitrary, non-UTF8 bytes, use a binary type wrapper
185 (see "Binary Data", below).
186 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 An example of inserting boolean values:
195 use boolean;
197 $collection->insert_one({"okay" => true, "name" => "fred"});
199 An example of using boolean values for query operators (only returns
201 documents where the name field exists):
202 $cursor = $collection->find({"name" => {'$exists' => true}});
204 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 Boolean objects from the following JSON libraries will also be encoded
210 correctly in the database:
211 • JSON::XS
213 • JSON::PP
215 • Cpanel::JSON::XS
217 • Mojo::JSON
219 • JSON::Tiny
221 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 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 The BSON::OID class is the type wrapper for object IDs.
233 To create a unique id:
235 $oid = bson_oid();
237 To create a BSON::OID from an existing 24-character hexadecimal string:
239 $oid = bson_oid("123456789012345678901234");
241 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 $cursor = $collection->find({"name" => qr/[Jj]oh?n/});
249 Regular expressions will match strings saved in the database.
251 NOTE: only the following flags are supported: "imsxlu".
253 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 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 $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 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 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 The bson_time() helper function uses fractional epoch seconds, for
279 better integration with the Time::HiRes module:
280 use Time::HiRes 'time';
282 $later = bson_time( time() + 60 );
284 For convenience, The default value for the helper is
286 "Time::HiRes::time":
287 $now = bson_time();
289 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 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 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 To roundtrip binary data, use the BSON::Bytes wrapper:
310 # non-utf8 string
312 $bytes = "\xFF\xFE\xFF";
313 $collection->insert_one({"photo" => bson_bytes($bytes)});
315 Binary data will be decoded into a BSON::Bytes object. It stringifies
317 as the underlying bytes for convenience.
318 One can also store binary data by using a string reference.
320 $collection->insert_one({"photo" => \$bytes});
322 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 BSON::MaxKey is "greater than" any other value of any type. This can
328 be useful for always returning certain documents last.
329 There is a helper function for each:
331 $min = bson_minkey();
333 $max = bson_maxkey();
334
336 • David Golden <david@mongodb.com>
337 • Rassi <rassi@mongodb.com>
339 • Mike Friedman <friedo@friedo.com>
341 • Kristina Chodorow <k.chodorow@gmail.com>
343 • Florian Ragwitz <rafl@debian.org>
345
347 This software is Copyright (c) 2020 by MongoDB, Inc.
348 This is free software, licensed under:
350 The Apache License, Version 2.0, January 2004
352perl v5.38.0 2023-07-20 MongoDB::DataTypes(3)