.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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 turned on, 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MongoDB::DataTypes 3pm" .TH MongoDB::DataTypes 3pm "2014-10-09" "perl v5.20.1" "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 \- The data types used with MongoDB .SH "VERSION" .IX Header "VERSION" version v0.705.0.0 .SH "DESCRIPTION" .IX Header "DESCRIPTION" This goes over the types you can save to the database and use for queries in the Perl driver. If you are using another language, please refer to that language's documentation (). .SH "NOTES FOR SQL PROGRAMMERS" .IX Header "NOTES FOR SQL PROGRAMMERS" .SS "You must query for data using the correct type." .IX Subsection "You must query for data using the correct type." For example, it is perfectly valid to have some records where the field \*(L"foo\*(R" is 123 (integer) and other records where \*(L"foo\*(R" is \*(L"123\*(R" (string). Thus, you must query for the correct type. If you save \f(CW\*(C`{"foo" => "123"}\*(C'\fR, you cannot query for it with \f(CW\*(C`{"foo" => 123}\*(C'\fR. MongoDB is strict about types. .PP If the type of a field is ambiguous and important to your application, you should document what you expect the application to send to the database and convert your data to those types before sending. There are some object-document mappers that will enforce certain types for certain fields for you. .PP You generally shouldn't save numbers as strings, as they will behave like strings (e.g., range queries won't work correctly) and the data will take up more space. If you set \*(L"looks_like_number\*(R" in MongoDB::BSON, the driver will automatically convert everything that looks like a number to a number before sending it to the database. .PP Numbers are the only exception to the strict typing: all number types stored by MongoDB (32\-bit integers, 64\-bit integers, 64\-bit floating point numbers) will match each other. .SH "TYPES" .IX Header "TYPES" .SS "Numbers" .IX Subsection "Numbers" By default, numbers with a decimal point will be saved as doubles (64\-bit). .PP \fI32\-bit Platforms\fR .IX Subsection "32-bit Platforms" .PP Numbers without decimal points will be saved as 32\-bit integers. To save a number as a 64\-bit integer, use bigint: .PP .Vb 1 \& use bigint; \& \& $collection\->insert({"user_id" => 28347197234178}) .Ve .PP The driver will die if you try to insert a number beyond the signed 64\-bit range: \-9,223,372,036,854,775,808 to +9,223,372,036,854,775,807. .PP Numbers that are saved as 64\-bit integers will be decoded as doubles. .PP \fI64\-bit Platforms\fR .IX Subsection "64-bit Platforms" .PP Numbers without a decimal point will be saved and returned as 64\-bit integers. Note that there is no way to save a 32\-bit int on a 64\-bit machine. .PP Keep in mind that this can cause some weirdness to ensue if some machines are 32\-bit and others are 64\-bit. Take the following example: .IP "\(bu" 4 Programmer 1 saves an int on a 32\-bit platform. .IP "\(bu" 4 Programmer 2 retrieves the document on a 64\-bit platform and re-saves it, effectively converting it to a 64\-bit int. .IP "\(bu" 4 Programmer 1 retrieves the document on their 32\-bit machine, which decodes the 64\-bit int as a double. .PP Nothing drastic, but good to be aware of. .PP 64\-bit integers in the shell .IX Subsection "64-bit integers in the shell" .PP The Mongo shell has one numeric type: the 8\-byte float. This means that it cannot always represent an 8\-byte integer exactly. Thus, when you display a 64\-bit integer in the shell, it will be wrapped in a subobject that indicates it might be an approximate value. For instance, if we run this Perl on a 64\-bit machine: .PP .Vb 1 \& $coll\->insert({_id => 1}); .Ve .PP then look at it in the shell, we see: .PP .Vb 7 \& > db.whatever.findOne() \& { \& "_id" : \& { \& "floatApprox" : 1 \& } \& } .Ve .PP This doesn't mean that we saved a float, it just means that the float value of a 64\-bit integer may not be exact. .PP Dealing with numbers and strings in Perl .IX Subsection "Dealing with numbers and strings in Perl" .PP Perl is very flexible about whether something is number or a string: it generally infers the type from context. Unfortunately, the driver doesn't have any context when it has to choose how to serialize a variable. Therefore, the default behavior is to introspect the flags that are set on that variable and decide what the user meant, which are generally affected by the last operation. .PP .Vb 3 \& my $var = "4"; \& # stored as the string "4" \& $collection\->insert({myVar => $var}); \& \& $var = int($var) if (int($var) eq $var); \& # stored as the int 4 \& $collection\->insert({myVar => $var}); .Ve .PP Because of this, users often find that they end up with more strings than they wanted in their database. .PP If you would like to have everything that looks like a number saved as a number, set the \*(L"looks_like_number\*(R" in MongoDB::BSON option. .PP .Vb 1 \& $MongoDB::BSON::looks_like_number = 1; \& \& my $var = "4"; \& # stored as the int 4 \& $collection\->insert({myVar => $var}); .Ve .PP This will send anything that \*(L"looks like\*(R" a number as a number. It can recognize anything that Scalar::Util's \f(CW\*(C`looks_like_number\*(C'\fR function can recognize. .PP On the other hand, sometimes there is data that looks like a number but should be saved as a string. For example, suppose we were storing zip codes. If we wanted to generally convert strings to numbers, we might have something like: .PP .Vb 1 \& $MongoDB::BSON::looks_like_number = 1; \& \& # zip is stored as an int: 4101 \& $collection\->insert({city => "Portland", "zip" => "04101"}); .Ve .PP To force a \*(L"number\*(R" to be saved as a string with aggressive number conversion on, bless the string as a \f(CW\*(C`MongoDB::BSON::String\*(C'\fR type: .PP .Vb 2 \& my $z = "04101"; \& my $zip = bless(\e$z, "MongoDB::BSON::String"); \& \& # zip is stored as "04101" \& $collection\->insert({city => "Portland", \& zip => bless(\e$zip, "MongoDB::BSON::String")}); .Ve .PP Additionally, there are two utility functions, \f(CW\*(C`force_int\*(C'\fR and c, to explicitly set Perl's internal type flags to Integer (\f(CW\*(C`IV\*(C'\fR) and Double (\f(CW\*(C`NV\*(C'\fR) respectively, thus triggering MongoDB's recognition of the values as Int32/Int64 (depending on the platform) or Double: .PP .Vb 3 \& my $x = 1.0; \& MongoDB::force_int($x); \& $coll\->insert({x => $x}); # Inserts an integer \& \& MongoDB::force_double($x); \& $coll\->insert({x => $x}); # Inserts a double .Ve .SS "Strings" .IX Subsection "Strings" All strings must be valid \s-1UTF\-8\s0 to be sent to the database. If a string is not valid, it will not be saved. If you need to save a non\-UTF\-8 string, you can save it as a binary blob (see the Binary Data section below). .PP All strings returned from the database have the \s-1UTF\-8\s0 flag set. .PP Unfortunately, due to Perl weirdness, \s-1UTF\-8\s0 is not very pretty. For example, suppose we have a \s-1UTF\-8\s0 string: .PP .Vb 1 \& my $str = \*(AqA\*oland Islands\*(Aq; .Ve .PP Now, let's print it: .PP .Vb 1 \& print "$str\en"; .Ve .PP You can see in the output: .PP .Vb 1 \& "\ex{c5}land Islands" .Ve .PP Lovely, isn't it? This is how Perl prints \s-1UTF\-8. \s0 To make it \*(L"pretty,\*(R" there are a couple options: .PP .Vb 1 \& my $pretty_str = utf8::encode($str); .Ve .PP This, unintuitively, clears the \s-1UTF\-8\s0 flag. .PP You can also just run .PP .Vb 1 \& binmode STDOUT, \*(Aq:utf8\*(Aq; .Ve .PP and then the string (and all future \s-1UTF\-8\s0 strings) will print \*(L"correctly.\*(R" .PP You can also turn off \f(CW$MongoDB::BSON::utf_flag_on\fR, and the \s-1UTF\-8\s0 flag will not be set when strings are decoded: .PP .Vb 1 \& $MongoDB::BSON::utf8_flag_on = 0; .Ve .SS "Arrays" .IX Subsection "Arrays" Arrays must be saved as array references (\f(CW\*(C`\e@foo\*(C'\fR, not \f(CW@foo\fR). .SS "Embedded Documents" .IX Subsection "Embedded Documents" Embedded documents are of the same form as top-level documents: either hash references or Tie::IxHashs. .SS "Dates" .IX Subsection "Dates" The DateTime or DateTime::Tiny packages can be used to insert and query for dates. Dates stored in the database will be returned as instances of one of these classes, depending on the \f(CW\*(C`dt_type\*(C'\fR setting of the connection: .PP .Vb 1 \& $conn\->dt_type( \*(AqDateTime::Tiny\*(Aq ); .Ve .PP An example of storing and retrieving a date: .PP .Vb 1 \& use DateTime; \& \& my $now = DateTime\->now; \& $collection\->insert({\*(Aqts\*(Aq => $now}); \& \& my $obj = $collection\->find_one; \& print "Today is ".$obj\->{\*(Aqts\*(Aq}\->ymd."\en"; .Ve .PP An example of querying for a range of dates: .PP .Vb 2 \& my $start = DateTime\->from_epoch( epoch => 100000 ); \& my $end = DateTime\->from_epoch( epoch => 500000 ); \& \& my $cursor = $collection\->query({event => {\*(Aq$gt\*(Aq => $start, \*(Aq$lt\*(Aq => $end}}); .Ve .PP \&\fBWarning: creating Perl DateTime objects is extremely slow. Consider saving dates as numbers or \f(CB\*(C`DateTime::Tiny\*(C'\fB objects and converting the numbers to DateTimes only when needed. A single DateTime field can make deserialization up to 10 times slower.\fR .PP For example, you could use the time function to store seconds since the epoch: .PP .Vb 1 \& $collection\->update($criteria, {\*(Aq$set\*(Aq => {"last modified" => time()}}) .Ve .PP This will be faster to deserialize. .PP Note that (at least, as of \f(CW\*(C`DateTime::Tiny\*(C'\fR version 1.04) there is no time-zone attribute for \f(CW\*(C`DateTime::Tiny\*(C'\fR objects. We therefore consider all such times to be in the \f(CW\*(C`UTC\*(C'\fR time zone. Likewise, \&\f(CW\*(C`DateTime::Tiny\*(C'\fR has no notion of milliseconds (yet?), so the milliseconds portion of the datetime will be set to zero. .SS "Regular Expressions" .IX Subsection "Regular Expressions" Use \f(CW\*(C`qr/.../\*(C'\fR to use a regular expression in a query: .PP .Vb 1 \& my $cursor = $collection\->query({"name" => qr/[Jj]oh?n/}); .Ve .PP Regular expressions will match strings saved in the database. .PP You can also save and retrieve regular expressions themselves: .PP .Vb 5 \& $collection\->insert({"regex" => qr/foo/i}); \& $obj = $collection\->find_one; \& if ("FOO" =~ $obj\->{\*(Aqregex\*(Aq}) { # matches \& print "hooray\en"; \& } .Ve .PP Note for Perl 5.8 users: flags are lost when regular expressions are retrieved from the database (this does not affect queries or Perl 5.10+). .SS "Booleans" .IX Subsection "Booleans" Use the boolean package to get boolean values. \f(CW\*(C`boolean::true\*(C'\fR and \&\f(CW\*(C`boolean::false\*(C'\fR are the only parts of the package used, currently. .PP An example of inserting boolean values: .PP .Vb 1 \& use boolean; \& \& $collection\->insert({"okay" => true, "name" => "fred"}); .Ve .PP An example using boolean values for query operators (only returns documents where the name field exists): .PP .Vb 1 \& my $cursor = $collection\->query({"name" => {\*(Aq$exists\*(Aq => boolean::true}}); .Ve .PP Most of the time, you can just use 1 or 0 instead of \f(CW\*(C`true\*(C'\fR and \f(CW\*(C`false\*(C'\fR, such as for specifying fields to return. boolean is the only way to save booleans to the database, though. .PP By default, booleans are returned from the database as integers. To return booleans as booleans, set \f(CW$MongoDB::BSON::use_boolean\fR to 1. .SS "MongoDB::OID" .IX Subsection "MongoDB::OID" \&\*(L"\s-1OID\*(R"\s0 stands for \*(L"Object \s-1ID\*(R",\s0 and is a unique id that is automatically added to documents if they do not already have an \f(CW\*(C`_id\*(C'\fR field before they are saved to the database. They are 12 bytes which are guaranteed to be unique. Their string form is a 24\-character string of hexidecimal digits. .PP To create a unique id: .PP .Vb 1 \& my $oid = MongoDB::OID\->new; .Ve .PP To create a MongoDB::OID from an existing 24\-character hexidecimal string: .PP .Vb 1 \& my $oid = MongoDB::OID\->new("value" => "123456789012345678901234"); .Ve .SS "Binary Data" .IX Subsection "Binary Data" By default, all database strings are \s-1UTF8. \s0 To save images, binaries, and other non\-UTF8 data, you need to store it as binary data. There are two ways to do this. .PP \fIString Refs\fR .IX Subsection "String Refs" .PP In general, you can pass the string as a reference. For example: .PP .Vb 2 \& # non\-utf8 string \& my $string = "\exFF\exFE\exFF"; \& \& $collection\->insert({"photo" => \e$string}); .Ve .PP This will save the variable as binary data, bypassing the \s-1UTF8\s0 check. .PP Binary data can be matched exactly by the database, so this query will match the object we inserted above: .PP .Vb 1 \& $collection\->find({"photo" => \e$string}); .Ve .PP \fIMongoDB::BSON::Binary type\fR .IX Subsection "MongoDB::BSON::Binary type" .PP You can also use the MongoDB::BSON::Binary class. This allows you to preserve the \fIsubtype\fR of your data. Binary data in MongoDB stores a \*(L"type\*(R" field, which can be any integer between 0 and 255. Identical data will only match if the subtype is the same. .PP Perl uses the default subtype of \f(CW\*(C`SUBTYPE_GENERIC\*(C'\fR. .PP The driver defaults to returning binary data as strings, not instances of MongoDB::BSON::Binary (or even string references) for backwards compatibility reasons. If you need to round-trip binary data, set the \&\f(CW\*(C`MongoDB::BSON::use_binary\*(C'\fR flag: .PP .Vb 1 \& $MongoDB::BSON::use_binary = 1; .Ve .PP Comparisons (e.g., \f(CW$gt\fR, \f(CW$lt\fR) may not work as you expect with binary data, so it is worth experimenting. .SS "MongoDB::Code" .IX Subsection "MongoDB::Code" MongoDB::Code is used to represent JavaScript code and, optionally, scope. To create one: .PP .Vb 1 \& use MongoDB::Code; \& \& my $code = MongoDB::Code\->new("code" => "function() { return \*(Aqhello, world\*(Aq; }"); .Ve .PP Or, with a scope: .PP .Vb 2 \& my $code = MongoDB::Code\->new("code" => "function() { return \*(Aqhello, \*(Aq+name; }", \& "scope" => {"name" => "Fred"}); .Ve .PP Which would then return \*(L"hello, Fred\*(R" when run. .SS "MongoDB::MinKey" .IX Subsection "MongoDB::MinKey" \&\f(CW\*(C`MongoDB::MinKey\*(C'\fR is \*(L"less than\*(R" any other value of any type. This can be useful for always returning certain documents first (or last). .PP \&\f(CW\*(C`MongoDB::MinKey\*(C'\fR has no methods, fields, or string form. To create one, it is sufficient to say: .PP .Vb 1 \& bless $minKey, "MongoDB::MinKey"; .Ve .SS "MongoDB::MaxKey" .IX Subsection "MongoDB::MaxKey" \&\f(CW\*(C`MongoDB::MaxKey\*(C'\fR is \*(L"greater than\*(R" any other value of any type. This can be useful for always returning certain documents last (or first). .PP \&\f(CW\*(C`MongoDB::MaxKey\*(C'\fR has no methods, fields, or string form. To create one, it is sufficient to say: .PP .Vb 1 \& bless $minKey, "MongoDB::MaxKey"; .Ve .SS "MongoDB::Timestamp" .IX Subsection "MongoDB::Timestamp" .Vb 1 \& my $ts = MongoDB::Timestamp\->new({sec => $seconds, inc => $increment}); .Ve .PP Timestamps are used internally by MongoDB's replication. You can see them in their natural habitat by querying \f(CW\*(C`local.main.$oplog\*(C'\fR. Each entry looks something like: .PP .Vb 1 \& { "ts" : { "t" : 1278872990000, "i" : 1 }, "op" : "n", "ns" : "", "o" : { } } .Ve .PP In the shell, timestamps are shown in milliseconds, although they are stored as seconds. So, to represent this document in Perl, we would do: .PP .Vb 6 \& my $oplog = { \& "ts" => MongoDB::Timestamp\->new("sec" => 1278872990, "inc" => 1), \& "op" => "n", \& "ns" => "", \& "o" => {} \& } .Ve .PP Timestamps are not dates. You should not use them unless you are doing something low-level with replication. To save dates or times, use a number, DateTime object, or DateTime::Tiny object. .SH "AUTHORS" .IX Header "AUTHORS" .IP "\(bu" 4 David Golden .IP "\(bu" 4 Mike Friedman .IP "\(bu" 4 Kristina Chodorow .IP "\(bu" 4 Florian Ragwitz .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is Copyright (c) 2014 by MongoDB, Inc.. .PP This is free software, licensed under: .PP .Vb 1 \& The Apache License, Version 2.0, January 2004 .Ve