1MongoDB::DataTypes(3) User Contributed Perl DocumentationMongoDB::DataTypes(3)
2
6 MongoDB::DataTypes - The data types used with MongoDB
7
9 This goes over the types you can save to the database and use for
10 queries.
11
13 You must query for data using the correct type.
14 For example, it is perfectly valid to have some records where the field
15 "foo" is 123 (integer) and other records where "foo" is "123" (string).
16 Thus, you must query for the correct type. If you save "{"foo" ="
17 "123"}>, you cannot query for it with "{"foo" =" 123}>. MongoDB is
18 strict about types.
19 If the type of a field is ambiguous and important to your application,
21 you should document what you expect the application to send to the
22 database and convert your data to those types before sending. There
23 are some object-document mappers that will enforce certain types for
24 certain fields for you.
25 You generally shouldn't save numbers as strings, as they will behave
27 like strings (e.g., range queries won't work correctly) and the data
28 will take up more space.
29 Numbers are the only exception to the strict typing: all number types
31 stored by MongoDB (32-bit integers, 64-bit integers, 64-bit floating
32 point numbers) will match each other.
33
35 Strings
36 All strings must be valid UTF-8 to be sent to the database. If a
37 string is not valid, it will not be saved. If you need to save a
38 non-UTF-8 string, you can save it as a binary blob (see the Binary Data
39 section below).
40 All strings returned from the database have the UTF-8 flag set.
42 Unfortunately, due to Perl weirdness, UTF-8 is not very pretty. For
44 example, suppose we have a UTF-8 string:
45 my $str = 'A~Xland Islands';
47 Now, let's print it:
49 print "$str\n";
51 You can see in the output:
53 "\x{c5}land Islands"
55 Lovely, isn't it? This is how Perl prints UTF-8. To make it "pretty,"
57 there are a couple options:
58 my $pretty_str = utf8::encode($str);
60 This, unintuitively, clears the UTF-8 flag.
62 You can also just run
64 binmode STDOUT, ':utf8';
66 and then the string (and all future UTF-8 strings) will print
68 "correctly."
69 You can also turn off $MongoDB::BSON::utf_flag_on, and the UTF-8 flag
71 will not be set when strings are decoded:
72 $MongoDB::BSON::utf8_flag_on = 0;
74 Arrays
76 Arrays must be saved as array references ("\@foo", not @foo).
77 Embedded Documents
79 Embedded documents are of the same form as top-level documents: either
80 hash references or Tie::IxHashs.
81 Dates
83 The DateTime package can be used insert and query for dates. Dates
84 stored in the database will be returned as instances of DateTime.
85 An example of storing and retrieving a date:
87 use DateTime;
89 my $now = DateTime->now;
91 $collection->insert({'ts' => $now});
92 my $obj = $collection->find_one;
94 print "Today is ".$obj->{'ts'}->ymd."\n";
95 An example of querying for a range of dates:
97 my $start = DateTime->from_epoch( epoch => 100000 );
99 my $end = DateTime->from_epoch( epoch => 500000 );
100 my $cursor = $collection->query({event => {'$gt' => $start, '$lt' => $end}});
102 Warning: creating DateTime objects is extremely slow. Consider saving
104 dates as numbers and converting the numbers to DateTimes when needed.
105 A single DateTime field can make deserialization up to 10 times slower.
106 For example, you could use the time function to store seconds since the
108 epoch:
109 $collection->update($criteria, {'$set' => {"last modified" => time()}})
111 This will be faster to deserialize.
113 Regular Expressions
115 Use "qr/.../" to use a regular expression in a query:
116 my $cursor = $collection->query({"name" => qr/[Jj]oh?n/});
118 Regular expressions will match strings saved in the database.
120 You can also save and retrieve regular expressions themselves:
122 $collection->insert({"regex" => qr/foo/i});
124 $obj = $collection->find_one;
125 if ("FOO" =~ $obj->{'regex'}) { # matches
126 print "hooray\n";
127 }
128 Note for Perl 5.8 users: flags are lost when regular expressions are
130 retrieved from the database (this does not affect queries or Perl
131 5.10+).
132 Booleans
134 Use the boolean package to get boolean values. "boolean::true" and
135 "boolean::false" are the only parts of the package used, currently.
136 An example of inserting boolean values:
138 use boolean;
140 $collection->insert({"okay" => true, "name" => "fred"});
142 An example using boolean values for query operators (only returns
144 documents where the name field exists):
145 my $cursor = $collection->query({"name" => {'$exists' => boolean::true}});
147 Most of the time, you can just use 1 or 0 instead of "true" and
149 "false", such as for specifying fields to return. boolean is the only
150 way to save booleans to the database, though.
151 By default, booleans are returned from the database as integers. To
153 return booleans as booleans, set $MongoDB::BSON::use_boolean to 1.
154 Numbers
156 By default, numbers with a decimal point will be saved as doubles
157 (64-bit).
158 32-bit Platforms
160 Numbers without decimal points will be saved as 32-bit integers. To
162 save a number as a 64-bit integer, use bigint:
163 use bigint;
165 $collection->insert({"user_id" => 28347197234178})
167 The driver will die if you try to insert a number beyond the signed
169 64-bit range: -9,223,372,036,854,775,808 to +9,223,372,036,854,775,807.
170 Numbers that are saved as 64-bit integers will be decoded as doubles.
172 64-bit Platforms
174 Numbers without a decimal point will be saved and returned as 64-bit
176 integers. Note that there is no way to save a 32-bit int on a 64-bit
177 machine.
178 Keep in mind that this can cause some weirdness to ensue if some
180 machines are 32-bit and others are 64-bit. Take the following example:
181 · Programmer 1 saves an int on a 32-bit platform.
183 · Programmer 2 retrieves the document on a 64-bit platform and re-
185 saves it, effectively converting it to a 64-bit int.
186 · Programmer 1 retrieves the document on their 32-bit machine, which
188 decodes the 64-bit int as a double.
189 Nothing drastic, but good to be aware of.
191 64-bit integers in the shell
193 The Mongo shell has one numeric type: the 8-byte float. This means
195 that it cannot always represent an 8-byte integer exactly. Thus, when
196 you display a 64-bit integer in the shell, it will be wrapped in a
197 subobject that indicates it might be an approximate value. For
198 instance, if we run this Perl on a 64-bit machine:
199 $coll->insert({_id => 1});
201 then look at it in the shell, we see:
203 > db.whatever.findOne()
205 {
206 "_id" :
207 {
208 "floatApprox" : 1
209 }
210 }
211 This doesn't mean that we saved a float, it just means that the float
213 value of a 64-bit integer may not be exact.
214 MongoDB::OID
216 "OID" stands for "Object ID", and is a unique id that is automatically
217 added to documents if they do not already have an "_id" field before
218 they are saved to the database. They are 12 bytes which are guarenteed
219 to be unique. Their string form is a 24-character string of
220 hexidecimal digits.
221 To create a unique id:
223 my $oid = MongoDB::OID->new;
225 To create a MongoDB::OID from an existing 24-character hexidecimal
227 string:
228 my $oid = MongoDB::OID->new("123456789012345678901234");
230 Binary Data
232 By default, all database strings are UTF8. To save images, binaries,
233 and other non-UTF8 data, you can pass the string as a reference to the
234 database. For example:
235 # non-utf8 string
237 my $string = "\xFF\xFE\xFF";
238 $collection->insert({"photo" => \$string});
240 This will save the variable as binary data, bypassing the UTF8 check.
242 Binary data can be matched exactly by the database, so this query will
244 match the object we inserted above:
245 $collection->find({"photo" => \$string});
247 Comparisons (e.g., $gt, $lt) may not work as you expect with binary
249 data, so it is worth experimenting.
250 MongoDB::Code
252 MongoDB::Code is used to represent JavaScript code and, optionally,
253 scope. To create one:
254 use MongoDB::Code;
256 my $code = MongoDB::Code->new("code" => "function() { return 'hello, world'; }");
258 Or, with a scope:
260 my $code = MongoDB::Code->new("code" => "function() { return 'hello, '+name; }",
262 "scope" => {"name" => "Fred"});
263 Which would then return "hello, Fred" when run.
265 MongoDB::MinKey
267 "MongoDB::MinKey" is "less than" any other value of any type. This can
268 be useful for always returning certain documents first (or last).
269 "MongoDB::MinKey" has no methods, fields, or string form. To create
271 one, it is sufficient to say:
272 bless $minKey, "MongoDB::MinKey";
274 MongoDB::MaxKey
276 "MongoDB::MaxKey" is "greater than" any other value of any type. This
277 can be useful for always returning certain documents last (or first).
278 "MongoDB::MaxKey" has no methods, fields, or string form. To create
280 one, it is sufficient to say:
281 bless $minKey, "MongoDB::MaxKey";
283 MongoDB::Timestamp
285 my $ts = MongoDB::Timestamp->new({sec => $seconds, inc => $increment});
286 Timestamps are used internally by MongoDB's replication. You can see
288 them in their natural habitat by querying "local.main.$oplog". Each
289 entry looks something like:
290 { "ts" : { "t" : 1278872990000, "i" : 1 }, "op" : "n", "ns" : "", "o" : { } }
292 In the shell, timestamps are shown in milliseconds, although they are
294 stored as seconds. So, to represent this document in Perl, we would
295 do:
296 my $oplog = {
298 "ts" => MongoDB::Timestamp->new("sec" => 1278872990, "inc" => 1),
299 "op" => "n",
300 "ns" => "",
301 "o" => {}
302 }
303perl v5.12.3 2010-11-19 MongoDB::DataTypes(3)