diff --git a/.gitignore b/.gitignore index 537d36f4c74..55e5b6331cc 100644 --- a/.gitignore +++ b/.gitignore @@ -10,4 +10,6 @@ build/* source/includes/hash.rst source/includes/install-curl-release*.rst source/includes/table-*.rst +source/includes/manpage-options-auth-mongo.rst +source/includes/manpage-options-ssl-settings.rst TAGS diff --git a/bin/builder_data.py b/bin/builder_data.py index ba442438fd0..55f82d3e3d8 100644 --- a/bin/builder_data.py +++ b/bin/builder_data.py @@ -53,6 +53,7 @@ ('$(public-branch-output)/reference/mongo-shell-reference', 'mongo-shell', 'redirect'), ('$(public-branch-output)/reference/method/getShardDistribution', 'db.collection.getShardDistribution', 'redirect'), ('$(public-branch-output)/reference/method/getDB', 'Mongo.getDB', 'redirect'), + ('$(public-branch-output)/reference/operator/within', 'geoWithin', 'redirect'), ('$(public-branch-output)/reference/method/getShardVersion', 'db.collection.getShardVersion', 'redirect'), ('$(public-branch-output)/reference/command/whatsMyUri', 'whatsmyuri', 'redirect'), ('$(public-branch-output)/reference/command/writeBackListen', 'writebacklisten', 'redirect'), diff --git a/bin/fix-manpage-url b/bin/fix-manpage-url new file mode 100755 index 00000000000..1f4aaf0a30a --- /dev/null +++ b/bin/fix-manpage-url @@ -0,0 +1,20 @@ +#!/bin/sh + +countDirs () { + rval=`find source -type d | grep -v ".static" | grep -v "reference/" | wc -l` + echo $rval +} + +preFlightTest () { + if [ `countDirs` -eq 12 ]; then + return 1 + fi +} + +if (preFlightTest); then + echo "[error]: man page URL munging incorrect. Fix bin/makefile.manpages." + exit 1 +else + sed $1 's^(\\fB(/administration.*|/tutorial.*|/reference.*|/core.*|/replication.*|/sharding.*|/faq.*|/meta.*)\\fP)^http://docs.mongodb.org/manual\2^g' $2 + echo [man]: fixed urls in $2 manpage. +fi diff --git a/bin/makefile-builder/releases.py b/bin/makefile-builder/releases.py index a8095306589..7ba4e0221a3 100644 --- a/bin/makefile-builder/releases.py +++ b/bin/makefile-builder/releases.py @@ -55,9 +55,9 @@ def makefile_restat(builder, dependency): m.append_var(variable='installation-guides', value=target, block='guide') m.target(target=target, dependency=dependency, block='guide') - if builder == 'source/tutorial/install-mongodb-subscriber-edition.txt': - pass - else: + if builder == 'source/tutorial/install-mongodb-subscriber-edition.txt': + pass + else: m.job('touch $@', block='guide') m.msg('[build]: touched $@ to ensure a clean build.', block='guide') diff --git a/bin/makefile-builder/sphinx.py b/bin/makefile-builder/sphinx.py index 6fb0917f28c..9ce762259d5 100644 --- a/bin/makefile-builder/sphinx.py +++ b/bin/makefile-builder/sphinx.py @@ -51,7 +51,7 @@ def make_all_sphinx(sphinx): block='vars') m.section_break('sphinx prerequisites') - m.target('sphinx-prerequisites', 'setup installation-guides tables intersphinx', block='prereq') + m.target('sphinx-prerequisites', 'setup installation-guides tables intersphinx generate-manpages', block='prereq') m.msg('[build]: completed $@ buildstep.', block='prereq') m.section_break('sphinx targets', block='sphinx') diff --git a/bin/makefile.manpages b/bin/makefile.manpages new file mode 100644 index 00000000000..5eacd6ae353 --- /dev/null +++ b/bin/makefile.manpages @@ -0,0 +1,34 @@ +# man page support, uses sphinx `man` builder output. +manpages := $(wildcard $(branch-output)/man/*.1) +compressed-manpages := $(subst .1,.1.gz,$(manpages)) +manpages:$(manpages) $(branch-output)/manpages.tar.gz +compressed-manpages:$(compressed-manpages) +$(compressed-manpages):$(manpages) +$(manpages):man + @bin/fix-manpage-url "$(SED_ARGS_FILE)" $@ +$(branch-output)/man/%.1.gz: $(branch-output)/man/%.1 + @gzip $< -c > $@ + @echo [man]: compressing $< -- $@ +$(branch-output)/manpages.tar.gz:man + @touch $@.log + @$(TARBIN) -C $(branch-output)/ --transform=s/man/mongodb-manpages/ \ + -czvf $@ $(subst $(branch-output)/,,$(manpages)) >> $@.log + @echo [man]: created $@ archive of all manpages + +$(rst-include)/manpage-options-auth-mongo.rst:$(rst-include)/manpage-options-auth.rst + @cp $< $@ + @sed $(SED_ARGS_FILE) -e 's/fact-authentication-source-tool/fact-authentication-source-mongo/' $@ + @-git update-index --assume-unchanged + @echo "[generator]: generated the '$@' file." +manpage-auto += $(rst-include)/manpage-options-auth-mongo.rst + +$(rst-include)/manpage-options-ssl-settings.rst:$(rst-include)/manpage-options-ssl.rst + @cp $< $@ + @sed $(SED_ARGS_FILE) -e 's/\.\. option:: --/.. setting:: /' \ + -e 's/setting:: (.*) .*/setting:: \1/' \ + -e 's/:option:`--/:setting:`/g' $@ + @echo "[generator]: generated the '$@' file." +manpage-auto += $(rst-include)/manpage-options-ssl-settings.rst + +generate-manpages:$(manpage-auto) +.PHONY:$(manpages) $(manpage-auto) generate-manpages diff --git a/conf.py b/conf.py index d33db2306f5..986211908da 100644 --- a/conf.py +++ b/conf.py @@ -48,6 +48,7 @@ rst_epilog = ('.. |branch| replace:: ``' + meta['branch'] + '``' + BREAK + '.. |copy| unicode:: U+000A9' + BREAK + '.. |year| replace:: ' + meta['date'] + BREAK + + '.. |ent-build| replace:: the MongoDB Subscriber Edition' + BREAK + '.. |hardlink| replace:: http://docs.mongodb.org/' + meta['branch']) pygments_style = 'sphinx' @@ -179,7 +180,7 @@ ('reference/mongostat', 'mongostat', u'MongoDB', [u'MongoDB Documentation Project'], 1), ('reference/mongosniff', 'mongosniff', u'MongoDB', [u'MongoDB Documentation Project'], 1), ('reference/mongotop', 'mongotop', u'MongoDB', [u'MongoDB Documentation Project'], 1), - ('reference/configuration-options', 'mongodb-config', u'MongoDB', [u'MongoDB Documentation Project'], 1), + ('reference/mongoperf', 'mongoperf', u'MongoDB', [u'MongoDB Documentation Project'], 1), ] texinfo_documents = [ diff --git a/makefile b/makefile index 57191bc9f3f..35f9e9bb688 100644 --- a/makefile +++ b/makefile @@ -35,6 +35,7 @@ include bin/makefile.clean include bin/makefile.content include bin/makefile.tables include bin/makefile.push +include bin/makefile.manpages ############# Meta targets that control the build and publication process. ############# publish-if-up-to-date: @@ -109,22 +110,7 @@ $(branch-output)/latex/%.tex: ############# General purpose targets. Not used (directly) in the production build ############# tags: - @etags -I --language=none --regex=@bin/etags.regexp `find source -name "*.txt"` + @etags -I --language=none --regex=@bin/etags.regexp `find source -name "*.txt" | grep -v "\.#"` @echo "[dev]: etags generation complete." draft:draft-html draft-pdfs:draft-latex $(subst .tex,.pdf,$(wildcard $(branch-output)/draft-latex/*.tex)) -# man page support, uses sphinx `man` builder output. -.PHONY:$(manpages) -manpages := $(wildcard $(branch-output)/man/*.1) -compressed-manpages := $(subst .1,.1.gz,$(manpages)) -manpages:$(compressed-manpages) $(branch-output)/manpages.tar.gz -$(compressed-manpages):$(manpages) -$(manpages):man -$(branch-output)/man/%.1.gz: $(branch-output)/man/%.1 - @gzip $< -c > $@ - @echo [man]: compressing $< -- $@ -$(branch-output)/manpages.tar.gz:man - @touch $@.log - @$(TARBIN) -C $(branch-output)/ --transform=s/man/mongodb-manpages/ \ - -czvf $@ $(subst $(branch-output)/,,$(manpages)) >> $@.log - @echo [man]: created $@ archive of all manpages diff --git a/source/administration/production-notes.txt b/source/administration/production-notes.txt index 39386ed74c7..50a7ad11307 100644 --- a/source/administration/production-notes.txt +++ b/source/administration/production-notes.txt @@ -444,7 +444,7 @@ Additional Deployment Considerations - Check :doc:`ulimits ` settings. - Use SSD if available and economical. Spinning disks can work well - but SSDs capcity 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/administration/replica-sets.txt b/source/administration/replica-sets.txt index 066d23f5533..0f5ebf701f7 100644 --- a/source/administration/replica-sets.txt +++ b/source/administration/replica-sets.txt @@ -128,12 +128,13 @@ This reconfigures the set, with the following priority settings: .. note:: - The current :term:`primary` cannot be assigned a - :data:`~local.system.replset.members[n].priority` of 0. - If you want to prevent the current primary from being elected - primary again, you must demote it using - :method:`rs.stepDown()` and then set the appropriate priority - with the :method:`rs.reconfig()` method. + MongoDB does not permit the current :term:`primary` to have a + :data:`~local.system.replset.members[n].priority` of ``0``. If you + want to prevent the current primary from becoming primary, first + use :method:`rs.stepDown()` to step down the current primary, and + then :ref:`reconfigure the replica set + ` with :method:`rs.conf()` and + :method:`rs.reconfig()`. .. seealso:: :data:`~local.system.replset.members[n].priority` and :ref:`Replica Set Reconfiguration `. diff --git a/source/administration/sharded-clusters.txt b/source/administration/sharded-clusters.txt index 3d4126360e5..9dc9764219c 100644 --- a/source/administration/sharded-clusters.txt +++ b/source/administration/sharded-clusters.txt @@ -338,7 +338,7 @@ privileges: - Normal administrative privileges, which provide read-and-write access to the admin database and access to all administrative - commands, and which provide read-and-write accees to all other + commands, and which provide read-and-write access to all other databases on that shard. - Read-only administrative privileges, which provide read-only access diff --git a/source/administration/snmp.txt b/source/administration/snmp.txt index 0ab93b80ae1..dc11b35432d 100644 --- a/source/administration/snmp.txt +++ b/source/administration/snmp.txt @@ -202,7 +202,7 @@ You may also choose to specify a the path to the MIB file: .. code-block:: sh - nmpwalk -m /usr/share/snmp/mibs/MONGO-MIB -v 2c -c mongodb 127.0.0.1:1161 1.3.6.1.4.1.37601 + snmpwalk -m /usr/share/snmp/mibs/MONGO-MIB -v 2c -c mongodb 127.0.0.1:1161 1.3.6.1.4.1.37601 Use this command *only* to ensure that you can retrieve and validate SNMP data from MongoDB. diff --git a/source/applications/2d-indexes.txt b/source/applications/2d-indexes.txt new file mode 100644 index 00000000000..e80c87802bf --- /dev/null +++ b/source/applications/2d-indexes.txt @@ -0,0 +1,309 @@ +========== +2d Indexes +========== + +.. default-domain:: mongodb + +Use a 2d index for data stored as points on a two-dimensional plane. To +use a 2d index, format location data as arrays or documents consisting +of two grid coordinates. Do not use a 2d index for data stored as +GeoJSON objects. + +A 2d index allows calculations using planar (flat) geometry. + +A compound 2d index can reference multiple fields. The first indexed +field must be the location field, which means a 2d compound index +constructs queries that select first on the location field and second on +the additional criteria. If the location criteria selects a large number +of documents, the additional criteria will only filter the result set +and *not* result in a more targeted query. + +MongoDB allows one 2d index per collection. + +This index also supports the :operator:`$nearSphere` and +:operator:`$centerSphere` operators when computing ranges on a spherical +globe. Though for full spherical functionality, store data in GeoJSON +and use the ``2dsphere`` index type. + +.. _geospatial-indexes-store-grid-coordinates: + +Store Points on a 2D Plane +-------------------------- + +To store location data as grid coordinates on a two-dimensional plane, +use either an array (preferred): + +.. code-block:: javascript + + loc : [ , ] + +Or an embedded document: + +.. code-block:: javascript + + loc : { long : , lat : } + +Arrays are preferred as certain languages do not guarantee associative +map ordering. + +If you use longitude and latitude, store coordinates in this order: +**longitude, latitude**. + +.. _geospatial-create-2d-index: + +Create a 2d Index +----------------- + +To build a geospatial 2d index, use the :method:`ensureIndex() +` method and specify ``2d``. Use the +following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2d" , : } , + { } ) + +The ``2d`` index uses the following optional index-specification +options, described in this document: + +.. code-block:: javascript + + { min : , max : , + bits : } + +To create a geospatial index for points on a two-dimensional plane, use +the :method:`ensureIndex ` method and set +the value of the location field for your collection to ``2d``. Use the +following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2d" } ) + +.. _geospatial-indexes-range: + +Define Location Range for a 2d Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, a 2d index assumes longitude and latitude and has boundaries +of -180 inclusive and 180 non-inclusive (i.e. ``[-180, 180)``). If +documents contain coordinate data outside of the specified range, +MongoDB returns an error and rejects the documents. + +.. important:: The default boundaries allow applications to insert + documents with invalid latitudes greater than 90 or less than -90. + The behavior of geospatial queries with such invalid points is not + defined. + +On ``2d`` indexes you can change the location range. + +You can build a ``2d`` geospatial index with a location range other than +the default. Use the ``min`` and ``max`` options when creating the +index. Use the following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2d" } , + { min : , max : } ) + +.. _geospatial-indexes-precision: + +Define Location Precision for a 2d Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, geospatial index on grid coordinates uses 26 bits of +precision, which is roughly equivalent to 2 feet or 60 centimeters of +precision using the default range of -180 to 180. Precision is measured +by the size in bits of the :term:`geohash` values used to store location +data. You can configure geospatial indexes with up to 32 bits of +precision. + +Index precision does not affect query accuracy. The actual grid coordinates +are always used in the final query processing. Advantages to lower +precision are a lower processing overhead for insert operations and use +of less space. An advantage to higher precision is that queries scan +smaller portions of the index to return results. + +To configure a location precision other than the default, use the +``bits`` option when creating the index. Use following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : ""} , + { bits : } ) + +For information on the internals of geohash values, see +:ref:`geospatial-indexes-geohash`. + +Query a 2d Index +---------------- + +The following sections describe queries supported by the 2d index. +For an overview of recommended geospatial queries, see +:doc:`/applications/geospatial-preferred-queries`. + +Points within a Shape Defined on a Flat Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all grid coordinates found within a given shape on a flat +surface, use the :operator:`$geoWithin` operator along with a shape +operator. Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $box|$polygon|$center : + } } } ) + +The following queries for documents within a rectangle defined by ``[ 0 +, 0 ]`` at the bottom left corner and by ``[ 100 , 100 ]`` at the top +right corner. + +.. code-block:: javascript + + db.places.find( { loc : { $geoWithin : { $box : + [ [ 0 , 0 ] , + [ 100 , 100 ] ] } } } ) + +The following queries for documents that within the circle centered on +``[ -74 , 40.74 ]`` and with a radius of ``10``: + +.. code-block:: javascript + + db.places.find( { loc: { $geoWithin : + { $center : [ [-74, 40.74], 10 ] } + } } ) + +For syntax and examples for each shape, see the following: + + - :operator:`$box` + + - :operator:`$polygon` + + - :operator:`$center` (defines a circle) + +Points within a Circle Defined on a Sphere +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all grid coordinates in a "spherical cap" on a sphere, use +:operator:`$geoWithin` with the :operator:`$centerSphere` operator. +Specify an array that contains: + +- The grid coordinates of the circle's center point + +- The circle's radius measured in radians. To calculate radians, see + :doc:`/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes`. + +Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $centerSphere : [ [ , ] , ] } + } } ) + +The following example queries grid coordinates and returns all +documents within a 10 mile radius of longitude ``88 W`` and latitude +``30 N``. MongoDB converts the distance, 10 miles, to radians by +dividing by the approximate radius of the earth, 3959 miles: + +.. code-block:: javascript + + db.collection.find( { loc : { $geoWithin : + { $centerSphere : + [ [ 88 , 30 ] , 10 / 3959 ] + } } } ) + +Proximity to a Point on a Flat Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Proximity queries return the 100 points closest to the defined point and +sorts the results by distance. Proximity queries for points on a +two-dimensional plane require a 2d index. + +To query for proximity on data defined as grid coordinates on a flat +surface, use either the :operator:`$near` operator or +:dbcommand:`geoNear` command. + +The :operator:`$near` uses the following syntax: + +.. code-block:: javascript + + db..find( { : + { $near : [ , ] + } } ) + +For examples, see :operator:`$near`. + +The :dbcommand:`geoNear` command returns more information than does +:operator:`$near`. + +.. _geospatial-indexes-proximity-geonear: +.. _geospatial-indexes-geonear: + +``geoNear`` Syntax and Results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :dbcommand:`geoNear` command uses the following syntax: + +.. code-block:: javascript + + db.runCommand( { geoNear: , near: [ , ] } ) + +The :dbcommand:`geoNear` command offers more options than does the +:operator:`$near` operator. For the options, see :dbcommand:`geoNear`. + +The :dbcommand:`geoNear` command returns more information than does +:operator:`$near`. For a :operator:`$near` query that returns this: + +.. code-block:: javascript + + { "_id" : ObjectId(" ... "), "loc" : [ -73, 39 ] } + +The equivalent :dbcommand:`geoNear` command returns the following: + + .. code-block:: javascript + + { + "ns" : "test.places", + "results" : [ + { + "dis" : 3, + "obj" : { + "_id" : ObjectId(" ... "), + "loc" : [ + -73, + 39 + ] + } + } + ], + "stats" : { + "time" : 2, + "btreelocs" : 0, + "nscanned" : 1, + "objectsLoaded" : 1, + "avgDistance" : 3, + "maxDistance" : 3.0000188685220253 + }, + "near" : "0110000111111000000111111000000111111000000111111000", + "ok" : 1 + } + +.. index:: geospatial queries +.. index:: geospatial queries; exact +.. _geospatial-indexes-exact-match: + +Exact Matches on a Flat Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use the :method:`db.collection.find()` method to query for an +exact match on a location. These queries have the following form: + +.. code-block:: javascript + + db.collection.find( { : [ , ] } ) + +This query will return any documents with the value of ``[ , ]``. diff --git a/source/applications/2d.txt b/source/applications/2d.txt new file mode 100644 index 00000000000..39ef194229d --- /dev/null +++ b/source/applications/2d.txt @@ -0,0 +1,309 @@ +========== +2d Indexes +========== + +.. default-domain:: mongodb + +Use a 2d index for data stored as points on a two-dimensional plane. To +use a 2d index, format location data as arrays or documents consisting +of two grid coordinates. Do not use a 2d index for data stored as +GeoJSON objects. + +A 2d index allows calculations using planar (flat) geometry. + +A compound 2d index can reference multiple fields. The first indexed +field must be the location field, which means a 2d compound index +constructs queries that select first on the location field and second on +the additional criteria. If the location criteria selects a large number +of documents, the additional criteria will only filter the result set +and *not* result in a more targeted query. + +MongoDB allows one 2d index per collection. + +This index also supports the :operator:`$nearSphere` and +:operator:`$centerSphere` operators when computing ranges on a spherical +globe. Though for full spherical functionality, store data in GeoJSON +and use the ``2dsphere`` index type. + +.. _geospatial-indexes-store-grid-coordinates: + +Store Points on a 2D Plane +-------------------------- + +To store location data as grid coordinates on a two-dimensional plane, +use either an array (preferred): + +.. code-block:: javascript + + loc : [ , ] + +Or an embedded document: + +.. code-block:: javascript + + loc : { long : , lat : } + +Arrays are preferred as certain languages do not guarantee associative +map ordering. + +If you use longitude and latitude, store coordinates in this order: +**longitude, latitude**. + +.. _geospatial-create-2d-index: + +Create a 2d Index +----------------- + +To build a geospatial 2d index, use the :method:`ensureIndex() +` method and specify ``2d``. Use the +following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2d" , : } , + { } ) + +The ``2d`` index uses the following optional index-specification +options, described in this document: + +.. code-block:: javascript + + { min : , max : , + bits : } + +To create a geospatial index for points on a two-dimensional plane, use +the :method:`ensureIndex ` method and set +the value of the location field for your collection to ``2d``. Use the +following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2d" } ) + +.. _geospatial-indexes-range: + +Define Location Range for a 2d Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, a 2d index assumes longitude and latitude and has boundaries +of -180 inclusive and 180 non-inclusive (i.e. ``[-180, 180)``). If +documents contain coordinate data outside of the specified range, +MongoDB returns an error and rejects the documents. + +.. important:: The default boundaries allow applications to insert + documents with invalid latitudes greater than 90 or less than -90. + The behavior of geospatial queries with such invalid points is not + defined. + +On ``2d`` indexes you can change the location range. + +You can build a ``2d`` geospatial index with a location range other than +the default. Use the ``min`` and ``max`` options when creating the +index. Use the following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2d" } , + { min : , max : } ) + +.. _geospatial-indexes-precision: + +Define Location Precision for a 2d Index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, geospatial index on grid coordinates uses 26 bits of +precision, which is roughly equivalent to 2 feet or 60 centimeters of +precision using the default range of -180 to 180. Precision is measured +by the size in bits of the :term:`geohash` values used to store location +data. You can configure geospatial indexes with up to 32 bits of +precision. + +Index precision does not affect query accuracy. The actual grid coordinates +are always used in the final query processing. Advantages to lower +precision are a lower processing overhead for insert operations and use +of less space. An advantage to higher precision is that queries scan +smaller portions of the index to return results. + +To configure a location precision other than the default, use the +``bits`` option when creating the index. Use following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : ""} , + { bits : } ) + +For information on the internals of geohash values, see +:ref:`geospatial-indexes-geohash`. + +Query a 2d Index +---------------- + +The following sections describe queries supported by the 2d index. +For an overview of recommended geospatial queries, see +:doc:`/reference/geospatial-queries`. + +Points within a Shape Defined on a Flat Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all grid coordinates found within a given shape on a flat +surface, use the :operator:`$geoWithin` operator along with a shape +operator. Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $box|$polygon|$center : + } } } ) + +The following queries for documents within a rectangle defined by ``[ 0 +, 0 ]`` at the bottom left corner and by ``[ 100 , 100 ]`` at the top +right corner. + +.. code-block:: javascript + + db.places.find( { loc : { $geoWithin : { $box : + [ [ 0 , 0 ] , + [ 100 , 100 ] ] } } } ) + +The following queries for documents that within the circle centered on +``[ -74 , 40.74 ]`` and with a radius of ``10``: + +.. code-block:: javascript + + db.places.find( { loc: { $geoWithin : + { $center : [ [-74, 40.74], 10 ] } + } } ) + +For syntax and examples for each shape, see the following: + + - :operator:`$box` + + - :operator:`$polygon` + + - :operator:`$center` (defines a circle) + +Points within a Circle Defined on a Sphere +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all grid coordinates in a "spherical cap" on a sphere, use +:operator:`$geoWithin` with the :operator:`$centerSphere` operator. +Specify an array that contains: + +- The grid coordinates of the circle's center point + +- The circle's radius measured in radians. To calculate radians, see + :doc:`/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes`. + +Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $centerSphere : [ [ , ] , ] } + } } ) + +The following example queries grid coordinates and returns all +documents within a 10 mile radius of longitude ``88 W`` and latitude +``30 N``. MongoDB converts the distance, 10 miles, to radians by +dividing by the approximate radius of the earth, 3959 miles: + +.. code-block:: javascript + + db.collection.find( { loc : { $geoWithin : + { $centerSphere : + [ [ 88 , 30 ] , 10 / 3959 ] + } } } ) + +Proximity to a Point on a Flat Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Proximity queries return the 100 points closest to the defined point and +sorts the results by distance. Proximity queries for points on a +two-dimensional plane require a 2d index. + +To query for proximity on data defined as grid coordinates on a flat +surface, use either the :operator:`$near` operator or +:dbcommand:`geoNear` command. + +The :operator:`$near` uses the following syntax: + +.. code-block:: javascript + + db..find( { : + { $near : [ , ] + } } ) + +For examples, see :operator:`$near`. + +The :dbcommand:`geoNear` command returns more information than does +:operator:`$near`. + +.. _geospatial-indexes-proximity-geonear: +.. _geospatial-indexes-geonear: + +``geoNear`` Syntax and Results +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :dbcommand:`geoNear` command uses the following syntax: + +.. code-block:: javascript + + db.runCommand( { geoNear: , near: [ , ] } ) + +The :dbcommand:`geoNear` command offers more options than does the +:operator:`$near` operator. For the options, see :dbcommand:`geoNear`. + +The :dbcommand:`geoNear` command returns more information than does +:operator:`$near`. For a :operator:`$near` query that returns this: + +.. code-block:: javascript + + { "_id" : ObjectId(" ... "), "loc" : [ -73, 39 ] } + +The equivalent :dbcommand:`geoNear` command returns the following: + + .. code-block:: javascript + + { + "ns" : "test.places", + "results" : [ + { + "dis" : 3, + "obj" : { + "_id" : ObjectId(" ... "), + "loc" : [ + -73, + 39 + ] + } + } + ], + "stats" : { + "time" : 2, + "btreelocs" : 0, + "nscanned" : 1, + "objectsLoaded" : 1, + "avgDistance" : 3, + "maxDistance" : 3.0000188685220253 + }, + "near" : "0110000111111000000111111000000111111000000111111000", + "ok" : 1 + } + +.. index:: geospatial queries +.. index:: geospatial queries; exact +.. _geospatial-indexes-exact-match: + +Exact Matches on a Flat Surface +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use the :method:`db.collection.find()` method to query for an +exact match on a location. These queries have the following form: + +.. code-block:: javascript + + db.collection.find( { : [ , ] } ) + +This query will return any documents with the value of ``[ , ]``. diff --git a/source/applications/2dsphere-indexes.txt b/source/applications/2dsphere-indexes.txt new file mode 100644 index 00000000000..45873ccd26d --- /dev/null +++ b/source/applications/2dsphere-indexes.txt @@ -0,0 +1,239 @@ +================ +2dsphere Indexes +================ + +.. default-domain:: mongodb + +.. versionadded:: 2.4 + +MongoDB's 2dsphere indexes support data stored in the `GeoJSON +`_-format. + +.. primary use case ??? + +2dsphere indexes store points, lines, and shapes, and calculate geometry +on a sphere. + +2dsphere indexes also support pre-MongoDB-2.4 data stored as points +(grid coordinates in an array or document) by converting the data to the +GeoJSON ``Point`` type. + +.. In what way are 2dsphere indexes compatible with 2.2 and earlier data + stored as points (grid coordinates) ??? + If you are upgrading and want to use 2dsphere ... ??? + +MongoDB allows one 2dsphere index per collection. + +A :ref:`compound ` 2dsphere index can reference +multiple location and non-location fields within a collection’s +documents. You can arrange the fields in any order. + +.. _geospatial-indexes-store-geojson: + +Store GeoJSON Objects +--------------------- + +.. versionadded:: 2.4 + +MongoDB supports the following `GeoJSON `_ objects: + + - ``Point`` + + - ``LineString`` + + - ``Polygon`` + +To store GeoJSON data, store coordinates in this order: +**longitude, latitude.** Use the following syntax: + +.. code-block:: javascript + + { : { type : "Point|LineString|Polygon" , + coordinates : } + +The following example stores a GeoJSON ``Point``: + +.. code-block:: javascript + + { loc : { type : "Point" , coordinates : [ 40, 5 ] } } + +The following example stores a GeoJSON ``LineString``: + +.. code-block:: javascript + + { loc : { type : "LineString" , coordinates : [ [ 40 , 5 ] , [ 41 , 6 ] ] } } + +The following example stores a GeoJSON ``Polygon`` with an exterior ring +and no interior rings (or holes): + +.. code-block:: javascript + + { loc : + { type : "Polygon" , + coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] + } } + +.. _geospatial-indexes-create-2dsphere: + +Create a 2dsphere Index +----------------------- + +To create a geospatial index for GeoJSON-formatted data, use the +:method:`ensureIndex ` method and set the +value of the location field for your collection to ``2dsphere``. A +2dsphere index can be a :ref:`compound index ` +and does not require the location field to be the first field indexed. + +To create the index use the following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2dsphere" } ) + +The following are four example commands for creating a 2dsphere index: + +.. code-block:: javascript + + db.collection.ensureIndex( { loc : "2dsphere" } ) + db.collection.ensureIndex( { loc : "2dsphere", type : 1 } ) + db.collection.ensureIndex( { type : 1, loc : "2dsphere" } ) + db.collection.ensureIndex( { loc : "2dsphere", type : 1, rating : -1 } ) + +The first example creates a simple geospatial index on the location +field ``loc``. The second example creates a compound index where the +second field contains non-location data. The third example creates an +index where the location field is not the primary field: the location +field does not have to be the first field in a 2dsphere index. The +fourth example creates a compound index with three fields: you can +include as many fields as you like in a 2dsphere index. + +Query a 2dsphere Index +---------------------- + +The following sections describe queries supported by the 2dsphere index. +For an overview of recommended geospatial queries, see +:doc:`/applications/geospatial-preferred-queries`. + +GeoJSON Objects Bounded by a Polygon +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all points and shapes found within a `GeoJSON +`_ polygon, your data must be +stored in GeoJSON format. Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $geometry : + { type : "Polygon" , + coordinates : [ ] + } } } } ) + +The following example selects all points and shapes that +exist entirely within a GeoJSON polygon: + +.. code-block:: javascript + + db.places.find( { loc : + { $geoWithin : + { $geometry : + { type : "Polygon" , + coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] + } } } } ) + +Intersections of GeoJSON Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.4 + +The :operator:`$geoIntersects` operator queries for location data that +intersects a `GeoJSON `_ object. +Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoIntersects : + { $geometry : + { type : "Point|LineString|Polygon" , + coordinates : [ ] + } } } } ) + +The following example uses :operator:`$geoIntersects` to select all +indexed points and shapes that intersect with the polygon defined by the +``coordinates`` array. + +.. code-block:: javascript + + db.places.find( { loc : + { $geoIntersects : + { $geometry : + { type : "Polygon" , + coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] } + } } } } ) + +The query returns true if the intersection between shapes is non-empty. +This includes documents that have a shared edge. + +Proximity to a GeoJSON Point +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Proximity queries return the 100 points closest to the defined point and +sorts the results by distance. A proximity query on GeoJSON data +requires a 2dsphere index. + +To query for proximity to a `GeoJSON +`_ point, use either the +:operator:`$near` operator or :dbcommand:`geoNear` command. Distance is +in meters. + +The :operator:`$near` uses the following syntax: + +.. code-block:: javascript + + db..find( { : + { $near : + { $geometry : + { type : "Point" , + coordinates : [ , ] } , + $maxDistance : + } } } ) + +For examples, see :operator:`$near`. + +The :dbcommand:`geoNear` command returns more information than does +:operator:`$near`. See :ref:`geospatial-indexes-geonear`. + +Points within a Circle Defined on a Sphere +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all grid coordinates in a "spherical cap" on a sphere, use +:operator:`$geoWithin` with the :operator:`$centerSphere` operator. +Specify an array that contains: + +- The grid coordinates of the circle's center point + +- The circle's radius measured in radians. To calculate radians, see + :doc:`/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes`. + +Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $centerSphere : [ [ , ] , ] } + } } ) + +The following example queries grid coordinates and returns all +documents within a 10 mile radius of longitude ``88 W`` and latitude +``30 N``. The example converts the distance, 10 miles, to radians by +dividing by the approximate radius of the earth, 3959 miles: + +.. code-block:: javascript + + db.collection.find( { loc : { $geoWithin : + { $centerSphere : + [ [ 88 , 30 ] , 10 / 3959 ] + } } } ) diff --git a/source/applications/2dsphere.txt b/source/applications/2dsphere.txt new file mode 100644 index 00000000000..bd0602f8047 --- /dev/null +++ b/source/applications/2dsphere.txt @@ -0,0 +1,239 @@ +================ +2dsphere Indexes +================ + +.. default-domain:: mongodb + +.. versionadded:: 2.4 + +MongoDB's 2dsphere indexes support data stored in the `GeoJSON +`_-format. + +.. primary use case ??? + +2dsphere indexes store points, lines, and shapes, and calculate geometry +on a sphere. + +2dsphere indexes also support pre-MongoDB-2.4 data stored as points +(grid coordinates in an array or document) by converting the data to the +GeoJSON ``Point`` type. + +.. In what way are 2dsphere indexes compatible with 2.2 and earlier data + stored as points (grid coordinates) ??? + If you are upgrading and want to use 2dsphere ... ??? + +MongoDB allows one 2dsphere index per collection. + +A :ref:`compound ` 2dsphere index can reference +multiple location and non-location fields within a collection’s +documents. You can arrange the fields in any order. + +.. _geospatial-indexes-store-geojson: + +Store GeoJSON Objects +--------------------- + +.. versionadded:: 2.4 + +MongoDB supports the following `GeoJSON `_ objects: + + - ``Point`` + + - ``LineString`` + + - ``Polygon`` + +To store GeoJSON data, store coordinates in this order: +**longitude, latitude.** Use the following syntax: + +.. code-block:: javascript + + { : { type : "Point|LineString|Polygon" , + coordinates : } + +The following example stores a GeoJSON ``Point``: + +.. code-block:: javascript + + { loc : { type : "Point" , coordinates : [ 40, 5 ] } } + +The following example stores a GeoJSON ``LineString``: + +.. code-block:: javascript + + { loc : { type : "LineString" , coordinates : [ [ 40 , 5 ] , [ 41 , 6 ] ] } } + +The following example stores a GeoJSON ``Polygon`` with an exterior ring +and no interior rings (or holes): + +.. code-block:: javascript + + { loc : + { type : "Polygon" , + coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] + } } + +.. _geospatial-indexes-create-2dsphere: + +Create a 2dsphere Index +----------------------- + +To create a geospatial index for GeoJSON-formatted data, use the +:method:`ensureIndex ` method and set the +value of the location field for your collection to ``2dsphere``. A +2dsphere index can be a :ref:`compound index ` +and does not require the location field to be the first field indexed. + +To create the index use the following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex( { : "2dsphere" } ) + +The following are four example commands for creating a 2dsphere index: + +.. code-block:: javascript + + db.collection.ensureIndex( { loc : "2dsphere" } ) + db.collection.ensureIndex( { loc : "2dsphere", type : 1 } ) + db.collection.ensureIndex( { type : 1, loc : "2dsphere" } ) + db.collection.ensureIndex( { loc : "2dsphere", type : 1, rating : -1 } ) + +The first example creates a simple geospatial index on the location +field ``loc``. The second example creates a compound index where the +second field contains non-location data. The third example creates an +index where the location field is not the primary field: the location +field does not have to be the first field in a 2dsphere index. The +fourth example creates a compound index with three fields: you can +include as many fields as you like in a 2dsphere index. + +Query a 2dsphere Index +---------------------- + +The following sections describe queries supported by the 2dsphere index. +For an overview of recommended geospatial queries, see +:doc:`/reference/geospatial-queries`. + +GeoJSON Objects Bounded by a Polygon +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all points and shapes found within a `GeoJSON +`_ polygon, your data must be +stored in GeoJSON format. Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $geometry : + { type : "Polygon" , + coordinates : [ ] + } } } } ) + +The following example selects all points and shapes that +exist entirely within a GeoJSON polygon: + +.. code-block:: javascript + + db.places.find( { loc : + { $geoWithin : + { $geometry : + { type : "Polygon" , + coordinates : [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] + } } } } ) + +Intersections of GeoJSON Objects +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 2.4 + +The :operator:`$geoIntersects` operator queries for location data that +intersects a `GeoJSON `_ object. +Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoIntersects : + { $geometry : + { type : "Point|LineString|Polygon" , + coordinates : [ ] + } } } } ) + +The following example uses :operator:`$geoIntersects` to select all +indexed points and shapes that intersect with the polygon defined by the +``coordinates`` array. + +.. code-block:: javascript + + db.places.find( { loc : + { $geoIntersects : + { $geometry : + { type : "Polygon" , + coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] } + } } } } ) + +The query returns true if the intersection between shapes is non-empty. +This includes documents that have a shared edge. + +Proximity to a GeoJSON Point +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Proximity queries return the 100 points closest to the defined point and +sorts the results by distance. A proximity query on GeoJSON data +requires a 2dsphere index. + +To query for proximity to a `GeoJSON +`_ point, use either the +:operator:`$near` operator or :dbcommand:`geoNear` command. Distance is +in meters. + +The :operator:`$near` uses the following syntax: + +.. code-block:: javascript + + db..find( { : + { $near : + { $geometry : + { type : "Point" , + coordinates : [ , ] } , + $maxDistance : + } } } ) + +For examples, see :operator:`$near`. + +The :dbcommand:`geoNear` command returns more information than does +:operator:`$near`. See :ref:`geospatial-indexes-geonear`. + +Points within a Circle Defined on a Sphere +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To select all grid coordinates in a "spherical cap" on a sphere, use +:operator:`$geoWithin` with the :operator:`$centerSphere` operator. +Specify an array that contains: + +- The grid coordinates of the circle's center point + +- The circle's radius measured in radians. To calculate radians, see + :doc:`/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes`. + +Use the following syntax: + +.. code-block:: javascript + + db..find( { : + { $geoWithin : + { $centerSphere : [ [ , ] , ] } + } } ) + +The following example queries grid coordinates and returns all +documents within a 10 mile radius of longitude ``88 W`` and latitude +``30 N``. The example converts the distance, 10 miles, to radians by +dividing by the approximate radius of the earth, 3959 miles: + +.. code-block:: javascript + + db.collection.find( { loc : { $geoWithin : + { $centerSphere : + [ [ 88 , 30 ] , 10 / 3959 ] + } } } ) diff --git a/source/applications/geohaystack-indexes.txt b/source/applications/geohaystack-indexes.txt new file mode 100644 index 00000000000..663b0e9ecf3 --- /dev/null +++ b/source/applications/geohaystack-indexes.txt @@ -0,0 +1,126 @@ +================================= +Create and Query Haystack Indexes +================================= + +.. default-domain:: mongodb + +A haystack index is a special index that is optimized to return results +over small areas. Haystack indexes improve performance on queries that +use flat geometry. + +For queries that use spherical geometry, +a **2dsphere index is a better option** than a haystack index. 2dsphere +indexes allow field reordering; haystack indexes require the first field +to be the location field. Also, haystack indexes are only usable via +commands and so always return all results at once. + +Haystack indexes create "buckets" of documents from the same geographic +area in order to improve performance for queries limited to that area. +Each bucket in a haystack index contains all the documents within a +specified proximity to a given longitude and latitude. + +This document describes how to: + +- :ref:`geospatial-indexes-haystack-index` + +- :ref:`geospatial-indexes-haystack-queries` + +.. _geospatial-indexes-haystack-index: + +Create a Haystack Index +~~~~~~~~~~~~~~~~~~~~~~~ + +To build a haystack index, use the ``bucketSize`` option when creating +the index. A ``bucketSize`` of ``5`` creates an index that groups +location values that are within 5 units of the specified longitude and +latitude. The ``bucketSize`` also determines the granularity of the +index. You can tune the parameter to the distribution of your data so +that in general you search only very small regions. The areas defined by +buckets can overlap. A document can exist in multiple buckets. + +A haystack index can reference two fields: the location field and a +second field. The second field is used for exact matches. Haystack +indexes return documents based on location *and* an exact match on a +*single* additional criteria. These indexes are not necessarily suited +to returning the closest documents to a particular location. + +To build a haystack index, use following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex({ : "geoHaystack" , + : 1 , + bucketSize : ) + +.. example:: + + If you have a collection with documents that contain fields similar to + the following: + + .. code-block:: javascript + + { _id : 100, pos: { long : 126.9, lat : 35.2 } , type : "restaurant"} + { _id : 200, pos: { long : 127.5, lat : 36.1 } , type : "restaurant"} + { _id : 300, pos: { long : 128.0, lat : 36.7 } , type : "national park"} + + The following operations create a haystack index with buckets that + store keys within 1 unit of longitude or latitude. + + .. code-block:: javascript + + db.collection.ensureIndex( { pos : "geoHaystack", type : 1 }, { bucketSize : 1 } ) + + This index stores the document with an ``_id`` field that has the + value ``200`` in two different buckets: + + - In a bucket that includes the document where the ``_id`` field has + a value of ``100`` + + - In a bucket that includes the document where the ``_id`` field has + a value of ``300`` + +To query using a haystack index you use the :dbcommand:`geoSearch` +command. See :ref:`geospatial-indexes-haystack-queries`. + +By default, queries that use a haystack index return 50 documents. + +.. _geospatial-indexes-haystack-queries: + +Query a Haystack Index +---------------------- + +A haystack index is a special ``2d`` geospatial index that is optimized +to return results over small areas. To create a haystack index see +:ref:`geospatial-indexes-haystack-index`. + +To query a haystack index, use the :dbcommand:`geoSearch` +command. You must specify both the coordinate and other field to +:dbcommand:`geoSearch`, which take the following form: + +.. code-block:: javascript + + db.runCommand( { geoSearch: , search: { : } } ) + +For example, to return all documents with the value ``restaurants`` in +the ``type`` field near the example point, the command would resemble: + +.. code-block:: javascript + + db.runCommand( { geoSearch: "places", + search: { type: "restaurant" }, + near: [-74, 40.74] } ) + +.. note:: + + Haystack indexes are not suited to returning a full list of the + closest documents to a particular location, as the closest + documents could be far away compared to the ``bucketSize``. + +.. note:: + + :doc:`Spherical query operations + ` + are not currently supported by haystack indexes. + + The :method:`find() ` method and + :dbcommand:`geoNear` command cannot access the haystack index. diff --git a/source/applications/geohaystack.txt b/source/applications/geohaystack.txt new file mode 100644 index 00000000000..663b0e9ecf3 --- /dev/null +++ b/source/applications/geohaystack.txt @@ -0,0 +1,126 @@ +================================= +Create and Query Haystack Indexes +================================= + +.. default-domain:: mongodb + +A haystack index is a special index that is optimized to return results +over small areas. Haystack indexes improve performance on queries that +use flat geometry. + +For queries that use spherical geometry, +a **2dsphere index is a better option** than a haystack index. 2dsphere +indexes allow field reordering; haystack indexes require the first field +to be the location field. Also, haystack indexes are only usable via +commands and so always return all results at once. + +Haystack indexes create "buckets" of documents from the same geographic +area in order to improve performance for queries limited to that area. +Each bucket in a haystack index contains all the documents within a +specified proximity to a given longitude and latitude. + +This document describes how to: + +- :ref:`geospatial-indexes-haystack-index` + +- :ref:`geospatial-indexes-haystack-queries` + +.. _geospatial-indexes-haystack-index: + +Create a Haystack Index +~~~~~~~~~~~~~~~~~~~~~~~ + +To build a haystack index, use the ``bucketSize`` option when creating +the index. A ``bucketSize`` of ``5`` creates an index that groups +location values that are within 5 units of the specified longitude and +latitude. The ``bucketSize`` also determines the granularity of the +index. You can tune the parameter to the distribution of your data so +that in general you search only very small regions. The areas defined by +buckets can overlap. A document can exist in multiple buckets. + +A haystack index can reference two fields: the location field and a +second field. The second field is used for exact matches. Haystack +indexes return documents based on location *and* an exact match on a +*single* additional criteria. These indexes are not necessarily suited +to returning the closest documents to a particular location. + +To build a haystack index, use following syntax: + +.. code-block:: javascript + + db.collection.ensureIndex({ : "geoHaystack" , + : 1 , + bucketSize : ) + +.. example:: + + If you have a collection with documents that contain fields similar to + the following: + + .. code-block:: javascript + + { _id : 100, pos: { long : 126.9, lat : 35.2 } , type : "restaurant"} + { _id : 200, pos: { long : 127.5, lat : 36.1 } , type : "restaurant"} + { _id : 300, pos: { long : 128.0, lat : 36.7 } , type : "national park"} + + The following operations create a haystack index with buckets that + store keys within 1 unit of longitude or latitude. + + .. code-block:: javascript + + db.collection.ensureIndex( { pos : "geoHaystack", type : 1 }, { bucketSize : 1 } ) + + This index stores the document with an ``_id`` field that has the + value ``200`` in two different buckets: + + - In a bucket that includes the document where the ``_id`` field has + a value of ``100`` + + - In a bucket that includes the document where the ``_id`` field has + a value of ``300`` + +To query using a haystack index you use the :dbcommand:`geoSearch` +command. See :ref:`geospatial-indexes-haystack-queries`. + +By default, queries that use a haystack index return 50 documents. + +.. _geospatial-indexes-haystack-queries: + +Query a Haystack Index +---------------------- + +A haystack index is a special ``2d`` geospatial index that is optimized +to return results over small areas. To create a haystack index see +:ref:`geospatial-indexes-haystack-index`. + +To query a haystack index, use the :dbcommand:`geoSearch` +command. You must specify both the coordinate and other field to +:dbcommand:`geoSearch`, which take the following form: + +.. code-block:: javascript + + db.runCommand( { geoSearch: , search: { : } } ) + +For example, to return all documents with the value ``restaurants`` in +the ``type`` field near the example point, the command would resemble: + +.. code-block:: javascript + + db.runCommand( { geoSearch: "places", + search: { type: "restaurant" }, + near: [-74, 40.74] } ) + +.. note:: + + Haystack indexes are not suited to returning a full list of the + closest documents to a particular location, as the closest + documents could be far away compared to the ``bucketSize``. + +.. note:: + + :doc:`Spherical query operations + ` + are not currently supported by haystack indexes. + + The :method:`find() ` method and + :dbcommand:`geoNear` command cannot access the haystack index. diff --git a/source/applications/geospatial-indexes.txt b/source/applications/geospatial-indexes.txt index 39fd76242f6..536510d200e 100644 --- a/source/applications/geospatial-indexes.txt +++ b/source/applications/geospatial-indexes.txt @@ -1,418 +1,60 @@ -====================================== -Geospatial Queries with ``2d`` Indexes -====================================== +:orphan: -.. default-domain:: mongodb - -MongoDB provides support for querying location-based data using -special geospatial indexes. For an introduction to these ``2d`` -indexes, see :doc:`/core/geospatial-indexes`. - -MongoDB supports the following geospatial query types: - -- Proximity queries, which select documents based on distance to a - given point. See :ref:`geospatial-indexes-proximity`. - -- Bounded queries, which select documents that have coordinates within - a specified area. See :ref:`geospatial-indexes-bounded`. - -- Exact queries, which select documents with an exact coordinate pair, - which has limited applicability. See :ref:`geospatial-indexes-exact-match`. - -.. index:: geospatial queries; proximity -.. _geospatial-indexes-near: -.. _geospatial-indexes-proximity: - -Proximity Queries -~~~~~~~~~~~~~~~~~ - -Proximity queries select the documents closest to the point specified -in the query. To perform proximity queries you use either the -:method:`find() ` method with the -:operator:`$near` operator or you use the :dbcommand:`geoNear` -command. - -The :method:`find() ` method with the -:operator:`$near` operator returns 100 documents by default and sorts -the results by distance. The :operator:`$near` operator uses the -following form: - -.. code-block:: javascript - - db.collection.find( { : { $near: [ x, y ] } } ) - -.. example:: - - The following query - - .. code-block:: javascript - - db.places.find( { loc: { $near: [ -70, 40 ] } } ) - - returns output similar to the following: - - .. code-block:: javascript - - { "_id" : ObjectId(" ... "), "loc" : [ -73, 39 ] } - -The :dbcommand:`geoNear` command returns more information than does the -:operator:`$near` operator. The :dbcommand:`geoNear` command can only -return a single 16-megabyte result set. The -:dbcommand:`geoNear` command also offers additional operators, such as -operators to query for :ref:`maximum ` or -:ref:`spherical ` distance. For a list of -operators, see :dbcommand:`geoNear`. - -Without additional operators, the :dbcommand:`geoNear` command uses the -following form: - -.. code-block:: javascript - - db.runCommand( { geoNear: , near: [ x, y ] } ) - -.. example:: - - The following command returns the same results as the - :operator:`$near` in the previous example but with more information: - - .. code-block:: javascript - - db.runCommand( { geoNear: "places", near: [ -74, 40.74 ] } ) - - This operation will return the following output: - - .. code-block:: javascript - - { - "ns" : "test.places", - "results" : [ - { - "dis" : 3, - "obj" : { - "_id" : ObjectId(" ... "), - "loc" : [ - -73, - 39 - ] - } - } - ], - "stats" : { - "time" : 2, - "btreelocs" : 0, - "nscanned" : 1, - "objectsLoaded" : 1, - "avgDistance" : 3, - "maxDistance" : 3.0000188685220253 - }, - "near" : "0110000111111000000111111000000111111000000111111000", - "ok" : 1 - } - -.. index:: geospatial queries; distance limit -.. _geospatial-indexes-distance: - -Distance Queries -~~~~~~~~~~~~~~~~ - -You can limit a proximity query to those documents that fall within a -maximum distance of a point. You specify the maximum distance using the -units specified by the coordinate system. For example, if the coordinate -system uses meters, you specify maximum distance in meters. - -To specify distance using the :method:`find() ` -method, use :operator:`$maxDistance` operator. Use the following form: - -.. code-block:: javascript - - db.collection.find( { : { $near : [ x , y ] , $maxDistance : } } ) - -To specify distance with the :dbcommand:`geoNear` command, use the -``maxDistance`` option. Use the following form: - -.. code-block:: javascript - - db.runCommand( { geoNear: , near: [ x, y ], maxDistance: } ) - -.. _geospatial-indexes-limit: - -Limit the Number of Results -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -By default, geospatial queries using :method:`~db.collection.find()` -method return 100 documents, sorted by distance. To limit the result -when using the :method:`~db.collection.find()` method, use the -:method:`~cursor.limit()` method, as in the following prototype: - -.. code-block:: javascript - - db.collection.find( { : { $near: [ x, y ] } } ).limit() - -To limit the result set when using the :dbcommand:`geoNear` command, use -the ``num`` option. Use the following form: - -.. code-block:: javascript - - db.runCommand( { geoNear: , near: [ x, y ], num: z } ) - -To limit geospatial search results by distance, see -:ref:`geospatial-indexes-distance`. - -.. _geospatial-indexes-within: -.. _geospatial-indexes-bounded: - -Bounded Queries ---------------- - -Bounded queries return documents within a shape defined using the -:operator:`$within` operator. MongoDB's bounded queries support the -following shapes: - -- :ref:`geospatial-indexes-circles` -- :ref:`geospatial-indexes-rectangles` -- :ref:`geospatial-indexes-polygons` - -Bounded queries do not return sorted results. As a result MongoDB can -return bounded queries more quickly than :ref:`proximity queries -`. Bounded queries have the following -form: - -.. code-block:: javascript - - db.collection.find( { : - { "$within" : - { : } - } - } ) - -The following sections describe each of the shapes supported by -bounded queries: - -.. _geospatial-indexes-circles: - -Circles -~~~~~~~ - -To query for documents with coordinates inside the bounds of a circle, -specify the center and the radius of the circle using the -:operator:`$within` operator and :operator:`$center` option. Consider -the following prototype query: - -.. code-block:: javascript - - db.collection.find( { "field": { "$within": { "$center": [ center, radius ] } } } ) - -The following example query returns all documents that have coordinates -that exist within the circle centered on ``[-74, 40.74]`` and with a -radius of ``10``, using a geospatial index on the ``loc`` field: +============================== +Geospatial Indexes and Queries +============================== -.. code-block:: javascript - - db.places.find( { "loc": { "$within": - { "$center": [ [-74, 40.74], 10 ] } - } - } ) - -The :operator:`$within` operator using :operator:`$center` is similar -to using :operator:`$maxDistance`, but :operator:`$center` has -different performance characteristics. MongoDB does not sort queries -that use the :operator:`$within` operator are not sorted, unlike -queries using the :operator:`$near` operator. - -.. _geospatial-indexes-rectangles: - -Rectangles -~~~~~~~~~~ - -To query for documents with coordinates inside the bounds of a -rectangle, specify the lower-left and upper-right corners of the -rectangle using the :operator:`$within` operator and :operator:`$box` -option. Consider the following prototype query: - -.. code-block:: javascript - - db.collection.find( { "field": { "$within": { "$box": [ coordinate0, coordinate1 ] } } } ) - -The following query returns all documents that have coordinates -that exist within the rectangle where the lower-left corner is at -``[ 0, 0 ]`` and the upper-right corner is at ``[ 3, 3 ]``, using a -geospatial index on the ``loc`` field: - -.. code-block:: javascript - - db.places.find( { "loc": { "$within": { "$box": [ [0, 0] , [3, 3] ] } } } ) - -.. _geospatial-indexes-polygons: - -Polygons -~~~~~~~~ - -.. versionadded:: 1.9 - Support for polygon queries. - -To query for documents with coordinates inside of a polygon, specify the points -of the polygon in an array, using the :operator:`$within` operator -with the :operator:`$polygon` option. MongoDB automatically connects the -last point in the array to the first point. Consider the following -prototype query: - -.. code-block:: javascript - - db.places.find({ "loc": { "$within": { "$polygon": [ points ] } } }) - -The following query returns all documents that have coordinates -that exist within the polygon defined by ``[ [0,0], [3,3], [6,0] ]``: - -.. code-block:: javascript - - db.places.find({ "loc": { "$within": { "$polygon": - [ [ 0,0], [3,3], [6,0] ] } } } ) - -.. index:: geospatial queries -.. index:: geospatial queries; exact -.. _geospatial-indexes-exact-match: - -Query for Exact Matches ------------------------ - -You can use the :method:`db.collection.find()` method to query for an -exact match on a location. These queries have the following form: - -.. code-block:: javascript - - db.collection.find( { : [ x, y ] } ) - -This query will return any documents with the value of ``[ x, y ]``. - -Exact geospatial queries only applicability for a limited selection of -cases, the :ref:`proximity ` and -:ref:`bounded ` queries provide more useful -results for more applications. - -.. _geospatial-indexes-spherical: - -Calculate Distances Using Spherical Geometry --------------------------------------------- - -When you query using the ``2d`` index, MongoDB calculates distances -using flat geometry by default, which models points on a flat surface. - -Optionally, you may instruct MongoDB to calculate distances using spherical geometry, which -models points on a spherical surface. Spherical geometry is useful for -modeling coordinates on the surface of Earth. - -To calculate distances using spherical geometry, use MongoDB's -spherical query operators and options: - -- :method:`find() ` method with the - :operator:`$nearSphere` operator. - -- :method:`find() ` method with the - :operator:`$centerSphere`. - -- :dbcommand:`geoNear` command with the ``{ spherical: true }`` option. - -.. seealso:: :ref:`geospatial-query-operators`. - -For more information on differences between flat and spherical distance -calculation, see :ref:`geospatial-indexes-distance-calculation`. - -.. _geospatial-indexes-distance-multiplier: - -Distance Multiplier -------------------- - -The ``distanceMultiplier`` option :dbcommand:`geoNear` returns -distances only after multiplying the results by command by an assigned -value. This allows MongoDB to return converted values, and removes the -requirement to convert units in application logic. - -.. note:: - - Because ``distanceMultiplier`` is an option to - :dbcommand:`geoNear`, the multiplication operation occurs on the - :program:`mongod` process. The operation adds a slight overhead to - the operation of :dbcommand:`geoNear`. - -Using ``distanceMultiplier`` in spherical queries allows one to use -results from the :dbcommand:`geoNear` command without radian to -distance conversion. The following example uses ``distanceMultiplier`` -in the :dbcommand:`geoNear` command with a :ref:`spherical -` example: - -.. code-block:: javascript - - db.runCommand( { geoNear: "places", - near: [ -74, 40.74 ], - spherical: true, - distanceMultiplier: 3963.192 - } ) - -The output of the above operation would resemble the following: - -.. code-block:: javascript - - { - // [ ... ] - "results" : [ - { - "dis" : 73.46525170413567, - "obj" : { - "_id" : ObjectId( ... ) - "loc" : [ - -73, - 40 - ] - } - } - ], - "stats" : { - // [ ... ] - "avgDistance" : 0.01853688938212826, - "maxDistance" : 0.01853714811400047 - }, - "ok" : 1 - } - -.. seealso:: The :ref:`Distance operator `. - -.. _geospatial-indexes-haystack-queries: - -Querying Haystack Indexes -------------------------- - -Haystack indexes are a special ``2d`` geospatial index that optimized -to return results over small areas. To create geospatial indexes see -:ref:`geospatial-indexes-haystack-index`. - -To query the haystack index, use the :dbcommand:`geoSearch` -command. You must specify both the coordinate and other field to -:dbcommand:`geoSearch`, which take the following form: - -.. code-block:: javascript - - db.runCommand( { geoSearch: , - search: { : } } ) - -For example, to return all documents with the value ``restaurants`` in -the ``type`` field near the example point, the command would resemble: - -.. code-block:: javascript - - db.runCommand( { geoSearch: "places", - search: { type: "restaurant" }, - near: [-74, 40.74] } ) - -.. note:: - - Haystack indexes are not suited to returning a full list of the - closest documents to a particular location, as the closest - documents could be far away compared to the ``bucketSize``. - -.. note:: - - :ref:`Spherical query operations ` - are not currently supported by haystack indexes. +.. default-domain:: mongodb - The :method:`find() ` method and - :dbcommand:`geoNear` command cannot access the haystack index. +MongoDB provides three special index types that support geospatial +queries in a number of different use cases. Depending on the query and +index type, MongoDB allows applications to represent geospatial data +in :term:`documents ` as either `GeoJSON +`_ objects or as coordinate +pairs on a two-dimensional plane. + +MongoDB's geospatial query operators support queries for: + +- points and geometries (shapes) within a geometry. (:operator:`$geoWithin`) + +- points and geometries that intersect a geometry. (:operator:`$geoIntersects`) + +- points in proximity to another point. (:operator:`$geoNear`) + +To support these geospatial queries, MongoDB provides the following +index types: + +- :doc:`2sphere `, which supports data sets + that refer to geospatial data with *spherical coordinate systems*, + and: + + - polygon intersection (i.e. :operator:`$geoIntersects`.) + - indexing geometries in addition to points. + - GeoJSON points, lines, and polygons. + - supports compound indexes with scalar index + (i.e. ascending/descending,) as a prefix or suffix of the + ``2dsphere`` index field. + + .. versionadded:: 2.4 + ``2dsphere`` indexes are not available before version 2.4. + +- :doc:`2d `, which supports data sets that refer to + geospatial data that refer to points on a *planar coordinate system*, + and: + + - can only store point data using legacy-coordinate pairs. + - supports a compound index with one additional field only as a + suffix of the ``2d`` index field. + +See the following documents for complete documentation of geospatial +indexes and documentation: + +.. toctree:: + :maxdepth: 1 + + /applications/2d + /applications/2dsphere + /applications/geohaystack + /reference/geospatial-queries + /tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes + /core/geospatial-indexes diff --git a/source/applications/geospatial-preferred-queries.txt b/source/applications/geospatial-preferred-queries.txt new file mode 100644 index 00000000000..be58e41c78e --- /dev/null +++ b/source/applications/geospatial-preferred-queries.txt @@ -0,0 +1,13 @@ +============================== +Recommended Geospatial Queries +============================== + +.. default-domain:: mongodb + +While numerous combinations of query operators are possible, the +following table shows the recommended operators for different types of +queries. The table uses the :operator:`$geoWithin`, :operator:`$geoIntersects` +and :operator:`$near` operators. + +.. include:: /includes/table-geospatial-queries.rst + diff --git a/source/core/geospatial-indexes.txt b/source/core/geospatial-indexes.txt index 5fb964fbf78..4d88bc2c532 100644 --- a/source/core/geospatial-indexes.txt +++ b/source/core/geospatial-indexes.txt @@ -1,345 +1,34 @@ -========================= -``2d`` Geospatial Indexes -========================= +========================== +Geospatial Index Internals +========================== .. default-domain:: mongodb -Overview --------- +This document provides a more in-depth explanation of the internals +geospatial features. This material is not necessary for normal operation +or application development but may be useful for troubleshooting and for +further understanding MongoDB's behavior and approach. -``2d`` geospatial indexes make it possible to associate documents with -locations in two-dimensional space, such as a point on a map. MongoDB -interprets two-dimensional coordinates in a location field as points -and can index these points in a special index type to support -location-based queries. Geospatial indexes provide special geospatial -query operators. For example, you can query for documents based on -proximity to another location or based on inclusion in a specified -region. - -Geospatial indexes support queries on both the coordinate field *and* -another field, such as a type of business or attraction. For example, -you might write a query to find restaurants a specific distance from a -hotel or to find museums within a certain defined neighborhood. - -This document describes how to store location data in your documents -and how to create geospatial indexes. For information on querying data -stored in geospatial indexes, see :doc:`/applications/geospatial-indexes`. - -.. _geospatial-indexes-coordinates: - -Store Location Data -------------------- - -To use ``2d`` geospatial indexes, you must model location data on a -predetermined two-dimensional coordinate system, such as longitude -and latitude. You store a document's location data as two coordinates -in a field that holds either a two-dimensional array or an embedded -document with two fields. Consider the following two examples: - -.. code-block:: javascript - - loc : [ x, y ] - - loc : { x: 1, y: 2 } - -All documents must store location data in the same order. If -you use latitude and longitude as your coordinate system, always store -longitude first. MongoDB's :ref:`2d spherical index operators -` only recognize ``[ longitude, latitude]`` -ordering. - -.. _geospatial-indexes-create: - -Create a Geospatial Index -------------------------- - -.. important:: MongoDB only supports *one* geospatial index per - collection. - -To create a geospatial index, use the :method:`ensureIndex -` method with the value ``2d`` for the -location field of your collection. Consider the following prototype: - -.. code-block:: javascript - - db.collection.ensureIndex( { : "2d" } ) - -MongoDB's :ref:`geospatial operations -` use this index when querying for location -data. - -When you create the index, MongoDB converts location data to binary -:term:`geohash` values and calculates these values using the location -data and the index's location range, as described in -:ref:`geospatial-indexes-range`. The default range for ``2d`` indexes -assumes longitude and latitude and uses the bounds -180 inclusive and -180 non-inclusive. - -.. important:: The default boundaries of ``2d`` indexes allow - applications to insert documents with invalid latitudes greater - than 90 or less than -90. The behavior of geospatial queries with - such invalid points is not defined. - -When creating a ``2d`` index, MongoDB provides the following options: - -.. _geospatial-indexes-range: - -Location Range -~~~~~~~~~~~~~~ - -All ``2d`` geospatial indexes have boundaries defined by a coordinate -range. By default, ``2d`` geospatial indexes assume longitude and -latitude have boundaries of -180 inclusive and 180 non-inclusive -(i.e. ``[-180, 180)``). MongoDB returns an error and rejects documents -with coordinate data outside of the specified range. - -To build an index with a location range other than the -default, use the ``min`` and ``max`` options with the -:method:`ensureIndex() ` operation when -creating a ``2d`` index, as in the following prototype: - -.. code-block:: javascript - - db.collection.ensureIndex( { : "2d" } , - { min: , max: } ) - -.. _geospatial-indexes-precision: - -Location Precision -~~~~~~~~~~~~~~~~~~ - -``2d`` indexes use a :ref:`geohash ` -representation of all coordinate data internally. Geohashes have a -precision that is determined by the number of bits in the hash. More bits -allow the index to provide results with greater precision, while fewer -bits mean the index provides results with more limited -precision. - -Indexes with lower precision have a lower processing overhead for -insert operations and will consume less space. However, higher -precision indexes means that queries will need to scan smaller -portions of the index to return results. The actual stored values are -always used in the final query processing, and index precision does -not affect query accuracy. - -By default, geospatial indexes use 26 bits of precision, which is -roughly equivalent to 2 feet or about 60 centimeters of precision -using the default range of -180 to 180. You can configure ``2d`` -geospatial indexes with up to 32 bits of precision. - -To configure a location precision other than the default, use the -``bits`` option in the :method:`~db.collection.ensureIndex()` method, -as in the following prototype: - -.. code-block:: javascript - - db.collection.ensureIndex( {: "2d"} , - { bits: } ) - -For more information on the relationship between bits and precision, -see :ref:`geospatial-indexes-geohash`. - -Compound Geospatial Indexes -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -``2d`` geospatial indexes may be :ref:`compound -`, if and only if the field with location data is -the first field. A compound geospatial index makes it possible to -construct queries that primarily select on a location-based field but -also select on a second criteria. For example, you could use such -an index to support queries for carpet wholesalers within a specific -region. - -.. note:: Geospatial queries will *only* use additional query - parameters after applying the geospatial criteria. If your - geospatial query criteria selects a large number of - documents, the additional query will only filter the result set - and *not* result in a more targeted query. - -To create a geospatial index with two fields, specify the location field -first, then the second field. For example, to create a compound index on -the ``loc`` location field and on the ``product`` field (sorted in -ascending order), you would issue the following: - -.. code-block:: javascript - - db.storeInfo.ensureIndex( { loc: "2d", product: 1 } ); - -This creates an index that supports queries on just the location field -(i.e. ``loc``), as well as queries on both the ``loc`` and -``product``. - -.. _geospatial-indexes-haystack-index: - -Haystack Indexes -~~~~~~~~~~~~~~~~ - -Haystack indexes create "buckets" of documents from the same geographic -area in order to improve performance for queries limited to that area. - -Each bucket in a haystack index contains all the documents within a -specified proximity to a given longitude and latitude. Use the -``bucketSize`` parameter of :method:`ensureIndex() -` to determine proximity. A -``bucketSize`` of ``5`` creates an index that groups location values -that are within 5 units of the specified longitude and latitude. - -``bucketSize`` also determines the granularity of the index. You can -tune the parameter to the distribution of your data so that in general -you search only very small regions of a two-dimensional -space. Furthermore, the areas defined by buckets can overlap. As a -result a document can exist in multiple buckets. - -To build a haystack index, use the ``bucketSize`` parameter in the -:method:`ensureIndex() ` method, as in the -following prototype: - -.. code-block:: javascript - - db.collection.ensureIndex({ : "geoHaystack", type: 1 }, - { bucketSize: }) - -.. example:: - - Consider a collection with documents that contain fields similar to - the following: - - .. code-block:: javascript - - { _id : 100, pos: { long : 126.9, lat : 35.2 }, type : "restaurant"} - { _id : 200, pos: { long : 127.5, lat : 36.1 }, type : "restaurant"} - { _id : 300, pos: { long : 128.0, lat : 36.7 }, type : "national park"} - - The following operations creates a haystack index with buckets that - store keys within 1 unit of longitude or latitude. - - .. code-block:: javascript - - db.collection.ensureIndex( { pos : "geoHaystack", type : 1 }, { bucketSize : 1 } ) - - Therefore, this index stores the document with an ``_id`` field - that has the value ``200`` in two - different buckets: - - 1. in a bucket that includes the document where the ``_id`` field - has a value of ``100``, and - - 2. in a bucket that includes the document where the ``_id`` field - has a value of ``300``. - -To query using a haystack index you use the :dbcommand:`geoSearch` -command. For command details, see :ref:`geospatial-indexes-haystack-queries`. - -Haystack indexes are ideal for returning documents based on location -*and* an exact match on a *single* additional criteria. These indexes -are not necessarily suited to returning the closest documents to a -particular location. - -:ref:`Spherical queries ` are not -supported by geospatial haystack indexes. - -By default, queries that use a haystack index return 50 documents. - -.. _geospatial-indexes-distance-calculation: - -Distance Calculation --------------------- - -MongoDB performs distance calculations before performing ``2d`` -geospatial queries. By default, MongoDB uses flat geometry to -calculate distances between points. MongoDB also supports distance -calculations using spherical geometry, to provide accurate distances -for geospatial information based on a sphere or earth. - -.. admonition:: Spherical Queries Use Radians for Distance - - For spherical operators to function properly, you must convert - distances to radians, and convert from radians to the distances units - used by your application. - - To convert: - - - *distance to radians*: divide the distance by the radius of the - sphere (e.g. the Earth) in the same units as the distance - measurement. - - - *radians to distance*: multiply the radian measure by the radius - of the sphere (e.g. the Earth) in the units system that you want to - convert the distance to. - - The radius of the Earth is approximately ``3963.192`` miles or - ``6378.137`` kilometers. - -The following query would return documents from the ``places`` -collection within the circle described by the center ``[ -74, 40.74 ]`` -with a radius of ``100`` miles: - -.. code-block:: javascript - - db.places.find( { loc: { $within: { $centerSphere: [ [ -74, 40.74 ] , - 100 / 3963.192 ] } } } ) - -You may also use the ``distanceMultiplier`` option to the -:dbcommand:`geoNear` to convert radians in the :program:`mongod` -process, rather than in your application code. Please see the -:ref:`distance multiplier ` section. - -The following spherical ``2d`` query, returns all documents in the -collection ``places`` within ``100`` miles from the point ``[ -74, -40.74 ]``. - -.. code-block:: javascript - - db.runCommand( { geoNear: "places", - near: [ -74, 40.74 ], - spherical: true - } ) - -The output of the above command would be: - -.. code-block:: javascript - - { - // [ ... ] - "results" : [ - { - "dis" : 0.01853688938212826, - "obj" : { - "_id" : ObjectId( ... ) - "loc" : [ - -73, - 40 - ] - } - } - ], - "stats" : { - // [ ... ] - "avgDistance" : 0.01853688938212826, - "maxDistance" : 0.01853714811400047 - }, - "ok" : 1 - } - -.. warning:: - - Spherical queries that wrap around the poles or at the transition - from ``-180`` to ``180`` longitude raise an error. +Geospatial Indexes and Sharding +------------------------------- -.. note:: +You *cannot* use a geospatial index as a :term:`shard key` when sharding +a collection. However, you can create and maintain a geospatial index on +a sharded collection by using a different field as the shard key. You +can query for geospatial data using :dbcommand:`geoNear` and +:operator:`$geoWithin`. - While the default Earth-like bounds for geospatial indexes are - between ``-180`` inclusive, and ``180``, valid values for latitude - are between ``-90`` and ``90``. +Queries using :operator:`$near` are not supported for sharded +collections. Use :dbcommand:`geoNear` instead. .. _geospatial-indexes-geohash: Geohash Values -------------- -To create a geospatial index, MongoDB computes the :term:`geohash` -value for coordinate pairs within the specified :ref:`range -` and indexes the geohash for that point . +When you create a geospatial index on grid coordinates, MongoDB computes +:term:`geohash` values for the coordinate pairs within the specified +:ref:`range ` and indexes the geohash values. To calculate a geohash value, continuously divide a 2D map into quadrants. Then assign each quadrant a two-bit value. For example, a @@ -371,45 +60,31 @@ and concatenate the two-bit identifier for each division. The more area that the hash can describe and the higher the resolution of the geospatial index. -Geospatial Indexes and Sharding -------------------------------- - -You *cannot* use a geospatial index as a :term:`shard key` when -sharding a collection. However, you *can* create and maintain a -geospatial index on a sharded collection by using a different field as -the shard key. Your application may query for geospatial data using -:dbcommand:`geoNear` and :operator:`$within`. However, queries using -:operator:`$near` are not supported for sharded collections. - .. _geospatial-indexes-multi-location: -Multi-location Documents ------------------------- +Multi-location Documents for 2D Indexes +--------------------------------------- .. versionadded:: 2.0 Support for multiple locations in a document. -While ``2d`` indexes do not support more than one set of coordinates in -a document, you can use a :ref:`multi-key indexes ` -to store and index multiple coordinate pairs in a single document. In the -simplest example you may have a field (e.g. ``locs``) that holds an -array of coordinates, as in the following prototype data -model: +While ``2d`` geospatial indexes do not support more than one set of +coordinates in a document, you can use a :ref:`multi-key index +` to store and index multiple coordinate pairs in +a single document. In the simplest example you may have a field (e.g. +``locs``) that holds an array of coordinates, as in the following +example: .. code-block:: javascript - { - "_id": ObjectId(...), - "locs": [ - [ 55.5, 42.3 ], - [ -74, 44.74 ], - { "lat": 55.3, "long": 40.2 } - ] + { _id : ObjectId(...), + locs : [ [ 55.5 , 42.3 ] , + [ -74 , 44.74 ] , + { long : 4.2 , lat : 55.3 } ] } -The values of the array may either be arrays holding coordinates, as -in ``[ 55.5, 42.3 ]``, or embedded documents, as in ``{ "lat": 55.3, -"long": 40.2 }``. +The values of the array may be either arrays, as in ``[ 55.5, 42.3 ]``, +or embedded documents, as in ``{ long : 4.2 , lat : 55.3 }``. You could then create a geospatial index on the ``locs`` field, as in the following: @@ -422,21 +97,19 @@ You may also model the location data as a field inside of a sub-document. In this case, the document would contain a field (e.g. ``addresses``) that holds an array of documents where each document has a field (e.g. ``loc:``) that holds location -coordinates. Consider the following prototype data model: +coordinates. For example: .. code-block:: javascript - { - "_id": ObjectId(...), - "name": "...", - "addresses": [ - { - "context": "home", - "loc": [ 55.5, 42.3 ] - }, + { _id : ObjectId(...), + name : "...", + addresses : [ { + context : "home" , + loc : [ 55.5, 42.3 ] + } , { - "context": "home", - "loc": [ -74, 44.74 ] + context : "home", + loc : [ -74 , 44.74 ] } ] } @@ -451,9 +124,9 @@ in the following example: For documents with multiple coordinate values, queries may return the same document multiple times if more than one indexed coordinate pair satisfies the query constraints. Use the ``uniqueDocs`` parameter to -:dbcommand:`geoNear` or the :operator:`$uniqueDocs` operator in -conjunction with :operator:`$within`. +:dbcommand:`geoNear` or the :operator:`$uniqueDocs` operator with +:operator:`$geoWithin`. -To include the location field with the distance field in -multi-location document queries, specify ``includeLocs: true`` -in the :dbcommand:`geoNear` command. +To include the location field with the distance field in multi-location +document queries, specify ``includeLocs: true`` in the +:dbcommand:`geoNear` command. diff --git a/source/core/indexes.txt b/source/core/indexes.txt index 1dcef62b77e..a4b03b7583c 100644 --- a/source/core/indexes.txt +++ b/source/core/indexes.txt @@ -557,9 +557,13 @@ following: Be aware of the following behaviors with background index construction: -- A :program:`mongod` instance can only build one background index per - database, at a time. +- A :program:`mongod` instance can build more than one index in the + background concurrently. + .. versionchanged:: 2.4 + Before 2.4, a :program:`mongod` instance could only build one + background index per database at a time. + .. versionchanged:: 2.2 Before 2.2, a single :program:`mongod` instance could only build one index at a time. diff --git a/source/core/replication-internals.txt b/source/core/replication-internals.txt index 784279d10bd..9cee4a1d508 100644 --- a/source/core/replication-internals.txt +++ b/source/core/replication-internals.txt @@ -291,6 +291,8 @@ behaviors: seconds. If a connection times out, the member may select a new member to sync from. +.. _replica-set-internals-multi-threaded-replication: + Multithreaded Replication ------------------------- diff --git a/source/core/sharded-clusters.txt b/source/core/sharded-clusters.txt index ac4838464aa..b96c57e905e 100644 --- a/source/core/sharded-clusters.txt +++ b/source/core/sharded-clusters.txt @@ -62,7 +62,7 @@ The ideal shard key: - is easily divisible which makes it easy for MongoDB to distribute content among the shards. Shard keys that have a limited number of possible values are not ideal as they can result in some chunks that - are "unsplittable." See the :ref:`sharding-shard-key-cardinality` + are "unsplitable." See the :ref:`sharding-shard-key-cardinality` section for more information. - will distribute write operations among the cluster, to prevent any diff --git a/source/faq/developers.txt b/source/faq/developers.txt index b157347c939..7789b9562ae 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -347,7 +347,7 @@ In some cases, you may wish to build a BSON object with a user-provided key. In these situations, keys will need to substitute the reserved ``$`` and ``.`` characters. Any character is sufficient, but consider using the Unicode full width equivalents: ``U+FF04`` -(i.e. "＄") and ``U+FFOE`` (i.e. "．"). +(i.e. "＄") and ``U+FF0E`` (i.e. "．"). Consider the following example: @@ -682,7 +682,7 @@ size. To *minimize* document movements, MongoDB uses You should not have to pad manually because MongoDB adds :ref:`padding automatically ` and can -adaptive adjust the amount of padding added to documents to prevent +adaptively adjust the amount of padding added to documents to prevent document relocations following updates. You can change the default :data:`~collStats.paddingFactor` diff --git a/source/includes/fact-authentication-source-mongo.rst b/source/includes/fact-authentication-source-mongo.rst new file mode 100644 index 00000000000..403cc171e8e --- /dev/null +++ b/source/includes/fact-authentication-source-mongo.rst @@ -0,0 +1,3 @@ +By default, |binary-name| assumes that the database name specified +in the :ref:`db address ` holds the user's +credentials, unless you specify :option:`--authenticationDatabase`. diff --git a/source/includes/fact-authentication-source-tool.rst b/source/includes/fact-authentication-source-tool.rst new file mode 100644 index 00000000000..68ca7aa1d1c --- /dev/null +++ b/source/includes/fact-authentication-source-tool.rst @@ -0,0 +1,3 @@ +By default, |binary-name| assumes that the database specified to the +:option:`--db` argument holds the user's credentials, unless you +specify :option:`--authenticationDatabase`. diff --git a/source/includes/manpage-options-auth.rst b/source/includes/manpage-options-auth.rst new file mode 100644 index 00000000000..1c4953a0672 --- /dev/null +++ b/source/includes/manpage-options-auth.rst @@ -0,0 +1,32 @@ +.. use |binary-name| to refer to the tool + +.. option:: --authenticationDatabase + + .. versionadded:: 2.4 + + Specifies the database that holds the user's (e.g + :option:`--username`) credentials. + + .. build system replaces this with + /includes/fact-authentication-source-mongo on the mongo shell + man page. + + .. include:: /includes/fact-authentication-source-tool.rst + + See :data:`~.system.users.userSource`, + :doc:`/reference/privilege-documents` and + :doc:`/reference/user-privileges` for more information about + delegated authentication in MongoDB. + +.. option:: --authenticationMechanism + + .. versionadded:: 2.4 + + Specifies the authentication mechanism. By default, the + authentication mechanism is ``MONGODB-CR``, which is the MongoDB + challenge/response authentication mechanism. In |ent-build|, + |binary-name| also includes support for ``GSSAPI`` to handle + Kerberos authentication. + + See :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` + for more information about Kerberos authentication. diff --git a/source/includes/manpage-options-ssl.rst b/source/includes/manpage-options-ssl.rst new file mode 100644 index 00000000000..888d5e3831a --- /dev/null +++ b/source/includes/manpage-options-ssl.rst @@ -0,0 +1,95 @@ +.. use |binary-name| to refer to ``mongos``/``mongod``. + +.. include:: /includes/replace-pem-path-name.rst + +.. option:: --sslOnNormalPorts + + .. versionadded:: 2.2 + + .. include:: /includes/note-general-ssl-support.rst + + Enables SSL for |binary-name|. With :option:`--sslOnNormalPorts`, + a |binary-name| requires SSL encryption for all connections on the + default MongoDB port, or the port specified by :option:`--port`. By + default, :option:`--sslOnNormalPorts` is disabled. + +.. option:: --sslPEMKeyFile + + .. versionadded:: 2.2 + + .. include:: /includes/note-general-ssl-support.rst + + Specifies the :file:`.pem` file that contains both the SSL + certificate and key. |pem-path-name| + + When using :option:`--sslOnNormalPorts`, you must specify + :option:`--sslPEMKeyFile`. + +.. option:: --sslPEMKeyPassword + + .. versionadded:: 2.2 + + .. include:: /includes/note-general-ssl-support.rst + + Specifies the password to de-crypt the certificate-key file + (i.e. :option:`--sslPEMKeyFile`). Only use + :option:`--sslPEMKeyPassword` if the certificate-key file is + encrypted. In all cases, |binary-name| will redact the password from + all logging and reporting output. + + .. versionchanged:: 2.4 + :option:`--sslPEMKeyPassword` is only needed when the private + key is encrypted. In earlier versions |binary-name| would require + :option:`--sslPEMKeyPassword` whenever using + :option:`--sslOnNormalPorts`, even when the private key was not + encrypted. + +.. option:: --sslCAFile + + .. versionadded:: 2.4 + + .. include:: /includes/note-general-ssl-support.rst + + Specifies the :file:`.pem` file that contains the root certificate + chain from the Certificate Authority. |pem-path-name| + +.. option:: --sslCRLFile + + .. versionadded:: 2.4 + + .. include:: /includes/note-general-ssl-support.rst + + Specifies the :file:`.pem` file that contains the Certificate + Revocation List. |pem-path-name| + +.. option:: --sslWeakCertificateValidation + + .. versionadded:: 2.4 + + .. include:: /includes/note-general-ssl-support.rst + + Disables the requirement for SSL certificate validation, that + :option:`--sslCAFile` enables. With + :option:`--sslWeakCertificateValidation`, |binary-name| will accept + connections if the client does not present a certificate when + establishing the connection. + + If the client presents a certificate and |binary-name| has + :option:`--sslWeakCertificateValidation` enabled, |binary-name| + will validate the certificate using the root certificate chain + specified by :option:`--sslCAFile`, and reject clients with invalid + certificates. + + Use :option:`--sslWeakCertificateValidation` if you have a mixed + deployment that includes clients that do not or cannot present + certificates to |binary-name|. + +.. option:: --sslFIPSMode + + .. versionadded:: 2.4 + + .. include:: /includes/note-general-ssl-support.rst + + When specified, |binary-name| will use the FIPS mode of the + installed OpenSSL library. Your system must have a FIPS compliant + OpenSSL library to use :option:`--sslFIPSMode`. diff --git a/source/includes/note-general-ssl-support.rst b/source/includes/note-general-ssl-support.rst new file mode 100644 index 00000000000..56e04e8ab63 --- /dev/null +++ b/source/includes/note-general-ssl-support.rst @@ -0,0 +1,7 @@ +.. note:: + + The `default distribution of MongoDB + `_ does **not** contain support + for SSL. To use SSL you can either compile MongoDB with SSL + support or use |ent-build|. See :doc:`/administration/ssl` for + more information about SSL and MongoDB. diff --git a/source/includes/note-geospatial-index-must-exist.rst b/source/includes/note-geospatial-index-must-exist.rst index 77c2b77fc3e..34c66e95e4f 100644 --- a/source/includes/note-geospatial-index-must-exist.rst +++ b/source/includes/note-geospatial-index-must-exist.rst @@ -1,12 +1,6 @@ .. versionchanged:: 2.2.3 - Before 2.2.3, a geospatial index *must* exist on a field holding - coordinates before using any of the geolocation query - operators. After 2.2.3, applications may use geolocation query - operators *without* having a geospatial index; however, geospatial - indexes will support much faster geospatial queries than the - unindexed equivalents. - -.. note:: - - A geospatial index *must* exist on a field and the field must hold coordinates - before you can use any of the geolocation query operators. + Applications can use this operator *without* having a geospatial + index. However, geospatial indexes support much faster queries than + the unindexed equivalents. Before 2.2.3, a geospatial index *must* + exist on a field holding coordinates before using any of the + geospatial query operators. diff --git a/source/includes/replace-pem-path-name.rst b/source/includes/replace-pem-path-name.rst new file mode 100644 index 00000000000..547225b9bd6 --- /dev/null +++ b/source/includes/replace-pem-path-name.rst @@ -0,0 +1,2 @@ +.. |pem-path-name| replace:: Specify the file name of the :file:`.pem` + file using relative or absolute paths diff --git a/source/includes/table-geospatial-queries.yaml b/source/includes/table-geospatial-queries.yaml new file mode 100644 index 00000000000..586455fd939 --- /dev/null +++ b/source/includes/table-geospatial-queries.yaml @@ -0,0 +1,150 @@ +# table structure. all content symbolic. +section: layout +header: [ meta.header1, meta.header2, meta.header3, meta.header4 ] +rows: + - 1: [ content.query1, content.shape1, content.shapetype1, content.index1 ] + - 2: [ content.query2, content.shape2, content.shapetype2, content.index2 ] + - 3: [ content.query3, content.shape3, content.shapetype3, content.index3 ] + - 4: [ content.query4, content.shape4, content.shapetype4, content.index4 ] + - 5: [ content.query5, content.shape5, content.shapetype5, content.index5 ] + - 6: [ content.query6, content.shape6, content.shapetype6, content.index6 ] + - 7: [ content.query7, content.shape7, content.shapetype7, content.index7 ] + - 8: [ content.query8, content.shape8, content.shapetype8, content.index8 ] + - 9: [ content.query9, content.shape9, content.shapetype9, content.index9 ] + - 10: [ content.query10, content.shape10, content.shapetype10, content.index10 ] +--- +# table metadata, as meta. +section: meta +header1: "Preferred Geospatial Query Document" +header2: "Shape for Query Condition" +header3: "Shape / Units for Calculation" +header4: "Supported by this Index" +--- +# table content, as content. +section: content +query1: | + **Returns points, lines and polygons** +shape1: | + +shapetype1: | + +index1: | + +query2: | + .. code-block:: javascript + + { $geoWithin : { + $geometry : + } } +shape2: | + point, line or polygon +shapetype2: | + sphere / meters +index2: | + 2dsphere +query3: | + .. code-block:: javascript + + { $geoIntersects : { + $geometry : + } } +shape3: | + point, line or polygon +shapetype3: | + sphere / meters +index3: | + 2dsphere +query4: | + .. code-block:: javascript + + { $near : { + $geometry : , + $maxDistance : d + } } +shape4: | + circular region +shapetype4: | + sphere / meters +index4: | + 2dsphere + + The index is required. +query5: | + **Returns points only** +shape5: | + +shapetype5: | + +index5: | + +query6: | + .. code-block:: javascript + + { $geoWithin : { + $box : [[x1, y1], [x2, y2]] + } } +shape6: | + rectangle +shapetype6: | + flat / flat units +index6: | + 2d +query7: | + .. code-block:: javascript + + { $geoWithin : { + $polygon : [[x1, y1], + [x1, y2], + [x2, y2], + [x2, y1]] + } } +shape7: | + polygon +shapetype7: | + flat / flat units +index7: | + 2d +query8: | + .. code-block:: javascript + + { $geoWithin : { + $center : [x1, y1], + $maxDistance : d + } } +shape8: | + circular region +shapetype8: | + flat / flat units +index8: | + 2d +query9: | + .. code-block:: javascript + + { $geoWithin : { + $centerSphere : + [[x, y], radius] + $maxDistance : d + } } +shape9: | + circular region +shapetype9: | + sphere / radians +index9: | + 2d + + 2dsphere +query10: | + .. code-block:: javascript + + { $near : [x1, y1], + $maxDistance : d + } +shape10: | + circular region +shapetype10: | + flat / flat units +index10: | + 2d + + The index is required. +... diff --git a/source/includes/warning-splitting-chunks.rst b/source/includes/warning-splitting-chunks.rst index 5527b6dab15..b2ea2607e98 100644 --- a/source/includes/warning-splitting-chunks.rst +++ b/source/includes/warning-splitting-chunks.rst @@ -3,7 +3,7 @@ Be careful when splitting data in a sharded collection to create new chunks. When you shard a collection that has existing data, MongoDB automatically creates chunks to evenly distribute the - collection. To effectively split data in a sharded you must + collection. To split data effectively in a sharded cluster you must consider the number of documents in a chunk and the average document size to create a uniform chunk size. When chunks have irregular sizes, shards may have an equal number of chunks but have diff --git a/source/indexes.txt b/source/indexes.txt index 121f7d40208..634aaab278c 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -13,13 +13,28 @@ and operational concerns, see :doc:`/administration/indexes`. For information on how applications might use indexes, see :doc:`/applications/indexes`. -The following outlines the indexing documentation: +Core MongoDB Indexing Background +-------------------------------- .. toctree:: - :maxdepth: 2 + :maxdepth: 1 core/indexes administration/indexes applications/indexes - applications/geospatial-indexes - core/geospatial-indexes + +Geospatial Indexing +------------------- + +See :doc:`/applications/geospatial-indexes` for an introduction to +geospatial indexing. + +.. toctree:: + :maxdepth: 1 + + /applications/2d + /applications/2dsphere + /applications/geohaystack + /reference/geospatial-queries + /tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes + /core/geospatial-indexes diff --git a/source/reference/bsondump.txt b/source/reference/bsondump.txt index 603a288a47d..0a7188f3aa7 100644 --- a/source/reference/bsondump.txt +++ b/source/reference/bsondump.txt @@ -36,9 +36,24 @@ Options .. option:: --objcheck - Validates each :term:`BSON` object before outputting it in :term:`JSON` format. Use - this option to filter corrupt objects from the output. This option - has some performance impact. + Validates each :term:`BSON` object before outputting it in + :term:`JSON` format. By default, :program:`bsondump` enables + :option:`--objcheck` by default. For objects with a high degree of + sub-document nesting, :option:`--objcheck` can have a small impact + on performance. You can set :option:`--noobjcheck` to disable + object checking. + + .. versionchanged:: 2.4 + MongoDB enables :option:`--objcheck` by default, to prevent any + client from inserting malformed or invalid BSON into a MongoDB + database. + +.. option:: --noobjcheck + + .. versionadded:: 2.4 + + Disables the default document validation that :program:`bsondump` + performs on all BSON documents. .. option:: --filter '' diff --git a/source/reference/command/captrunc.txt b/source/reference/command/captrunc.txt index 2bb3677c2ec..974b643c724 100644 --- a/source/reference/command/captrunc.txt +++ b/source/reference/command/captrunc.txt @@ -30,7 +30,7 @@ captrunc (internal) db.runCommand({captrunc: "records", n:100, inc:true}) - .. |dbcommand| replace:: :dbcommand:`captruc` + .. |dbcommand| replace:: :dbcommand:`captrunc` .. include:: /includes/note-enabletestcommands.rst .. write-lock diff --git a/source/reference/command/collMod.txt b/source/reference/command/collMod.txt index 4f469b2b2b7..608ff86b639 100644 --- a/source/reference/command/collMod.txt +++ b/source/reference/command/collMod.txt @@ -23,6 +23,7 @@ collMod .. index:: document; space allocation .. index:: usePowerOf2Sizes + .. _usePowerOf2Sizes: .. collflag:: usePowerOf2Sizes The :collflag:`usePowerOf2Sizes` flag changes the method that @@ -41,7 +42,7 @@ collMod with :collflag:`usePowerOf2Sizes` set, :program:`mongod` will allocate records in full megabytes by rounding up to the nearest megabyte. - + :collflag:`usePowerOf2Sizes` is useful for collections where you will be inserting and deleting large numbers of documents to ensure that MongoDB will effectively use space on disk. @@ -62,6 +63,7 @@ collMod db.runCommand( { collMod: "products", "usePowerOf2Sizes": false }) + .. warning:: .. versionchanged:: 2.2.1 :collflag:`usePowerOf2Sizes` now @@ -74,10 +76,49 @@ collMod as a result of document growth, and *does not* affect existing allocations. - .. note:: + .. index:: expireAfterSeconds + .. collflag:: index + + The :collflag:`index` flag changes the expiration time of a + :doc:`TTL Collection `. + + Specify the key and new expiration time with a document of the form: + + .. code-block:: javascript + + {keyPattern: , expireAfterSeconds: } + + where ```` is an existing index in the collection and + ``seconds`` is the number of seconds to subtract from the current + time. + + .. example:: + + To update the expiration value for a collection + named ``sessions`` indexed on a ``lastAccess`` field from 30 + minutes to 60 minutes, use the following operation: + + .. code-block:: javascript + + db.runCommand({collMod: "sessions", + index: {keyPattern: {lastAccess:1}, + expireAfterSeconds: 3600}}) + + Which will return the document: + + .. code-block:: javascript + + { "expireAfterSeconds_old" : 1800, "expireAfterSeconds_new" : 3600, "ok" : 1 } + + On success a document with fields ``expireAfterSeconds_old`` + and ``expireAfterSeconds_new`` set to the respective + values is returned. - :collflag:`usePowerOf2Sizes` has no effect on - :term:`capped collections `. + On failure, a document is returned with + ``no expireAfterSeconds field to update`` + if there is no existing ``expireAfterSeconds`` field or + ``cannot find index { **key**: 1.0 } for ns **namespace**`` + if the specified ``keyPattern`` does not exist. .. Commenting out the following after DOCS-717, it does take a lock but its to cover a very small metadata change. diff --git a/source/reference/command/compact.txt b/source/reference/command/compact.txt index 03750b5342a..e66fb3d30b5 100644 --- a/source/reference/command/compact.txt +++ b/source/reference/command/compact.txt @@ -50,11 +50,16 @@ compact *Maximum:* ``4.0`` The ``paddingFactor`` describes the :term:`record size` - allocated for each document as a factor of the document size. If - your updates increase the size of the documents, padding will - increase the amount of space allocated to each document and - avoid expensive document relocation operations within the data - files. + allocated for each document as a factor of the document size, + for all records compacted during the :dbcommand:`compact` + operation. ``paddingFactor`` does not affect the padding of + subsequent record allocations after :dbcommand:`compact` + completes. + + If your updates increase the size of the documents, + padding will increase the amount of space allocated to each + document and avoid expensive document relocation operations + within the data files. You can calculate the padding size by subtracting the document size from the record size or, in terms of the ``paddingFactor``, @@ -78,12 +83,22 @@ compact db.runCommand ( { compact: '', paddingFactor: 1.1 } ) + :dbcommand:`compact` compacts existing documents, but does not + reset ``paddingFactor`` statistics for the collection. After the + :dbcommand:`compact` MongoDB will use the existing + ``paddingFactor`` when allocating new records for documents in + this collection. + :param paddingBytes: .. versionadded:: 2.2 - The ``paddingBytes`` sets the padding as an absolute number - of bytes. Specifying ``paddingBytes`` can be useful if your + The ``paddingBytes`` sets the padding as an absolute number of + bytes, for all records compacted during the :dbcommand:`compact` + operation. After running :dbcommand:`compact`, ``paddingBytes`` + does not affect the padding of subsequent record allocations. + + Specifying ``paddingBytes`` can be useful if your documents start small but then increase in size significantly. For example,if your documents are initially 40 bytes long and you grow them by 1KB, using @@ -113,13 +128,12 @@ compact :program:`mongod` log file, or by running the :method:`db.currentOp()` in another shell instance. - - :dbcommand:`compact` removes any :term:`padding factor` in the - collection when issued without either the - ``paddingFactor`` option or the ``paddingBytes`` option. This may - impact performance if the documents grow regularly. However, - :dbcommand:`compact` retains - existing paddingFactor statistics for the collection that MongoDB - will use to calculate the padding factor for future inserts. + - :dbcommand:`compact` compacts existing documents in the + collection. However, unlike :dbcommand:`repairDatabase`, + :dbcommand:`compact` does not reset ``paddingFactor`` statistics + for the collection. MongoDB will use the existing + ``paddingFactor`` when allocating new records for documents in + this collection. - :dbcommand:`compact` generally uses less disk space than :dbcommand:`repairDatabase` and is faster. However,the diff --git a/source/reference/command/cursorInfo.txt b/source/reference/command/cursorInfo.txt index 2242d516b34..d95008937f2 100644 --- a/source/reference/command/cursorInfo.txt +++ b/source/reference/command/cursorInfo.txt @@ -13,7 +13,7 @@ cursorInfo { cursorInfo: 1 } - The value (e.g. ``1`` above,) does not effect the output of the + The value (e.g. ``1`` above,) does not affect the output of the command. :dbcommand:`cursorInfo` returns the total number of open cursors diff --git a/source/reference/command/geoNear.txt b/source/reference/command/geoNear.txt index 6f0ce07658b..c3b7ea3d594 100644 --- a/source/reference/command/geoNear.txt +++ b/source/reference/command/geoNear.txt @@ -7,7 +7,7 @@ geoNear .. dbcommand:: geoNear The :dbcommand:`geoNear` command provides an alternative to the - :operator :`$near` operator. In addition to the + :operator:`$near` operator. In addition to the functionality of :operator:`$near`, :dbcommand:`geoNear` returns the distance of each item from the specified point along with additional diagnostic information. For example: @@ -28,7 +28,12 @@ geoNear return. The default value is 100. :field maxDistance: Optional. Limits the results to those falling within - a given distance of the center coordinate. + a given distance of the center coordinate. For + `GeoJSON `_ + data distance is in meters. For :ref:`grid + coordinate + ` data + distance is in radians. :field query: Optional. Further narrows the results using any standard MongoDB query operator or selection. See :method:`db.collection.find()` diff --git a/source/reference/command/listDatabases.txt b/source/reference/command/listDatabases.txt index 6ae718392be..07a24bb5957 100644 --- a/source/reference/command/listDatabases.txt +++ b/source/reference/command/listDatabases.txt @@ -13,7 +13,7 @@ listDatabases { listDatabases: 1 } - The value (e.g. ``1``) does not effect the output of the + The value (e.g. ``1``) does not affect the output of the command. :dbcommand:`listDatabases` returns a document for each database Each document contains a ``name`` field with the database name, a ``sizeOnDisk`` field with the total size of the database diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index bf28cabd638..04e716b13fc 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -36,7 +36,7 @@ moveChunk :param boolean _secondaryThrottle: - Optional. Set to ``false`` by default. If set to ``true``, the + Optional. Set to ``true`` by default. When ``true``, the balancer waits for replication to :term:`secondaries ` while copying and deleting data during migrations. For details, see diff --git a/source/reference/command/shardingState.txt b/source/reference/command/shardingState.txt index 870acbd9adb..3f3cc7f5a0c 100644 --- a/source/reference/command/shardingState.txt +++ b/source/reference/command/shardingState.txt @@ -6,14 +6,61 @@ shardingState .. dbcommand:: shardingState - The :dbcommand:`shardingState` command returns ``true`` if the - :program:`mongod` instance is a member of a sharded cluster. Run the - command using the following syntax: + :dbcommand:`shardingState` is an admin command that reports if + :program:`mongod` is a member of a :term:`sharded cluster`. + :dbcommand:`shardingState` has the following prototype form: .. code-block:: javascript { shardingState: 1 } + For :dbcommand:`shardingState` to detect that a :program:`mongod` + is a member of a sharded cluster, the :program:`mongod` must + satisfy the following conditions: + + #. the :program:`mongod` is a primary member of a replica set, and + + #. the :program:`mongod` instance is a member of a sharded + cluster. + + If :dbcommand:`shardingState` detects that a :program:`mongod` is a + member of a sharded cluster, :dbcommand:`shardingState` returns a + document that resembles the following prototype: + + .. code-block:: javascript + + { + "enabled" : true, + "configServer" : "", + "shardName" : "", + "shardHost" : "string:", + "versions" : { + "." : Timestamp(<...>), + "." : Timestamp(<...>) + }, + "ok" : 1 + } + + Otherwise, :dbcommand:`shardingState` will return the following + document: + + .. code-block:: javascript + + { "note" : "from execCommand", "ok" : 0, "errmsg" : "not master" } + + The response from :dbcommand:`shardingState` when used with a + :term:`config server ` is: + + .. code-block:: javascript + + { "enabled": false, "ok": 1 } + + + .. note:: + + :program:`mongos` instances do not provide the + :dbcommand:`shardingState`. + .. warning:: This command obtains a write lock on the affected database and diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index a60d50c2817..83aa8845c23 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -102,7 +102,7 @@ Settings Specifies a TCP port for the :program:`mongod` or :program:`mongos` instance to listen for client connections. UNIX-like systems - require root access for ports with numbers lower than 1000. + require root access for ports with numbers lower than 1024. .. setting:: bind_ip @@ -142,12 +142,28 @@ Settings .. setting:: objcheck + *Default:* true + + .. versionchanged:: 2.4 + The default setting for :setting:`objcheck` became ``true`` in + 2.4. In earlier versions :setting:`objcheck` was ``false`` by + default. + + Forces the :program:`mongod` to validate all requests from clients + upon receipt to ensure that clients never insert invalid documents + into the database. For objects with a high degree of sub-document + nesting, :setting:`objcheck` can have a small impact on + performance. You can set :setting:`noobjcheck` to disable object + checking at run-time. + +.. setting:: noobjcheck + + .. versionadded:: 2.4 + *Default:* false - Set to ``true`` to force :program:`mongod` to validate all requests - from clients upon receipt to ensure that invalid :term:`BSON` - objects are never inserted into the database. :program:`mongod` - does not enable this by default because of the required overhead. + Disables the default object validation that MongoDB performs on all + incoming BSON documents. .. setting:: logpath @@ -605,7 +621,7 @@ Settings mode that attempts to limit the amount of output. This option suppresses: - output from :term:`database commands `, - including :dbcommand:`drop`, :dbcommand:`dropIndexs`, + including :dbcommand:`drop`, :dbcommand:`dropIndexes`, :dbcommand:`diagLogging`, :dbcommand:`validate`, and :dbcommand:`clean`. @@ -634,7 +650,7 @@ Settings .. include:: /includes/list-set-parameters.rst Replication Options -``````````````````` +~~~~~~~~~~~~~~~~~~~ .. setting:: replSet @@ -696,7 +712,7 @@ Replication Options loading *any* index into memory. Master/Slave Replication -```````````````````````` +~~~~~~~~~~~~~~~~~~~~~~~~ .. setting:: master @@ -753,8 +769,8 @@ Master/Slave Replication option, the slave will not attempt an automatic resync more than once in a ten minute period. -Sharding Cluster Options -```````````````````````` +Sharded Cluster Options +~~~~~~~~~~~~~~~~~~~~~~~ .. setting:: configsvr @@ -907,3 +923,9 @@ Sharding Cluster Options With :setting:`noAutoSplit` enabled, the data in your sharded cluster may become imbalanced over time. Enable with caution. + +SSL Options +~~~~~~~~~~~ + +.. |binary-name| replace:: :program:`mongod` or :program:`mongos` +.. include:: /includes/manpage-options-ssl-settings.rst diff --git a/source/reference/connection-pool-stats.txt b/source/reference/connection-pool-stats.txt index 8076deb3542..a1e391fdd3d 100644 --- a/source/reference/connection-pool-stats.txt +++ b/source/reference/connection-pool-stats.txt @@ -151,8 +151,7 @@ Output :data:`~connPoolStats.totalAvailable` reports the running total of connections from the :program:`mongos` or :program:`mongod` to all :program:`mongod` instances in - the :term:`sharded cluster` available for use. This value does not - reflect those connections that + the :term:`sharded cluster` available for use. .. data:: connPoolStats.totalCreated diff --git a/source/reference/explain.txt b/source/reference/explain.txt index 74a733df295..161e71cfa5d 100644 --- a/source/reference/explain.txt +++ b/source/reference/explain.txt @@ -190,8 +190,6 @@ Core Explain Output .. data:: explain.scanAndOrder - .. versionadded:: 2.2 - :data:`~explain.scanAndOrder` is a boolean that is ``true`` when the query **cannot** use the index for returning sorted results. diff --git a/source/reference/geospatial-queries.txt b/source/reference/geospatial-queries.txt new file mode 100644 index 00000000000..6bb27240aa9 --- /dev/null +++ b/source/reference/geospatial-queries.txt @@ -0,0 +1,13 @@ +==================================== +Geospatial Query Compatibility Chart +==================================== + +.. default-domain:: mongodb + +While numerous combinations of query operators are possible, the +following table shows the recommended operators for different types of +queries. The table uses the :operator:`$geoWithin`, :operator:`$geoIntersects` +and :operator:`$near` operators. + +.. include:: /includes/table-geospatial-queries.rst + diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 5816f752bc0..2344e11fe0c 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -170,13 +170,13 @@ Glossary MongoDB's :term:`geospatial` indexes and querying system allow you to build queries around multi-sided polygons on two-dimensional coordinate systems. These queries use - the :operator:`$within` operator and a sequence of points that define + the :operator:`$geoWithin` operator and a sequence of points that define the corners of the polygon. circle MongoDB's :term:`geospatial` indexes and querying system allow you to build queries around circles on two-dimensional - coordinate systems. These queries use the :operator:`$within` operator + coordinate systems. These queries use the :operator:`$geoWithin` operator and the :operator:`$center` operator to define a circle using the center and the radius of the circle. diff --git a/source/reference/method/sh.addTagRange.txt b/source/reference/method/sh.addTagRange.txt index 7ed440ed968..39281165287 100644 --- a/source/reference/method/sh.addTagRange.txt +++ b/source/reference/method/sh.addTagRange.txt @@ -37,21 +37,29 @@ sh.addTagRange() Always issue :method:`sh.addTagRange()` when connected to a :program:`mongos` instance. - - .. example:: - + + .. note:: + + If you add a tag range to a collection using + :method:`sh.addTagRange()`, and then later drop the collection + or its database, MongoDB does not remove tag association. If you + later create a new collection with the same name, the old tag + association will apply to the new collection. + + .. example:: + Given a shard key of ``{STATE:1,ZIP:1}``, create a tag range covering ZIP codes in New York State: - + .. code-block:: javascript - - sh.addTagRange( "exampledb.collection", - {STATE: "NY", ZIP: {minKey:1}}, - {STATE:"NY", ZIP: {maxKey:1}}, + + sh.addTagRange( "exampledb.collection", + {STATE: "NY", ZIP: {minKey:1}}, + {STATE:"NY", ZIP: {maxKey:1}}, "NY" ) - - + + .. seealso:: :method:`sh.addShardTag()`, diff --git a/source/reference/mongo.txt b/source/reference/mongo.txt index 5b0e6466575..2f9e19fa084 100644 --- a/source/reference/mongo.txt +++ b/source/reference/mongo.txt @@ -112,6 +112,49 @@ Options password interactively, if the :program:`mongod` or :program:`mongos` requires authentication. +.. |binary-name| replace:: :program:`mongo` +.. include:: /includes/manpage-options-auth-mongo.rst + +.. option:: --ssl + + Enable connection to a :program:`mongod` or + :program:`mongos` that has SSL encryption. + +.. option:: --sslPEMKeyFile + + .. versionadded:: 2.4 + + .. include:: /includes/replace-pem-path-name.rst + + .. include:: /includes/note-general-ssl-support.rst + + Specifies the :file:`.pem` file that contains both the SSL + certificate and key. |pem-path-name| + + Required when using the :option:`--ssl` option if the + :program:`mongod` or :program:`mongos` has :setting:`sslCAFile` + enabled *without* :setting:`sslWeakCertificateValidation`. + +.. option:: --sslPEMKeyPassword + + .. versionadded:: 2.4 + + .. include:: /includes/note-general-ssl-support.rst + + Specifies the password to decrypt the root certificate chain + specified by :option:`--sslPEMKeyFile`. + + Only required if the certificate-key file is encrypted. + +.. option:: --sslCAFile + + .. versionadded:: 2.4 + + .. include:: /includes/note-general-ssl-support.rst + + Specifies the :file:`.pem` file that contains the certificate from + the Certificate Authority. |pem-path-name| + .. option:: --help, -h Returns a basic help and usage text. @@ -132,6 +175,8 @@ Options and processes, including :program:`mongo`, disable IPv6 support by default. +.. _mongo-db-address: + .. option:: Specifies the "database address" of the database to connect to. For diff --git a/source/reference/mongod.txt b/source/reference/mongod.txt index a2e16018263..a91861fd22f 100644 --- a/source/reference/mongod.txt +++ b/source/reference/mongod.txt @@ -74,7 +74,7 @@ Options port 27017. UNIX-like systems require root privileges to use ports with numbers - lower than 1000. + lower than 1024. .. option:: --bind_ip @@ -98,9 +98,23 @@ Options .. option:: --objcheck Forces the :program:`mongod` to validate all requests from clients - upon receipt to ensure that invalid objects are never inserted into - the database. Enabling this option will produce some performance - impact, and is not enabled by default. + upon receipt to ensure that clients never insert invalid documents + into the database. For objects with a high degree of sub-document + nesting, :option:`--objcheck` can have a small impact on + performance. You can set :option:`--noobjcheck` to disable object + checking at run-time. + + .. versionchanged:: 2.4 + MongoDB enables :option:`--objcheck` by default, to prevent any + client from inserting malformed or invalid BSON into a MongoDB + database. + +.. option:: --noobjcheck + + .. versionadded:: 2.4 + + Disables the default document validation that MongoDB performs on all + incoming BSON documents. .. option:: --logpath @@ -625,6 +639,15 @@ Sharding Cluster Options the "from" server during migrations as "paranoid mode." Setting this option disables this paranoia. +SSL Options +``````````` + +.. see:: :doc:`/administration/ssl` for full documentation of + MongoDB's support. + +.. |binary-name| replace:: :program:`mongod` +.. include:: /includes/manpage-options-ssl.rst + Usage ----- diff --git a/source/reference/mongodump.txt b/source/reference/mongodump.txt index 55b8e57c08d..d12c95bae9c 100644 --- a/source/reference/mongodump.txt +++ b/source/reference/mongodump.txt @@ -92,7 +92,7 @@ Options :option:`--password ` option to supply a password. -.. option:: --password +.. option:: --password , -p Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the :option:`--username ` @@ -102,6 +102,9 @@ Options without the :option:`--password` option, :program:`mongodump` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongodump` +.. include:: /includes/manpage-options-auth.rst + .. option:: --dbpath Specifies the directory of the MongoDB data files. If used, the diff --git a/source/reference/mongoexport.txt b/source/reference/mongoexport.txt index bfa2ff52e3c..1f26e5848a3 100644 --- a/source/reference/mongoexport.txt +++ b/source/reference/mongoexport.txt @@ -84,7 +84,7 @@ Options database requires authentication. Use in conjunction with the :option:`mongoexport --password` option to supply a password. -.. option:: --password +.. option:: --password , -p Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the :option:`--username ` @@ -94,6 +94,9 @@ Options without the :option:`--password` option, :program:`mongoexport` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongoexport` +.. include:: /includes/manpage-options-auth.rst + .. option:: --dbpath Specifies the directory of the MongoDB data files. If used, the @@ -177,6 +180,29 @@ Options name, the :program:`mongoexport` writes data to standard output (e.g. ``stdout``). +.. option:: --forceTableScan + + .. versionadded:: 2.2 + + Forces :program:`mongoexport` to scan the data store directly: + typically, :program:`mongoexport` saves entries as they appear in the + index of the ``_id`` field. Use :option:`--forceTableScan` to skip + the index and scan the data directly. Typically there are two cases + where this behavior is preferable to the default: + + 1. If you have key sizes over 800 bytes that would not be present + in the ``_id`` index. + + 2. Your database uses a custom ``_id`` field. + + When you run with :option:`--forceTableScan`, :program:`mongoexport` + does not use :operator:`$snapshot`. As a result, the export produced + by :program:`mongoexport` can reflect the state of the database at + many different points in time. + + .. warning:: Use :option:`--forceTableScan` with extreme caution + and consideration. + Usage ----- diff --git a/source/reference/mongofiles.txt b/source/reference/mongofiles.txt index c190b35dd4e..c3a114663b6 100644 --- a/source/reference/mongofiles.txt +++ b/source/reference/mongofiles.txt @@ -138,7 +138,7 @@ Options database requires authentication. Use in conjunction with the :option:`mongofiles --password` option to supply a password. -.. option:: --password +.. option:: --password , -p Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the :option:`mongofiles --username` option to @@ -148,6 +148,9 @@ Options without the :option:`--password` option, :program:`mongofiles` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongofiles` +.. include:: /includes/manpage-options-auth.rst + .. option:: --dbpath Specifies the directory of the MongoDB data files. If used, the diff --git a/source/reference/mongoimport.txt b/source/reference/mongoimport.txt index eef6d64eafd..4fa39aae1ea 100644 --- a/source/reference/mongoimport.txt +++ b/source/reference/mongoimport.txt @@ -96,7 +96,7 @@ Options database requires authentication. Use in conjunction with the :option:`mongoimport --password` option to supply a password. -.. option:: --password +.. option:: --password , -p Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the :option:`mongoimport --username` option to @@ -106,6 +106,9 @@ Options without the :option:`--password` option, :program:`mongoimport` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongoimport` +.. include:: /includes/manpage-options-auth.rst + .. option:: --dbpath Specifies the directory of the MongoDB data files. If used, the @@ -151,20 +154,19 @@ Options restore data into a MongoDB instance that already has data, or to restore only some data in the specified imported data set. -.. option:: --fields , -f +.. option:: --fields >, -f - Specify a field or number fields to *import* from the specified - file. All other fields present in the export will be *excluded* - during importation. Comma separate a list of fields to limit the - fields imported. + Specify a comma seperatedlist of field names when importing + :term:`csv` or :term:`tsv` files that do not have field names in + the first (i.e. header) line of the file. .. option:: --fieldFile - As an alternative to ":option:`mongoimport --fields`" the - :option:`--fieldFile` option allows you to specify a file - (e.g. `````) to hold a list of field names to specify a list - of fields to *include* in the export. All other fields will be - *excluded* from the export. Place one field per line. + As an alternative to ":option:`--fields`" the :option:`--fieldFile` + option allows you to specify a file (e.g. `````) to that + holds a list of field names if your :term:`csv:` or :term:`tsv` + file does not include field names in the first (i.e. header) line + of the file. Place one field per line. .. option:: --ignoreBlanks diff --git a/source/reference/mongooplog.txt b/source/reference/mongooplog.txt index a0aedfb85ec..54396f2a78c 100644 --- a/source/reference/mongooplog.txt +++ b/source/reference/mongooplog.txt @@ -122,6 +122,9 @@ Options without the :option:`--password` option, :program:`mongooplog` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongooplog` +.. include:: /includes/manpage-options-auth.rst + .. option:: --dbpath Specifies a directory, containing MongoDB data files, to which diff --git a/source/reference/mongoperf.txt b/source/reference/mongoperf.txt index c22ff3849f6..dcbadccc3fd 100644 --- a/source/reference/mongoperf.txt +++ b/source/reference/mongoperf.txt @@ -54,7 +54,7 @@ Options .. code-block:: sh - mongperf < config + mongoperf < config In this example ``config`` is the name of a file that holds a JSON document that resembles the following example: diff --git a/source/reference/mongorestore.txt b/source/reference/mongorestore.txt index 1c5a95d827c..34bc3fa4931 100644 --- a/source/reference/mongorestore.txt +++ b/source/reference/mongorestore.txt @@ -96,7 +96,7 @@ Options :option:`--password ` option to supply a password. -.. option:: --password +.. option:: --password , -p Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the :option:`mongorestore --username` option to @@ -106,6 +106,9 @@ Options without the :option:`--password` option, :program:`mongorestore` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongorestore` +.. include:: /includes/manpage-options-auth.rst + .. option:: --dbpath Specifies the directory of the MongoDB data files. If used, the @@ -159,11 +162,24 @@ Options .. option:: --objcheck - Verifies each object as a valid :term:`BSON` object before inserting - it into the target database. If the object is not a valid - :term:`BSON` object, :program:`mongorestore` will not insert the - object into the target database and stop processing remaining - documents for import. This option has some performance impact. + Forces the :program:`mongorestore` to validate all requests from + clients upon receipt to ensure that clients never insert invalid + documents into the database. For objects with a high degree of + sub-document nesting, :option:`--objcheck` can have a small impact + on performance. You can set :option:`--noobjcheck` to disable + object checking at run-time. + + .. versionchanged:: 2.4 + MongoDB enables :option:`--objcheck` by default, to prevent any + client from inserting malformed or invalid BSON into a MongoDB + database. + +.. option:: --noobjcheck + + .. versionadded:: 2.4 + + Disables the default document validation that MongoDB performs on all + incoming BSON documents. .. option:: --filter '' diff --git a/source/reference/mongos.txt b/source/reference/mongos.txt index f2fe620256e..c949dd3bc1a 100644 --- a/source/reference/mongos.txt +++ b/source/reference/mongos.txt @@ -75,7 +75,7 @@ Options port 27017. UNIX-like systems require root access to access ports with numbers - lower than 1000. + lower than 1024. .. option:: --bind_ip @@ -298,3 +298,12 @@ Options With :option:`--noAutoSplit` enabled, the data in your sharded cluster may become imbalanced over time. Enable with caution. + +SSL Options +~~~~~~~~~~~ + +.. see:: :doc:`/administration/ssl` for full documentation of + MongoDB's support. + +.. |binary-name| replace:: :program:`mongos` +.. include:: /includes/manpage-options-auth.rst diff --git a/source/reference/mongostat.txt b/source/reference/mongostat.txt index 9ddaac39e94..850a342fad2 100644 --- a/source/reference/mongostat.txt +++ b/source/reference/mongostat.txt @@ -96,7 +96,7 @@ Options database requires authentication. Use in conjunction with the :option:`mongostat --password` option to supply a password. -.. option:: --password +.. option:: --password , -p Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the :option:`mongostat --username` option to @@ -106,6 +106,9 @@ Options without the :option:`--password` option, :program:`mongostat` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongostat` +.. include:: /includes/manpage-options-auth.rst + .. option:: --noheaders Disables the output of column or field names. diff --git a/source/reference/mongotop.txt b/source/reference/mongotop.txt index e643f895b59..03b8510eae1 100644 --- a/source/reference/mongotop.txt +++ b/source/reference/mongotop.txt @@ -85,7 +85,7 @@ Options :option:`mongotop ` option to supply a password. -.. option:: --password +.. option:: --password , -p Specifies a password to authenticate to the MongoDB instance. Use in conjunction with the :option:`--username ` @@ -95,6 +95,9 @@ Options the :option:`--password` option, :program:`mongotop` will prompt for a password interactively. +.. |binary-name| replace:: :program:`mongotop` +.. include:: /includes/manpage-options-auth.rst + .. option:: --locks .. versionadded:: 2.2 diff --git a/source/reference/operator/box.txt b/source/reference/operator/box.txt index 1d08a7c12fc..6a2f79f568a 100644 --- a/source/reference/operator/box.txt +++ b/source/reference/operator/box.txt @@ -8,17 +8,36 @@ $box .. versionadded:: 1.4 - The :operator:`$box` operator specifies a rectangular shape for the - :operator:`$within` operator in :term:`geospatial` queries. To use - the :operator:`$box` operator, you must specify the bottom left and - top right corners of the rectangle in an array object. Consider the - following example: + The :operator:`$box` operator specifies a rectangle for a + :term:`geospatial` :operator:`$geoWithin` query. The query returns + documents that are within the bounds of the rectangle, according to + their point-based location data. The :operator:`$box` operator + returns documents based on :ref:`grid coordinates + ` and does *not* query for + GeoJSON shapes. + + The query calculates distances using planar geometry. The ``2d`` + geospatial index supports the :operator:`$box` operator. + + To use the :operator:`$box` operator, you must specify the bottom + left and top right corners of the rectangle in an array object. + Use the following syntax: .. code-block:: javascript - db.collection.find( { loc: { $within: { $box: [ [0,0], [100,100] ] } } } ) + { : { $geoWithin : { $box : + [ [ ] , + [ ] ] } } } + + .. important:: If you use longitude and latitude, specify **longitude first**. + + The following example query returns all documents that are within the + box having points at: ``[ 0 , 0 ]``, ``[ 0 , 100 ]``, ``[ 100 , 0 ]``, and ``[ 100 , 100 ]``. + + .. code-block:: javascript - This will return all the documents that are within the box having - points at: ``[0,0]``, ``[0,100]``, ``[100,0]``, and ``[100,100]``. + db.places.find( { loc : { $geoWithin : { $box : + [ [ 0 , 0 ] , + [ 100 , 100 ] ] } } } ) .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/center.txt b/source/reference/operator/center.txt index 6364e293d30..0b01f902bd3 100644 --- a/source/reference/operator/center.txt +++ b/source/reference/operator/center.txt @@ -8,21 +8,41 @@ $center .. versionadded:: 1.4 - This specifies a circle shape for the :operator:`$within` operator - in :term:`geospatial` queries. To define the bounds of a query - using :operator:`$center`, you must specify: + The :operator:`$center` operator specifies a circle for a + :term:`geospatial` :operator:`$geoWithin` query. The query returns + documents that are within the bounds of the circle, according to + their point-based location data. The :operator:`$center` operator + returns documents based on :ref:`grid coordinates + ` and does *not* query for + GeoJSON shapes. - - the center point, and + The query calculates distances using planar geometry. The ``2d`` + geospatial index supports the :operator:`$center` operator. - - the radius + To use the :operator:`$center` operator, specify an array that + contains: - Considering the following example: + - The grid coordinates of the circle's center point + + - The circle's radius, as measured in the units used by the + coordinate system + + .. important:: If you use longitude and latitude, specify **longitude first**. + + Use the following syntax: .. code-block:: javascript - db.collection.find( { location: { $within: { $center: [ [0,0], 10 ] } } } ); + { : { $geoWithin : { $center : [ [ , ] , ] } } } + + The following example query returns all documents that have + coordinates that exist within the circle centered on ``[ -74 , 40.74 ]`` + and with a radius of ``10``: + + .. code-block:: javascript - The above command returns all the documents that fall within a - 10 unit radius of the point ``[0,0]``. + db.places.find( { loc: { $geoWithin : + { $center : [ [-74, 40.74], 10 ] } + } } ) .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/centerSphere.txt b/source/reference/operator/centerSphere.txt index ce74670dd77..9821bbf8753 100644 --- a/source/reference/operator/centerSphere.txt +++ b/source/reference/operator/centerSphere.txt @@ -8,38 +8,47 @@ $centerSphere .. versionadded:: 1.8 - The :operator:`$centerSphere` operator is the spherical equivalent - of the :operator:`$center` operator. :operator:`$centerSphere` uses - spherical geometry to define a circle for use by the - :operator:`$within` operator in :term:`geospatial` queries. + The :operator:`$centerSphere` operator defines a circle for a + :term:`geospatial` query that uses spherical geometry. The query + returns documents that are within the bounds of the circle, according to + their point-based location data. The :operator:`$centerSphere` operator + returns documents based on :ref:`grid coordinates + ` and does *not* query for + GeoJSON shapes. - To define the bounds of a query using :operator:`$centerSphere`, you - must specify: + The ``2d`` and ``2dsphere`` geospatial indexes both support + :operator:`$centerSphere`. You can use the :operator:`$centerSphere` + operator on both `GeoJSON objects + `_ and grid coordinates. - - The center point + To use :operator:`$centerSphere`, specify an array that contains: - - The angular distance in radians (distance along the surface of the - earth). + - The grid coordinates of the circle's center point - Consider the following prototype: + - The circle's radius measured in radians. To calculate radians, see + :doc:`/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes`. + + Use the following syntax: .. code-block:: javascript - db.collection.find( { loc: { $within: - { $centerSphere: - [ [,], / ] - } } } ) + db..find( { : + { $geoWithin : + { $centerSphere : [ [ , ] , ] } + } } ) + + .. important:: If you use longitude and latitude, specify **longitude first**. - The following example returns all documents within a 10 mile radius - of longitude ``88 W`` and latitude ``30 N``. MongoDB converts the - distance, 10 miles, to radians by dividing by the approximate - radius of the earth, 3959 miles: + The following example queries grid coordinates and returns all + documents within a 10 mile radius of longitude ``88 W`` and latitude + ``30 N``. MongoDB converts the distance, 10 miles, to radians by + dividing by the approximate radius of the earth, 3959 miles: .. code-block:: javascript - db.collection.find( { loc: { $within: - { $centerSphere: - [ [88,30], 10 / 3959 ] - } } } ) + db.collection.find( { loc : { $geoWithin : + { $centerSphere : + [ [ 88 , 30 ] , 10 / 3959 ] + } } } ) .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/each.txt b/source/reference/operator/each.txt index 4059ee395e4..97120b7e1ad 100644 --- a/source/reference/operator/each.txt +++ b/source/reference/operator/each.txt @@ -2,21 +2,44 @@ $each ===== +.. default-domain:: mongodb + .. note:: - The :mongodb:operator:`$each` operator is only used with the - :mongodb:operator:`$addToSet` see the documentation of - :doc:`/reference/operator/addToSet` for more information. - -.. default-domain:: mongodb + The :operator:`$each` modifier is only used with the + :operator:`$addToSet` and :operator:`$push` operators. + See the documentation of :operator:`$addToSet` and :operator:`$push` + for more information. .. operator:: $each - The :operator:`$each` operator is available within the - :operator:`$addToSet`, which allows you to add multiple values - to the array if they do not exist in the ``field`` array in a - single operation. Consider the following prototype: + The :operator:`$each` modifier is available for use with the + :operator:`$addToSet` operator and the :operator:`$push` + operator. + + - Use the :operator:`$each` modifier with the :operator:`$addToSet` + operator to add multiple values to an array ```` if the + values do not exist in the ````. + + .. code-block:: javascript + + db.collection.update( , + { + $addToSet: { : { $each: [ , ... ] } } + } + ) + + - Use the :operator:`$each` modifier with the :operator:`$push` + operator to append multiple values to an array ````. + + .. code-block:: javascript - .. code-block:: javascript + db.collection.update( , + { + $push: { : { $each: [ , ... ] } } + } + ) - db.collection.update( { field: value }, { $addToSet: { field: { $each : [ value1, value2, value3 ] } } } ); + .. versionchanged:: 2.4 + MongoDB adds support for the :operator:`$each` modifier to the + :operator:`$push` operator. diff --git a/source/reference/operator/geoIntersects.txt b/source/reference/operator/geoIntersects.txt new file mode 100644 index 00000000000..29e8c35c365 --- /dev/null +++ b/source/reference/operator/geoIntersects.txt @@ -0,0 +1,45 @@ +============== +$geoIntersects +============== + +.. default-domain:: mongodb + +.. operator:: $geoIntersects + + .. versionadded:: 2.4 + + The :operator:`$geoIntersects` operator selects all indexed points + that intersect with a + `GeoJSON object `_. + The :operator:`$geoIntersects` operator uses spherical geometry. The + ``2dsphere`` geospatial index supports :operator:`$geoIntersects`. + + Pass the GeoJSON object to :operator:`$geoIntersects` through the + :operator:`$geometry` operator. Use the following syntax: + + .. code-block:: javascript + + db..find( { : + { $geoIntersects : + { $geometry : + { type : "Point|LineString|Polygon" , + coordinates : [ ] + } } } } ) + + .. important:: Specify coordinates in this order: **"longitude, latitude."** + + The following example uses :operator:`$geoIntersects` to select all + indexed points and shapes that intersect with the polygon defined by + the ``coordinates`` array. + + .. code-block:: javascript + + db.places.find( { loc : + { $geoIntersects : + { $geometry : + { type : "Polygon" , + coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] } + } } } } ) + + The query returns true if the intersection between shapes is + non-empty. This includes documents that have a shared edge. diff --git a/source/reference/operator/geoWithin.txt b/source/reference/operator/geoWithin.txt new file mode 100644 index 00000000000..ba4c4ba331c --- /dev/null +++ b/source/reference/operator/geoWithin.txt @@ -0,0 +1,80 @@ +========== +$geoWithin +========== + +.. default-domain:: mongodb + +.. operator:: $geoWithin + + .. versionadded:: 2.4 + + The :operator:`$geoWithin` operator is a geospatial query operator + that queries for a defined point, line or shape that exists entirely + within another defined shape. When determining inclusion, MongoDB + considers the border of a shape to be part of the shape (subject to + the precision of floating point numbers). + + The :operator:`$geoWithin` operator queries for inclusion in a + `GeoJSON `_ polygon or a shape + defined by legacy coordinate pairs. + + The :operator:`$geoWithin` operator does not return sorted results. + As a result MongoDB can return :operator:`$geoWithin` queries more + quickly than geospatial :operator:`$near` or :operator:`$nearSphere` + queries, which sort results. + + The ``2dsphere`` and ``2d`` indexes both support the + :operator:`$geoWithin` operator. + + If querying for inclusion in a GeoJSON polygon on a sphere, pass the polygon to + :operator:`$geoWithin` through the :operator:`$geometry` operator + using the following syntax: + + .. code-block:: javascript + + db..find( { : + { $geoWithin : + { $geometry : + { type : "Polygon" , + coordinates : [ [ [ , ], [ , ] ...] ] + } } } } ) + + .. important:: Specify coordinates in this order: **"longitude, latitude."** + + The following example selects all indexed points and shapes that + exist entirely within a GeoJSON polygon: + + .. code-block:: javascript + + db.places.find( { loc : + { $geoWithin : + { $geometry : + { type : "Polygon" , + coordinates: [ [ [ 0 , 0 ] , [ 3 , 6 ] , [ 6 , 1 ] , [ 0 , 0 ] ] ] + } } } } ) + + If querying for inclusion in a shape defined by grid coordinates on a plane, use + the following syntax: + + .. code-block:: javascript + + db..find( { : + { $geoWithin : + { $box|$polygon|$center|$centerSphere : + } } } ) + + For specific syntax for a shape, see the shape: + + - :operator:`$box` + + - :operator:`$polygon` + + - :operator:`$center` (defines a circle) + + - :operator:`$centerSphere` (defines a circle on a sphere) + +.. operator:: $within + + .. deprecated:: 2.4 + In 2.4, :operator:`$geoWithin` replaces :operator:`$within`. + \ No newline at end of file diff --git a/source/reference/operator/geometry.txt b/source/reference/operator/geometry.txt new file mode 100644 index 00000000000..bc573b6b01d --- /dev/null +++ b/source/reference/operator/geometry.txt @@ -0,0 +1,20 @@ +========= +$geometry +========= + +.. default-domain:: mongodb + +.. operator:: $geometry + + .. versionadded:: 2.4 + + The :operator:`$geometry` operator specifies a `GeoJSON object + `_ for a geospatial query + operators. For details on using :operator:`$geometry` with an + operator, see the operator: + + - :operator:`$near` + + - :operator:`$geoWithin` + + - :operator:`$geoIntersects` diff --git a/source/reference/operator/maxDistance.txt b/source/reference/operator/maxDistance.txt index 9f8f527bd0c..a1228f31900 100644 --- a/source/reference/operator/maxDistance.txt +++ b/source/reference/operator/maxDistance.txt @@ -6,23 +6,25 @@ $maxDistance .. operator:: $maxDistance - The :operator:`$maxDistance` operator specifies an upper bound to limit - the results of a geolocation query. See below, where the - :operator:`$maxDistance` operator narrows the results of the - :operator:`$near` query: + The :operator:`$maxDistance` operator specifies a maximum distance + for which to return the results of a geospatial :operator:`$near` or + :operator:`$nearSphere` query. Specify the maximum distance in the + units specified by the coordinate system. For + `GeoJSON `_ ``Point`` objects, + specify the distance in meters, not radians. - .. code-block:: javascript + The ``2d`` and ``2dsphere`` geospatial indexes both support + :operator:`$maxDistance`. - db.collection.find( { location: { $near: [100,100], $maxDistance: 10 } } ); + The following example query returns documents with location values + that are ``10`` or fewer units from the point ``[ 100 , 100 ]``. - This query will return documents with ``location`` fields from - ``collection`` that have values with a distance of 5 or fewer units - from the point ``[100,100]``. :operator:`$near` returns results - ordered by their distance from ``[100,100]``. This operation will - return the first 100 results unless you modify the query with the - :method:`cursor.limit()` method. + .. code-block:: javascript - Specify the value of the :operator:`$maxDistance` argument in the - same units as the document coordinate system. + db.collection.find( { loc : { $near : [ 100 , 100 ] , + $maxDistance: 10 } + } ) - .. include:: /includes/note-geospatial-index-must-exist.rst + MongoDB orders the results by their distance from ``[ 100 , 100 ]``. + The operation returns the first 100 results, unless you modify the + query with the :method:`cursor.limit()` method. diff --git a/source/reference/operator/near.txt b/source/reference/operator/near.txt index 25c75a487f9..294c59b1406 100644 --- a/source/reference/operator/near.txt +++ b/source/reference/operator/near.txt @@ -4,28 +4,85 @@ $near .. default-domain:: mongodb +.. operator:: $geoNear + .. operator:: $near - The :operator:`$near` operator takes an argument, coordinates for a - point in the form of ``[x, y]``, and returns a list of objects - sorted by distance from nearest to farthest with respect to those - coordinates. See the following example: + .. versionchanged:: 2.4 + + The :operator:`$near` operator specifies a point for which a + :term:`geospatial` query returns the 100 closest documents. The query + sorts the documents from nearest to farthest. + + The :operator:`$near` operator can query for a `GeoJSON + `_ point or for a point defined + by :ref:`grid coordinates + `. + + The :operator:`$near` operator requires a geospatial index. For + GeoJSON points, :operator:`$near` uses a ``2dsphere`` index. For grid + coordinates, :operator:`$near` uses a ``2d`` index. + + The optional :operator:`$maxDistance` operator limits a + :operator:`$near` query to return only those documents that fall + within a maximum distance of a point. Specify the maximum distance in + the units specified by the coordinate system. For a GeoJSON point, + specify the distance in meters, not radians. + + If querying for GeoJSON data, use the following syntax: + + .. code-block:: javascript + + db..find( { : + { $near : + { $geometry : + { type : "Point" , + coordinates : [ , ] } , + $maxDistance : + } } } ) + + .. important:: Specify coordinates in this order: **"longitude, latitude."** + + The following example selects the 100 documents with coordinates + nearest to ``[ 40 , 5 ]`` and limits the maximum distance to 100 + meters from the specified GeoJSON point: .. code-block:: javascript - db.collection.find( { location: { $near: [100,100] } } ); + db.places.find( { loc : { $near : + { $geometry : + { type : "Point" , + coordinates: [ 40 , 5 ] } } , + $maxDistance : 100 + } } } ) - This query will return 100 ordered records with a ``location`` - field in ``collection``. Specify a different limit using the - :method:`cursor.limit()`, or another :ref:`geolocation operator - `, or a non-geospatial operator to limit the - results of the query. + If querying for grid coordinates, use the following syntax: + + .. code-block:: javascript + + db..find( { : + { $near : [ , ] , + $maxDistance: + } } ) + + .. important:: If you use longitude and latitude, specify **longitude first**. + + The following example selects the 100 documents with coordinates + nearest to ``[ 40 , 5 ]``: + + .. code-block:: javascript + + db.places.find( { loc : + { $near : [ 40 , 5 ] , + $maxDistance : 10 + } } ) .. note:: + You can further limit the number of results using + :method:`cursor.limit()`. + Specifying a batch size (i.e. :method:`batchSize() `) in conjunction with queries that use the :operator:`$near` is not defined. See :issue:`SERVER-5236` for more information. - - .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/nearSphere.txt b/source/reference/operator/nearSphere.txt index 4b700bfc731..667d64c0d52 100644 --- a/source/reference/operator/nearSphere.txt +++ b/source/reference/operator/nearSphere.txt @@ -8,12 +8,43 @@ $nearSphere .. versionadded:: 1.8 - The :operator:`$nearSphere` operator is the spherical equivalent of - the :operator:`$near` operator. :operator:`$nearSphere` returns all - documents near a point, calculating distances using spherical geometry. + The :operator:`$nearSphere` operator specifies a point for which a + :term:`geospatial` query returns the 100 closest documents. The + operator queries for a point defined by :ref:`grid coordinates + ` and calculates distances + using spherical geometry. The query sorts the documents from nearest + to farthest. + + The :operator:`$nearSphere` operator requires a geospatial index. The + ``2dsphere`` and ``2d`` indexes both support the + :operator:`$nearSphere` operator. In a ``2dsphere`` index, a grid + coordinate is interpreted as a `GeoJSON + `_ point. + + The optional :operator:`$maxDistance` operator limits a + :operator:`$nearSphere` query to return only those documents that fall + within a maximum distance of a point. Specify the maximum distance in + the units specified by the coordinate system. + + The :operator:`$nearSphere` operator uses the following syntax: + + .. code-block:: javascript + + db.collection.find( { : + { $nearSphere: [ , ] , + $maxDistance: + } } ) + + .. important:: If you use longitude and latitude, specify **longitude first**. + + The following example selects the 100 documents with coordinates + nearest to ``[ 40 , 5 ]`` as calculated by spherical geometry: .. code-block:: javascript - db.collection.find( { loc: { $nearSphere: [0,0] } } ) + db.places.find( { loc : + { $nearSphere : [ 40 , 5 ] + $maxDistance : 10 + } } ) .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/polygon.txt b/source/reference/operator/polygon.txt index f3b907fbb52..e221d0410ef 100644 --- a/source/reference/operator/polygon.txt +++ b/source/reference/operator/polygon.txt @@ -8,20 +8,40 @@ $polygon .. versionadded:: 1.9 - Use :operator:`$polygon` to specify a polygon for a bounded query - using the :operator:`$within` operator for :term:`geospatial` - queries. To define the polygon, you must specify an array of - coordinate points, as in the following: + The :operator:`$polygon` operator specifies a polygon for a + :term:`geospatial` :operator:`$geoWithin` query. The query returns + documents that are within the bounds of the polygon, according to + their point-based location data. The :operator:`$polygon` operator + returns documents based on :ref:`grid coordinates + ` and does *not* query for + GeoJSON shapes. - [ [ x1,y1 ], [x2,y2], [x3,y3] ] + The query calculates distances using planar geometry. The ``2d`` + geospatial index supports the :operator:`$polygon` operator. + + To define the polygon, specify an array of coordinate points. Use the + following syntax: + + .. code-block:: javascript + + { : { $geoWithin : { $polygon : [ [ , ] , + [ , ] , + [ , ] ] } } } + + .. important:: If you use longitude and latitude, specify **longitude first**. The last point specified is always implicitly connected to the first. You can specify as many points, and therefore sides, as you - like. Consider the following bounded query for documents with - coordinates within a polygon: + like. + + The following query returns all documents that have coordinates that + exist within the polygon defined by ``[ 0 , 0 ]``, ``[ 3 , 3 ]``, and + ``[ 6 , 0 ]``: .. code-block:: javascript - db.collection.find( { loc: { $within: { $polygon: [ [0,0], [3,6], [6,0] ] } } } ) + db.places.find( { loc : { $geoWithin : { $polygon : [ [ 0 , 0 ] , + [ 3 , 6 ] , + [ 6 , 0 ] ] } } } ) .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operator/pop.txt b/source/reference/operator/pop.txt index 5955e103197..c01d4bf9e3f 100644 --- a/source/reference/operator/pop.txt +++ b/source/reference/operator/pop.txt @@ -7,7 +7,7 @@ $pop .. operator:: $pop The :operator:`$pop` operator removes the first or last element of an - array. Pass :operator:`$pop` a value of ``1``` to remove the last element + array. Pass :operator:`$pop` a value of ``1`` to remove the last element in an array and a value of ``-1`` to remove the first element of an array. Consider the following syntax: diff --git a/source/reference/operator/push.txt b/source/reference/operator/push.txt index ceb4e875d5e..5c6882e97b4 100644 --- a/source/reference/operator/push.txt +++ b/source/reference/operator/push.txt @@ -6,26 +6,87 @@ $push .. operator:: $push - The :operator:`$push` operator appends a specified value to an array. For - example: + The :operator:`$push` operator appends a specified value to an array. .. code-block:: javascript - db.collection.update( { field: value }, { $push: { field: value1 } } ); + db.collection.update( , + { $push: { : } } + ) - Here, :operator:`$push` appends ``value1`` to the array identified by - ``value`` in ``field``. Be aware of the following behaviors: + The following example appends ``89`` to the ``scores`` array for the + first document where the ``name`` field equals ``joe``: - - If the field specified in the :operator:`$push` statement - (e.g. ``{ $push: { field: value1 } }``) does not exist in the - matched document, the operation adds a new array with the - specified field and value (e.g. ``value1``) to the matched - document. + .. code-block:: javascript + + db.students.update( + { name: "joe" }, + { $push: { scores: 89 } } + ) + + .. note:: + + - If the field is absent in the document to update, + :operator:`$push` adds the array field with the value as its + element. + + - If the field is **not** an array, the operation will fail. + + - If the value is an array, :operator:`$push` appends the whole + array as a *single* element. To add each element of the value + separately, use :operator:`$push` with the :operator:`$each` + modifier. + + The following example appends each element of ``[ 90, 92, 85 ]`` to + the ``scores`` array for the document where the ``name`` field + equals ``joe``: + + .. code-block:: javascript + + db.students.update( + { name: "joe" }, + { $push: { scores: { $each: [ 90, 92, 85 ] } } } + ) + + .. versionchanged:: 2.4 + MongoDB adds support for the :operator:`$each` modifier to + the :operator:`$push` operator. Before 2.4, use + :operator:`$pushAll` for similar functionality. - - The operation will fail if the field specified in the - :operator:`$push` statement is *not* an array. :operator:`$push` - does not fail when pushing a value to a non-existent field. + .. versionchanged:: 2.4 + You can use the :operator:`$push` operator with the following + modifiers: + + - :operator:`$each` appends multiple values to the array field, + + - :operator:`$slice`, which is only available with + :operator:`$each`, limits the number of array elements, and + + - :operator:`$sort`, which is only available with + :operator:`$each`, orders elements of the + array. :operator:`$sort` can only order array elements that + are documents. + + The following example uses: + + - the :operator:`$each` modifier to append documents to the + ``quizzes`` array, + + - the :operator:`$sort` modifier to sort all the elements of the + modified ``quizzes`` array by the ascending ``score`` field, and + + - the :operator:`$slice` modifier to keep only the **last** five + sorted elements of the ``quizzes`` array. + + .. code-block:: javascript - - If ``value1`` is an array itself, :operator:`$push` appends the whole array as an - element in the identified array. To add multiple items to an - array, use :operator:`$pushAll`. + db.students.update( { name: "joe" }, + { $push: { quizzes: { $each: [ { id: 3, score: 8 }, + { id: 4, score: 7 }, + { id: 5, score: 6 } ], + $sort: { score: 1 }, + $slice: -5 + } + } + } + ) diff --git a/source/reference/operator/pushAll.txt b/source/reference/operator/pushAll.txt index 584ba4fb88f..c44a1568415 100644 --- a/source/reference/operator/pushAll.txt +++ b/source/reference/operator/pushAll.txt @@ -6,6 +6,9 @@ $pushAll .. operator:: $pushAll + .. deprecated:: 2.4 + Use the :operator:`$push` operator with :operator:`$each` instead. + The :operator:`$pushAll` operator is similar to the :operator:`$push` but adds the ability to append several values to an array at once. diff --git a/source/reference/operator/slice.txt b/source/reference/operator/slice.txt new file mode 100644 index 00000000000..5c36a47b4f6 --- /dev/null +++ b/source/reference/operator/slice.txt @@ -0,0 +1,48 @@ +====== +$slice +====== + +.. default-domain:: mongodb + +.. operator:: $slice + + .. versionadded:: 2.4 + + The :operator:`$slice` modifier limits the number of array + elements during a :operator:`$push` operation. To project, or return, + a specified number of array elements from a read operation, see the + :projection:`$slice` projection operator instead. + + To use the :operator:`$slice` modifier, it must appear with the + :operator:`$each` modifier, *and* the :operator:`$each` modifier must + be the first modifier for the :operator:`$push` operation. + + .. code-block:: javascript + + db.collection.update( , + { $push: { + : { + $each: [ , , ... ], + $slice: + } + } + } + ) + + The ```` is either a **negative** number or **zero**: + + - If ```` is **negative**, the array ```` contains only + the last ```` elements. + + - If ```` is **zero**, the array ```` is an empty array. + + .. code-block:: javascript + + db.students.update( { _id: 2 }, + { $push: { grades: { + $each: [ 80, 78, 86 ], + $slice: -5 + } + } + } + ) diff --git a/source/reference/operator/sort.txt b/source/reference/operator/sort.txt new file mode 100644 index 00000000000..a06ca6361e4 --- /dev/null +++ b/source/reference/operator/sort.txt @@ -0,0 +1,87 @@ +===== +$sort +===== + +.. default-domain:: mongodb + +.. operator:: $sort + + .. versionadded:: 2.4 + + The :operator:`$sort` modifier orders the elements of an array + during a :operator:`$push` operation. The elements of the array + **must** be documents. + + :operator:`$sort` modifies :operator:`$push` updates that use the + :operator:`$each` and :operator:`$slice` modifiers, where + :operator:`$each` is the first modifier for the + :operator:`$push` operation. + + .. code-block:: javascript + + db.collection.update( , + { $push: { + : { + $each: [ , + , + ... + ], + $slice: , + $sort: , + } + } + } + ) + + .. important:: + + The ```` only accesses the fields from the + elements in the array and does **not** refer to the array + ````. + + Consider the following example where the collection ``students`` + contain the following document: + + .. code-block:: javascript + + { "_id": 3, + "name": "joe", + "quizzes": [ + { "id" : 1, "score" : 6 }, + { "id" : 2, "score" : 9 } + ] + } + + The following update appends additional documents to the ``quizzes`` + array, sorts all the elements of the array by ascending ``score`` + field, and slices the array to keep the last five elements: + + .. code-block:: javascript + + db.students.update( { name: "joe" }, + { $push: { quizzes: { $each: [ { id: 3, score: 8 }, + { id: 4, score: 7 }, + { id: 5, score: 6 } ], + $sort: { score: 1 }, + $slice: -5 + } + } + } + ) + + After the update, the array elements are in order of ascending + ``score`` field.: + + .. code-block:: javascript + + { + "_id" : 3, + "name" : "joe", + "quizzes" : [ + { "id" : 1, "score" : 6 }, + { "id" : 5, "score" : 6 }, + { "id" : 4, "score" : 7 }, + { "id" : 3, "score" : 8 }, + { "id" : 2, "score" : 9 } + ] + } diff --git a/source/reference/operator/uniqueDocs.txt b/source/reference/operator/uniqueDocs.txt index ecf71db95f2..645d1f1a013 100644 --- a/source/reference/operator/uniqueDocs.txt +++ b/source/reference/operator/uniqueDocs.txt @@ -8,40 +8,36 @@ $uniqueDocs .. versionadded:: 2.0 - For :term:`geospatial` queries, MongoDB may return a single - document more than once for a single query, because geospatial - indexes may include multiple coordinate pairs in a single - document, and therefore return the same document more than once. + The :operator:`$uniqueDocs` operator returns a document only once for + a :term:`geospatial` query if the document matches the query multiple + times. A document might match a query multiple times if the documents + contains multiple coordinate values. - The :operator:`$uniqueDocs` operator inverts the default behavior - of the :operator:`$within` operator. By default, the - :operator:`$within` operator returns the document only once. If you - specify a value of ``false`` for :operator:`$uniqueDocs`, MongoDB - will return multiple instances of a single document. + You can use :operator:`$uniqueDocs` only with the + :operator:`$geoWithin` and :operator:`$geoWithin` operators. The + ``2d`` geospatial index supports :operator:`$uniqueDocs`. .. example:: - Given an ``addressBook`` collection with a document in the following form: + Given a collection of addresses with documents in the following + form: .. code-block:: javascript - { addresses: [ { name: "Home", loc: [55.5, 42.3] }, { name: "Work", loc: [32.3, 44.2] } ] } + { addrs : [ { name : "H" , loc : [ 55.5 , 42.3 ] } , { name : "W" , loc : [ 32.3 , 44.2 ] } ] } - The following query would return the same document multiple - times: + The following query would return the same document multiple times: .. code-block:: javascript - db.addressBook.find( { "addresses.loc": { "$within": { "$box": [ [0,0], [100,100] ], $uniqueDocs: false } } } ) + db.list.find( { addrs.loc : { $geoWithin : { $box : [ [ 0 , 0 ] , [ 100 , 100 ] ] } } } ) - The following query would return each matching document, only - once: + The following query would return each matching document only once: .. code-block:: javascript - db.addressBook.find( { "address.loc": { "$within": { "$box": [ [0,0], [100,100] ], $uniqueDocs: true } } } ) + db.list.find( { addrs.loc : { $geoWithin : { $box : [ [ 0 , 0 ] , [ 100 , 100 ] ], $uniqueDocs: true } } } ) - You cannot specify :operator:`$uniqueDocs` with :operator:`$near` - or haystack queries. - - .. include:: /includes/note-geospatial-index-must-exist.rst + .. note:: If you specify a value of ``false`` for + :operator:`$uniqueDocs`, MongoDB will return multiple instances of + a single document. diff --git a/source/reference/operator/within.txt b/source/reference/operator/within.txt deleted file mode 100644 index 37bb3e2ca71..00000000000 --- a/source/reference/operator/within.txt +++ /dev/null @@ -1,59 +0,0 @@ -======= -$within -======= - -.. default-domain:: mongodb - -.. operator:: $within - - The :operator:`$within` operator allows you to select items that exist - within a shape on a coordinate system for :term:`geospatial` queries. This operator uses the - following syntax: - - .. code-block:: javascript - - db.collection.find( { location: { $within: { shape } } } ); - - Replace ``{ shape }`` with a document that describes a shape. The - :operator:`$within` command supports the following shapes. These shapes and the - relevant expressions follow: - - - Rectangles. Use the :operator:`$box` operator, consider the following - variable and :operator:`$within` document: - - .. code-block:: javascript - - db.collection.find( { location: { $within: { $box: [[100,0], [120,100]] } } } ); - - Here a box, ``[[100,120], [100,0]]`` describes the parameter - for the query. As a minimum, you must specify the lower-left and - upper-right corners of the box. - - - Circles. Use the :operator:`$center` operator. Specify circles in the following form: - - .. code-block:: javascript - - db.collection.find( { location: { $within: { $center: [ center, radius } } } ); - - - Circular distance on a sphere. Use the - :operator:`$centerSphere` operator. For the syntax, see :operator:`$centerSphere`. - - - Polygons. Use the :operator:`$polygon` operator. Specify polygons with an array of points. See the - following example: - - .. code-block:: javascript - - db.collection.find( { location: { $within: { $polygon: [[100,120], [100,100], [120,100], [240,200]] } } } ); - - The last point of a polygon is implicitly connected to the first - point. - - All shapes include the border of the shape as part of the shape, - although this is subject to the imprecision of floating point - numbers. - - Use :operator:`$uniqueDocs` to control whether documents with - many location fields show up multiple times when more than one - of its fields match the query. - - .. include:: /includes/note-geospatial-index-must-exist.rst diff --git a/source/reference/operators.txt b/source/reference/operators.txt index a41c99d1c8f..07bd20289af 100644 --- a/source/reference/operators.txt +++ b/source/reference/operators.txt @@ -101,22 +101,21 @@ JavaScript Geospatial ~~~~~~~~~~ +Operators: + - :operator:`$near` -- :operator:`$within` - :operator:`$nearSphere` +- :operator:`$geoWithin` +- :operator:`$geoIntersects` -Use the following operators within the context of -:operator:`$near`: +Parameters: +- :operator:`$geometry` - :operator:`$maxDistance` - -Use the following operators within the context of -:operator:`$within`: - - :operator:`$center` +- :operator:`$centerSphere` - :operator:`$box` - :operator:`$polygon` -- :operator:`$centerSphere` - :operator:`$uniqueDocs` .. index:: query selectors; array @@ -156,6 +155,12 @@ Array - :operator:`$pushAll` - :operator:`$push` + - :operator:`$each` modifier + + - :operator:`$slice` modifier + + - :operator:`$sort` modifier + Bitwise ~~~~~~~ diff --git a/source/reference/privilege-documents.txt b/source/reference/privilege-documents.txt index 1e56ba68361..e63bc9ae0ea 100644 --- a/source/reference/privilege-documents.txt +++ b/source/reference/privilege-documents.txt @@ -97,18 +97,6 @@ Data Model - :authrole:`clusterAdmin` - :authrole:`readAnyDatabase` - :authrole:`readWriteAnyDatabase` - - - - - - - - - - - - - :authrole:`userAdminAnyDatabase` - :authrole:`dbAdminAnyDatabase` @@ -118,10 +106,10 @@ Data Model .. data:: .system.users.userSource A string that holds the name of the database that contains the - credentials for the user. If :data:`~.system.users.userSource` - - is ``$external``, then MongoDB will use an external resource, - such as Kerberos, for authentication credentials. + credentials for the user. If + :data:`~.system.users.userSource` is ``$external``, + then MongoDB will use an external resource, such as Kerberos, for + authentication credentials. .. note:: diff --git a/source/reference/projection/slice.txt b/source/reference/projection/slice.txt index e7d3f561c7c..e96f43763fc 100644 --- a/source/reference/projection/slice.txt +++ b/source/reference/projection/slice.txt @@ -6,8 +6,12 @@ $slice (projection) .. projection:: $slice - The :projection:`$slice` operator controls the number of items of an array - that a query returns. Consider the following prototype query: + The :projection:`$slice` operator controls the number of items of an + array that a query returns. For information on limiting the size of + an array during an update with :operator:`$push`, see the + :operator:`$slice` modifier instead. + + Consider the following prototype query: .. code-block:: javascript diff --git a/source/reference/server-status-index.txt b/source/reference/server-status-index.txt index 961296927ba..349c6982f03 100644 --- a/source/reference/server-status-index.txt +++ b/source/reference/server-status-index.txt @@ -162,13 +162,11 @@ use: .. code-block:: javascript "indexCounters" : { - "btree" : { - "accesses" : , - "hits" : , - "misses" : , - "resets" : , - "missRatio" : - } + "accesses" : , + "hits" : , + "misses" : , + "resets" : , + "missRatio" : }, .. _server-status-example-backgroundflushing: @@ -231,7 +229,6 @@ for replica sets. ], "primary" : , "me" : - }, .. _server-status-example-opcountersrepl: @@ -249,20 +246,6 @@ of replicated operations: "command" : }, -.. _server-status-example-replnetworkqueue: - -The ":ref:`server-status-repl-network-queue`" document holds -information regarding the queue that :term:`secondaries ` -use to poll data from other members of their set: - -.. code-block:: javascript - - "replNetworkQueue" : { - "waitTimeMs" : , - "numElems" : , - "numBytes" : - }, - .. _server-status-example-opcounters: The ":ref:`server-status-opcounters`" document reports the number of @@ -349,6 +332,106 @@ when required data isn't in memory: } }, +.. _server-status-example-workingset: + +The ":ref:`server-status-workingset`" document provides an estimated +size of the MongoDB instance's working set. This data may not exactly +reflect the size of the working set in all cases. Additionally, the +:data:`~serverStatus.workingSet` document is only present in the +output of :dbcommand:`serverStatus` when explicitly enabled. + +.. versionadded:: 2.4 + +.. code-block:: javascript + + "workingSet" : { + "note" : "thisIsAnEstimate", + "pagesInMemory" : , + "computationTimeMicros" : , + "overSeconds" : num + }, + +.. _server-status-example-metrics: + +The ":ref:`server-status-metrics`" document contains a number of +operational metrics that are useful for monitoring the state and +workload of a :program:`mongod` instance. + +.. versionadded:: 2.4 + +.. code-block:: javascript + + "metrics" : { + "document" : { + "deleted" : NumberLong(), + "inserted" : NumberLong(), + "returned" : NumberLong(), + "updated" : NumberLong() + }, + "getLastError" : { + "wtime" : { + "num" : , + "totalMillis" : + }, + "wtimeouts" : NumberLong() + }, + "operation" : { + "fastmod" : NumberLong(), + "idhack" : NumberLong(), + "scanAndOrder" : NumberLong() + }, + "queryExecutor": { + "scanned" : NumberLong() + }, + "record" : { + "moves" : NumberLong() + }, + "repl" : { + "apply" : { + "batches" : { + "num" : , + "totalMillis" : + }, + "ops" : NumberLong() + }, + "buffer" : { + "count" : NumberLong(), + "maxSizeBytes" : , + "sizeBytes" : NumberLong() + }, + "network" : { + "bytes" : NumberLong(), + "getmores" : { + "num" : , + "totalMillis" : + }, + "ops" : NumberLong(), + "readersCreated" : NumberLong() + }, + "oplog" : { + "insert" : { + "num" : , + "totalMillis" : + }, + "insertBytes" : NumberLong() + }, + "preload" : { + "docs" : { + "num" : , + "totalMillis" : + }, + "indexes" : { + "num" : , + "totalMillis" : + } + } + }, + "ttl" : { + "deletedDocuments" : NumberLong(), + "passes" : NumberLong() + } + }, + The final ``ok`` field holds the return status for the :dbcommand:`serverStatus` command: diff --git a/source/reference/server-status.txt b/source/reference/server-status.txt index f900d8a63e0..cdb5df8091c 100644 --- a/source/reference/server-status.txt +++ b/source/reference/server-status.txt @@ -314,11 +314,6 @@ globalLock operations have held :data:`~serverStatus.globalLock` infrequently for longer periods of time. -.. _globallock-currentqueue: - -globalLock.currentQueue -~~~~~~~~~~~~~~~~~~~~~~~ - .. data:: serverStatus.globalLock.currentQueue The :data:`~serverStatus.globalLock.currentQueue` data structure value provides more @@ -359,8 +354,8 @@ globalLock.activeClients granular information about the number of connected clients and the operation types (e.g. read or write) performed by these clients. - Use this data to provide context for the :ref:`currentQueue - ` data. + Use this data to provide context for the + :data:`~serverStatus.globalLock.currentQueue` data. .. data:: serverStatus.globalLock.activeClients.total @@ -530,57 +525,57 @@ indexCounters absolute index use. In 2.2 and later, these data reflect actual index use. + .. versionchanged:: 2.4 + Fields previously in the ``btree`` sub-document of + :data:`~serverStatus.indexCounters` are now fields in the + :data:`~serverStatus.indexCounters` document. + The :data:`~serverStatus.indexCounters` data structure reports information regarding the state and use of indexes in MongoDB. -.. data:: serverStatus.indexCounters.btree +.. data:: serverStatus.indexCounters.accesses - The :data:`~serverStatus.indexCounters.btree` data structure contains data - regarding MongoDB's :term:`btree` indexes. - -.. data:: serverStatus.indexCounters.btree.accesses - - :data:`~serverStatus.indexCounters.btree.accesses` reports the number of times + :data:`~serverStatus.indexCounters.accesses` reports the number of times that operations have accessed indexes. This value is the - combination of the :data:`~serverStatus.indexCounters.btree.hits` and - :data:`~serverStatus.indexCounters.btree.misses`. Higher values indicate that + combination of the :data:`~serverStatus.indexCounters.hits` and + :data:`~serverStatus.indexCounters.misses`. Higher values indicate that your database has indexes and that queries are taking advantage of these indexes. If this number does not grow over time, this might indicate that your indexes do not effectively support your use. -.. data:: serverStatus.indexCounters.btree.hits +.. data:: serverStatus.indexCounters.hits - The :data:`~serverStatus.indexCounters.btree.hits` value reflects the number of + The :data:`~serverStatus.indexCounters.hits` value reflects the number of times that an index has been accessed and :program:`mongod` is able to return the index from memory. A higher value indicates effective index - use. :data:`~serverStatus.indexCounters.btree.hits` values that represent a - greater proportion of the :data:`~serverStatus.indexCounters.btree.accesses` + use. :data:`~serverStatus.indexCounters.hits` values that represent a + greater proportion of the :data:`~serverStatus.indexCounters.accesses` value, tend to indicate more effective index configuration. -.. data:: serverStatus.indexCounters.btree.misses +.. data:: serverStatus.indexCounters.misses - The :data:`~serverStatus.indexCounters.btree.misses` value represents the + The :data:`~serverStatus.indexCounters.misses` value represents the number of times that an operation attempted to access an index that was not in memory. These "misses," do not indicate a failed query or operation, but rather an inefficient use of the index. Lower values in this field indicate better index use and likely overall performance as well. -.. data:: serverStatus.indexCounters.btree.resets +.. data:: serverStatus.indexCounters.resets - The :data:`~serverStatus.indexCounters.btree.resets` value reflects the number + The :data:`~serverStatus.indexCounters.resets` value reflects the number of times that the index counters have been reset since the database last restarted. Typically this value is ``0``, but use this value to provide context for the data specified by other :data:`~serverStatus.indexCounters` values. -.. data:: serverStatus.indexCounters.btree.missRatio +.. data:: serverStatus.indexCounters.missRatio - The :data:`~serverStatus.indexCounters.btree.missRatio` value is the ratio of - :data:`~serverStatus.indexCounters.btree.hits` to - :data:`~serverStatus.indexCounters.btree.misses` misses. This value is + The :data:`~serverStatus.indexCounters.missRatio` value is the ratio of + :data:`~serverStatus.indexCounters.hits` to + :data:`~serverStatus.indexCounters.misses` misses. This value is typically ``0`` or approaching ``0``. .. _server-status-backgroundflushing: @@ -724,42 +719,43 @@ repl .. data:: serverStatus.repl - The :data:`~serverStatus.repl` data structure contains status information for - MongoDB's replication (i.e. "replica set") configuration. These - values only appear when the current host has replication enabled. + The :data:`~serverStatus.repl` data structure contains status + information for MongoDB's replication (i.e. "replica set") + configuration. These values only appear when the current host has + replication enabled. See :doc:`/core/replication` for more information on replication. .. data:: serverStatus.repl.setName - The :data:`~serverStatus.repl.setName` field contains a string with the name of the - current replica set. This value reflects the :option:`--replSet ` - command line argument, or :setting:`replSet` value in the - configuration file. + The :data:`~serverStatus.repl.setName` field contains a string with + the name of the current replica set. This value reflects the + :option:`--replSet ` command line argument, or + :setting:`replSet` value in the configuration file. See :doc:`/core/replication` for more information on replication. .. data:: serverStatus.repl.ismaster - The value of the :data:`~serverStatus.repl.ismaster` field is either ``true`` or - ``false`` and reflects whether the current node is the master or - primary node in the replica set. + The value of the :data:`~serverStatus.repl.ismaster` field is + either ``true`` or ``false`` and reflects whether the current node + is the master or primary node in the replica set. See :doc:`/core/replication` for more information on replication. .. data:: serverStatus.repl.secondary - The value of the :data:`~serverStatus.repl.secondary` field is either ``true`` or - ``false`` and reflects whether the current node is a secondary - node in the replica set. + The value of the :data:`~serverStatus.repl.secondary` field is + either ``true`` or ``false`` and reflects whether the current node + is a secondary node in the replica set. See :doc:`/core/replication` for more information on replication. .. data:: serverStatus.repl.hosts - :data:`~serverStatus.repl.hosts` is an array that lists the other nodes in the - current replica set. Each member of the replica set appears in the - form of ``hostname:port``. + :data:`~serverStatus.repl.hosts` is an array that lists the other + nodes in the current replica set. Each member of the replica set + appears in the form of ``hostname:port``. See :doc:`/core/replication` for more information on replication. @@ -824,41 +820,6 @@ opcountersRepl of replicated commands issued to the database since the :program:`mongod` instance last started. -.. _server-status-replnetworkqueue: -.. _server-status-repl-network-queue: - -replNetworkQueue ----------------- - -.. versionadded:: 2.1.2 - -.. example:: :ref:`output of the replNetworkQueue fields `. - -.. data:: serverStatus.replNetworkQueue - - The :data:`~serverStatus.replNetworkQueue` document reports on the network - replication buffer, which permits replication operations to happen - in the background. This feature is internal. - - This document only appears on :term:`secondary` members of - :term:`replica sets `. - -.. data:: serverStatus.replNetworkQueue.waitTimeMs - - :data:`~serverStatus.replNetworkQueue.waitTimeMs` reports the amount of time that - a :term:`secondary` waits to add operations to network queue. This - value is cumulative. - -.. data:: serverStatus.replNetworkQueue.numElems - - :data:`~serverStatus.replNetworkQueue.numElems` reports the number of operations - stored in the queue. - -.. data:: serverStatus.replNetworkQueue.numBytes - - :data:`~serverStatus.replNetworkQueue.numBytes` reports the total size of the - network replication queue. - .. _server-status-opcounters: opcounters @@ -875,6 +836,14 @@ opcounters These numbers will grow over time and in response to database use. Analyze these values over time to track database utilization. + .. note:: + + The data in :data:`~serverStatus.opcounters` treats operations + that affect multiple documents, such as bulk insert or + multi-update operations, as a single operation. See + :data:`~serverStatus.metrics.document` for more granular + document-level operation tracking. + .. data:: serverStatus.opcounters.insert :data:`~serverStatus.opcounters.insert` provides a counter of the total number @@ -982,14 +951,11 @@ writeBacksQueued .. _journaling-status: .. _server-status-journaling: -dur ---- +Journaling (dur) +---------------- .. versionadded:: 1.8 -Journaling -~~~~~~~~~~ - .. example:: :ref:`output of the journaling fields `. .. data:: serverStatus.dur @@ -1012,8 +978,6 @@ Journaling .. seealso:: ":doc:`/administration/journaling`" for more information about journaling operations. -.. STUB :doc:`/core/journaling` - .. data:: serverStatus.dur.commits The :data:`~serverStatus.dur.commits` provides the number of transactions @@ -1165,3 +1129,424 @@ recordStats :data:`~serverStatus.recordStats..pageFaultExceptionsThrown` reflects the number of page fault exceptions thrown by :program:`mongod` when accessing data for the ```` database. + +.. _server-status-workingset: +.. _server-status-working-set: + +workingSet +---------- + +.. versionadded:: 2.4 + +.. example:: :ref:`output of the workingSet ` fields. + +.. note:: + + The :data:`~serverStatus.workingSet` data is only included in the + output of :dbcommand:`serverStatus` *if* explicitly enabled. To + return the :data:`~serverStatus.workingSet` use one of the + following commands: + + .. code-block:: javascript + + db.serverStatus( { workingSet: 1 } ) + db.runCommand( { serverStatus: 1, workingSet: 1 } ) + +.. data:: serverStatus.workingSet + + :data:`~serverStatus.workingSet` is a document that contains values + useful for predicting the size of the working set, which is the + amount of data that MongoDB uses actively. + +.. data:: serverStatus.workingSet.note + + :data:`~serverStatus.workingSet.note` is a field that holds a + string warning that the :data:`~serverStatus.workingSet` + document is an estimate. + +.. data:: serverStatus.workingSet.pagesInMemory + + :data:`~serverStatus.workingSet.pagesInMemory` contains a count of + the total number of pages in the system's RAM. On Linux systems, + the default page size if 4 kilobytes. + + If your total working set is less than the size of physical memory, + over time the value of + :data:`~serverStatus.workingSet.pagesInMemory` will equal your data + size. Conversely, if your data set is greater than the size of the + physical RAM, this number will approach the total size of physical + RAM. + + Use :data:`~serverStatus.workingSet.pagesInMemory` in conjunction + with :data:`~serverStatus.workingSet.overSeconds` to help estimate + the actual size of the working set. + +.. data:: serverStatus.workingSet.computationTimeMicros + + :data:`~serverStatus.workingSet.computationTimeMicros` reports the + amount of time the :program:`mongod` used to compute the other + fields in the :data:`~serverStatus.workingSet` section. + + Reporting on :data:`~serverStatus.workingSet` may impact the + performance of other operations on the :program:`mongod` instance + because MongoDB must collect some data within the context of a + lock. Ensure that automated monitoring tools use this value when + determining the collection frequency for + :data:`~serverStatus.workingSet`. + +.. data:: serverStatus.workingSet.overSeconds + + :data:`~serverStatus.workingSet.overSeconds` returns the amount of + time between the newest and oldest pages tracked in the + :data:`~serverStatus.workingSet.pagesInMemory` data point. + + If :data:`~serverStatus.workingSet.pagesInMemory` equals physical + RAM *and* :data:`~serverStatus.workingSet.overSeconds` is very + small, the working set may be much larger than physical RAM. When + :data:`~serverStatus.workingSet.overSeconds` is large, MongoDB's + data set is equal to or smaller than physical RAM. + +.. _server-status-metrics: + +metrics +------- + +.. example:: :ref:`output of the metrics ` + fields. + +.. versionadded:: 2.4 + +.. data:: serverStatus.metrics + + The :data:`~serverStatus.metrics` document holds a number of + statistics that reflect the current use and state of a running + :program:`mongod` instance. + +.. data:: serverStatus.metrics.document + + The :data:`~serverStatus.metrics.document` holds a document of that + reflect document access and modification patterns and data + use. Compare these values to the data in the + :data:`~serverStatus.opcounters` document, which track total number + of operations. + +.. data:: serverStatus.metrics.document.deleted + + :data:`~serverStatus.metrics.document.related` reports the total + number of documents deleted. + +.. data:: serverStatus.metrics.document.inserted + + :data:`~serverStatus.metrics.document.inserted` reports the total + number of documents inserted. + +.. data:: serverStatus.metrics.document.returned + + :data:`~serverStatus.metrics.document.returned` reports the total + number of documents returned by queries. + +.. data:: serverStatus.metrics.document.updated + + :data:`~serverStatus.metrics.document.updated` reports the total + number of documents updated. + +.. data:: serverStatus.metrics.getLastError + + :data:`~serverStatus.metrics.getLastError` is a document that + reports on :dbcommand:`getLastError` use. + +.. data:: serverStatus.metrics.getLastError.wtime + + :data:`~serverStatus.metrics.getLastError.wtime` is a sub-document + that reports :dbcommand:`getLastError` operation counts with a + ``w`` argument greater than ``1``. + +.. data:: serverStatus.metrics.getLastError.wtime.num + + :data:`~serverStatus.metrics.getLastError.wtime.num` reports the + total number of :dbcommand:`getLastError` operations without a + specified write concern (i.e. ``w``) that wait for one or more + members of a replica set to acknowledge the write operation + (i.e. greater than ``1``.) + +.. data:: serverStatus.metrics.getLastError.wtime.totalMillis` + + :data:`~serverStatus.metrics.getLastError.wtime.totalMills` reports + the total amount of time in milliseconds that the :program:`mongod` + has spent performing :dbcommand:`getLastError` operations with + write concern (i.e. ``w``) that wait for one or more members of a + replica set to acknowledge the write operation (i.e. greater than + ``1``.) + +.. data:: serverStatus.metrics.getLastError.wtimeouts + + :data:`~serverStatus.metrics.getLastError.wtimeouts` reports the + number of times that :term:`write concern` operations have timed out + as a result of the ``wtimeout`` threshold to + :dbcommand:`getLastError`. + +.. data:: serverStatus.metrics.operation + + :data:`~serverStatus.metrics.operation` is a sub-document that + holds counters for several types of update and query operations + that MongoDB handles using special operation types. + +.. data:: serverStatus.metrics.operation.fastmod + + :data:`~serverStatus.metrics.operation.fastmod` reports the number + of :doc:`update ` operations that neither + cause documents to grow nor require updates to the index. For + example, this counter would record an update operation that use the + :operator:`$inc` operator to increment the value of a field that is + not indexed. + +.. data:: serverStatus.metrics.operation.idhack + + :data:`~serverStatus.metrics.operation.idhack` reports the number + of queries that contain the ``_id`` field. For these queries, + MongoDB will use default index on the ``_id`` field and skip all + query plan analysis. + +.. data:: serverStatus.metrics.operation.scanAndOrder + + :data:`~serverStatus.metrics.operation.scanAndOrder` reports the + total number of queries that return sorted numbers that cannot + perform the sort operation using an index. + +.. data:: serverStatus.metrics.queryExecutor + + :data:`~serverStatus.metrics.queryExecutor` is a document that + reports data from the query execution system. + +.. data:: serverStatus.metrics.queryExecutor.scanned + + :data:`~serverStatus.metrics.queryExecutor.scanned` reports the total + number of index items scanned during queries and query-plan + evaluation. This counter is the same as :data:`~explain.nscanned` + in the output of :method:`~cursor.explain()`. + +.. data:: serverStatus.metrics.record + + :data:`~serverStatus.metrics.record` is a document that reports + data related to record allocation in the on-disk memory files. + +.. data:: serverStatus.metrics.record.moves + + :data:`~serverStatus.metrics.record.moves` reports the total number + of times documents move within the on-disk representation of the + MongoDB data set. Documents move as a result of operations that + increase the size of the document beyond their allocated record + size. + +.. _server-status-replnetworkqueue: +.. _server-status-repl-network-queue: + +.. data:: serverStatus.metrics.repl + + :data:`~serverStatus.metrics.repl` holds a sub-document that + reports metrics related to the replication process. + :data:`~serverStatus.metrics.repl` document appears on all + :program:`mongod` instances, even those that aren't members of + :term:`replica sets `. + +.. data:: serverStatus.metrics.repl.apply + + :data:`~serverStatus.metrics.repl.apply` holds a sub-document that + reports on the application of operations from the replication + :term:`oplog`. + +.. data:: serverStatus.metrics.repl.apply.batches + + :data:`~serverStatus.metrics.repl.apply.batches` reports on the + oplog application process on :term:`secondaries ` + members of replica sets. See + :ref:`replica-set-internals-multi-threaded-replication` for more + information on the oplog application processes + +.. data:: serverStatus.metrics.repl.apply.batches.num + + :data:`~serverStatus.metrics.repl.apply.batches.num` reports the + total number of batches applied across all databases. + +.. data:: serverStatus.metrics.repl.apply.batches.totalMills + + :data:`~serverStatus.metrics.repl.apply.batches.totalMills` reports + the total amount of time the :program:`mongod` has spent applying + operations from the oplog. + +.. data:: serverStatus.metrics.repl.apply.ops + + :data:`~serverStatus.metrics.repl.apply.ops` reports the total + number of :term:`oplog` operations applied. + +.. data:: serverStatus.metrics.repl.buffer + + MongoDB buffers oplog operations from the replication sync source + buffer before applying oplog entries in a + batch. :data:`~serverStatus.metrics.repl.buffer` provides a way to + track the oplog buffer. See + :ref:`replica-set-internals-multi-threaded-replication` for more + information on the oplog application process. + +.. data:: serverStatus.metrics.repl.buffer.count + + :data:`~serverStatus.metrics.repl.buffer.count` reports the current + number of operations in the oplog buffer. + +.. data:: serverStatus.metrics.repl.buffer.maxSizeBytes + + :data:`~serverStatus.metrics.repl.buffer.maxSizeBytes` reports the + maximum size of the buffer. This value is a constant setting in + the :program:`mongod`, and is not configurable. + +.. data:: serverStatus.metrics.repl.buffer.sizeBytes + + :data:`~serverStatus.metrics.repl.sizeBytes` reports the current + size of the contents of the oplog buffer. + +.. data:: serverStatus.metrics.repl.network + + :data:`~serverStatus.metrics.repl.network` reports network use by + the replication process. + +.. data:: serverStatus.metrics.repl.network.bytes + + :data:`~serverStatus.metrics.repl.network.bytes` reports the total + amount of data read from the replication sync source. + +.. data:: serverStatus.metrics.repl.network.getmores + + :data:`~serverStatus.metrics.repl.network.getmores` reports on the + ``getmore`` operations,which are requests for additional results + from the oplog :term:`cursor` as part of the oplog replication + process. + + .. TODO move the documentation of getmore into some central place + +.. data:: serverStatus.metrics.repl.network.getmores.num + + :data:`~serverStatus.metrics.repl.network.getmores.num` reports the + total number of ``getmore`` operations, which are operations that + request an additional set of operations from the replication sync + source. + +.. data:: serverStatus.metrics.repl.network.getmores.totalMillis + + :data:`~serverStatus.metrics.repl.network.getmores.totalMillis` + reports the total amount of time required to collect data from + ``getmore`` operations. + + .. note:: + + This number can be quite large, as MongoDB will wait for more + data even if the ``getmore`` operation does not initial return + data. + +.. data:: serverStatus.metrics.repl.network.ops + + :data:`~serverStatus.metrics.repl.network.ops` reports the total + number of operations read from the replication source. + +.. data:: serverStatus.metrics.repl.network.readersCreated + + :data:`~serverStatus.metrics.repl.network.readersCreated` reports + the total number of oplog query processes created. MongoDB will + create a new oplog query any time an error occurs in the + connection, including a timeout, or a network + operation. Furthermore, + :data:`~serverStatus.metrics.repl.network.readersCreated` will + increment every time MongoDB selects a new source fore replication. + +.. data:: serverStatus.metrics.repl.oplog + + :data:`~serverStatus.metrics.repl.oplog` is a document that reports + on the size and use of the :term:`oplog` by this :program:`mongod` + instance. + +.. data:: serverStatus.metrics.repl.oplog.insert + + :data:`~serverStatus.metrics.repl.oplog.insert` is a document that + reports insert operations into the :term:`oplog`. + +.. data:: serverStatus.metrics.repl.oplog.insert.num + + :data:`~serverStatus.metrics.repl.oplog.insert.num` reports the total + number of items inserted into the :term:`oplog`. + +.. data:: serverStatus.metrics.repl.oplog.insert.totalMillis + + :data:`~serverStatus.metrics.repl.oplog.insert.totalMillis` reports the + total amount of time spent for the :program:`mongod` to insert data + into the :term:`oplog`. + +.. data:: serverStatus.metrics.repl.oplog.insertBytes + + :data:`~serverStatus.metrics.repl.oplog.insertBytes` the total size + of documents inserted into the oplog. + +.. data:: serverStatus.metrics.repl.preload + + :data:`~serverStatus.metrics.repl.preload` reports on the + "pre-fetch" stage, where MongoDB loads documents and indexes into + RAM to improve replication throughput. + + See :ref:`replica-set-internals-multi-threaded-replication` for + more information about the *pre-fetch* stage of the replication + process. + +.. data:: serverStatus.metrics.repl.preload.docs + + :data:`~serverStatus.metrics.repl.preload.docs` is a sub-document + that reports on the documents loaded into memory during the + *pre-fetch* stage. + +.. data:: serverStatus.metrics.repl.preload.docs.num + + :data:`~serverStatus.metrics.repl.preload.docs.num` reports the + total number of documents loaded during the *pre-fetch* stage of + replication. + +.. data:: serverStatus.metrics.repl.preload.docs.totalMillis + + :data:`~serverStatus.metrics.repl.preload.docs.totalMillis` reports + the total amount of time spent loading documents as part of + the *pre-fetch* stage of replication. + +.. data:: serverStatus.metrics.repl.preload.indexes + + :data:`~serverStatus.metrics.repl.preload.indexes` is a + sub-document that reports on the index items loaded into + memory during the *pre-fetch* stage of replication. + + See :ref:`replica-set-internals-multi-threaded-replication` for + more information about the *pre-fetch* stage of replication. + +.. data:: serverStatus.metrics.repl.preload.indexes.num + + :data:`~serverStatus.metrics.repl.preload.indexes.num` reports the + total number of index entries loaded by members before updating + documents as part of the *pre-fetch* stage of replication. + +.. data:: serverStatus.metrics.repl.preload.indexes.totalMillis + + :data:`~serverStatus.metrics.repl.preload.indexes.totalMillis` + reports the total amount of time spent loading index entries as + part of the *pre-fetch* stage of replication. + +.. data:: serverStatus.metrics.ttl + + :data:`~serverStatus.metrics.ttl` is a sub-document that reports on + the operation of the resource use of the :doc:`ttl index + ` process. + +.. data:: serverStatus.metrics.ttl.deletedDocuments + + :data:`~serverStatus.metrics.ttl.deletedDocuments` reports the + total number of documents deleted from collections with a :doc:`ttl + index `. + +.. data:: serverStatus.metrics.ttl.passes + + :data:`~serverStatus.metrics.ttl.passes` reports the number of + times the background process removes documents from collections with a + :doc:`ttl index `. diff --git a/source/reference/user-privileges.txt b/source/reference/user-privileges.txt index cf9ab40712d..3834c6aa479 100644 --- a/source/reference/user-privileges.txt +++ b/source/reference/user-privileges.txt @@ -25,11 +25,12 @@ write data to the ``records`` database. .. note:: - MongoDB 2.4 also supports the "old-style" access control roles - provided by MongoDB 2.2, unless explicitly disabled using the + By default, MongoDB 2.4 is backwards-compatible with the MongoDB 2.2 + access control roles. You can, however, explicitly disable this + backwards-compatibility by setting the :parameter:`supportCompatibilityFormPrivilegeDocuments` option to - :setting:`setParameter`, as set in the following command-line - invocation of MongoDB: + ``0`` during startup, as in the following command-line invocation of + MongoDB: .. code-block:: sh diff --git a/source/release-notes/2.4-upgrade.txt b/source/release-notes/2.4-upgrade.txt index 3c38217a236..9b7a36c9443 100644 --- a/source/release-notes/2.4-upgrade.txt +++ b/source/release-notes/2.4-upgrade.txt @@ -59,10 +59,10 @@ metadata in any other way. .. note:: The upgraded config database will require more storage space than - before, though this storage increase represents a fraction of the - current config database size. The additional storage requirement - will be less for deployments that have run with 2.2 for a - non-trivial period of time. See + before, to make backup and working copies of the + :data:`config.chunks` and :data:`config.collections` collections. + As always, if storage requirements increase, the :program:`mongod` + might need to pre-allocate additional data files. See :ref:`faq-tools-for-measuring-storage-use` for more information. .. _2.4-upgrade-meta-data: @@ -93,7 +93,11 @@ procedure. #. Start a single 2.4 :program:`mongos` process with :setting:`configdb` pointing to the sharded cluster's :ref:`config servers ` and with the :option:`--upgrade - ` option. You can upgrade an existing + ` option. The upgrade process happens before the + process becomes a daemon (i.e. before + :option:`--fork `.) + + You can upgrade an existing :program:`mongos` instance to 2.4 or you can start a new `mongos` instance that can reach all config servers if you need to avoid reconfiguring a production :program:`mongos`. @@ -123,40 +127,43 @@ procedure. config servers during the upgrade, you may always safely retry the upgrade. - However, if the upgrade failed in the short critical section, - the retry will end with a warning that manual intervention is required. - To continue upgrading, you must follow the :ref:`upgrade-cluster-resync` - procedure. + However, if the upgrade failed during the short critical section, + the :program:`mongos` will exit and report that the upgrade will + require manual intervention. To continue the upgrade process, you + must follow the :ref:`upgrade-cluster-resync` procedure. .. optional:: - If the :program:`mongos` logs show the upgrade waiting for the upgrade - lock, a previous upgrade process may still be active or may have ended - abnormally. After 15 minutes of no remote activity :program:`mongos` - will force the upgrade lock. If you can verify that there are no running upgrade - processes, you may connect to a 2.2 :program:`mongos` process - and force the lock manually: + If the :program:`mongos` logs show the upgrade waiting for the + upgrade lock, a previous upgrade process may still be active or + may have ended abnormally. After 15 minutes of no remote + activity :program:`mongos` will force the upgrade lock. If you + can verify that there are no running upgrade processes, you may + connect to a 2.2 :program:`mongos` process and force the lock + manually: - .. code-block:: sh + .. code-block:: sh - mongo + mongo - .. code-block:: javascript + .. code-block:: javascript - db.getMongo().getCollection("config.locks").findOne({ _id : "upgradeLock" }) + db.getMongo().getCollection("config.locks").findOne({ _id : "configUpgrade" }) If the process specified in the ``process`` field of this document is *verifiably* offline, run the following operation to force the lock. - .. code-block:: javascript + .. code-block:: javascript - db.getMongo().getCollection("config.locks").update({ _id : "upgradeLock" }, { $set : { state : 0 } }) + db.getMongo().getCollection("config.locks").update({ _id : "configUpgrade" }, { $set : { state : 0 } }) - It is always more safe to wait for the :program:`mongos` to verify - that the lock is inactive, if you have any doubts about the - activity of another upgrade operation. Note also that mongos may also - have to wait for other collection locks, which should not be forced. + It is always more safe to wait for the :program:`mongos` to + verify that the lock is inactive, if you have any doubts about + the activity of another upgrade operation. In addition to the + ``configUpgrade``, the :program:`mongos` may need to wait for + specific collection locks. Do not force the specific collection + locks. #. Upgrade and restart other :program:`mongos` processes in the sharded cluster, *without* the :option:`--upgrade ` @@ -176,8 +183,8 @@ incompatibilities in future versions of MongoDB. .. _upgrade-cluster-resync: -Resync after a Network Interruption -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Resync after an Interruption of the Critical Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ During the short critical section of the upgrade that applies changes to the metadata, it is unlikely but possible that a network diff --git a/source/release-notes/2.4.txt b/source/release-notes/2.4.txt index bc4ad12a24c..8dadd0a9028 100644 --- a/source/release-notes/2.4.txt +++ b/source/release-notes/2.4.txt @@ -6,16 +6,13 @@ Release Notes for MongoDB 2.4 (2.3 Development Series) MongoDB 2.4 is currently in development, as part of the 2.3 development release series. While 2.3-series releases are currently -available, these versions of MongoDB are for **testing** *only*, and -are *not for production use* under any circumstances. - -.. important:: *All* interfaces *and* functionality described in this - document are subject to change before the 2.4.0 release. +available, these versions of MongoDB, including the 2.4 release +candidate builds, are for *testing only and +not for production use*. This document will eventually contain the full release notes for -MongoDB 2.4; during the development cycle this document will contain -documentation of new features and functionality only available in the -2.3 releases. +MongoDB 2.4; before its release this document covers the 2.3.x +development branch as a work-in-progress. .. contents:: See the :doc:`full index of this page <2.4-changes>` for a complete list of changes included in 2.4. @@ -26,7 +23,7 @@ documentation of new features and functionality only available in the Downloading ----------- -You can download the 2.3 release on the `downloads page`_ in the +You can download the 2.4 release canditate on the `downloads page`_ in the :guilabel:`Development Release (Unstable)` section. There are no distribution packages for development releases, but you can use the binaries provided for testing purposes. See @@ -57,7 +54,7 @@ Text Indexes Background `````````` -MongoDB 2.3.2 includes a new ``text`` index type. ``text`` indexes +MongoDB 2.4 includes a new ``text`` index type. ``text`` indexes support boolean text search queries: - Any set of fields containing string data may be text indexed. @@ -596,10 +593,10 @@ Also consider the following documents that address authenticating to MongoDB using Kerberos: - :ecosystem:`Authenticate to MongoDB using Kerberos and the Java - Driver ` + Driver ` - :ecosystem:`Authenticate to MongoDB using Kerberos and the C# Driver - ` + ` .. see:: :doc:`MongoDB Security Practices and Procedures `. @@ -678,17 +675,31 @@ abbreviated as ES5, adds many new language features, including: - getters and setters. -With V8, MongoDB supports the latest standardized version of JavaScript -with the following exceptions. The following features do not work as expected -on documents returned from MongoDB queries: +With V8, MongoDB supports the ES5 implementation of Javascript with the +following exceptions. + +.. note:: + + The following features do not work as expected on documents + **returned from MongoDB queries**: + + - ``Object.seal()`` throws an exception on documents returned from + MongoDB queries. + + - ``Object.freeze()`` throws an exception on documents returned from + MongoDB queries. -- ``Object.seal()``, + - ``Object.preventExtensions()`` incorrectly allows the addition of + new properties on documents returned from MongoDB queries. -- ``Object.freeze()``, + - ``enumerable`` properties, when added to documents returned from + MongoDB queries, are not saved during write operations. -- ``Object.preventExtensions()``, and + See :issue:`SERVER-8216`, :issue:`SERVER-8223`, + :issue:`SERVER-8215`, and :issue:`SERVER-8214` for more information. -- enumerable properties. + For objects that have not been returned from MongoDB queries, the + features work as expected. Removed Non-Standard SpiderMonkey Features `````````````````````````````````````````` @@ -1131,90 +1142,32 @@ in MongoDB 2.4: New Geospatial Indexes with GeoJSON and Improved Spherical Geometry ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. note:: - - In 2.3.2, the index type for Spherical Geospatial Indexes - become ``2dsphere``. - -The 2.3 series adds a new type of geospatial index that supports -improved spherical queries and GeoJSON. Create the index by specifying -``2dsphere`` as the value of the field in the index specification, as -any of the following: - -.. code-block:: javascript - - db.collection.ensureIndex( { geo: "2dsphere" } ) - db.collection.ensureIndex( { type: 1, geo: "2dsphere" } ) - db.collection.ensureIndex( { geo: "2dsphere", type: 1 } ) - -In the first example you create a spherical geospatial index on the -field named ``geo``, in the second example, you create a compound -index where the first field is a normal index, and the index of the -second field is a spherical geospatial index. Unlike ``2d`` indexes, -fields indexed using the ``2dsphere`` type do not have to be the first -field in a compound index. - -You must store data in the fields indexed using the ``2dsphere`` index -using the `GeoJSON`_ specification, at the moment. Support for storing -points, in the form used by the existing ``2d`` (i.e. geospatial) -indexes is forthcoming. Currently, ``2dsphere`` indexes only support -the following GeoJSON shapes: - -- ``Point``, as in the following: - - .. code-block:: javascript - - { "type": "Point", "coordinates": [ 40, 5 ] } - -- ``LineString``, as in the following: - - .. code-block:: javascript - - { "type": "LineString", "coordinates": [ [ 40, 5 ], [ 41, 6 ] ] } +MongoDB adds the new ``2dsphere`` geospatial index in addition to the +existing ``2d`` index. The ``2dsphere`` index supports improved +spherical queries and supports the following `GeoJSON +`_ objects: -- ``Polygon``, as in the following: +- ``Point`` - .. code-block:: javascript - - { - "type": "Polygon", - "coordinates": [ [ [ 40, 5 ], [ 40, 6 ], [ 41, 6 ], [ 41, 5 ], [ 40, 5 ] ] ] - } - -To query ``2dsphere`` indexes, all current geospatial :ref:`query operators -` with an additional -:operator:`$geoIntersects` operator. Currently, all queries using the -``2dsphere`` index must pass the query selector (e.g. :operator:`$near`, -:operator:`$geoIntersects`) a GeoJSON document. With the exception of the -GeoJSON requirement, the operation of :operator:`$near` is the same -for ``2dsphere`` indexes as ``2d`` indexes. +- ``LineString`` -.. operator:: $geoIntersects +- ``Polygon`` - The :operator:`$geoIntersects` selects all indexed points that - intersect with the provided geometry. (i.e. ``Point``, ``LineString``, - and ``Polygon``.) You must pass :operator:`$geoIntersects` a document - in GeoJSON format. +The ``2dsphere`` index supports all current geospatial :ref:`query +operators ` and introduces the following new +query operator for queries on GeoJSON data: - .. code-block:: javascript - - db.collection.find( { loc: { $geoIntersects: - { $geometry: { "type": "Point", - "coordinates": [ 40, 5 ] - } } } } ) +- :operator:`$geoWithin` operator - This query will select all indexed objects that intersect with the - ``Point`` with the coordinates ``[ 40, 5 ]``. MongoDB will return - documents as intersecting if they have a shared edge. +- :operator:`$geoIntersects` operator - The :operator:`$geometry` operator takes a single `GeoJSON - document`_. +The operators use the new :operator:`$geometry` parameter. -.. operator:: $geometry +For more information, see: - .. _`GeoJSON document`: http://www.geojson.org/geojson-spec.html#appendix-a-geometry-examples +- :doc:`/applications/geospatial-indexes` -.. _`GeoJSON`: http://geojson.org/geojson-spec.html +- :doc:`/core/geospatial-indexes` New Hashed Index and Sharding with a Hashed Shard Key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1326,6 +1279,28 @@ key. Consider the following properties when using a hashed shard key: point values, see :ref:`hashed indexes ` for more information. +Increased Chunk Migration Write Concern +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default, all insert and delete operations that occur as part of a +:term:`chunk` migration in a :term:`sharded cluster` will have an +increased write concern, to ensure that at least one secondary +acknowledges each insert and deletion operation. This change slows the +potential speed of a chunk migration, but increases reliability and +ensures that a large number of chunk migrations *cannot* affect the +availability of a sharded cluster. + +BSON Document Validation Enabled by Default for ``mongod`` and ``mongorestore`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Starting in 2.4, MongoDB enables basic :term:`BSON` object validation +for :program:`mongod` and :program:`mongorestore` when writing to +MongoDB data files. This prevents any client from inserting invalid or +malformed BSON into a MongoDB database. For objects with a high degree +of sub-document nesting this validation may have a small performance +impact. :setting:`objcheck`, which was previously disabled by default, +provides this validation. + ``db.killOp()`` Can Now Kill Foreground Index Builds ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1371,6 +1346,21 @@ performs an insert, use the :operator:`$setOnInsert` operator with the update and for :method:`updates ` when the ``upsert`` option is ``false``. +``$each``, ``$slice``, and ``$sort`` Available for Use with ``$push`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can now use the :operator:`$push` operator with the following +modifiers: + +- :operator:`$each` to append multiple values to the array field, + +- :operator:`$slice` to restrict the number of array elements and which + must be used with :operator:`$each`, and + +- :operator:`$sort` to order the elements of the array, which + must be used with :operator:`$slice` and can **only** sort + arrays that contain documents. + ``--setParameter`` Option Available on the ``mongos`` and ``mongod`` Command Line ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1382,3 +1372,31 @@ and :setting:`setParameter` in the configuration file. Currently See :doc:`/reference/parameters` for full documentation of available parameters and their use. + +Multiple Index Builds +~~~~~~~~~~~~~~~~~~~~~ + +A single :program:`mongod` instance can build multiple indexes in the +background at the same time. See :ref:`building indexes in the +background ` for more information on +background index builds. Foreground index builds hold a database lock +and must proceed one at a time. + +Changes to ``serverStatus`` Output Including Additional Metrics +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In 2.4 MongoDB adds a number of counters and system metrics to the +output of the :dbcommand:`serverStatus` command, including: + +- a :ref:`working set estimator `. + +- operation counters, in :data:`~serverStatus.metrics.document` + and :data:`~serverStatus.metrics.operation`. + +- record allocation, in :data:`~serverStatus.metrics.record`. + +- thorough metrics of the replication process, + in :data:`~serverStatus.metrics.repl`. + +- metrics on the :doc:`ttl index ` + documentation. diff --git a/source/tutorial/backup-small-sharded-cluster-with-mongodump.txt b/source/tutorial/backup-small-sharded-cluster-with-mongodump.txt index 3a970b983aa..ca0d0a12315 100644 --- a/source/tutorial/backup-small-sharded-cluster-with-mongodump.txt +++ b/source/tutorial/backup-small-sharded-cluster-with-mongodump.txt @@ -7,54 +7,60 @@ Backup a Small Sharded Cluster with ``mongodump`` Overview -------- -If your :term:`sharded cluster` comprises a small collection of data, -you can connect to a :program:`mongos` and issue the -:program:`mongodump` command. You can use this approach if the following -is true: - -- It's possible to store the entire backup on one system or on a single - storage device. Consider both backups of entire instances and - incremental dumps of data. - -- The state of the database at the beginning of the operation is - not significantly different than the state of the database at the - end of the backup. - - Your application must be able to operate given a copy of the data - that reflects many moments in time. If the data collected by the - backup operation is not sufficient to restore from, using - :program:`mongodump` for your back ups is not viable. - -- The backup can run and complete without affecting the performance of - the cluster. - -If these conditions are not all true, then this backup method will not -support the needs of your deployment. Read -:ref:`sharded-cluster-backups` for a high-level overview of important +If your :term:`sharded cluster` holds a small data set, you can +connect to a :program:`mongos` using :program:`mongodump`. You can +create backups of your MongoDB cluster, if your backup infrastructure +can capture the entire backup in a reasonable amount of time and if +you have a storage system that can hold the complete MongoDB data set. + +Read :ref:`sharded-cluster-backups` for a high-level overview of important considerations as well as a list of alternate backup tutorials. +.. important:: By default :program:`mongodump` issue its queries to + the non-primary nodes. + Procedure --------- -.. note:: If you use :program:`mongodump` without specifying the a database or - collection, the output will contain both the collection data and the - sharding config metadata from the :ref:`config servers `. +Capture Data +~~~~~~~~~~~~ + +.. note:: + + If you use :program:`mongodump` without specifying the a database + or collection, :program:`mongodump` will capture collection data + *and* the cluster meta-data from the :ref:`config servers + `. You cannot use the :option:`--oplog ` option for - :program:`mongodump` when dumping from a :program:`mongos`. This option is only - available when running directly against a :term:`replica set` member. + :program:`mongodump` when capturing data from + :program:`mongos`. This option is only available when running + directly against a :term:`replica set` member. -To perform a backup of a shard cluster by connecting -:program:`mongodump` by connecting directly, use the following -operation a your system's prompt: +To perform a backup of a :term:`sharded cluster` by connecting +:program:`mongodump` by connecting to a :program:`mongos`, use the +following operation at your system's prompt: .. code-block:: sh - mongodump --journal --host mongos3.example.net --port 27017 + mongodump --host mongos3.example.net --port 27017 + +:program:`mongodump` will write :term:`BSON` files that hold a copy of +data stored in the :term:`sharded cluster` accessible via the +:program:`mongos` listening on port ``27017`` of the +``mongos3.example.net`` host. + +Restore Data +~~~~~~~~~~~~ -This will create a database dump of the shard cluster accessible via -the :program:`mongos` listening on port ``27017`` of the -``mongos3.example.net`` mongos instance. +Backups created with :program:`mongodump` do not reflect the chunks or +the distribution of data in the sharded collection or +collections. Like all :program:`mongodump` output, these backups +contain separate directories for each database and :term:`BSON` files +for each collection in that database. -The dump produced by this operation will effectively "unshard" your -data: you must re-shard and re-balance the data when you restore. +You can restore :program:`mongodump` output to any MongoDB instance, +including a standalone, a :term:`replica set`, or a new +:term:`sharded cluster`. When restoring data to sharded cluster, you +must deploy and configure sharding before restoring data from the +backup. See :doc:`/tutorial/deploy-shard-cluster` for more information. diff --git a/source/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes.txt b/source/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes.txt new file mode 100644 index 00000000000..87ed04a64b3 --- /dev/null +++ b/source/tutorial/calculate-distances-using-spherical-geometry-with-2d-geospatial-indexes.txt @@ -0,0 +1,151 @@ +============================================================== +Calculate Distances in a ``2d`` Index Using Spherical Geometry +============================================================== + +.. default-domain:: mongodb + +.. note:: While basic queries using spherical distance are supported by + the ``2d`` index, consider moving to a ``2dsphere`` index if your + data is primarily longitude and latitude. + +By default, ``2d`` indexes use flat (euclidean) geometry to calculate distances +between points, but they also support queries where distances between +points are computed using spherical geometry. The following operators +and command support such queries: + +- :operator:`$nearSphere` operator. + +- :operator:`$centerSphere`. + +- :dbcommand:`geoNear` command with the ``{ spherical: true }`` option. + +.. important:: These three queries use radians for distance. Other query types do not. + + For spherical query operators to function properly, you must convert + distances to radians, and convert from radians to the distances units + used by your application. + + To convert: + + - *distance to radians*: divide the distance by the radius of the + sphere (e.g. the Earth) in the same units as the distance + measurement. + + - *radians to distance*: multiply the radian measure by the radius + of the sphere (e.g. the Earth) in the units system that you want to + convert the distance to. + + The radius of the Earth is approximately ``3,959`` miles or + ``6,371`` kilometers. + +The following query would return documents from the ``places`` +collection within the circle described by the center ``[ -74, 40.74 ]`` +with a radius of ``100`` miles: + +.. code-block:: javascript + + db.places.find( { loc: { $geoWithin: { $centerSphere: [ [ -74, 40.74 ] , + 100 / 3959 ] } } } ) + +You may also use the ``distanceMultiplier`` option to the +:dbcommand:`geoNear` to convert radians in the :program:`mongod` +process, rather than in your application code. See :ref:`distance +multiplier `. + +The following spherical query, returns all documents in the +collection ``places`` within ``100`` miles from the point ``[ -74, +40.74 ]``. + +.. code-block:: javascript + + db.runCommand( { geoNear: "places", + near: [ -74, 40.74 ], + spherical: true + } ) + +The output of the above command would be: + +.. code-block:: javascript + + { + // [ ... ] + "results" : [ + { + "dis" : 0.01853688938212826, + "obj" : { + "_id" : ObjectId( ... ) + "loc" : [ + -73, + 40 + ] + } + } + ], + "stats" : { + // [ ... ] + "avgDistance" : 0.01853688938212826, + "maxDistance" : 0.01853714811400047 + }, + "ok" : 1 + } + +.. warning:: + + Spherical queries that wrap around the poles or at the transition + from ``-180`` to ``180`` longitude raise an error. + +.. note:: + + While the default Earth-like bounds for geospatial indexes are + between ``-180`` inclusive, and ``180``, valid values for latitude + are between ``-90`` and ``90``. + +.. _geospatial-indexes-distance-multiplier: + +Distance Multiplier +------------------- + +The ``distanceMultiplier`` option :dbcommand:`geoNear` returns +distances only after multiplying the results by command by an assigned +value. This allows MongoDB to return converted values, and removes the +requirement to convert units in application logic. + +Using ``distanceMultiplier`` in spherical queries provides results from +the :dbcommand:`geoNear` command that do not need radian-to-distance +conversion. The following example uses ``distanceMultiplier`` in the +:dbcommand:`geoNear` command with a :doc:`spherical +` example: + +.. code-block:: javascript + + db.runCommand( { geoNear: "places", + near: [ -74, 40.74 ], + spherical: true, + distanceMultiplier: 3959 + } ) + +The output of the above operation would resemble the following: + +.. code-block:: javascript + + { + // [ ... ] + "results" : [ + { + "dis" : 73.46525170413567, + "obj" : { + "_id" : ObjectId( ... ) + "loc" : [ + -73, + 40 + ] + } + } + ], + "stats" : { + // [ ... ] + "avgDistance" : 0.01853688938212826, + "maxDistance" : 0.01853714811400047 + }, + "ok" : 1 + } diff --git a/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt b/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt index 488377f1217..af71b91d64e 100644 --- a/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt +++ b/source/tutorial/control-access-to-mongodb-with-kerberos-authentication.txt @@ -65,7 +65,7 @@ Create Users and Privilege Documents For every user that you want to be able to authenticate using Kerberos, you must create corresponding privilege documents in the -:data:`system.users <.system.users` collection to provision +:data:`system.users <.system.users>` collection to provision access to users. Consider the following document: .. code-block:: javascript @@ -108,7 +108,7 @@ method, as in the following example: To modify a user document, use :doc:`update ` operations on documents in the :data:`system.users -<.system.users` collection. +<.system.users>` collection. .. seealso:: :doc:`/reference/privilege-documents` and :doc:`/reference/user-privileges`. diff --git a/source/tutorial/deploy-shard-cluster.txt b/source/tutorial/deploy-shard-cluster.txt index 29e32128930..687c5458831 100644 --- a/source/tutorial/deploy-shard-cluster.txt +++ b/source/tutorial/deploy-shard-cluster.txt @@ -14,7 +14,8 @@ sharded cluster for the first time, consider the To set up a sharded cluster, complete the following sequence of tasks in the order defined below: -1. :ref:`sharding-setup-start-cfgsrvr` + +#. :ref:`sharding-setup-start-cfgsrvr` #. :ref:`sharding-setup-start-mongos` @@ -52,7 +53,7 @@ instance on a system that runs other cluster components. .. code-block:: sh - mkdir /data/db/config + mkdir /data/configdb #. Start the three config server instances. Start each by issuing a command using the following syntax: diff --git a/source/tutorial/manage-chunks-in-sharded-cluster.txt b/source/tutorial/manage-chunks-in-sharded-cluster.txt index 52a3e11d30d..97c127aa974 100644 --- a/source/tutorial/manage-chunks-in-sharded-cluster.txt +++ b/source/tutorial/manage-chunks-in-sharded-cluster.txt @@ -174,19 +174,20 @@ To create and migrate chunks manually, use the following procedure: Modify Chunk Size ----------------- -When you initialize a sharded cluster, the default chunk size is 64 -megabytes. This default chunk size works well for most deployments. However, if you -notice that automatic migrations are incurring a level of I/O that -your hardware cannot handle, you may want to reduce the chunk -size. For the automatic splits and migrations, a small chunk size -leads to more rapid and frequent migrations. +When you initialize a sharded cluster, [#mongos-initialization]_ the +default chunk size is 64 megabytes. this default chunk size works well +for most deployments. however, if you notice that automatic migrations +are incurring a level of i/o that your hardware cannot handle, you may +want to reduce the chunk size. for the automatic splits and +migrations, a small chunk size leads to more rapid and frequent +migrations. -To modify the chunk size, use the following procedure: +to modify the chunk size, use the following procedure: -#. Connect to any :program:`mongos` in the cluster using the +#. connect to any :program:`mongos` in the cluster using the :program:`mongo` shell. -#. Issue the following command to switch to the :ref:`config-database`: +#. issue the following command to switch to the :ref:`config-database`: .. code-block:: javascript @@ -205,12 +206,13 @@ To modify the chunk size, use the following procedure: .. note:: - The :setting:`chunkSize` and :option:`--chunkSize ` - options, passed at runtime to the :program:`mongos` **do not** - affect the chunk size after you have initialized the cluster. + The :setting:`chunkSize` and :option:`--chunkSize ` options, passed at runtime to the :program:`mongos` + **do not** affect the chunk size after you have initialized the + cluster. [#mongos-initialization]_ To eliminate confusion you should *always* set chunk size using the - above procedure and never use the runtime options. + above procedure and never use the runtime options. Modifying the chunk size has several limitations: @@ -225,6 +227,10 @@ Modifying the chunk size has several limitations: If you increase the chunk size, existing chunks must grow through insertion or updates until they reach the new size. +.. [#mongos-initialization] The first :program:`mongos` that connects + to a set of :term:`config servers ` initializes + the sharded cluster. + .. _sharding-balancing-manual-migration: Migrate Chunks @@ -286,6 +292,10 @@ to pre-splitting. ` throughout the migration operation. For more information, see :ref:`sharded-cluster-config-secondary-throttle`. +.. versionchanged:: 2.4 + In 2.4, ``_secondaryThrottle`` is ``true`` by default. + + .. warning:: The :dbcommand:`moveChunk` command may produce the following error diff --git a/source/tutorial/manage-sharded-cluster-config-server.txt b/source/tutorial/manage-sharded-cluster-config-server.txt index 964848b9190..b6edc6de41a 100644 --- a/source/tutorial/manage-sharded-cluster-config-server.txt +++ b/source/tutorial/manage-sharded-cluster-config-server.txt @@ -120,6 +120,9 @@ server and it *will not* be accessible via the same hostname. If possible, avoid changing the hostname so that you can use the :ref:`previous procedure `. +#. Disable the cluster balancer process temporarily. See + :ref:`sharding-balancing-disable-temporally` for more information. + #. Shut down the :ref:`config server ` you're moving. This will render all config data for your cluster "read only:" @@ -152,6 +155,11 @@ possible, avoid changing the hostname so that you can use the :setting:`configdb`) for all :program:`mongos` instances and restart all :program:`mongos` instances. +#. Re-enable the balancer to allow the cluster to resume normal + balancing operations. See the + :ref:`sharding-balancing-disable-temporally` section for more + information on managing the balancer process. + .. _sharding-config-server-replace: Replace a Config Server @@ -164,6 +172,9 @@ you must change the hostname of the instance, use the process for :ref:`migrating a config server to a different hostname `. +#. Disable the cluster balancer process temporarily. See + :ref:`sharding-balancing-disable-temporally` for more information. + #. Provision a new system, with the same hostname as the previous host. @@ -190,6 +201,11 @@ you must change the hostname of the instance, use the process for mongod --configsvr +#. Re-enable the balancer to allow the cluster to resume normal + balancing operations. See the + :ref:`sharding-balancing-disable-temporally` section for more + information on managing the balancer process. + .. note:: In the course of this procedure *never* remove a config server from @@ -208,6 +224,9 @@ The cluster will remain operational [#read-only]_ without one of the config database's :program:`mongod` instances, creating a backup of the cluster metadata from the config database is straight forward: +#. Disable the cluster balancer process temporarily. See + :ref:`sharding-balancing-disable-temporally` for more information. + #. Shut down one of the :term:`config databases `. #. Create a full copy of the data files (i.e. the path specified by @@ -215,6 +234,11 @@ of the cluster metadata from the config database is straight forward: #. Restart the original configuration server. +#. Re-enable the balancer to allow the cluster to resume normal + balancing operations. See the + :ref:`sharding-balancing-disable-temporally` section for more + information on managing the balancer process. + .. seealso:: :doc:`/administration/backups`. .. [#read-only] While one of the three config servers is unavailable, diff --git a/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt b/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt index ffb0e5dd742..c07d9210bdc 100644 --- a/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt +++ b/source/tutorial/write-a-tumblelog-application-with-django-mongodb-engine.txt @@ -496,9 +496,8 @@ following code to generate the comments form: Your tumblelog's readers can now comment on your posts! Run ``python -manage.py runserver`` to see the changes. Run ``python manage.py -runserver`` and go to `http://localhost:8000/hello-world/ -`_ to see the following: +manage.py runserver`` to see the changes by visiting `http://localhost:8000/hello-world/ +`_. You should see the following: .. image:: .static/django-nonrel-comment-form.png :align: center diff --git a/source/use-cases/storing-comments.txt b/source/use-cases/storing-comments.txt index c64d2d31e89..2af73703953 100644 --- a/source/use-cases/storing-comments.txt +++ b/source/use-cases/storing-comments.txt @@ -577,7 +577,7 @@ logic to support this: This :py:meth:`update() ` operation includes the last known number of pages in the query to prevent a race -condition where the number of pages incriments twice, that would +condition where the number of pages increments twice, that would result in a nearly or totally empty document. If another process increments the number of pages, then update above does nothing. diff --git a/themes/mongodb/jiracollector.html b/themes/mongodb/jiracollector.html index e2e4c9ee878..86c3c64aafd 100644 --- a/themes/mongodb/jiracollector.html +++ b/themes/mongodb/jiracollector.html @@ -1,15 +1,27 @@ +{#- Comments on this, do not remove #} +{#- to add the popup to another target, add an id to the target #} +{#- and copy the #jirafeedback line below with the new id #} +{#- it is assumed that there is a component matching theme_project #} +{#- in JIRA. if you need to tweak it add a line in the if/else block -#} +{#- TODO: embed commit in environment metadata -#} {%- block jiracollector -%} +{%- if theme_project == 'manual' %} +{%- set component = 'mongodb-manual' -%} +{%- else -%} +{%- set component = theme_project -%} +{%- endif -%} {%- endblock -%} diff --git a/themes/mongodb/layout.html b/themes/mongodb/layout.html index 11a84aff3e3..eaabfb62275 100644 --- a/themes/mongodb/layout.html +++ b/themes/mongodb/layout.html @@ -149,7 +149,7 @@ {%- endif %}