.\" Automatically generated by Pod::Man 2.27 (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 "MongoDBx::Class::Collection 3pm" .TH MongoDBx::Class::Collection 3pm "2014-02-04" "perl v5.18.2" "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" MongoDBx::Class::Collection \- A MongoDBx::Class collection object .SH "VERSION" .IX Header "VERSION" version 1.030002 .SH "EXTENDS" .IX Header "EXTENDS" MongoDB::Collection .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # get a collection from a L object \& my $coll = $db\->get_collection($coll_name); # or $db\->$coll_name \& \& # insert a document \& my $doc = $coll\->insert({ title => \*(AqThe Valley of Fear\*(Aq, year => 1914, author => \*(AqConan Doyle\*(Aq, _class => \*(AqNovel\*(Aq }, { safe => 1 }); \& \& # find some documents \& my @docs = $coll\->find({ author => \*(AqConan Doyle\*(Aq })\->sort({ year => 1 })\->all; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" MongoDBx::Class::Collection extends MongoDB::Collection. It adds some convenient options to the syntax and a few method modifications to allow automatic document expansion (when finding) and collapsing (when inserting). .PP If you're not familiar with MongoDB::Collection, please read it first. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" No special attributes are added. .SH "OBJECT METHODS" .IX Header "OBJECT METHODS" The following methods are available along with all methods defined in MongoDB::Collection. However, most (or all) of those are modifications of MongoDB::Collection methods. .SS "find( \e%query, [ \e%attrs ] )" .IX Subsection "find( %query, [ %attrs ] )" .SS "query( \e%query, [ \e%attrs ] )" .IX Subsection "query( %query, [ %attrs ] )" .SS "search( \e%query, [ \e%attrs ] )" .IX Subsection "search( %query, [ %attrs ] )" All three methods are equivalent (the last two aliases of the first). These methods perform a search for documents in the collection for documents matching a certain query and return a MongoDBx::Class::Cursor object. Refer to \&\*(L"find($query)\*(R" in MongoDB::Collection for more information about queries. .PP These methods are modified in the following way: .PP 1. They return a MongoDBx::Class::Cursor object instead of a plain MongoDB::Cursor object. .PP 2. The \f(CW\*(C`sort_by\*(C'\fR attribute in the \f(CW$attr\fR hash-ref can contain an array-ref instead of a Tie::IxHash object, such as: .PP .Vb 1 \& $coll\->find({ some => \*(Aqthing\*(Aq }, { sort_by => [ title => 1, some => \-1 ] }) .Ve .PP This array-ref will be converted into a Tie::IxHash object automatically. .ie n .SS "find_one( $query, [ \e%fields ] )" .el .SS "find_one( \f(CW$query\fP, [ \e%fields ] )" .IX Subsection "find_one( $query, [ %fields ] )" Performs a query on the collection and returns the first matching document. .PP This method is modified in the following way: .PP 1. In MongoDB::Collection, \f(CW$query\fR can either be a hash-ref, a Tie::IxHash object or an array-ref. Here, however, \f(CW$query\fR can also be a MongoDB::OID, or a MongoDB::OID's string representation (see \*(L"to_string\*(R" in MongoDB::OID). Searching by internal \s-1ID\s0 is thus much more convenient: .PP .Vb 1 \& my $doc = $coll\->find_one("4cbca90d3a41e35916720100"); .Ve .PP 2. The matching document is automatically expanded to the appropriate document class, but only if it has the '_class' attribute (as described in \*(L"\s-1CAVEATS AND THINGS TO CONSIDER\*(R"\s0 in MongoDBx::Class). If it doesn't, or if expansion is impossible due to other reasons, it will be returned as is (i.e. as a hash-ref). .PP 3. In MongoDB::Collection, passing a \f(CW\*(C`\e%fields\*(C'\fR hash-ref will result in the document being returned with those fields only (and the _id field). Behavior of this when documents are expanded is currently undefined. .ie n .SS "insert( $doc, [ \e%opts ] )" .el .SS "insert( \f(CW$doc\fP, [ \e%opts ] )" .IX Subsection "insert( $doc, [ %opts ] )" Inserts the given document into the database, automatically collapsing it before insertion. .PP An optional options hash-ref can be passed. If this hash-ref holds a safe key with a true value, insert will be safe (refer to \*(L"insert ($object, \f(CW$options\fR?)\*(R" in MongoDB::Collection for more information). When performing a safe insert, the newly created document is returned (after expansions). If unsafe, its MongoDB::OID is returned. .PP If your connection object has a true value for the safe attribute, insert will be safe by default. If that is the case, and you want the specific insert to be unsafe, pass a false value for \&\f(CW\*(C`safe\*(C'\fR in the \f(CW\*(C`\e%opts\*(C'\fR hash-ref. .PP Document to insert can either be a hash-ref, a Tie::IxHash object or an even-numbered array-ref, but currently only hash-refs are automatically collapsed. .SS "batch_insert( \e@docs, [ \e%opts ] )" .IX Subsection "batch_insert( @docs, [ %opts ] )" Receives an array-ref of documents and an optional hash-ref of options, and inserts all the documents to the collection one after the other. \f(CW\*(C`\e%opts\*(C'\fR can have a \*(L"safe\*(R" key that should hold a boolean value. If true (and if your connection object has a true value for the safe attribute), inserts will be safe, and an array of all the documents inserted (after expansion) will be returned. If false, an array with all the document IDs is returned. .PP Documents to insert can either be hash-refs, Tie::IxHash objects or even-numbered array references, but currently only hash-refs are automatically collapsed. .SS "update( \e%criteria, \e%object, [ \e%options ] )" .IX Subsection "update( %criteria, %object, [ %options ] )" Searches for documents matching \f(CW\*(C`\e%criteria\*(C'\fR and updates them according to \f(CW\*(C`\e%object\*(C'\fR (refer to \*(L"update (\e%criteria, \e%object, \e%options?)\*(R" in MongoDB::Collection for more info). As opposed to the original method, this method will automatically collapse the \f(CW\*(C`\e%object\*(C'\fR hash-ref. It will croak if criteria and/or object aren't hash references. .PP Do not use this method to update a specific document that you already have (i.e. after expansion). MongoDBx::Class::Document has its own update method which is more convenient. .PP Notice that this method doesn't collapse attributes with the Parsed trait. Only the MongoDBx::Class::Document update method performs that. .ie n .SS "ensure_index( $keys, [ \e%options ] )" .el .SS "ensure_index( \f(CW$keys\fP, [ \e%options ] )" .IX Subsection "ensure_index( $keys, [ %options ] )" Makes sure the given keys of this collection are indexed. \f(CW$keys\fR is either an unordered hash-ref, an ordered Tie::IxHash object, or an ordered, even-numbered array reference like this: .PP .Vb 1 \& $coll\->ensure_index([ title => 1, date => \-1 ]) .Ve .SH "INTERNAL METHODS" .IX Header "INTERNAL METHODS" The following methods are only to be used internally: .SS "_collapse_hash( \e%object )" .IX Subsection "_collapse_hash( %object )" Collapses an entire hash-ref for proper database insertions. .SH "AUTHOR" .IX Header "AUTHOR" Ido Perlmuter, \f(CW\*(C`\*(C'\fR .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-mongodbx\-class at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc MongoDBx::Class::Collection .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "SEE ALSO" .IX Header "SEE ALSO" MongoDB::Collection. .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright 2010\-2014 Ido Perlmuter. .PP This program is free software; you can redistribute it and/or modify it under the terms of either: the \s-1GNU\s0 General Public License as published by the Free Software Foundation; or the Artistic License. .PP See http://dev.perl.org/licenses/ for more information.