.\" 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::Indexing 3pm" .TH MongoDB::Indexing 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::Indexing \- Indexing collections .SH "VERSION" .IX Header "VERSION" version v0.705.0.0 .SH "CREATING AN INDEX" .IX Header "CREATING AN INDEX" Unique and non-unique indexes can be created on collections using \&\f(CW\*(C`MongoDB::Collection::ensure_index\*(C'\fR. .PP For example, to create a non-unique index on \f(CW\*(C`x\*(C'\fR: .PP .Vb 1 \& $collection\->ensure_index({\*(Aqx\*(Aq => 1}) .Ve .PP To create a unique index on \f(CW\*(C`y\*(C'\fR: .PP .Vb 1 \& $collection\->ensure_index({"y" => 1}, {"unique" => 1}); .Ve .PP Multi-key indexes can be created to speed up queries like \*(L"sort by name, then by age.\*(R" Index direction (1 or \-1) is only important for multi-key indexes and should be the sort order. So, for example, if we want a fast sort by name ascending and age descending, we'd write: .PP .Vb 2 \& my $idx = Tie::IxHash\->new(name => 1, age => \-1); \& $collection\->ensure_index($idx); .Ve .PP Keep in mind that you should use Tie::IxHash for multi-key indexes to guarantee the keys will be saved in the correct order. .SS "Options" .IX Subsection "Options" The second parameter to \f(CW\*(C`MongoDB::Collection::ensure_index\*(C'\fR specifies index options. Available options are: .ie n .IP """unique => boolean""" 4 .el .IP "\f(CWunique => boolean\fR" 4 .IX Item "unique => boolean" By default, indexes are not unique. To create a unique index, pass \&\f(CW\*(C`unique => true\*(C'\fR. \f(CW\*(C`true\*(C'\fR can be boolean::true or any other true value. .ie n .IP """drop_dups => boolean""" 4 .el .IP "\f(CWdrop_dups => boolean\fR" 4 .IX Item "drop_dups => boolean" If a unique index is being created on an existing set of data that has duplicate values, creating the index will fail. To force the index creation by deleting duplicate values, use this option. Again, any value that evaluates to true will work. .ie n .IP """safe => boolean""" 4 .el .IP "\f(CWsafe => boolean\fR" 4 .IX Item "safe => boolean" If the update fails and safe is set, this function will return 0. You should check \f(CW\*(C`MongoDB::Database::last_error\*(C'\fR to find out why the update failed. .ie n .IP """background => boolean""" 4 .el .IP "\f(CWbackground => boolean\fR" 4 .IX Item "background => boolean" Create the index as a background operation. .ie n .IP """name => string""" 4 .el .IP "\f(CWname => string\fR" 4 .IX Item "name => string" Give the index a non-default name. This can be useful if the index contains so many keys that you get an \*(L"index name too long\*(R" assertion, or if you just prefer a more human-readable name. .SS "See Also" .IX Subsection "See Also" MongoDB documentation on indexing: . .SH "GEOSPATIAL INDEXES" .IX Header "GEOSPATIAL INDEXES" Starting in version 1.3.3 of MongoDB, you can create geospatial indexes. These are useful for querying for \*(L"N documents nearest this point\*(R" or \*(L"documents within this shape.\*(R" .PP To create an index for geospatial queries, use \*(L"2d\*(R" instead of 1 or \-1. For example, this would create an index on the \*(L"location\*(R" field: .PP .Vb 1 \& $coll\->ensure_index({"location" => "2d"}); .Ve .PP Then, you can query for documents using \f(CW$near\fR: .PP .Vb 1 \& my $cursor = $coll\->query({"location" => {\*(Aq$near\*(Aq => [44, \-70]}})\->limit(10); .Ve .PP This finds the 10 nearest documents (automatically sorted by distance ascending) to latitude \-70, longitude 44. .PP Documents must have some sort of pair in the \*(L"location\*(R" field, although the database is pretty flexible as to what it will accept: .PP .Vb 4 \& # valid geospatial locations \& $coll\->insert({"location" => [44, \-70]}); \& $coll\->insert({"location" => {"x" => 44, "y" => \-70}}); \& $coll\->insert({"location" => {"foo" => 44, "bar" => \-70}}); .Ve .PP You can save values in \f(CW\*(C`(x,y)\*(C'\fR or \f(CW\*(C`(y,x)\*(C'\fR order, but you must be consistent. .PP By default, the geospatial index assumes that points will lie between \-180 and 180, for longitude and latitude queries. .SS "Options" .IX Subsection "Options" .ie n .IP """min => int""" 4 .el .IP "\f(CWmin => int\fR" 4 .IX Item "min => int" By default, the geospatial index assumes that points will lie between \-180 and 180, for longitude and latitude queries. If you need an alternative minimum value, you can use this option. This value is exclusive: if you specify \&\f(CW\*(C`min => 0\*(C'\fR, you cannot save a point with a 0 value coordinate. .ie n .IP """max => int""" 4 .el .IP "\f(CWmax => int\fR" 4 .IX Item "max => int" Alternative maximum value, exclusive. .SS "See Also" .IX Subsection "See Also" MongoDB documentation on geospatial indexes: . .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