diff --git a/source/about.txt b/source/about.txt index 1f5a5bc8dc2..c8fb3e4a4cb 100644 --- a/source/about.txt +++ b/source/about.txt @@ -118,7 +118,7 @@ system shell: About the Documentation Process ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The MongoDB Manual uses `Sphinx `_, a +The MongoDB Manual uses `Sphinx `_, a sophisticated documentation engine built upon `Python Docutils `_. The original `reStructured Text `_ files, as well as all diff --git a/source/administration/production-notes.txt b/source/administration/production-notes.txt index df985de7e96..9d4f3a66b90 100644 --- a/source/administration/production-notes.txt +++ b/source/administration/production-notes.txt @@ -32,7 +32,7 @@ information, specifically: - :doc:`/tutorial/configure-windows-netsh-firewall` For Windows users, consider the `Windows Server Technet Article on TCP -Configuration `_ +Configuration `_ when deploying MongoDB on Windows. MongoDB on Linux @@ -279,7 +279,7 @@ other miscellaneous things such as replica set arbiters. BSON Document Size Limit ~~~~~~~~~~~~~~~~~~~~~~~~ -There is a :limit:`BSON Document Size` -- at the time of this writing +There is a :limit:`BSON Document Size` limit -- at the time of this writing 16MB per document. If you have large objects, use :doc:`GridFS ` instead. @@ -448,7 +448,7 @@ Additional Deployment Considerations - Check :doc:`ulimits ` settings. - Use SSD if available and economical. Spinning disks can work well - but SSDs capacity for random I/O operations work well with the update + but SSDs' capacity for random I/O operations work well with the update model of :program:`mongod`. See :ref:`production-nfs` for more info. - Ensure that clients keep reasonable pool sizes to avoid overloading diff --git a/source/aggregation.txt b/source/aggregation.txt index d428369ba75..728d5c1fff8 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -8,11 +8,12 @@ Aggregation In version 2.2, MongoDB introduced the :doc:`aggregation framework ` that provides a powerful and flexible set -of tools to use for many data aggregation tasks. If you're familiar with data aggregation in SQL, consider the -:doc:`/reference/sql-aggregation-comparison` document as an introduction to -some of the basic concepts in the aggregation framework. Consider the +of tools to use for many data aggregation tasks. If you're familiar with +data aggregation in SQL, consider the +:doc:`/reference/sql-aggregation-comparison` document as an introduction +to some of the basic concepts in the aggregation framework. Consider the full documentation of the aggregation framework and other data -aggregation tools for MongoDB here: +aggregation tools for MongoDB here: .. toctree:: :titlesonly: diff --git a/source/data-modeling.txt b/source/data-modeling.txt index 2e16acffb1f..177ba95e645 100644 --- a/source/data-modeling.txt +++ b/source/data-modeling.txt @@ -6,7 +6,7 @@ Data in MongoDB has a *flexible schema*. :term:`Collections ` do not enforce :term:`document` structure. Although you may be able to use different structures for a single data set in MongoDB, different data models may have significant impacts on MongoDB -and applications performance. Consider :doc:`/core/data-modeling` for +and application performance. Consider :doc:`/core/data-modeling` for a conceptual overview of data modeling problems in MongoDB, and the :ref:`data-modeling-patterns` documents for examples of different approaches to data models. @@ -22,7 +22,7 @@ Background /core/data-modeling -.. _data-modeling-patterns: +.. _data-modeling-patterns: Data Modeling Patterns ---------------------- diff --git a/source/faq/concurrency.txt b/source/faq/concurrency.txt index 4c0e9304145..138f086567b 100644 --- a/source/faq/concurrency.txt +++ b/source/faq/concurrency.txt @@ -83,7 +83,7 @@ Does a read or write operation ever yield the lock? .. versionadded:: 2.0 -A read and write operations will yield their locks if the +Read and write operations will yield their locks if the :program:`mongod` receives a :term:`page fault` *or* fetches data that is unlikely to be in memory. Yielding allows other operations that only need to access documents that are already in memory to complete @@ -131,7 +131,7 @@ of a :term:`replica set`, take the :program:`mongod` offline and let other members of the set service load while maintenance is in progress. The following administrative operations require an exclusive -(i.e. write) lock to a the database for extended periods: +(i.e. write) lock on the database for extended periods: - :method:`db.collection.ensureIndex()`, when issued *without* setting ``background`` to ``true``, @@ -214,12 +214,12 @@ allow reads while applying the write operations, and apply write operations in the order that they appear in the oplog. MongoDB can apply several writes in parallel on replica set -secondaries, in a two phases: +secondaries, in two phases: 1. During the first *prefer* phase, under a read lock, the :program:`mongod` ensures that all documents affected by the operations are in memory. During this phase, other clients may - execute queries against this number. + execute queries against this member. 2. A thread pool using write locks applies all write operations in the batch as part of a coordinated write phase. diff --git a/source/faq/developers.txt b/source/faq/developers.txt index bc38aa839b9..a4dba11fb30 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -32,9 +32,9 @@ single set of data files. For an example ``acme.users`` namespace, ``acme`` is the database name and ``users`` is the collection name. Period characters **can** -occur in collection names, so that the ``acme.user.history`` is a -valid namespace, with the ``acme`` database name, and the -``user.history`` collection name. +occur in collection names, so that ``acme.user.history`` is a +valid namespace, with ``acme`` as the database name, and +``user.history`` as the collection name. While data models like this appear to support nested collections, the collection namespace is flat, and there is no difference from the @@ -54,7 +54,7 @@ duplicate the entire collection: .. note:: Because this process decodes :term:`BSON` documents to :term:`JSON` - during the copy procedure, documents you may incur a loss of + during the copy procedure, documents may incur a loss of type-fidelity. Consider using :program:`mongodump` and :program:`mongorestore` to @@ -68,8 +68,8 @@ If you remove a document, does MongoDB remove it from disk? Yes. -When you use :method:`db.collection.remove()`, the object will no longer exist in -MongoDB's on-disk data storage. +When you use :method:`db.collection.remove()`, the object will no longer +exist in MongoDB's on-disk data storage. When does MongoDB write updates to disk? ---------------------------------------- @@ -119,7 +119,7 @@ framework `," with the :dbcommand:`aggregate` command. MongoDB also supports :term:`map-reduce` with the -:dbcommand:`mapReduce`, as well as basic aggregation with the +:dbcommand:`mapReduce` command, as well as basic aggregation with the :dbcommand:`group`, :dbcommand:`count`, and :dbcommand:`distinct`. commands. @@ -155,7 +155,7 @@ Why are MongoDB's data files so large? MongoDB aggressively preallocates data files to reserve space and avoid file system fragmentation. You can use the :setting:`smallfiles` -flag to modify the file preallocation strategy. +setting to modify the file preallocation strategy. .. seealso:: :ref:`faq-disk-size` @@ -188,7 +188,7 @@ storage utilization for these collections: You can store any value in the ``_id`` field, but because this value serves as a primary key for documents in the collection, it must uniquely identify them. If the field's value is not unique, then it - cannot serve as a primary key as there would be collisions in + cannot serve as a primary key as there would be collisions in the collection. - Use shorter field names. @@ -271,8 +271,9 @@ How does MongoDB address SQL or Query injection? BSON ~~~~ -As a client program assembles a query in MongoDB, it builds a BSON object, not a string. Thus -traditional SQL injection attacks are not a problem. More details and some nuances are covered below. +As a client program assembles a query in MongoDB, it builds a BSON +object, not a string. Thus traditional SQL injection attacks are not a +problem. More details and some nuances are covered below. MongoDB represents queries as :term:`BSON` objects. Typically :doc:`client libraries ` provide a convenient, @@ -298,7 +299,7 @@ JavaScript .. include:: /includes/fact-disable-javascript-with-noscript.rst All of the following MongoDB operations permit you to run arbitrary JavaScript -expressions directly on the server:- :operator:`$where`: +expressions directly on the server: - :operator:`$where` - :method:`db.eval()` @@ -337,7 +338,7 @@ JavaScript code to the :operator:`$where` field. Dollar Sign Operator Escaping ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Field names in MongoDB's query language have a semantic. The +Field names in MongoDB's query language have semantic meaning. The dollar sign (i.e ``$``) is a reserved character used to represent :doc:`operators ` (i.e. :operator:`$inc`.) Thus, you should ensure that your application's users cannot inject operators @@ -553,8 +554,8 @@ driver <>`. db.getCollection("_foo").insert( { a : 1 } ) - To perform a query, use the :method:`find() ` - find method, in as the following: + To perform a query, use the :method:`~db.collection.find()` + method, in as the following: .. code-block:: javascript diff --git a/source/faq/diagnostics.txt b/source/faq/diagnostics.txt index 0541c551b77..0ff5a7f84c0 100644 --- a/source/faq/diagnostics.txt +++ b/source/faq/diagnostics.txt @@ -97,7 +97,7 @@ Do I need to configure swap space? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Always configure systems to have swap space. Without swap, your system -may not be reliant in some situations with extreme memory constrains, +may not be reliant in some situations with extreme memory constraints, memory leaks, or multiple programs using the same memory. Think of the swap space as something like a steam release valve that allows the system to release extra pressure without affecting the overall diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt index 70f3e630610..45bda1f545b 100644 --- a/source/faq/fundamentals.txt +++ b/source/faq/fundamentals.txt @@ -63,7 +63,7 @@ of the documents in the collection. You can change the structure of documents simply by adding new fields or deleting existing ones. Documents in a collection need not have an identical set of fields. -In practice, it is common for a the documents in a collection to have +In practice, it is common for the documents in a collection to have a largely homogeneous structure; however, this is not a requirement. MongoDB's flexible schemas mean that schema migration and augmentation are very easy in practice, and you will rarely, if ever, @@ -73,13 +73,13 @@ MongoDB. .. see:: :doc:`/reference/sql-comparison` -What languages can I use to work with the MongoDB? --------------------------------------------------- +What languages can I use to work with MongoDB? +---------------------------------------------- MongoDB :term:`client drivers ` exist for all of the most popular programming languages, and many -of the less popular ones. See the `latest list of -drivers `_ +other ones. See the :ecosystem:`latest list of +drivers `_ for details. .. seealso:: ":doc:`/applications/drivers`." @@ -125,7 +125,7 @@ writes with a write concern of ``{j: true}`` to ensure that the writes block until the journal has synced to disk. Users have built successful e-commerce systems using MongoDB, -but application requiring multi-object commit with rollback +but applications requiring multi-object commits with rollback generally aren't feasible. Does MongoDB require a lot of RAM? @@ -211,7 +211,8 @@ drivers use C extensions for better performance. What are the limitations of 32-bit versions of MongoDB? ------------------------------------------------------- -MongoDB uses :ref:`memory-mapped files `. When running a 32-bit build of +MongoDB uses :ref:`memory-mapped files `. +When running a 32-bit build of MongoDB, the total storage size for the server, including data and indexes, is 2 gigabytes. For this reason, do not deploy MongoDB to production on 32-bit machines. diff --git a/source/faq/mongo.txt b/source/faq/mongo.txt index 5e692879f97..a2217721f8c 100644 --- a/source/faq/mongo.txt +++ b/source/faq/mongo.txt @@ -15,7 +15,7 @@ How can I enter multi-line operations in the ``mongo`` shell? If you end a line with an open parenthesis (``'('``), an open brace (``'{'``), or an open bracket (``'['``), then the subsequent lines start -with ellipsis (``"..."``) until the you enter the corresponding closing +with ellipsis (``"..."``) until you enter the corresponding closing parenthesis (``')'``), the closing brace (``'}'``) or the closing bracket (``']'``). The :program:`mongo` shell waits for the closing parenthesis, closing brace, or the closing bracket before evaluating @@ -26,7 +26,7 @@ the code, as in the following example: > if ( x > 0 ) { ... count++; ... print (x); - ... } + ... } You can exit the line continuation mode if you enter two blank lines, as in the following example: @@ -34,14 +34,14 @@ lines, as in the following example: .. code-block:: javascript > if (x > 0 - ... - ... - > + ... + ... + > .. _mongo-shell-getSiblingDB: -How can I access to different databases temporarily? ----------------------------------------------------- +How can I access different databases temporarily? +------------------------------------------------- You can use :method:`db.getSiblingDB()` method to access another database without switching databases, as in the following example which @@ -70,7 +70,7 @@ The :program:`mongo` shell supports keyboard shortcuts. For example, complete the method name starting with the letter ``'c'``: .. code-block:: javascript - + db.myCollection.c Because there are many collection methods starting with the letter @@ -95,28 +95,28 @@ a string, consider the following examples: .. code-block:: javascript - var host = db.serverStatus().host; + var host = db.serverStatus().host; var prompt = function() { return db+"@"+host+"> "; } The :program:`mongo` shell prompt should now reflect the new prompt: .. code-block:: none - test@my-machine.local> + test@my-machine.local> - Set the shell prompt to display the database statistics: .. code-block:: javascript - var prompt = function() { - return "Uptime:"+db.serverStatus().uptime+" Documents:"+db.stats().objects+" > "; + var prompt = function() { + return "Uptime:"+db.serverStatus().uptime+" Documents:"+db.stats().objects+" > "; } The :program:`mongo` shell prompt should now reflect the new prompt: .. code-block:: none - Uptime:1052 Documents:25024787 > + Uptime:1052 Documents:25024787 > You can add the logic for the prompt in the :ref:`.mongorc.js ` file to set the prompt each time you start up the @@ -135,8 +135,8 @@ edit with the specified editor by typing ``edit `` or ``edit #. Set the :envvar:`EDITOR` variable from the command line prompt: - .. code-block:: javascript - + .. code-block:: sh + EDITOR=vim #. Start the :program:`mongo` shell: @@ -148,28 +148,28 @@ edit with the specified editor by typing ``edit `` or ``edit #. Define a function ``myFunction``: .. code-block:: javascript - + function myFunction () { } #. Edit the function using your editor: .. code-block:: javascript - + edit myFunction - + The command should open the ``vim`` edit session. Remember to save your changes. #. Type ``myFunction`` to see the function definition: .. code-block:: javascript - + myFunction - + The result should be the changes from your saved edit: - + .. code-block:: javascript - + function myFunction() { print("This was edited"); } diff --git a/source/faq/replica-sets.txt b/source/faq/replica-sets.txt index a4f9d1c9d92..041c475fb5b 100644 --- a/source/faq/replica-sets.txt +++ b/source/faq/replica-sets.txt @@ -29,7 +29,7 @@ What do the terms "primary" and "master" mean? that can accept writes. MongoDB's replication is "single-master:" only one node can accept write operations at a time. -In a replica set, if a the current "primary" node fails or becomes +In a replica set, if the current "primary" node fails or becomes inaccessible, the other members can autonomously :term:`elect ` one of the other members of the set to be the new "primary". @@ -88,11 +88,11 @@ Yes, but not without connection failures and the obvious latency. Members of the set will attempt to reconnect to the other members of the set in response to networking flaps. This does not require administrator intervention. However, if the network connections -between the nodes in the replica set are very slow, it might not be +among the nodes in the replica set are very slow, it might not be possible for the members of the node to keep up with the replication. If the TCP connection between the secondaries and the :term:`primary` -instance breaks, a :term:`replica set` the set will automatically +instance breaks, a :term:`replica set` will automatically elect one of the :term:`secondary` members of the set as primary. What is the preferred replication method: master/slave or replica sets? @@ -158,7 +158,7 @@ for :term:`primary` but do not replicate the data like :term:`secondary` members. :term:`Replica sets ` require a majority of the -original nodes present to elect a primary. Arbiters allow you +remaining nodes present to elect a primary. Arbiters allow you to construct this majority without the overhead of adding replicating nodes to the system. diff --git a/source/faq/sharding.txt b/source/faq/sharding.txt index 67df2c92be9..2dc01d5f83f 100644 --- a/source/faq/sharding.txt +++ b/source/faq/sharding.txt @@ -166,7 +166,7 @@ collection. Until you have configured the shard key, MongoDB will not create :term:`chunks `, and :term:`sharding` will not occur. Next, keep in mind that the default chunk size is 64 MB. As a result, -in most situations, the collection needs at least 64 MB before a +in most situations, the collection needs to have at least 64 MB of data before a migration will occur. Additionally, the system which balances chunks among the servers @@ -302,7 +302,7 @@ If the query includes multiple sub-expressions that reference the fields indexed by the shard key *and* the secondary index, the :program:`mongos` can route the queries to a specific shard and the shard will use the index that will allow it to fulfill most -efficiently. See `this document `_ +efficiently. See `this presentation `_ for more information. Can shard keys be randomly generated? diff --git a/source/faq/storage.txt b/source/faq/storage.txt index 124ee52a91a..afceb7979b6 100644 --- a/source/faq/storage.txt +++ b/source/faq/storage.txt @@ -24,7 +24,7 @@ A memory-mapped file is a file with data that the operating system places in memory by way of the ``mmap()`` system call. ``mmap()`` thus *maps* the file to a region of virtual memory. Memory-mapped files are the critical piece of the storage engine in MongoDB. By using memory -mapped files MongoDB can treat the content of its data files as if +mapped files MongoDB can treat the contents of its data files as if they were in memory. This provides MongoDB with an extremely fast and simple method for accessing and manipulating data. @@ -81,7 +81,7 @@ What tools can I use to investigate storage use in MongoDB? The :method:`db.stats()` method in the :program:`mongo` shell, returns the current state of the "active" database. The -:doc:`/reference/database-statistics` document outlines the meaning of +:doc:`/reference/database-statistics` document describes the fields in the :method:`db.stats()` output. What is the working set? @@ -119,7 +119,7 @@ inserted into the database. Consider the following possible causes: In the data directory, MongoDB preallocates data files to a particular size, in part to prevent file system - fragmentation. MongoDB names first data file ``.0``, + fragmentation. MongoDB names the first data file ``.0``, the next ``.1``, etc. The first file :program:`mongod` allocates is 64 megabytes, the next 128 megabytes, and so on, up to 2 gigabytes, at which point all subsequent files are 2 @@ -133,7 +133,7 @@ inserted into the database. Consider the following possible causes: the background prevents significant delays when a new database file is next allocated. - You can disable preallocation with :setting:`noprealloc` run time + You can disable preallocation with the :setting:`noprealloc` run time option. However :setting:`noprealloc` is **not** intended for use in production environments: only use :setting:`noprealloc` for testing and with small data sets where you frequently drop databases. @@ -151,7 +151,7 @@ inserted into the database. Consider the following possible causes: directory includes the :term:`oplog.rs ` file, which is a preallocated :term:`capped collection` in the ``local`` database. The default allocation is approximately 5% of disk space - on a 64-bit installations, see :ref:`Oplog Sizing + on 64-bit installations, see :ref:`Oplog Sizing ` for more information. In most cases, you should not need to resize the oplog. However, if you do, see :doc:`/tutorial/change-oplog-size`. @@ -229,7 +229,7 @@ following procedures in the :program:`mongo` shell: db.system.namespaces.find() -- Check the value of :data:`~collStats.indexSizes` value in the output of +- Check the value of :data:`~collStats.indexSizes` in the output of the :method:`db.collection.stats()` command. .. example:: Issue the following command to retrieve index namespaces: diff --git a/source/reference/config-database.txt b/source/reference/config-database.txt index 0c7a68bcec5..7189be40e45 100644 --- a/source/reference/config-database.txt +++ b/source/reference/config-database.txt @@ -22,7 +22,7 @@ documentation of sharded clusters. functioning system may lead to instability or inconsistent data sets. -To access a the ``config`` database, connect to a :program:`mongos` +To access the ``config`` database, connect to a :program:`mongos` instance in a sharded cluster, and use the following helper: .. code-block:: javascript diff --git a/source/reference/method/cursor.limit.txt b/source/reference/method/cursor.limit.txt index a7793585f59..2f0671eaaf2 100644 --- a/source/reference/method/cursor.limit.txt +++ b/source/reference/method/cursor.limit.txt @@ -7,7 +7,7 @@ cursor.limit() .. method:: cursor.limit() Use the :method:`cursor.limit()` method on a cursor to specify the maximum - number of documents a the cursor will return. :method:`cursor.limit()` is + number of documents the cursor will return. :method:`cursor.limit()` is analogous to the ``LIMIT`` statement in a SQL database. .. note:: diff --git a/source/tutorial/install-mongodb-on-debian.txt b/source/tutorial/install-mongodb-on-debian.txt index b5d17e3dc8b..bfcc5a68d50 100644 --- a/source/tutorial/install-mongodb-on-debian.txt +++ b/source/tutorial/install-mongodb-on-debian.txt @@ -66,7 +66,7 @@ sign packages with GPG keys. Issue the following command to import the sudo apt-key adv --keyserver keyserver.ubuntu.com --recv 7F0CEB10 -Create a the ``/etc/apt/sources.list.d/10gen.list`` file and include +Create the ``/etc/apt/sources.list.d/10gen.list`` file and include the following line for the 10gen repository. .. code-block:: sources.list diff --git a/source/tutorial/manage-sharded-cluster-balancer.txt b/source/tutorial/manage-sharded-cluster-balancer.txt index e97af3d6b2b..b37a70200f0 100644 --- a/source/tutorial/manage-sharded-cluster-balancer.txt +++ b/source/tutorial/manage-sharded-cluster-balancer.txt @@ -99,6 +99,10 @@ be able to migrate chunks: beginning and end boundaries of the balancing window. These times will be evaluated relative to the time zone of each individual :program:`mongos` instance in the sharded cluster. + If your :program:`mongos` instances are physically located in different + time zones, use a common time zone (e.g. GMT) to ensure that the + balancer window is interpreted correctly. + For instance, running the following will force the balancer to run between 11PM and 6AM local time only: diff --git a/source/tutorial/monitor-with-snmp.txt b/source/tutorial/monitor-with-snmp.txt index 25d43506bea..45bbb8409c7 100644 --- a/source/tutorial/monitor-with-snmp.txt +++ b/source/tutorial/monitor-with-snmp.txt @@ -196,7 +196,7 @@ SNMP: snmpwalk -m MONGO-MIB -v 2c -c mongodb 127.0.0.1:1161 1.3.6.1.4.1.37601 -You may also choose to specify a the path to the MIB file: +You may also choose to specify the path to the MIB file: .. code-block:: sh