Mongo db reference manual

MongoDB Reference Manual Release 2.6.4 MongoDB Documentation Project

  1. Deysi Gmarra
    MongoDB Reference Manual
    Release 2.6.4
    MongoDB Documentation Project
    Transcript Header:
    Mongo db reference manual
    Transcript Body:
    • 1. MongoDB Reference Manual Release 2.6.4 MongoDB Documentation Project September 16, 2014
    • 2. 2
    • 3. Contents 1 About MongoDB Documentation 3 1.1 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Editions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3 Version and Revisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.4 Report an Issue or Make a Change Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.5 Contribute to the Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2 Interfaces Reference 21 2.1 mongo Shell Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 2.2 Database Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 2.3 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 2.4 Aggregation Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 3 MongoDB and SQL Interface Comparisons 547 3.1 SQL to MongoDB Mapping Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547 3.2 SQL to Aggregation Mapping Chart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 4 Program and Tool Reference Pages 555 4.1 MongoDB Package Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 5 Internal Metadata 647 5.1 Config Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 5.2 The local Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 5.3 System Collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654 6 General System Reference 657 6.1 Exit Codes and Statuses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 6.2 MongoDB Limits and Thresholds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658 6.3 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663 7 Release Notes 675 7.1 Current Stable Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675 7.2 Previous Stable Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713 7.3 Other MongoDB Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759 Index 761 i
    • 4. ii
    • 5. MongoDB Reference Manual, Release 2.6.4 This document contains all of the reference material from the MongoDB Manual, reflecting the 2.6.4 release. See the full manual, for complete documentation of MongoDB, it’s operation, and use. Contents 1
    • 6. MongoDB Reference Manual, Release 2.6.4 2 Contents
    • 7. CHAPTER 1 About MongoDB Documentation The MongoDB Manual1 contains comprehensive documentation on the MongoDB document-oriented database man-agement system. This page describes the manual’s licensing, editions, and versions, and describes how to make a change request and how to contribute to the manual. For more information on MongoDB, see MongoDB: A Document Oriented Database2. To download MongoDB, see the downloads page3. 1.1 License This manual is licensed under a Creative Commons “Attribution-NonCommercial-ShareAlike 3.0 Unported4” (i.e. “CC-BY-NC-SA”) license. The MongoDB Manual is copyright © 2011-2014 MongoDB, Inc. 1.2 Editions In addition to the MongoDB Manual5, you can also access this content in the following editions: • ePub Format6 • Single HTML Page7 • PDF Format8 (without reference.) • HTML tar.gz9 You also can access PDF files that contain subsets of the MongoDB Manual: • MongoDB Reference Manual10 • MongoDB CRUD Operations11 1 2 3 4 5 6 7 8 9 10 11 3
    • 8. MongoDB Reference Manual, Release 2.6.4 • Data Models for MongoDB12 • MongoDB Data Aggregation13 • Replication and MongoDB14 • Sharding and MongoDB15 • MongoDB Administration16 • MongoDB Security17 MongoDB Reference documentation is also available as part of dash18. You can also access the MongoDB Man Pages19 which are also distributed with the official MongoDB Packages. 1.3 Version and Revisions This version of the manual reflects version 2.6 of MongoDB. See the MongoDB Documentation Project Page20 for an overview of all editions and output formats of the MongoDB Manual. You can see the full revision history and track ongoing improvements and additions for all versions of the manual from its GitHub repository21. This edition reflects “master” branch of the documentation as of the “6b5d51a49f42f8c4046a3bd277c5b24840a24e87” revision. This branch is explicitly accessible via “” and you can always reference the commit of the current manual in the release.txt22 file. The most up-to-date, current, and stable version of the manual is always available at “”. 1.4 Report an Issue or Make a Change Request To report an issue with this manual or to make a change request, file a ticket at the MongoDB DOCS Project on Jira23. 1.5 Contribute to the Documentation 1.5.1 MongoDB Manual Translation The original language of all MongoDB documentation is American English. However it is of critical importance to the documentation project to ensure that speakers of other languages can read and understand the documentation. 12 13 14 15 16 17 18 19 20 21 22 23 4 Chapter 1. About MongoDB Documentation
    • 9. MongoDB Reference Manual, Release 2.6.4 To this end, the MongoDB Documentation Project is preparing to launch a translation effort to allow the community to help bring the documentation to speakers of other languages. If you would like to express interest in helping to translate the MongoDB documentation once this project is opened to the public, please: • complete the MongoDB Contributor Agreement24, and • join the mongodb-translators25 user group. The mongodb-translators26 user group exists to facilitate collaboration between translators and the documentation team at large. You can join the group without signing the Contributor Agreement, but you will not be allowed to contribute translations. See also: • Contribute to the Documentation (page 4) • Style Guide and Documentation Conventions (page 6) • MongoDB Manual Organization (page 15) • MongoDB Documentation Practices and Processes (page 12) • MongoDB Documentation Build System (page 16) The entire documentation source for this manual is available in the mongodb/docs repository27, which is one of the MongoDB project repositories on GitHub28. To contribute to the documentation, you can open a GitHub account29, fork the mongodb/docs repository30, make a change, and issue a pull request. In order for the documentation team to accept your change, you must complete the MongoDB Contributor Agree-ment31. You can clone the repository by issuing the following command at your system shell: git clone git:// 1.5.2 About the Documentation Process The MongoDB Manual uses Sphinx32, a sophisticated documentation engine built upon Python Docutils33. The orig-inal reStructured Text34 files, as well as all necessary Sphinx extensions and build tools, are available in the same repository as the documentation. For more information on the MongoDB documentation process, see: 24 25 26 27 28 29 30 31 32 33 34 1.5. Contribute to the Documentation 5
    • 10. MongoDB Reference Manual, Release 2.6.4 Style Guide and Documentation Conventions This document provides an overview of the style for the MongoDB documentation stored in this repository. The overarching goal of this style guide is to provide an accessible base style to ensure that our documentation is easy to read, simple to use, and straightforward to maintain. For information regarding the MongoDB Manual organization, see MongoDB Manual Organization (page 15). Document History 2011-09-27: Document created with a (very) rough list of style guidelines, conventions, and questions. 2012-01-12: Document revised based on slight shifts in practice, and as part of an effort of making it easier for people outside of the documentation team to contribute to documentation. 2012-03-21: Merged in content from the Jargon, and cleaned up style in light of recent experiences. 2012-08-10: Addition to the “Referencing” section. 2013-02-07: Migrated this document to the manual. Added “map-reduce” terminology convention. Other edits. 2013-11-15: Added new table of preferred terms. Naming Conventions This section contains guidelines on naming files, sections, documents and other document elements. • File naming Convention: – For Sphinx, all files should have a .txt extension. – Separate words in file names with hyphens (i.e. -.) – For most documents, file names should have a terse one or two word name that de-scribes the material covered in the document. Allow the path of the file within the doc-ument tree to add some of the required context/categorization. For example it’s ac-ceptable to have and – For tutorials, the full title of the document should be in the file name. For example,• Phrase headlines and titles so users can determine what questions the text will answer, and material that will be addressed, without needing them to read the content. This shortens the amount of time that people spend looking for answers, and improvise search/scanning, and possibly “SEO.” • Prefer titles and headers in the form of “Using foo” over “How to Foo.” • When using target references (i.e. :ref: references in documents), use names that include enough context to be intelligible through all documentation. For example, use “replica-set-secondary-only-node” as opposed to “secondary-only-node”. This makes the source more usable and easier to maintain. Style Guide This includes the local typesetting, English, grammatical, conventions and preferences that all documents in the manual should use. The goal here is to choose good standards, that are clear, and have a stylistic minimalism that does not interfere with or distract from the content. A uniform style will improve user experience and minimize the effect of a multi-authored document. 6 Chapter 1. About MongoDB Documentation
    • 11. MongoDB Reference Manual, Release 2.6.4 Punctuation • Use the Oxford comma. Oxford commas are the commas in a list of things (e.g. “something, something else, and another thing”) before the conjunction (e.g. “and” or “or.”). • Do not add two spaces after terminal punctuation, such as periods. • Place commas and periods inside quotation marks. Headings Use title case for headings and document titles. Title case capitalizes the first letter of the first, last, and all significant words. Verbs Verb tense and mood preferences, with examples: • Avoid the first person. For example do not say, “We will begin the backup process by locking the database,” or “I begin the backup process by locking my database instance.” • Use the second person. “If you need to back up your database, start by locking the database first.” In practice, however, it’s more concise to imply second person using the imperative, as in “Before initiating a backup, lock the database.” • When indicated, use the imperative mood. For example: “Backup your databases often” and “To prevent data loss, back up your databases.” • The future perfect is also useful in some cases. For example, “Creating disk snapshots without locking the database will lead to an invalid state.” • Avoid helper verbs, as possible, to increase clarity and concision. For example, attempt to avoid “this does foo” and “this will do foo” when possible. Use “does foo” over “will do foo” in situations where “this foos” is unacceptable. Referencing • To refer to future or planned functionality in MongoDB or a driver, always link to the Jira case. The Manual’s provides an :issue: role that links directly to a Jira case (e.g. :issue:‘SERVER-9001‘). • For non-object references (i.e. functions, operators, methods, database commands, settings) always reference only the first occurrence of the reference in a section. You should always reference objects, except in section headings. • Structure references with the why first; the link second. For example, instead of this: Use the procedure if you have an existing replica set. Type this: To deploy a sharded cluster for an existing replica set, see Formulations • Contractions are acceptable insofar as they are necessary to increase readability and flow. Avoid otherwise. • Make lists grammatically correct. – Do not use a period after every item unless the list item completes the unfinished sentence before the list. 1.5. Contribute to the Documentation 7
    • 12. MongoDB Reference Manual, Release 2.6.4 – Use appropriate commas and conjunctions in the list items. – Typically begin a bulleted list with an introductory sentence or clause, with a colon or comma. • The following terms are one word: – standalone – workflow • Use “unavailable,” “offline,” or “unreachable” to refer to a mongod instance that cannot be accessed. Do not use the colloquialism “down.” • Always write out units (e.g. “megabytes”) rather than using abbreviations (e.g. “MB”.) Structural Formulations • There should be at least two headings at every nesting level. Within an “h2” block, there should be either: no “h3” blocks, 2 “h3” blocks, or more than 2 “h3” blocks. • Section headers are in title case (capitalize first, last, and all important words) and should effectively describe the contents of the section. In a single document you should strive to have section titles that are not redundant and grammatically consistent with each other. • Use paragraphs and paragraph breaks to increase clarity and flow. Avoid burying critical information in the middle of long paragraphs. Err on the side of shorter paragraphs. • Prefer shorter sentences to longer sentences. Use complex formations only as a last resort, if at all (e.g. com-pound complex structures that require semi-colons). • Avoid paragraphs that consist of single sentences as they often represent a sentence that has unintentionally become too complex or incomplete. However, sometimes such paragraphs are useful for emphasis, summary, or introductions. As a corollary, most sections should have multiple paragraphs. • For longer lists and more complex lists, use bulleted items rather than integrating them inline into a sentence. • Do not expect that the content of any example (inline or blocked) will be self explanatory. Even when it feels redundant, make sure that the function and use of every example is clearly described. ReStructured Text and Typesetting • Place spaces between nested parentheticals and elements in JavaScript examples. For example, prefer { [ a, a, a ] } over {[a,a,a]}. • For underlines associated with headers in RST, use: – = for heading level 1 or h1s. Use underlines and overlines for document titles. – - for heading level 2 or h2s. – ~ for heading level 3 or h3s. – ‘ for heading level 4 or h4s. • Use hyphens (-) to indicate items of an ordered list. • Place footnotes and other references, if you use them, at the end of a section rather than the end of a file. Use the footnote format that includes automatic numbering and a target name for ease of use. For instance a footnote tag may look like: [#note]_ with the corresponding directive holding the body of the footnote that resembles the following: .. [#note]. Do not include .. code-block:: [language] in footnotes. 8 Chapter 1. About MongoDB Documentation
    • 13. MongoDB Reference Manual, Release 2.6.4 • As it makes sense, use the .. code-block:: [language] form to insert literal blocks into the text. While the double colon, ::, is functional, the .. code-block:: [language] form makes the source easier to read and understand. • For all mentions of referenced types (i.e. commands, operators, expressions, functions, statuses, etc.) use the reference types to ensure uniform formatting and cross-referencing. 1.5. Contribute to the Documentation 9
    • 14. MongoDB Reference Manual, Release 2.6.4 10 Chapter 1. About MongoDB Documentation
    • 15. MongoDB Reference Manual, Release 2.6.4 Jargon and Common Terms Pre-ferred Term Concept Dispreferred Alternatives Notes docu-ment A single, top-level object/record in a MongoDB collection. record, object, row Prefer document over object because of concerns about cross-driver language handling of objects. Reserve record for “allocation” of storage. Avoid “row,” as possible. databaseA group of collections. Refers to a group of data files. This is the “logical” sense of the term “database.” Avoid genericizing “database.” Avoid using database to refer to a server process or a data set. This applies both to the datastoring contexts as well as other (related) operational contexts (command context, authentication/authorization context.) in-stance A daemon process. (e.g. mongos or mongod) process (acceptable sometimes), node (never acceptable), server. Avoid using instance, unless it modifies something specifically. Having a descriptor for a process/instance makes it possible to avoid needing to make mongod or mongos plural. Server and node are both vague and contextually difficult to disambiguate with regards to application servers, and underlying hardware. field name The identifier of a value in a document. key, column Avoid introducing unrelated terms for a single field. In the documentation we’ve rarely had to discuss the identifier of a field, so the extra word here isn’t burdensome. field/valueThe name/value pair that describes a unit of data in MongoDB. key, slot, attribute Use to emphasize the difference between the name of a field and its value For example, “_id” is the field and the default value is an ObjectId. value The data content of a field. data Mon-goDB A group of processes, or deployment that implement the MongoDB interface. mongo, mongodb, cluster Stylistic preference, mostly. In some cases it’s useful to be able to refer generically to instances (that may be either mongod or mongos.) sub-document An embedded or nested document within a document or an array. embedded document, nested document map-reduce An operation performed by the mapReduce command. mapReduce, map reduce, map/reduce Avoid confusion with the command, shell helper, and driver interfaces. Makes it possible to discuss the operation generally. clus-ter A sharded cluster. grid, shard cluster, set, deployment Cluster is a great word for a group of processes; however, it’s important to avoid letting the term become generic. Do not use for any group of MongoDB processes or deployments. sharded clus-ter A sharded cluster. shard cluster, cluster, sharded system replica set A deployment of replicating mongod programs that provide redundancy and automatic failover. set, replication deployment de-ploy-ment A group of MongoDB processes, or a standalone mongod instance. cluster, system Typically in the form MongoDB deployment. Includes standalones, replica sets and sharded clusters. 1.5. Contribute to the Documentation 11 data set The collection of physical databases provided by a MongoDB deployment. database, data Important to keep the distinction between the data provided by a mongod or a sharded cluster as distinct from each “database” (i.e. a logical
    • 16. MongoDB Reference Manual, Release 2.6.4 Database Systems and Processes • To indicate the entire database system, use “MongoDB,” not mongo or Mongo. • To indicate the database process or a server instance, use mongod or mongos. Refer to these as “processes” or “instances.” Reserve “database” for referring to a database structure, i.e., the structure that holds collections and refers to a group of files on disk. Distributed System Terms • Refer to partitioned systems as “sharded clusters.” Do not use shard clusters or sharded systems. • Refer to configurations that run with replication as “replica sets” (or “master/slave deployments”) rather than “clusters” or other variants. Data Structure Terms • “document” refers to “rows” or “records” in a MongoDB database. Potential confusion with “JSON Docu-ments.” Do not refer to documents as “objects,” because drivers (and MongoDB) do not preserve the order of fields when fetching data. If the order of objects matter, use an array. • “field” refers to a “key” or “identifier” of data within a MongoDB document. • “value” refers to the contents of a “field”. • “sub-document” describes a nested document. Other Terms • Use (and .org or .com if needed) for all examples and samples. • Hyphenate “map-reduce” in order to avoid ambiguous reference to the command name. Do not camel-case. Notes on Specific Features • Geo-Location 1. While MongoDB is capable of storing coordinates in sub-documents, in practice, users should only store coordinates in arrays. (See: DOCS-4135.) MongoDB Documentation Practices and Processes This document provides an overview of the practices and processes. Commits When relevant, include a Jira case identifier in a commit message. Reference documentation cases when applicable, but feel free to reference other cases from jira.mongodb.org36. Err on the side of creating a larger number of discrete commits rather than bundling large set of changes into one commit. 35 36 12 Chapter 1. About MongoDB Documentation
    • 17. MongoDB Reference Manual, Release 2.6.4 For the sake of consistency, remove trailing whitespaces in the source file. “Hard wrap” files to between 72 and 80 characters per-line. Standards and Practices • At least two people should vet all non-trivial changes to the documentation before publication. One of the reviewers should have significant technical experience with the material covered in the documentation. • All development and editorial work should transpire on GitHub branches or forks that editors can then merge into the publication branches. Collaboration To propose a change to the documentation, do either of the following: • Open a ticket in the documentation project37 proposing the change. Someone on the documentation team will make the change and be in contact with you so that you can review the change. • Using GitHub38, fork the mongodb/docs repository39, commit your changes, and issue a pull request. Someone on the documentation team will review and incorporate your change into the documentation. Builds Building the documentation is useful because Sphinx40 and docutils can catch numerous errors in the format and syntax of the documentation. Additionally, having access to an example documentation as it will appear to the users is useful for providing more effective basis for the review process. Besides Sphinx, Pygments, and Python-Docutils, the documentation repository contains all requirements for building the documentation resource. Talk to someone on the documentation team if you are having problems running builds yourself. Publication The makefile for this repository contains targets that automate the publication process. Use make html to publish a test build of the documentation in the build/ directory of your repository. Use make publish to build the full contents of the manual from the current branch in the ../public-docs/ directory relative the docs repository. Other targets include: • man - builds UNIX Manual pages for all Mongodb utilities. • push - builds and deploys the contents of the ../public-docs/. • pdfs - builds a PDF version of the manual (requires LaTeX dependencies.) Branches This section provides an overview of the git branches in the MongoDB documentation repository and their use. 37 38 39 40 1.5. Contribute to the Documentation 13
    • 18. MongoDB Reference Manual, Release 2.6.4 At the present time, future work transpires in the master, with the main publication being current. As the documentation stabilizes, the documentation team will begin to maintain branches of the documentation for specific MongoDB releases. Migration from Legacy Documentation The Wiki contains a wealth of information. As the transition to the Manual (i.e. this project and resource) continues, it’s critical that no information disappears or goes missing. The following process outlines how to migrate a wiki page to the manual: 1. Read the relevant sections of the Manual, and see what the new documentation has to offer on a specific topic. In this process you should follow cross references and gain an understanding of both the underlying information and how the parts of the new content relates its constituent parts. 2. Read the wiki page you wish to redirect, and take note of all of the factual assertions, examples presented by the wiki page. 3. Test the factual assertions of the wiki page to the greatest extent possible. Ensure that example output is accurate. In the case of commands and reference material, make sure that documented options are accurate. 4. Make corrections to the manual page or pages to reflect any missing pieces of information. The target of the redirect need not contain every piece of information on the wiki page, if the manual as a whole does, and relevant section(s) with the information from the wiki page are accessible from the target of the redirection. 5. As necessary, get these changes reviewed by another writer and/or someone familiar with the area of the infor-mation in question. At this point, update the relevant Jira case with the target that you’ve chosen for the redirect, and make the ticket unassigned. 6. When someone has reviewed the changes and published those changes to Manual, you, or preferably someone else on the team, should make a final pass at both pages with fresh eyes and then make the redirect. Steps 1-5 should ensure that no information is lost in the migration, and that the final review in step 6 should be trivial to complete. Review Process Types of Review The content in the Manual undergoes many types of review, including the following: Initial Technical Review Review by an engineer familiar with MongoDB and the topic area of the documentation. This review focuses on technical content, and correctness of the procedures and facts presented, but can improve any aspect of the documentation that may still be lacking. When both the initial technical review and the content review are complete, the piece may be “published.” Content Review Textual review by another writer to ensure stylistic consistency with the rest of the manual. De-pending on the content, this may precede or follow the initial technical review. When both the initial technical review and the content review are complete, the piece may be “published.” 14 Chapter 1. About MongoDB Documentation
    • 19. MongoDB Reference Manual, Release 2.6.4 Consistency Review This occurs post-publication and is content focused. The goals of consistency reviews are to increase the internal consistency of the documentation as a whole. Insert relevant cross-references, update the style as needed, and provide background fact-checking. When possible, consistency reviews should be as systematic as possible and we should avoid encouraging stylistic and information drift by editing only small sections at a time. Subsequent Technical Review If the documentation needs to be updated following a change in functionality of the server or following the resolution of a user issue, changes may be significant enough to warrant additional technical review. These reviews follow the same form as the “initial technical review,” but is often less involved and covers a smaller area. Review Methods If you’re not a usual contributor to the documentation and would like to review something, you can submit reviews in any of the following methods: • If you’re reviewing an open pull request in GitHub, the best way to comment is on the “overview diff,” which you can find by clicking on the “diff” button in the upper left portion of the screen. You can also use the following URL to reach this interface:[pull-request-id]/files Replace [pull-request-id] with the identifier of the pull request. Make all comments inline, using GitHub’s comment system. You may also provide comments directly on commits, or on the pull request itself but these commit-comments are archived in less coherent ways and generate less useful emails, while comments on the pull request lead to less specific changes to the document. • Leave feedback on Jira cases in the DOCS41 project. These are better for more general changes that aren’t necessarily tied to a specific line, or affect multiple files. • Create a fork of the repository in your GitHub account, make any required changes and then create a pull request with your changes. If you insert lines that begin with any of the following annotations: .. TODO: TODO: .. TODO TODO followed by your comments, it will be easier for the original writer to locate your comments. The two dots .. format is a comment in reStructured Text, which will hide your comments from Sphinx and publication if you’re worried about that. This format is often easier for reviewers with larger portions of content to review. MongoDB Manual Organization This document provides an overview of the global organization of the documentation resource. Refer to the notes below if you are having trouble understanding the reasoning behind a file’s current location, or if you want to add new documentation but aren’t sure how to integrate it into the existing resource. If you have questions, don’t hesitate to open a ticket in the Documentation Jira Project42 or contact the documentation team43. 41 42 1.5. Contribute to the Documentation 15
    • 20. MongoDB Reference Manual, Release 2.6.4 Global Organization Indexes and Experience The documentation project has two “index files”: and The “contents” file provides the documentation’s tree structure, which Sphinx uses to create the left-pane navigational structure, to power the “Next” and “Previous” page functionality, and to provide all overarching outlines of the resource. The “index” file is not included in the “contents” file (and thus builds will produce a warning here) and is the page that users first land on when visiting the resource. Having separate “contents” and “index” files provides a bit more flexibility with the organization of the resource while also making it possible to customize the primary user experience. Topical Organization The placement of files in the repository depends on the type of documentation rather than the topic of the content. Like the difference between contents.txt and index.txt, by decoupling the organization of the files from the organization of the information the documentation can be more flexible and can more adequately address changes in the product and in users’ needs. Files in the source/ directory represent the tip of a logical tree of documents, while directories are containers of types of content. The administration and applications directories, however, are legacy artifacts and with a few exceptions contain sub-navigation pages. With several exceptions in the reference/ directory, there is only one level of sub-directories in the source/ directory. Tools The organization of the site, like all Sphinx sites derives from the toctree44 structure. However, in order to annotate the table of contents and provide additional flexibility, the MongoDB documentation generates toctree45 structures using data from YAML files stored in the source/includes/ directory. These files start with ref-toc or toc and generate output in the source/includes/toc/ directory. Briefly this system has the following behavior: • files that start with ref-toc refer to the documentation of API objects (i.e. commands, operators and methods), and the build system generates files that hold toctree46 directives as well as files that hold tables that list objects and a brief description. • files that start with toc refer to all other documentation and the build system generates files that hold toctree47 directives as well as files that hold definition lists that contain links to the documents and short descriptions the content. • file names that have spec following toc or ref-toc will generate aggregated tables or definition lists and allow ad-hoc combinations of documents for landing pages and quick reference guides. MongoDB Documentation Build System This document contains more direct instructions for building the MongoDB documentation. Getting Started Install Dependencies The MongoDB Documentation project depends on the following tools: 44 45 46 47 16 Chapter 1. About MongoDB Documentation
    • 21. MongoDB Reference Manual, Release 2.6.4 • GNU Make • GNU Tar • Python • Git • Sphinx (documentation management toolchain) • Pygments (syntax highlighting) • PyYAML (for the generated tables) • Droopy (Python package for static text analysis) • Fabric (Python package for scripting and orchestration) • Inkscape (Image generation.) • python-argparse (For Python 2.6.) • LaTeX/PDF LaTeX (typically texlive; for building PDFs) • Common Utilities (rsync, tar, gzip, sed) OS X Install Sphinx, Docutils, and their dependencies with easy_install the following command: easy_install Sphinx Jinja2 Pygments docutils PyYAML droopy fabric Feel free to use pip rather than easy_install to install python packages. To generate the images used in the documentation, download and install Inkscape48. Optional To generate PDFs for the full production build, install a TeX distribution (for building the PDF.) If you do not have a LaTeX installation, use MacTeX49. This is only required to build PDFs. Arch Linux Install packages from the system repositories with the following command: pacman -S python2-sphinx python2-yaml inkscape python2-pip Then install the following Python packages: pip install droopy fabric Optional To generate PDFs for the full production build, install the following packages from the system repository: pacman -S texlive-bin texlive-core texlive-latexextra Debian/Ubuntu Install the required system packages with the following command: apt-get install python-sphinx python-yaml python-argparse inkscape python-pip Then install the following Python packages: 48 49 1.5. Contribute to the Documentation 17
    • 22. MongoDB Reference Manual, Release 2.6.4 pip install droopy fabric Optional To generate PDFs for the full production build, install the following packages from the system repository: apt-get install texlive-latex-recommended texlive-latex-recommended Setup and Configuration Clone the repository: git clone git:// Then run the script in the docs/ repository, to configure the build dependencies: python This downloads and configures the mongodb/docs-tools50 repository, which contains the authoritative build system shared between branches of the MongoDB Manual and other MongoDB documentation projects. You can run regularly to update build system. Building the Documentation The MongoDB documentation build system is entirely accessible via make targets. For example, to build an HTML version of the documentation issue the following command: make html You can find the build output in build/ /html, where is the name of the current branch. In addition to the html target, the build system provides the following targets: publish Builds and integrates all output for the production build. Build output is in build/public/ /. When you run publish in the master, the build will generate some output in build/public/. push; stage Uploads the production build to the production or staging web servers. Depends on publish. Re-quires access production or staging environment. push-all; stage-all Uploads the entire content of build/public/ to the web servers. Depends on publish. Not used in common practice. push-with-delete; stage-with-delete Modifies the action of push and stage to remove remote file that don’t exist in the local build. Use with caution. html; latex; dirhtml; epub; texinfo; man; json These are standard targets derived from the default Sphinx Makefile, with adjusted dependencies. Additionally, for all of these targets you can append -nitpick to increase Sphinx’s verbosity, or -clean to remove all Sphinx build artifacts. latex performs several additional post-processing steps on .tex output generated by Sphinx. This target will also compile PDFs using pdflatex. html and man also generates a .tar.gz file of the build outputs for inclusion in the final releases. 50 18 Chapter 1. About MongoDB Documentation
    • 23. MongoDB Reference Manual, Release 2.6.4 Build Mechanics and Tools Internally the build system has a number of components and processes. See the docs-tools README51 for more information on the internals. This section documents a few of these components from a very high level and lists useful operations for contributors to the documentation. Fabric Fabric is an orchestration and scripting package for Python. The documentation uses Fabric to handle the deployment of the build products to the web servers and also unifies a number of independent build operations. Fabric commands have the following form: fab . [: ] The is optional in most cases. Additionally some tasks are available at the root level, without a module. To see a full list of fabric tasks, use the following command: fab -l You can chain fabric tasks on a single command line, although this doesn’t always make sense. Important fabric tasks include: tools.bootstrap Runs the script. Useful for re-initializing the repository without needing to be in root of the repository.; tools.reset switches the origin remote of the docs-tools checkout in build directory, to ../docs-tools to facilitate build system testing and development. tools.reset resets the origin remote for normal operation. tools.conf tools.conf returns the content of the configuration object for the current project. These data are useful during development. Returns, a collection of readability statistics. Specify file names relative to source/ tree. make Provides a thin wrapper around Make calls. Allows you to start make builds from different locations in the project repository. process.refresh_dependencies Updates the time stamp of .txt source files with changed include files, to facilitate Sphinx’s incremental rebuild process. This task runs internally as part of the build process. Buildcloth Buildcloth52 is a meta-build tool, used to generate Makefiles programmatically. This makes the build system easier to maintain, and makes it easier to use the same fundamental code to generate various branches of the Manual as well as related documentation projects. See makecloth/ in the docs-tools repository53 for the relevant code. Running make with no arguments will regenerate these parts of the build system automatically. Rstcloth Rstcloth54 is a library for generating reStructuredText programmatically. This makes it possible to generate content for the documentation, such as tables, tables of contents, and API reference material programmatically and transparently. See rstcloth/ in the docs-tools repository55 for the relevant code. If you have any questions, please feel free to open a Jira Case56. 51 52 53 54 55 56 1.5. Contribute to the Documentation 19
    • 24. MongoDB Reference Manual, Release 2.6.4 20 Chapter 1. About MongoDB Documentation
    • 25. CHAPTER 2 Interfaces Reference 2.1 mongo Shell Methods JavaScript in MongoDB Although these methods use JavaScript, most interactions with MongoDB do not use JavaScript but use an idiomatic driver in the language of the interacting application. 2.1.1 Collection Collection Methods Name Description db.collection.aggregate() (page 22) Provides access to the aggregation pipeline. db.collection.copyTo() (page 25) Wraps eval (page 235) to copy data between collections in db.collection.count() (page 26) Wraps count (page 211) to return a count of the number of db.collection.createIndex() (page 27) Builds an index on a collection. Use db.collection.ensureIndex() db.collection.dataSize() (page 28) Returns the size of the collection. Wraps the size (page 338) db.collection.distinct() (page 28) Returns an array of documents that have distinct values for db.collection.drop() (page 28) Removes the specified collection from the database. db.collection.dropIndex() (page 29) Removes a specified index on a collection. db.collection.dropIndexes() (page 30) Removes all indexes on a collection. db.collection.ensureIndex() (page 30) Creates an index if it does not currently exist. If the index exists db.collection.find() (page 33) Performs a query on a collection and returns a cursor object. db.collection.findAndModify() (page 38) Atomically modifies and returns a single document. db.collection.findOne() (page 42) Performs a query and returns a single document. db.collection.getIndexStats() (page 44) Renders a human-readable view of the data collected by indexStats db.collection.getIndexes() (page 45) Returns an array of documents that describe the existing indexes db.collection.getShardDistribution() (page 45) For collections in sharded clusters, db.collection.getShardDistribution() db.collection.getShardVersion() (page 47) Internal diagnostic method for shard cluster. (page 47) Provides simple data aggregation function. Groups documents db.collection.indexStats() (page 51) Renders a human-readable view of the data collected by indexStats db.collection.initializeOrderedBulkOp() (page 51) Initializes a Bulk() (page 135) operations builder for an ordered db.collection.initializeUnorderedBulkOp() (page 52) Initializes a Bulk() (page 135) operations builder for an unordered db.collection.insert() (page 53) Creates a new document in a collection. db.collection.isCapped() (page 56) Reports if a collection is a capped collection. 21
    • 26. MongoDB Reference Manual, Release 2.6.4 Table 2.1 – continued from Name Description db.collection.mapReduce() (page 56) Performs map-reduce style data aggregation. db.collection.reIndex() (page 63) Rebuilds all existing indexes on a collection. db.collection.remove() (page 64) Deletes documents from a collection. db.collection.renameCollection() (page 67) Changes the name of a collection. (page 68) Provides a wrapper around an insert() (page 53) and update() db.collection.stats() (page 69) Reports on the state of a collection. Provides a wrapper around db.collection.storageSize() (page 70) Reports the total size used by the collection in bytes. Provides db.collection.totalIndexSize() (page 70) Reports the total size used by the indexes on a collection. Provides db.collection.totalSize() (page 70) Reports the total size of a collection, including the size of all db.collection.update() (page 70) Modifies a document in a collection. db.collection.validate() (page 78) Performs diagnostic operations on a collection. db.collection.aggregate() New in version 2.2. Definition db.collection.aggregate(pipeline, options) Calculates aggregate values for the data in a collection. param array pipeline A sequence of data aggregation operations or stages. See the aggregation pipeline operators (page 458) for details. Changed in version 2.6: The method can still accept the pipeline stages as separate arguments instead of as elements in an array; however, if you do not specify the pipeline as an array, you cannot specify the options parameter. param document options Additional options that aggregate() (page 22) passes to the aggregate (page 208) command. New in version 2.6: Available only if you specify the pipeline as an array. The options document can contain the following fields and values: field boolean explain Specifies to return the information on the processing of the pipeline. See Return Information on Aggregation Pipeline Operation (page 24) for an example. New in version 2.6. field boolean allowDiskUse Enables writing to temporary files. When set to true, aggregation operations can write data to the _tmp subdirectory in the dbPath directory. See Perform Large Sort Operation with External Sort (page 24) for an example. New in version 2.6. field document cursor Specifies the initial batch size for the cursor. The value of the cursor field is a document with the field batchSize. See Specify an Initial Batch Size (page 24) for syntax and example. New in version 2.6. Returns A cursor to the documents produced by the final stage of the aggregation pipeline operation, or if you include the explain option, the document that provides details on the processing of the aggregation operation. 22 Chapter 2. Interfaces Reference
    • 27. MongoDB Reference Manual, Release 2.6.4 If the pipeline includes the $out (page 465) operator, aggregate() (page 22) returns an empty cursor. See $out (page 465) for more information. Changed in version 2.6: The db.collection.aggregate() (page 22) method returns a cursor and can return result sets of any size. Previous versions returned all results in a single document, and the result set was subject to a size limit of 16 megabytes. Changed in version 2.4: If an error occurs, the aggregate() (page 22) helper throws an exception. In previous versions, the helper returned a document with the error message and code, and ok status field not equal to 1, same as the aggregate (page 208) command. See also: For more information, see, Aggre-gation Reference (page 536),, and aggregate (page 208). Cursor Behavior In the mongo (page 580) shell, if the cursor returned from the db.collection.aggregate() (page 22) is not assigned to a variable using the var key-word, then the mongo (page 580) shell automatically iterates the cursor up to 20 times. See for cursor behavior in the mongo (page 580) shell and for handling cursors in the mongo (page 580) shell. Cursors returned from aggregation only supports cursor methods that operate on evaluated cursors (i.e. cursors whose first batch has been retrieved), such as the following methods: • cursor.hasNext() (page 88) • (page 93) • cursor.toArray() (page 100) • cursor.forEach() (page 88) • (page 89) • cursor.objsLeftInBatch() (page 94) • cursor.itcount() • cursor.pretty() Examples The examples in this section use the db.collection.aggregate() (page 22) helper provided in the 2.6 version of the mongo (page 580) shell. The following examples use the collection orders that contains the following documents: { _id: 1, cust_id: "abc1", ord_date: ISODate("2012-11-02T17:04:11.102Z"), status: "A", amount: 50 } { _id: 2, cust_id: "xyz1", ord_date: ISODate("2013-10-01T17:04:11.102Z"), status: "A", amount: 100 } { _id: 3, cust_id: "xyz1", ord_date: ISODate("2013-10-12T17:04:11.102Z"), status: "D", amount: 25 } { _id: 4, cust_id: "xyz1", ord_date: ISODate("2013-10-11T17:04:11.102Z"), status: "D", amount: 125 } { _id: 5, cust_id: "abc1", ord_date: ISODate("2013-11-12T17:04:11.102Z"), status: "A", amount: 25 } Group by and Calculate a Sum The following aggregation operation selects documents with status equal to "A", groups the matching documents by the cust_id field and calculates the total for each cust_id field from the sum of the amount field, and sorts the results by the total field in descending order: db.orders.aggregate([ { $match: { status: "A" } }, { $group: { _id: "$cust_id", total: { $sum: "$amount" } } }, { $sort: { total: -1 } } ]) 2.1. mongo Shell Methods 23
    • 28. MongoDB Reference Manual, Release 2.6.4 The operation returns a cursor with the following documents: { "_id" : "xyz1", "total" : 100 } { "_id" : "abc1", "total" : 75 } The mongo (page 580) shell iterates the returned cursor automatically to print the results. See for handling cursors manually in the mongo (page 580) shell. Return Information on Aggregation Pipeline Operation The following aggregation operation sets the option explain to true to return information about the aggregation operation. db.orders.aggregate( [ { $match: { status: "A" } }, { $group: { _id: "$cust_id", total: { $sum: "$amount" } } }, { $sort: { total: -1 } } ], { explain: true } ) The operation returns a cursor with the document that contains detailed information regarding the processing of the aggregation pipeline. For example, the document may show, among other details, which index, if any, the operation used. 1 If the orders collection is a sharded collection, the document would also show the division of labor between the shards and the merge operation, and for targeted queries, the targeted shards. Note: The intended readers of the explain output document are humans, and not machines, and the output format is subject to change between releases. The mongo (page 580) shell iterates the returned cursor automatically to print the results. See for handling cursors manually in the mongo (page 580) shell. Perform Large Sort Operation with External Sort Aggregation pipeline stages have maximum memory use limit. To handle large datasets, set allowDiskUse option to true to enable writing data to temporary files, as in the following example: var results = db.stocks.aggregate( [ { $project : { cusip: 1, date: 1, price: 1, _id: 0 } }, { $sort : { cusip : 1, date: 1 } } ], { allowDiskUse: true } ) Specify an Initial Batch Size To specify an initial batch size for the cursor, use the following syntax for the cursor option: 1 index-filters can affect the choice of index used. See index-filters for details. 24 Chapter 2. Interfaces Reference
    • 29. MongoDB Reference Manual, Release 2.6.4 cursor: { batchSize: } For example, the following aggregation operation specifies the initial batch size of 0 for the cursor: db.orders.aggregate( [ { $match: { status: "A" } }, { $group: { _id: "$cust_id", total: { $sum: "$amount" } } }, { $sort: { total: -1 } }, { $limit: 2 } ], { cursor: { batchSize: 0 } } ) A batchSize of 0 means an empty first batch and is useful for quickly returning a cursor or failure message without doing significant server-side work. Specify subsequent batch sizes to OP_GET_MORE2 operations as with other MongoDB cursors. The mongo (page 580) shell iterates the returned cursor automatically to print the results. See for handling cursors manually in the mongo (page 580) shell. db.collection.copyTo() Definition db.collection.copyTo(newCollection) Copies all documents from collection into newCollection using server-side JavaScript. If newCollection does not exist, MongoDB creates it. If authorization is enabled, you must have access to all actions on all resources in order to run db.collection.copyTo() (page 25). Providing such access is not recommended, but if your organi-zation requires a user to run db.collection.copyTo() (page 25), create a role that grants anyAction on resource-anyresource. Do not assign this role to any other user. param string newCollection The name of the collection to write data to. Warning: When using db.collection.copyTo() (page 25) check field types to ensure that the operation does not remove type information from documents during the translation from BSON to JSON. Consider using cloneCollection() (page 103) to maintain type fidelity. The db.collection.copyTo() (page 25) method uses the eval (page 235) command internally. As a result, the db.collection.copyTo() (page 25) operation takes a global lock that blocks all other read and write operations until the db.collection.copyTo() (page 25) completes. copyTo() (page 25) returns the number of documents copied. If the copy fails, it throws an exception. Behavior Because copyTo() (page 25) uses eval (page 235) internally, the copy operations will block all other operations on the mongod (page 555) instance. Example The following operation copies all documents from the source collection into the target collection. 2 2.1. mongo Shell Methods 25
    • 30. MongoDB Reference Manual, Release 2.6.4 db.source.copyTo(target) db.collection.count() Definition db.collection.count( ) Returns the count of documents that would match a find() (page 33) query. The db.collection.count() (page 26) method does not perform the find() (page 33) operation but instead counts and returns the number of results that match a query. The db.collection.count() (page 26) method has the following parameter: param document query The query selection criteria. The db.collection.count() (page 26) method is equivalent to the db.collection.find( ).count() construct. See also: cursor.count() (page 81) Behavior Sharded Clusters On a sharded cluster, db.collection.count() (page 26) can result in an inaccurate count if orphaned documents exist or if a chunk migration is in progress. To avoid these situations, on a sharded cluster, use the $group (page 460) stage of the db.collection.aggregate() (page 22) method to $sum (page 527) the documents. For example, the following operation counts the documents in a collection: db.collection.aggregate( [ { $group: { _id: null, count: { $sum: 1 } } } ] ) To get a count of documents that match a query condition, include the $match (page 464) stage as well: db.collection.aggregate( [ { $match: }, { $group: { _id: null, count: { $sum: 1 } } } ] ) See Perform a Count (page 465) for an example. Index Use Consider a collection with the following index: { a: 1, b: 1 } When performing a count, MongoDB can return the count using only the index if: • the query can use an index, • the query only contains conditions on the keys of the index, and • the query predicates access a single contiguous range of index keys. 26 Chapter 2. Interfaces Reference
    • 31. MongoDB Reference Manual, Release 2.6.4 For example, the following operations can return the count using only the index: db.collection.find( { a: 5, b: 5 } ).count() db.collection.find( { a: { $gt: 5 } } ).count() db.collection.find( { a: 5, b: { $gt: 10 } } ).count() If, however, the query can use an index but the query predicates do not access a single contiguous range of index keys or the query also contains conditions on fields outside the index, then in addition to using the index, MongoDB must also read the documents to return the count. db.collection.find( { a: 5, b: { $in: [ 1, 2, 3 ] } } ).count() db.collection.find( { a: { $gt: 5 }, b: 5 } ).count() db.collection.find( { a: 5, b: 5, c: 5 } ).count() In such cases, during the initial read of the documents, MongoDB pages the documents into memory such that subse-quent calls of the same count operation will have better performance. Examples Count all Documents in a Collection To count the number of all documents in the orders collection, use the following operation: db.orders.count() This operation is equivalent to the following: db.orders.find().count() Count all Documents that Match a Query Count the number of the documents in the orders collection with the field ord_dt greater than new Date(’01/01/2012’): db.orders.count( { ord_dt: { $gt: new Date('01/01/2012') } } ) The query is equivalent to the following: db.orders.find( { ord_dt: { $gt: new Date('01/01/2012') } } ).count() db.collection.createIndex() Definition db.collection.createIndex(keys, options) Deprecated since version 1.8. Creates indexes on collections. param document keys For each field to index, a key-value pair with the field and the index order: 1 for ascending or -1 for descending. param document options One or more key-value pairs that specify index options. For a list of options, see db.collection.ensureIndex() (page 30). See also:, db.collection.createIndex() (page 27), db.collection.dropIndex() (page 29), db.collection.dropIndexes() (page 30), db.collection.getIndexes() (page 45), db.collection.reIndex() (page 63), and db.collection.totalIndexSize() (page 70) 2.1. mongo Shell Methods 27
    • 32. MongoDB Reference Manual, Release 2.6.4 db.collection.dataSize() db.collection.dataSize() Returns The size of the collection. This method provides a wrapper around the size (page 338) output of the collStats (page 338) (i.e. db.collection.stats() (page 69)) com-mand. db.collection.distinct() Definition db.collection.distinct(field, query) Finds the distinct values for a specified field across a single collection and returns the results in an array. param string field The field for which to return distinct values. param document query A query that specifies the documents from which to retrieve the distinct values. The db.collection.distinct() (page 28) method provides a wrapper around the distinct (page 213) command. Results must not be larger than the maximum BSON size (page 658). When possible to use covered indexes, the db.collection.distinct() (page 28) method will use an index to find the documents in the query as well as to return the data. Examples The following are examples of the db.collection.distinct() (page 28) method: • Return an array of the distinct values of the field ord_dt from all documents in the orders collection: db.orders.distinct( 'ord_dt' ) • Return an array of the distinct values of the field sku in the subdocument item from all documents in the orders collection: db.orders.distinct( 'item.sku' ) • Return an array of the distinct values of the field ord_dt from the documents in the orders collection where the price is greater than 10: db.orders.distinct( 'ord_dt', { price: { $gt: 10 } } ) db.collection.drop() db.collection.drop() Call the db.collection.drop() (page 28) method on a collection to drop it from the database. The method provides a wrapper around the drop (page 327) command. db.collection.drop() (page 28) takes no arguments and will produce an error if called with any argu-ments. This method also removes any indexes associated with the dropped collection. Warning: This method obtains a write lock on the affected database and will block other operations until it has completed. 28 Chapter 2. Interfaces Reference
    • 33. MongoDB Reference Manual, Release 2.6.4 db.collection.dropIndex() Definition db.collection.dropIndex(index) Drops or removes the specified index from a collection. The db.collection.dropIndex() (page 29) method provides a wrapper around the dropIndexes (page 327) command. Note: You cannot drop the default index on the _id field. The db.collection.dropIndex() (page 29) method takes the following parameter: param string,document index Specifies the index to drop. You can specify the index either by the index name or by the index specification document. 3 To drop a text index, specify the index name. To get the index name or the index specification document for the db.collection.dropIndex() (page 29) method, use the db.collection.getIndexes() (page 45) method. Example Consider a pets collection. Calling the getIndexes() (page 45) method on the pets collection returns the following indexes: [ { "v" : 1, "key" : { "_id" : 1 }, "ns" : "test.pets", "name" : "_id_" }, { "v" : 1, "key" : { "cat" : -1 }, "ns" : "test.pets", "name" : "catIdx" }, { "v" : 1, "key" : { "cat" : 1, "dog" : -1 }, "ns" : "test.pets", "name" : "cat_1_dog_-1" } ] The single field index on the field cat has the user-specified name of catIdx 4 and the index specification document of { "cat" : -1 }. To drop the index catIdx, you can use either the index name: db.pets.dropIndex( "catIdx" ) Or you can use the index specification document { "cat" : -1 }: db.pets.dropIndex( { "cat" : -1 } ) 3 When using a mongo (page 580) shell version earlier than 2.2.2, if you specified a name during the index creation, you must use the name to drop the index. 4 During index creation, if the user does not specify an index name, the system generates the name by concatenating the index key field and value with an underscore, e.g. cat_1. 2.1. mongo Shell Methods 29
    • 34. MongoDB Reference Manual, Release 2.6.4 db.collection.dropIndexes() db.collection.dropIndexes() Drops all indexes other than the required index on the _id field. Only call dropIndexes() (page 30) as a method on a collection object. db.collection.ensureIndex() Definition db.collection.ensureIndex(keys, options) Creates an index on the specified field if the index does not already exist. The ensureIndex() (page 30) method has the following fields: param document keys A document that contains the field and value pairs where the field is the index key and the value describes the type of index for that field. For an ascending index on a field, specify a value of 1; for descending index, specify a value of -1. MongoDB supports several different index types including text, geospatial, and hashed indexes. See index-type-list for more information. param document options A document that contains a set of options that controls the creation of the index. See Options (page 30) for details. Options The options document contains a set of options that controls the creation of the index. Different index types can have additional options specific for that type. Options for All Index Types The following options are available for all index types unless otherwise specified: param Boolean background Builds the index in the background so that building an index does not block other database activities. Specify true to build in the background. The default value is false. param Boolean unique Creates a unique index so that the collection will not accept insertion of docu-ments where the index key or keys match an existing value in the index. Specify true to create a unique index. The default value is false. The option is unavailable for hashed indexes. param string name The name of the index. If unspecified, MongoDB generates an index name by con-catenating the names of the indexed fields and the sort order. Whether user specified or MongoDB generated, index names including their full namespace (i.e. database.collection) cannot be longer than the Index Name Limit (page 659). param Boolean dropDups Creates a unique index on a field that may have duplicates. MongoDB in-dexes only the first occurrence of a key and removes all documents from the collection that contain subsequent occurrences of that key. Specify true to create unique index. The default value is false. The option is unavailable for hashed indexes. Deprecated since version 2.6. Warning: dropDups will delete data from your collection when building the index. 30 Chapter 2. Interfaces Reference
    • 35. MongoDB Reference Manual, Release 2.6.4 param Boolean sparse If true, the index only references documents with the specified field. These in-dexes use less space but behave differently in some situations (particularly sorts). The default value is false. See for more in-formation. Changed in version 2.6: 2dsphere indexes are sparse by default and ignore this option. For a compound index that includes 2dsphere index key(s) along with keys of other types, only the 2dsphere index fields determine whether the index references a document. 2d, geoHaystack, and text indexes behave similarly to the 2dsphere indexes. param integer expireAfterSeconds Specifies a value, in seconds, as a TTL to control how long MongoDB retains documents in this collection. See for more informa-tion on this functionality. This applies only to TTL indexes. param index version v The index version number. The default index version depends on the version of mongod (page 555) running when creating the index. Before version 2.0, the this value was 0; versions 2.0 and later use version 1, which provides a smaller and faster index format. Specify a different index version only in unusual situations. Options for text Indexes The following options are available for text indexes only: param document weights For text indexes, a document that contains field and weight pairs. The weight is an integer ranging from 1 to 99,999 and de-notes the significance of the field relative to the other indexed fields in terms of the score. You can specify weights for some or all the indexed fields. See to adjust the scores. The default value is 1. param string default_language For text indexes, the language that deter-mines the list of stop words and the rules for the stemmer and to-kenizer. See text-search-languages for the available languages and for more information and examples. The default value is english. param string language_override For text indexes, the name of the field, in the collection’s docu-ments, that contains the override language for the document. The default value is language. See specify-language-field-text-index-example for an example. param integer textIndexVersion For text indexes, the text index version number. Version can be either 1 or 2. In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1. New in version 2.6. Options for 2dsphere Indexes The following option is available for 2dsphere indexes only: param integer 2dsphereIndexVersion For 2dsphere indexes, the 2dsphere index version number. Version can be either 1 or 2. In MongoDB 2.6, the default version is 2. MongoDB 2.4 can only support version 1. New in version 2.6. Options for 2d Indexes The following options are available for 2d indexes only: 2.1. mongo Shell Methods 31
    • 36. MongoDB Reference Manual, Release 2.6.4 param integer bits For 2d indexes, the number of precision of the stored geohash value of the location data. The bits value ranges from 1 to 32 inclusive. The default value is 26. param number min For 2d indexes, the lower inclusive boundary for the longitude and latitude values. The default value is -180.0. param number max For 2d indexes, the upper inclusive boundary for the longitude and latitude values. The default value is 180.0. Options for geoHaystack Indexes The following option is available for geoHaystack indexes only: param number bucketSize For geoHaystack indexes, specify the number of units within which to group the location values; i.e. group in the same bucket those location values that are within the specified number of units to each other. The value must be greater than 0. Behaviors The ensureIndex() (page 30) method has the behaviors described here. • To add or change index options you must drop the index using the dropIndex() (page 29) method and issue another ensureIndex() (page 30) operation with the new options. If you create an index with one set of options, and then issue the ensureIndex() (page 30) method with the same index fields and different options without first dropping the index, ensureIndex() (page 30) will not rebuild the existing index with the new options. • If you call multiple ensureIndex() (page 30) methods with the same index specification at the same time, only the first operation will succeed, all other operations will have no effect. • Non-background indexing operations will block all other operations on a database. • MongoDB will not create an index (page 30) on a collection if the index entry for an existing document exceeds the Maximum Index Key Length. Previous versions of MongoDB would create the index but not index such documents. Changed in version 2.6. Examples Create an Ascending Index on a Single Field The following example creates an ascending index on the field orderDate. db.collection.ensureIndex( { orderDate: 1 } ) If the keys document specifies more than one field, then ensureIndex() (page 30) creates a compound index. Create an Index on a Multiple Fields The following example creates a compound index on the orderDate field (in ascending order) and the zipcode field (in descending order.) db.collection.ensureIndex( { orderDate: 1, zipcode: -1 } ) A compound index cannot include a hashed index component. Note: The order of an index is important for supporting sort() (page 96) operations using the index. See also: 32 Chapter 2. Interfaces Reference
    • 37. MongoDB Reference Manual, Release 2.6.4 • The section of this manual for full documentation of indexes and indexing in MongoDB. • for details on creating text indexes. • index-feature-geospatial and index-geohaystack-index for geospatial queries. • index-feature-ttl for expiration of data. • db.collection.getIndexes() (page 45) to view the specifications of existing indexes for a collection. db.collection.find() Definition db.collection.find( , ) Selects documents in a collection and returns a cursor to the selected documents. 5 param document criteria Specifies selection criteria using query operators (page 386). To return all documents in a collection, omit this parameter or pass an empty document ({}). param document projection Specifies the fields to return using projection operators (page 422). To return all fields in the matching document, omit this parameter. Returns A cursor to the documents that match the query criteria. When the find() (page 33) method “returns documents,” the method is actually returning a cursor to the documents. If the projection argument is specified, the matching documents contain only the projection fields and the _id field. You can optionally exclude the _id field. Executing find() (page 33) directly in the mongo (page 580) shell automatically iterates the cursor to display up to the first 20 documents. Type it to continue iteration. To access the returned documents with a driver, use the appropriate cursor handling mechanism for the driver language. The projection parameter takes a document of the following form: { field1: , field2: ... } The value can be any of the following: • 1 or true to include the field. The find() (page 33) method always includes the _id field even if the field is not explicitly stated to return in the projection parameter. • 0 or false to exclude the field. A projection cannot contain both include and exclude specifications, except for the exclusion of the _id field. In projections that explicitly include fields, the _id field is the only field that you can explicitly exclude. Examples Find All Documents in a Collection The find() (page 33) method with no parameters returns all documents from a collection and returns all fields for the documents. For example, the following operation returns all documents in the bios collection: 5 db.collection.find() (page 33) is a wrapper for the more formal query structure that uses the $query (page 532) operator. 2.1. mongo Shell Methods 33
    • 38. MongoDB Reference Manual, Release 2.6.4 db.bios.find() Find Documents that Match Query Criteria To find documents that match a set of selection criteria, call find() with the parameter. The following operation returns all the documents from the collection products where qty is greater than 25: db.products.find( { qty: { $gt: 25 } } ) Query for Equality The following operation returns documents in the bios collection where _id equals 5: db.bios.find( { _id: 5 } ) Query Using Operators The following operation returns documents in the bios collection where _id equals either 5 or ObjectId("507c35dd8fada716c89d0013"): db.bios.find( { _id: { $in: [ 5, ObjectId("507c35dd8fada716c89d0013") ] } } ) Query for Ranges Combine comparison operators to specify ranges. The following operation returns documents with field between value1 and value2: db.collection.find( { field: { $gt: value1, $lt: value2 } } ); Query a Field that Contains an Array If a field contains an array and your query has multiple conditional operators, the field as a whole will match if either a single array element meets the conditions or a combination of array elements meet the conditions. Given a collection students that contains the following documents: { "_id" : 1, "score" : [ -1, 3 ] } { "_id" : 2, "score" : [ 1, 5 ] } { "_id" : 3, "score" : [ 5, 5 ] } The following query: db.students.find( { score: { $gt: 0, $lt: 2 } } ) Matches the following documents: { "_id" : 1, "score" : [ -1, 3 ] } { "_id" : 2, "score" : [ 1, 5 ] } In the document with _id equal to 1, the score: [ -1, 3 ] meets the conditions because the element -1 meets the $lt: 2 condition and the element 3 meets the $gt: 0 condition. In the document with _id equal to 2, the score: [ 1, 5 ] meets the conditions because the element 1 meets both the $lt: 2 condition and the $gt: 0 condition. Query Arrays 34 Chapter 2. Interfaces Reference
    • 39. MongoDB Reference Manual, Release 2.6.4 Query for an Array Element The following operation returns documents in the bios collection where the array field contribs contains the element "UNIX": db.bios.find( { contribs: "UNIX" } ) Query an Array of Documents The following operation returns documents in the bios collection where awards array contains a subdocument element that contains the award field equal to "Turing Award" and the year field greater than 1980: db.bios.find( { awards: { $elemMatch: { award: "Turing Award", year: { $gt: 1980 } } } } ) Query Subdocuments Query Exact Matches on Subdocuments The following operation returns documents in the bios collection where the subdocument name is exactly { first: "Yukihiro", last: "Matsumoto" }, including the order: db.bios.find( { name: { first: "Yukihiro", last: "Matsumoto" } } ) The name field must match the sub-document exactly. The query does not match documents with the following name fields: { first: "Yukihiro", aka: "Matz", last: "Matsumoto" } { last: "Matsumoto", first: "Yukihiro" } Query Fields of a Subdocument The following operation returns documents in the bios collection where the subdocument name contains a field first with the value "Yukihiro" and a field last with the value "Matsumoto". The query uses dot notation to access fields in a subdocument: 2.1. mongo Shell Methods 35
    • 40. MongoDB Reference Manual, Release 2.6.4 db.bios.find( { "name.first": "Yukihiro", "name.last": "Matsumoto" } ) The query matches the document where the name field contains a subdocument with the field first with the value "Yukihiro" and a field last with the value "Matsumoto". For instance, the query would match documents with name fields that held either of the following values: { first: "Yukihiro", aka: "Matz", last: "Matsumoto" } { last: "Matsumoto", first: "Yukihiro" } Projections The projection parameter specifies which fields to return. The parameter contains either include or exclude specifications, not both, unless the exclude is for the _id field. Specify the Fields to Return The following operation returns all the documents from the products collection where qty is greater than 25 and returns only the _id, item and qty fields: db.products.find( { qty: { $gt: 25 } }, { item: 1, qty: 1 } ) The operation returns the following: { "_id" : 11, "item" : "pencil", "qty" : 50 } { "_id" : ObjectId("50634d86be4617f17bb159cd"), "item" : "bottle", "qty" : 30 } { "_id" : ObjectId("50634dbcbe4617f17bb159d0"), "item" : "paper", "qty" : 100 } The following operation finds all documents in the bios collection and returns only the name field, contribs field and _id field: db.bios.find( { }, { name: 1, contribs: 1 } ) Explicitly Excluded Fields The following operation queries the bios collection and returns all fields except the first field in the name subdocument and the birth field: db.bios.find( { contribs: 'OOP' }, { 'name.first': 0, birth: 0 } ) Explicitly Exclude the _id Field The following operation excludes the _id and qty fields from the result set: db.products.find( { qty: { $gt: 25 } }, { _id: 0, qty: 0 } ) The documents in the result set contain all fields except the _id and qty fields: 36 Chapter 2. Interfaces Reference
    View More