diff --git a/config/migrations.yaml b/config/migrations.yaml index da74e10a942..2c05f9dfc51 100644 --- a/config/migrations.yaml +++ b/config/migrations.yaml @@ -10,7 +10,7 @@ dependency: # - $(public-output)/manual - links command: "fab generate.sitemap" -message: "[sitemap]: sitemap build complete at `date`." +message: "[sitemap]: sitemap build complete at ``date``." action: cmd --- # target: '$(public-output)/manual' diff --git a/draft/use-cases/ad-campaign-management.txt b/draft/use-cases/ad-campaign-management.txt index 85851636af2..71a3f7bc417 100644 --- a/draft/use-cases/ad-campaign-management.txt +++ b/draft/use-cases/ad-campaign-management.txt @@ -145,5 +145,7 @@ TODO: describe indexes to optimize this query Sharding -------- -.. seealso:: ":doc:`/faq/sharding`" and the ":wiki:`Sharding` wiki +.. seealso:: + + ":doc:`/faq/sharding`" and the ":wiki:`Sharding` wiki page. diff --git a/draft/use-cases/social-networking-updates-and-profiles.txt b/draft/use-cases/social-networking-updates-and-profiles.txt index b209417a3d4..097ec7fc533 100644 --- a/draft/use-cases/social-networking-updates-and-profiles.txt +++ b/draft/use-cases/social-networking-updates-and-profiles.txt @@ -648,5 +648,7 @@ on ``_id``, then, you'll need to execute the following command: ... 'key': {'_id': 1 } } ) { "collectionsharded": "social.post", "ok": 1 } -.. seealso:: ":doc:`/faq/sharding`" and the ":wiki:`Sharding` wiki +.. seealso:: + + ":doc:`/faq/sharding`" and the ":wiki:`Sharding` wiki page. diff --git a/snooty.toml b/snooty.toml index 4534449d385..8c4c550e868 100644 --- a/snooty.toml +++ b/snooty.toml @@ -1,4 +1,190 @@ -name = "manual" +name = "docs" +title = "MongoDB Manual" + +intersphinx = [ "https://pymongo.readthedocs.io/en/stable/objects.inv", + "https://motor.readthedocs.io/en/stable/objects.inv", + "https://docs.atlas.mongodb.com/objects.inv", + "https://docs.mongodb.com/php-library/master/objects.inv", + "https://docs.mongodb.com/compass/current/objects.inv", + "https://docs.mongodb.com/database-tools/objects.inv" + ] + +# toc_landing_pages are pages that have pages nested beneath them +# and **should** open when a user clicks on that page in the TOC +# (i.e. they're not drawers) +toc_landing_pages = [ + "/administration", + "/administration/analyzing-mongodb-performance", + "/administration/backup-sharded-clusters", + "/administration/configuration-and-maintenance", + "/administration/install-community", + "/administration/install-enterprise-linux", + "/administration/install-enterprise", + "/administration/install-on-linux/", + "/administration/monitoring", + "/administration/replica-set-deployment", + "/administration/replica-set-maintenance", + "/administration/replica-set-member-configuration", + "/administration/sharded-cluster-administration", + "/administration/sharded-cluster-config-servers", + "/administration/upgrade-community-to-enterprise", + "/aggregation", + "/applications/indexes", + "/applications/replication", + "/changeStreams", + "/core/2d", + "/core/2dsphere", + "/core/aggregation-pipeline", + "/core/auditing", + "/core/authentication-mechanisms-enterprise", + "/core/authentication-mechanisms", + "/core/authentication", + "/core/authorization", + "/core/backups", + "/core/crud", + "/core/databases-and-collections", + "/core/geohaystack", + "/core/index-creation", + "/core/index-multikey", + "/core/index-text", + "/core/index-ttl", + "/core/index-wildcard", + "/core/journaling", + "/core/kerberos", + "/core/map-reduce", + "/core/query-optimization", + "/core/read-isolation-consistency-recency", + "/core/read-preference", + "/core/replica-set-architectures", + "/core/replica-set-high-availability", + "/core/replica-set-members", + "/core/replica-set-secondary", + "/core/security-automatic-client-side-encryption", + "/core/security-client-side-encryption-key-management", + "/core/security-client-side-encryption", + "/core/security-encryption-at-rest", + "/core/security-hardening", + "/core/security-internal-authentication", + "/core/security-ldap", + "/core/security-transport-encryption", + "/core/security-users", + "/core/security-x.509", + "/core/sharded-cluster-components", + "/core/sharding-balancer-administration", + "/core/sharding-data-partitioning", + "/core/storage-engines", + "/core/transactions", + "/core/wiredtiger", + "/core/zone-sharding", + "/core/zone-sharding", + "/crud", + "/geospatial-queries", + "/indexes", + "/installation", + "/introduction", + "/mongo", + "/reference/aggregation", + "/reference/bson-types", + "/reference/collation", + "/reference/command", + "/reference/command/nav-administration", + "/reference/command/nav-aggregation", + "/reference/command/nav-auditing", + "/reference/command/nav-authentication", + "/reference/command/nav-crud", + "/reference/command/nav-diagnostic", + "/reference/command/nav-free-monitoring", + "/reference/command/nav-geospatial", + "/reference/command/nav-plan-cache", + "/reference/command/nav-replication", + "/reference/command/nav-role-management", + "/reference/command/nav-sessions", + "/reference/command/nav-sharding", + "/reference/command/nav-user-management", + "/reference/configuration-options", + "/reference/method", + "/reference/method/js-bulk", + "/reference/method/js-client-side-field-level-encryption", + "/reference/method/js-collection", + "/reference/method/js-connection", + "/reference/method/js-constructor", + "/reference/method/js-cursor", + "/reference/method/js-database", + "/reference/method/js-free-monitoring", + "/reference/method/js-native", + "/reference/method/js-plan-cache", + "/reference/method/js-replication", + "/reference/method/js-role-management", + "/reference/method/js-sharding", + "/reference/method/js-user-management", + "/reference/operator/aggregation-pipeline", + "/reference/operator/aggregation", + "/reference/operator/query-array", + "/reference/operator/query-bitwise", + "/reference/operator/query-comparison", + "/reference/operator/query-element", + "/reference/operator/query-evaluation", + "/reference/operator/query-geospatial", + "/reference/operator/query-logical", + "/reference/operator/query-miscellaneous", + "/reference/operator/query-modifiers", + "/reference/operator/query-projection", + "/reference/operator/query", + "/reference/operator/update-array", + "/reference/operator/update-bitwise", + "/reference/operator/update-field", + "/reference/operator/update", + "/reference/read-concern", + "/reference/replication", + "/reference/security", + "/reference/sharding", + "/release-notes/2.4", + "/release-notes/2.6", + "/release-notes/3.0", + "/release-notes/3.2-compatibility", + "/release-notes/3.2", + "/release-notes/3.4-downgrade", + "/release-notes/3.4", + "/release-notes/3.6", + "/release-notes/4.0", + "/release-notes/4.2-downgrade", + "/release-notes/4.2", + "/release-notes/4.4-downgrade", + "/release-notes/4.4", + "/replication", + "/security", + "/sharding", + "/storage", + "/text-search", + "/tutorial/insert-documents", + "/tutorial/install-mongodb-enterprise-on-amazon", + "/tutorial/install-mongodb-enterprise-on-debian", + "/tutorial/install-mongodb-enterprise-on-macos", + "/tutorial/install-mongodb-enterprise-on-red-hat", + "/tutorial/install-mongodb-enterprise-on-suse", + "/tutorial/install-mongodb-enterprise-on-ubuntu", + "/tutorial/install-mongodb-enterprise-on-windows", + "/tutorial/install-mongodb-on-amazon", + "/tutorial/install-mongodb-on-debian", + "/tutorial/install-mongodb-on-macos", + "/tutorial/install-mongodb-on-red-hat", + "/tutorial/install-mongodb-on-suse", + "/tutorial/install-mongodb-on-ubuntu", + "/tutorial/install-mongodb-on-windows", + "/tutorial/query-documents", + "/tutorial/remove-documents", + "/tutorial/update-documents" +] + +[substitutions] +compass = "MongoDB Compass" +mdb-shell = "MongoDB Shell" +copy = "©" +ent-build = "MongoDB Enterprise" +year = "2020" +bi = "MongoDB Connector for BI" +version = "4.2" + [constants] package-branch = "5.0" # For rc = testing. For GA, will be 4.2. @@ -6,11 +192,11 @@ windows-dir-version = "5.0" # The wizard installs in 4.2 branch package-name-org = "mongodb-org" package-name-enterprise = "mongodb-enterprise" version = "5.0" -release = "{+release+}" +release = "5.0" pgp-version = "{+version+}" -pgp-fingerprint = "E162F504A20CDF15827F718D4B7C549A058F8B6B" rsa-key = "4B7C549A058F8B6B" +pgp-fingerprint = "E162F504A20CDF15827F718D4B7C549A058F8B6B" pgp-fingerprint-fmt = "E162 F504 A20C DF15 827F 718D 4B7C 549A 058F 8B6B" -windows-sha256 = "C777DF7816BB8C9A760FDEA782113949408B6F39D72BE29A2551FA51E2FE0473" pgp-short-fingerprint = "0x4B7C549A058F8B6B" -source-available = "`source available and free to use `_" +windows-sha256 = "C777DF7816BB8C9A760FDEA782113949408B6F39D72BE29A2551FA51E2FE0473" +source-available = ":github:`source available and free to use `" diff --git a/source/about.txt b/source/about.txt index 123431f1ad1..678e81b3391 100644 --- a/source/about.txt +++ b/source/about.txt @@ -37,11 +37,6 @@ Manual. You can see the full revision history and track ongoing improvements and additions for all versions of the manual from its `GitHub repository `_. -This edition reflects "|branch|" branch of the documentation -as of the "|commit|" revision. This branch is explicitly accessible -via "|hardlink|" and you can always reference the commit of the -current manual in the :hardlink:`release.txt` file. - The most up-to-date, current, and stable version of the manual is always available at "https://docs.mongodb.com/manual/". diff --git a/source/administration/analyzing-mongodb-performance.txt b/source/administration/analyzing-mongodb-performance.txt index 6eec128496a..fc1a157d439 100644 --- a/source/administration/analyzing-mongodb-performance.txt +++ b/source/administration/analyzing-mongodb-performance.txt @@ -47,11 +47,11 @@ affecting your performance, refer to the :ref:`server-status-locks` section and the :ref:`globalLock` section of the :dbcommand:`serverStatus` output. -Dividing :serverstatus:`locks.timeAcquiringMicros` by -:serverstatus:`locks.acquireWaitCount` +Dividing :serverstatus:`locks..timeAcquiringMicros` by +:serverstatus:`locks..acquireWaitCount` can give an approximate average wait time for a particular lock mode. -:serverstatus:`locks.deadlockCount` provide +:serverstatus:`locks..deadlockCount` provide the number of times the lock acquisitions encountered deadlocks. If :serverstatus:`globalLock.currentQueue.total` is consistently high, @@ -156,8 +156,7 @@ processes run with FTDC on by default. For more information on MongoDB Support options, visit `Getting Started With MongoDB Support `_. -.. admonition:: FTDC Privacy - :class: important +.. important:: FTDC Privacy FTDC data files are compressed and not human-readable. MongoDB Inc. engineers cannot access FTDC data without explicit permission diff --git a/source/administration/backup-sharded-clusters.txt b/source/administration/backup-sharded-clusters.txt index f4f684bd55d..650c4312311 100644 --- a/source/administration/backup-sharded-clusters.txt +++ b/source/administration/backup-sharded-clusters.txt @@ -4,9 +4,6 @@ Backup and Restore Sharded Clusters .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger - .. contents:: On this page :local: :backlinks: none @@ -19,25 +16,23 @@ The following tutorials describe backup and restoration for sharded clusters: .. include:: /includes/extracts/sharded-clusters-backup-restore-mongodump-mongorestore-restriction.rst -.. class:: toc - - :doc:`/tutorial/backup-sharded-cluster-with-filesystem-snapshots` - Use file system snapshots back up each component in the sharded - cluster individually. The procedure involves stopping the cluster - balancer. If your system configuration allows file system backups, - this might be more efficient than using MongoDB tools. +:doc:`/tutorial/backup-sharded-cluster-with-filesystem-snapshots` + Use file system snapshots back up each component in the sharded + cluster individually. The procedure involves stopping the cluster + balancer. If your system configuration allows file system backups, + this might be more efficient than using MongoDB tools. - :doc:`/tutorial/backup-sharded-cluster-with-database-dumps` - Create backups using :binary:`~bin.mongodump` to back up each - component in the cluster individually. +:doc:`/tutorial/backup-sharded-cluster-with-database-dumps` + Create backups using :binary:`~bin.mongodump` to back up each + component in the cluster individually. - :doc:`/tutorial/schedule-backup-window-for-sharded-clusters` - Limit the operation of the cluster balancer to provide a window - for regular backup operations. +:doc:`/tutorial/schedule-backup-window-for-sharded-clusters` + Limit the operation of the cluster balancer to provide a window + for regular backup operations. - :doc:`/tutorial/restore-sharded-cluster` - An outline of the procedure and consideration for restoring an - *entire* sharded cluster from backup. +:doc:`/tutorial/restore-sharded-cluster` + An outline of the procedure and consideration for restoring an + *entire* sharded cluster from backup. .. toctree:: diff --git a/source/administration/change-streams-production-recommendations.txt b/source/administration/change-streams-production-recommendations.txt index dd61f3ab705..161533444e7 100644 --- a/source/administration/change-streams-production-recommendations.txt +++ b/source/administration/change-streams-production-recommendations.txt @@ -1,4 +1,4 @@ -.. index:: changeStreams notification + ========================================= Change Streams Production Recommendations diff --git a/source/administration/configuration-and-maintenance.txt b/source/administration/configuration-and-maintenance.txt index e83c57e1801..8351e81d6fa 100644 --- a/source/administration/configuration-and-maintenance.txt +++ b/source/administration/configuration-and-maintenance.txt @@ -7,26 +7,24 @@ Configuration and Maintenance This section describes routine management operations, including updating your MongoDB deployment's configuration. -.. class:: toc +:doc:`/administration/configuration` + Outlines common MongoDB configurations and examples of + best-practice configurations for common use cases. - :doc:`/administration/configuration` - Outlines common MongoDB configurations and examples of - best-practice configurations for common use cases. +:doc:`/tutorial/upgrade-revision` + Introduces the basic process for upgrading a MongoDB deployment + between different minor release versions. - :doc:`/tutorial/upgrade-revision` - Introduces the basic process for upgrading a MongoDB deployment - between different minor release versions. +:doc:`/tutorial/manage-mongodb-processes` + Start, configure, and manage running :binary:`~bin.mongod` + process. - :doc:`/tutorial/manage-mongodb-processes` - Start, configure, and manage running :binary:`~bin.mongod` - process. +:doc:`/tutorial/terminate-running-operations` + Stop in progress MongoDB client operations using + :method:`db.killOp()` and :method:`~cursor.maxTimeMS()`. - :doc:`/tutorial/terminate-running-operations` - Stop in progress MongoDB client operations using - :method:`db.killOp()` and :method:`~cursor.maxTimeMS()`. - - :doc:`/tutorial/rotate-log-files` - Archive the current log files and start new ones. +:doc:`/tutorial/rotate-log-files` + Archive the current log files and start new ones. .. toctree:: diff --git a/source/administration/configuration.txt b/source/administration/configuration.txt index 1b2f852da56..fb377c7dc96 100644 --- a/source/administration/configuration.txt +++ b/source/administration/configuration.txt @@ -216,7 +216,9 @@ The following configuration options are useful for limiting access to a connecting over the ``localhost`` interface for the first time to create user credentials. -.. seealso:: :doc:`/security` +.. seealso:: + + :doc:`/security` Replication and Sharding Configuration -------------------------------------- @@ -326,7 +328,9 @@ You can specify additional members of the config server replica set by specifying hostnames and ports in the form of a comma separated list after the replica set name. -.. seealso:: The :doc:`/sharding` section of the manual for more +.. seealso:: + + The :doc:`/sharding` section of the manual for more information on sharding and cluster configuration. Run Multiple Database Instances on the Same System @@ -351,7 +355,7 @@ The :setting:`~storage.dbPath` value controls the location of the :binary:`~bin.mongod` instance's data directory. Ensure that each database has a distinct and well labeled data directory. The :setting:`~processManagement.pidFilePath` controls where :binary:`~bin.mongod` process -places it's :term:`process id ` file. As this tracks the specific +places it's :term:`process id (PID) ` file. As this tracks the specific :binary:`~bin.mongod` file, it is crucial that file be unique and well labeled to make it easy to start and stop these processes. diff --git a/source/administration/install-community.txt b/source/administration/install-community.txt index 808ee0abcf7..043afb224d7 100644 --- a/source/administration/install-community.txt +++ b/source/administration/install-community.txt @@ -14,20 +14,17 @@ These documents provide instructions to install MongoDB Community Edition. .. _`MongoDB Download Center`: https://www.mongodb.com/try/download/community?tck=docs_server +:doc:`Install on Linux ` + Install MongoDB Community Edition and required dependencies on + Linux. -.. class:: toc +:doc:`Install on macOS ` + Install MongoDB Community Edition on macOS systems from MongoDB + archives. - :doc:`Install on Linux ` - Install MongoDB Community Edition and required dependencies on - Linux. - - :doc:`Install on macOS ` - Install MongoDB Community Edition on macOS systems from MongoDB - archives. - - :doc:`Install on Windows ` - Install MongoDB Community Edition on Windows systems and - optionally start MongoDB as a Windows service. +:doc:`Install on Windows ` + Install MongoDB Community Edition on Windows systems and + optionally start MongoDB as a Windows service. .. toctree:: diff --git a/source/administration/install-enterprise-linux.txt b/source/administration/install-enterprise-linux.txt index 32b1165b9d2..ed78f057667 100644 --- a/source/administration/install-enterprise-linux.txt +++ b/source/administration/install-enterprise-linux.txt @@ -7,27 +7,25 @@ Install MongoDB Enterprise on Linux These documents provide instructions to install MongoDB Enterprise Edition for supported Linux systems. -.. class:: toc +:doc:`Install on Red Hat ` + Install MongoDB Enterprise and required dependencies on Red Hat + Enterprise or CentOS Systems using packages. - :doc:`Install on Red Hat ` - Install MongoDB Enterprise and required dependencies on Red Hat - Enterprise or CentOS Systems using packages. +:doc:`Install on Ubuntu ` + Install MongoDB Enterprise and required dependencies on Ubuntu + Linux Systems using packages. - :doc:`Install on Ubuntu ` - Install MongoDB Enterprise and required dependencies on Ubuntu - Linux Systems using packages. +:doc:`Install on Debian ` + Install MongoDB Enterprise and required dependencies on Debian + Linux Systems using packages. - :doc:`Install on Debian ` - Install MongoDB Enterprise and required dependencies on Debian - Linux Systems using packages. +:doc:`Install on SUSE ` + Install MongoDB Enterprise and required dependencies on SUSE + Enterprise Linux. - :doc:`Install on SUSE ` - Install MongoDB Enterprise and required dependencies on SUSE - Enterprise Linux. - - :doc:`Install on Amazon ` - Install MongoDB Enterprise and required dependencies on Amazon - Linux AMI. +:doc:`Install on Amazon ` + Install MongoDB Enterprise and required dependencies on Amazon + Linux AMI. .. toctree:: diff --git a/source/administration/install-enterprise.txt b/source/administration/install-enterprise.txt index efa13f8cb80..c7bccb99d04 100644 --- a/source/administration/install-enterprise.txt +++ b/source/administration/install-enterprise.txt @@ -21,21 +21,19 @@ Event Auditing. .. include:: /includes/fact-macos-snmp.rst -.. class:: toc +:doc:`Install on Linux ` + Install the official builds of MongoDB Enterprise on Linux-based + systems. - :doc:`Install on Linux ` - Install the official builds of MongoDB Enterprise on Linux-based - systems. +:doc:`Install on macOS ` + Install the official build of MongoDB Enterprise on macOS - :doc:`Install on macOS ` - Install the official build of MongoDB Enterprise on macOS +:doc:`Install on Windows ` + Install MongoDB Enterprise on Windows using the ``.msi`` + installer. - :doc:`Install on Windows ` - Install MongoDB Enterprise on Windows using the ``.msi`` - installer. - - :doc:`Install with Docker ` - Install a MongoDB Enterprise Docker container. +:doc:`Install with Docker ` + Install a MongoDB Enterprise Docker container. .. toctree:: diff --git a/source/administration/install-on-linux.txt b/source/administration/install-on-linux.txt index ae0c665c5df..b56b6e1e6a3 100644 --- a/source/administration/install-on-linux.txt +++ b/source/administration/install-on-linux.txt @@ -17,27 +17,25 @@ Linux distributions. These packages are the preferred way to run MongoDB. The following guides detail the installation process for these systems: -.. class:: toc +:doc:`Install on Red Hat ` + Install MongoDB Community Edition on Red Hat Enterprise and + related Linux systems using ``.rpm`` packages. - :doc:`Install on Red Hat ` - Install MongoDB Community Edition on Red Hat Enterprise and - related Linux systems using ``.rpm`` packages. +:doc:`Install on Ubuntu ` + Install MongoDB Community Edition on Ubuntu Linux systems using + ``.deb`` packages. - :doc:`Install on Ubuntu ` - Install MongoDB Community Edition on Ubuntu Linux systems using - ``.deb`` packages. +:doc:`Install on Debian ` + Install MongoDB Community Edition on Debian systems using ``.deb`` + packages. - :doc:`Install on Debian ` - Install MongoDB Community Edition on Debian systems using ``.deb`` - packages. +:doc:`Install on SUSE ` + Install MongoDB Community Edition on SUSE Linux systems using + ``.rpm`` packages. - :doc:`Install on SUSE ` - Install MongoDB Community Edition on SUSE Linux systems using - ``.rpm`` packages. - - :doc:`Install on Amazon ` - Install MongoDB Community Edition on Amazon Linux AMI systems - using ``.rpm`` packages. +:doc:`Install on Amazon ` + Install MongoDB Community Edition on Amazon Linux AMI systems + using ``.rpm`` packages. .. include:: /includes/admonition-wsl.rst diff --git a/source/administration/monitoring.txt b/source/administration/monitoring.txt index d3b12488dc6..c5a45d1c1f7 100644 --- a/source/administration/monitoring.txt +++ b/source/administration/monitoring.txt @@ -431,7 +431,7 @@ the following helper in the shell: The :dbcommand:`replSetGetStatus` reference provides a more in-depth overview view of this output. In general, watch the value of -:data:`~replSetGetStatus.members.optimeDate`, and pay particular attention +:data:`~replSetGetStatus.members[n].optimeDate`, and pay particular attention to the time difference between the :term:`primary` and the :term:`secondary` members. @@ -463,7 +463,9 @@ instances. In addition, clusters require further monitoring to ensure that data is effectively distributed among nodes and that sharding operations are functioning appropriately. -.. seealso:: See the :doc:`/sharding` documentation for more +.. seealso:: + + See the :doc:`/sharding` documentation for more information. Config Servers diff --git a/source/administration/production-notes.txt b/source/administration/production-notes.txt index 9e7f7c6cddd..1cb1c887d35 100644 --- a/source/administration/production-notes.txt +++ b/source/administration/production-notes.txt @@ -13,8 +13,8 @@ Production Notes This page details system configurations that affect MongoDB, especially when running in production. -.. admonition:: MMAPv1 Removed - :class: warning +.. warning:: MMAPv1 Removed + MongoDB 4.2 removes the deprecated MMAPv1 storage engine. To change your MMAPv1 storage engine deployment to :doc:`/core/wiredtiger`, see: @@ -106,23 +106,23 @@ systems are recommended for production use on ``x86_64`` architecture: - Ubuntu LTS 16.04, 18.04, and 20.04 - Windows Server 2016 and 2019 -.. seealso:: :ref:`prod-notes-platform-considerations` +.. seealso:: + + :ref:`prod-notes-platform-considerations` Use the Latest Stable Packages ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Be sure you have the latest stable release. -All MongoDB releases are available on the `MongoDB Download Center`_ -page. The `MongoDB Download Center`_ page is a good place to verify the +All MongoDB releases are available on the :dl:`MongoDB Download Center <>` +page. The :dl:`MongoDB Download Center <>` is a good place to verify the current stable release, even if you are installing via a package manager. -For other MongoDB products, refer either to the `MongoDB Download Center`_ +For other MongoDB products, refer either to the :dl:`MongoDB Download Center <>` page or their `respective documentation `_. -.. _`MongoDB Download Center`: https://www.mongodb.com/try/download/community?tck=docs_server - MongoDB ``dbPath`` ------------------ @@ -149,7 +149,9 @@ readers and writers to the documents in a collection. Clients can read documents while write operations are in progress, and multiple threads can modify different documents in a collection at the same time. -.. seealso:: :ref:`prod-notes-ram` provides information about how WiredTiger +.. seealso:: + + :ref:`prod-notes-ram` provides information about how WiredTiger takes advantage of multiple CPU cores and how to improve operation throughput. @@ -296,7 +298,9 @@ If you are using MongoDB Enterprise with the :ref:`encrypted-storage-engine`, choose a CPU that supports AES-NI for better performance. -.. seealso:: :ref:`prod-notes-concurrency` +.. seealso:: + + :ref:`prod-notes-concurrency` Use Solid State Disks (SSDs) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -587,7 +591,9 @@ See :doc:`Sharded Cluster Production Architecture overview of recommended sharded cluster architectures for production deployments. -.. seealso:: :doc:`/administration/production-checklist-development` +.. seealso:: + + :doc:`/administration/production-checklist-development` Compression ----------- diff --git a/source/administration/replica-set-deployment.txt b/source/administration/replica-set-deployment.txt index 846cb1114a2..03687a90b52 100644 --- a/source/administration/replica-set-deployment.txt +++ b/source/administration/replica-set-deployment.txt @@ -12,37 +12,35 @@ Replica Set Deployment Tutorials The following tutorials provide information on deploying replica sets. -.. class:: toc +:doc:`/tutorial/deploy-replica-set` + Configure a three-member replica set for production systems. - :doc:`/tutorial/deploy-replica-set` - Configure a three-member replica set for production systems. +:doc:`/tutorial/deploy-replica-set-for-testing` + Configure a three-member replica set for either development or + testing systems. - :doc:`/tutorial/deploy-replica-set-for-testing` - Configure a three-member replica set for either development or - testing systems. +:doc:`/tutorial/deploy-geographically-distributed-replica-set` + Create a geographically redundant replica set to protect against + location-centered availability limitations (e.g. network and power + interruptions). - :doc:`/tutorial/deploy-geographically-distributed-replica-set` - Create a geographically redundant replica set to protect against - location-centered availability limitations (e.g. network and power - interruptions). +:doc:`/tutorial/add-replica-set-arbiter` + Add an arbiter to give a replica set an odd number of voting + members to prevent election ties. - :doc:`/tutorial/add-replica-set-arbiter` - Add an arbiter to give a replica set an odd number of voting - members to prevent election ties. +:doc:`/tutorial/convert-standalone-to-replica-set` + Convert an existing standalone ``mongod`` instance into a + three-member replica set. - :doc:`/tutorial/convert-standalone-to-replica-set` - Convert an existing standalone ``mongod`` instance into a - three-member replica set. +:doc:`/tutorial/expand-replica-set` + Add a new member to an existing replica set. - :doc:`/tutorial/expand-replica-set` - Add a new member to an existing replica set. +:doc:`/tutorial/remove-replica-set-member` + Remove a member from a replica set. - :doc:`/tutorial/remove-replica-set-member` - Remove a member from a replica set. - - :doc:`/tutorial/replace-replica-set-member` - Update the replica set configuration when the hostname of a - member's corresponding ``mongod`` instance has changed. +:doc:`/tutorial/replace-replica-set-member` + Update the replica set configuration when the hostname of a + member's corresponding ``mongod`` instance has changed. .. toctree:: diff --git a/source/administration/replica-set-maintenance.txt b/source/administration/replica-set-maintenance.txt index 3ce1a0bc812..3472540d7c6 100644 --- a/source/administration/replica-set-maintenance.txt +++ b/source/administration/replica-set-maintenance.txt @@ -13,43 +13,41 @@ Replica Set Maintenance Tutorials The following tutorials provide information in maintaining existing replica sets. -.. class:: toc +:doc:`/tutorial/change-oplog-size` + Increase the size of the :term:`oplog` which logs operations. In + most cases, the default oplog size is sufficient. - :doc:`/tutorial/change-oplog-size` - Increase the size of the :term:`oplog` which logs operations. In - most cases, the default oplog size is sufficient. +:doc:`/tutorial/perform-maintence-on-replica-set-members` + Perform maintenance on a member of a replica set while minimizing + downtime. - :doc:`/tutorial/perform-maintence-on-replica-set-members` - Perform maintenance on a member of a replica set while minimizing - downtime. +:doc:`/tutorial/force-member-to-be-primary` + Force a replica set member to become primary. - :doc:`/tutorial/force-member-to-be-primary` - Force a replica set member to become primary. +:doc:`/tutorial/resync-replica-set-member` + Sync the data on a member. Either perform initial sync on a new + member or resync the data on an existing member that has fallen + too far behind to catch up by way of normal replication. - :doc:`/tutorial/resync-replica-set-member` - Sync the data on a member. Either perform initial sync on a new - member or resync the data on an existing member that has fallen - too far behind to catch up by way of normal replication. +:doc:`/tutorial/configure-replica-set-tag-sets` + Assign tags to replica set members for use in targeting read and + write operations to specific members. - :doc:`/tutorial/configure-replica-set-tag-sets` - Assign tags to replica set members for use in targeting read and - write operations to specific members. +:doc:`/tutorial/reconfigure-replica-set-with-unavailable-members` + Reconfigure a replica set when a majority of replica set members + are down or unreachable. - :doc:`/tutorial/reconfigure-replica-set-with-unavailable-members` - Reconfigure a replica set when a majority of replica set members - are down or unreachable. +:doc:`/tutorial/manage-chained-replication` + Disable or enable chained replication. Chained replication occurs + when a secondary replicates from another secondary instead of the + primary. - :doc:`/tutorial/manage-chained-replication` - Disable or enable chained replication. Chained replication occurs - when a secondary replicates from another secondary instead of the - primary. +:doc:`/tutorial/change-hostnames-in-a-replica-set` + Update the replica set configuration to reflect changes in + members' hostnames. - :doc:`/tutorial/change-hostnames-in-a-replica-set` - Update the replica set configuration to reflect changes in - members' hostnames. - - :doc:`/tutorial/configure-replica-set-secondary-sync-target` - Specify the member that a secondary member synchronizes from. +:doc:`/tutorial/configure-replica-set-secondary-sync-target` + Specify the member that a secondary member synchronizes from. :doc:`/tutorial/rename-unsharded-replica-set` Rename an unsharded replica set. diff --git a/source/administration/replica-set-member-configuration.txt b/source/administration/replica-set-member-configuration.txt index 7f0302bd398..5d88573b65e 100644 --- a/source/administration/replica-set-member-configuration.txt +++ b/source/administration/replica-set-member-configuration.txt @@ -18,30 +18,28 @@ backups, to support reporting, or to act as a cold standby. .. include:: /includes/warning-mixed-version-rs-config.rst -.. class:: toc +:doc:`/tutorial/adjust-replica-set-member-priority` + Change the precedence given to a replica set members in an + election for primary. - :doc:`/tutorial/adjust-replica-set-member-priority` - Change the precedence given to a replica set member in an - election for primary. +:doc:`/tutorial/configure-secondary-only-replica-set-member` + Make a secondary member ineligible for election as primary. - :doc:`/tutorial/configure-secondary-only-replica-set-member` - Make a secondary member ineligible for election as primary. +:doc:`/tutorial/configure-a-hidden-replica-set-member` + Configure a secondary member to be invisible to applications in + order to support significantly different usage, such as a + dedicated backups. - :doc:`/tutorial/configure-a-hidden-replica-set-member` - Configure a secondary member to be invisible to applications in - order to support significantly different usage, such as a - dedicated backups. +:doc:`/tutorial/configure-a-delayed-replica-set-member` + Configure a secondary member to keep a delayed copy of the data + set in order to provide a rolling backup. - :doc:`/tutorial/configure-a-delayed-replica-set-member` - Configure a secondary member to keep a delayed copy of the data - set in order to provide a rolling backup. +:doc:`/tutorial/configure-a-non-voting-replica-set-member` + Create a secondary member that keeps a copy of the data set but + does not vote in an election. - :doc:`/tutorial/configure-a-non-voting-replica-set-member` - Create a secondary member that keeps a copy of the data set but - does not vote in an election. - - :doc:`/tutorial/convert-secondary-into-arbiter` - Convert a secondary to an arbiter. +:doc:`/tutorial/convert-secondary-into-arbiter` + Convert a secondary to an arbiter. .. toctree:: diff --git a/source/administration/security-checklist.txt b/source/administration/security-checklist.txt index 8e63a217fbe..814c33a2292 100644 --- a/source/administration/security-checklist.txt +++ b/source/administration/security-checklist.txt @@ -18,24 +18,21 @@ Pre-production Checklist/Considerations |arrow| Enable Access Control and Enforce Authentication ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. list-table:: - :widths: 5 95 - - * - - - - Enable access control and specify the authentication mechanism. - You can use MongoDB's SCRAM or x.509 authentication mechanism or - integrate with your existing Kerberos/LDAP infrastructure. Authentication - requires that all clients and servers provide valid credentials - before they can connect to the system. +.. container:: + + Enable access control and specify the authentication mechanism. + You can use MongoDB's SCRAM or x.509 authentication mechanism or + integrate with your existing Kerberos/LDAP infrastructure. Authentication + requires that all clients and servers provide valid credentials + before they can connect to the system. - See :doc:`/core/authentication` and - :doc:`/tutorial/enable-authentication`. + See :doc:`/core/authentication` and + doc:`/tutorial/enable-authentication`. .. _security-checklist-role-based-access-control: -|arrow| Configure Role-Based Access Control -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Configure Role-Based Access Control +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. list-table:: :widths: 5 95 diff --git a/source/administration/sharded-cluster-administration.txt b/source/administration/sharded-cluster-administration.txt index dd3401f536d..50073749500 100644 --- a/source/administration/sharded-cluster-administration.txt +++ b/source/administration/sharded-cluster-administration.txt @@ -27,43 +27,41 @@ Sharded Cluster Administration /tutorial/convert-replica-set-to-replicated-shard-cluster /tutorial/convert-shard-standalone-to-shard-replica-set -.. class:: toc +:doc:`Config Server Administration ` + This section contains articles and tutorials related to sharded + cluster config server administration - :doc:`Config Server Administration ` - This section contains articles and tutorials related to sharded - cluster config server administration +:doc:`/tutorial/view-sharded-cluster-configuration` + View status information about the cluster's databases, shards, and + chunks. - :doc:`/tutorial/view-sharded-cluster-configuration` - View status information about the cluster's databases, shards, and - chunks. +:doc:`/tutorial/restart-sharded-cluster` + Stop and restart a sharded cluster. - :doc:`/tutorial/restart-sharded-cluster` - Stop and restart a sharded cluster. +:doc:`/tutorial/migrate-sharded-cluster-to-new-hardware` + Migrate a sharded cluster to a different hardware system, for + example, when moving a pre-production environment to production. - :doc:`/tutorial/migrate-sharded-cluster-to-new-hardware` - Migrate a sharded cluster to a different hardware system, for - example, when moving a pre-production environment to production. +:doc:`/tutorial/add-shards-to-shard-cluster` + Add a shard to add capacity to a sharded cluster. - :doc:`/tutorial/add-shards-to-shard-cluster` - Add a shard to add capacity to a sharded cluster. +:doc:`/tutorial/remove-shards-from-cluster` + Migrate a single shard's data and remove the shard. - :doc:`/tutorial/remove-shards-from-cluster` - Migrate a single shard's data and remove the shard. +:doc:`/tutorial/clear-jumbo-flag` + Manually clear ``jumbo`` flag from a chunk. - :doc:`/tutorial/clear-jumbo-flag` - Manually clear ``jumbo`` flag from a chunk. +:doc:`/tutorial/backup-sharded-cluster-metadata` + Create a backup of a sharded cluster's metadata while keeping the + cluster operational. - :doc:`/tutorial/backup-sharded-cluster-metadata` - Create a backup of a sharded cluster's metadata while keeping the - cluster operational. +:doc:`/tutorial/convert-sharded-cluster-to-replica-set` + Convert a sharded cluster into a single replica set. - :doc:`/tutorial/convert-sharded-cluster-to-replica-set` - Convert a sharded cluster into a single replica set. +:doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` + Convert a replica set to a sharded cluster in which each shard is + its own replica set. - :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster` - Convert a replica set to a sharded cluster in which each shard is - its own replica set. - - :doc:`/tutorial/convert-shard-standalone-to-shard-replica-set` - Convert a shard standalone instance to a shard replica set. +:doc:`/tutorial/convert-shard-standalone-to-shard-replica-set` + Convert a shard standalone instance to a shard replica set. diff --git a/source/administration/sharded-cluster-config-servers.txt b/source/administration/sharded-cluster-config-servers.txt index 0553d8715a6..808d8a1e69b 100644 --- a/source/administration/sharded-cluster-config-servers.txt +++ b/source/administration/sharded-cluster-config-servers.txt @@ -16,10 +16,10 @@ Sharded Cluster Config Server Administration /tutorial/replace-config-server -.. class:: toc +:doc:`/tutorial/replace-config-server` + Replace a config server in a config server replica set. - :doc:`/tutorial/replace-config-server` - Replace a config server in a config server replica set. +.. seealso:: -.. seealso:: :doc:`/administration/backup-sharded-clusters` + :doc:`/administration/backup-sharded-clusters` diff --git a/source/aggregation.txt b/source/aggregation.txt index 2ce36218a3a..c7df889cc00 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -29,20 +29,6 @@ MongoDB's :doc:`aggregation framework processing pipelines. Documents enter a multi-stage pipeline that transforms the documents into an aggregated result. For example: -.. only:: website and dirhtml - - .. raw:: html - - - -.. only:: website and html and (not dirhtml) - - .. raw:: html - - - -In the example: - .. code-block:: javascript db.orders.aggregate([ diff --git a/source/appendix/security/appendixA-openssl-ca.txt b/source/appendix/security/appendixA-openssl-ca.txt index 60d3ab57304..39c65687d35 100644 --- a/source/appendix/security/appendixA-openssl-ca.txt +++ b/source/appendix/security/appendixA-openssl-ca.txt @@ -6,11 +6,8 @@ Appendix A - OpenSSL CA Certificate for Testing .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger +.. warning:: Disclaimer -.. admonition:: Disclaimer - :class: warning This page is provided for :red:`testing purposes` only and the certificates are for :red:`testing purposes only`. diff --git a/source/appendix/security/appendixB-openssl-server.txt b/source/appendix/security/appendixB-openssl-server.txt index eb0d21f004b..25bf95ba4a0 100644 --- a/source/appendix/security/appendixB-openssl-server.txt +++ b/source/appendix/security/appendixB-openssl-server.txt @@ -6,11 +6,10 @@ Appendix B - OpenSSL Server Certificates for Testing .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger -.. admonition:: Disclaimer - :class: warning + +.. warning:: Disclaimer + This page is provided for :red:`testing purposes` only and the certificates are for :red:`testing purposes only`. @@ -173,9 +172,7 @@ B. Generate the Test PEM File for Server :binary:`~bin.mongod` or a :binary:`~bin.mongos` for TLS/SSL :red:`testing`. For example: - **For MongoDB 4.2 or greater** - - .. container:: + .. example:: For MongoDB 4.2 or greater .. code-block:: javascript @@ -186,9 +183,7 @@ B. Generate the Test PEM File for Server :option:`--sslCAFile ` are :ref:`deprecated as of MongoDB 4.2 <4.2-tls>`. - **For MongoDB 4.0 and earlier** - - .. container:: + .. example:: For MongoDB 4.0 and earlier .. code-block:: javascript diff --git a/source/appendix/security/appendixC-openssl-client.txt b/source/appendix/security/appendixC-openssl-client.txt index 8cdf91cc072..eaaa48df098 100644 --- a/source/appendix/security/appendixC-openssl-client.txt +++ b/source/appendix/security/appendixC-openssl-client.txt @@ -6,11 +6,8 @@ Appendix C - OpenSSL Client Certificates for Testing .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger +.. warning:: Disclaimer -.. admonition:: Disclaimer - :class: warning This page is provided for :red:`testing purposes` only and the certificates are for :red:`testing purposes only`. @@ -139,18 +136,18 @@ B. Generate the Test PEM File for Client shell for TLS/SSL :red:`testing`. For example, to connect to a :binary:`~bin.mongod` or a :binary:`~bin.mongos`: - **For MongoDB 4.2 or greater**, include the following options for the client: + .. example:: - .. container:: + For MongoDB 4.2 or greater, include the following options for the client: .. code-block:: javascript mongo --tls --host --tlsCertificateKeyFile test-client.pem --tlsCAFile test-ca.pem - **For MongoDB 4.0 and earlier**, include the following options for the client: - - .. container:: + .. example:: + + For MongoDB 4.0 and earlier**, include the following options for the client: .. code-block:: javascript diff --git a/source/applications/data-models-applications.txt b/source/applications/data-models-applications.txt index 6f9c5a8a394..c6e61a52e23 100644 --- a/source/applications/data-models-applications.txt +++ b/source/applications/data-models-applications.txt @@ -10,30 +10,28 @@ Model Specific Application Contexts :depth: 1 :class: singlecol -.. class:: toc +:doc:`/tutorial/model-data-for-atomic-operations` + Illustrates how embedding fields related to an atomic update + within the same document ensures that the fields are in sync. - :doc:`/tutorial/model-data-for-atomic-operations` - Illustrates how embedding fields related to an atomic update - within the same document ensures that the fields are in sync. +:doc:`/tutorial/model-data-for-keyword-search` + Describes one method for supporting keyword search by storing + keywords in an array in the same document as the text field. + Combined with a multi-key index, this pattern can support + application's keyword search operations. - :doc:`/tutorial/model-data-for-keyword-search` - Describes one method for supporting keyword search by storing - keywords in an array in the same document as the text field. - Combined with a multi-key index, this pattern can support - application's keyword search operations. +:doc:`/tutorial/model-data-for-schema-versioning` + Describes one method for schema iteration without downtime. - :doc:`/tutorial/model-data-for-schema-versioning` - Describes one method for schema iteration without downtime. +:doc:`/tutorial/model-monetary-data` + Describes two methods to model monetary data in MongoDB. - :doc:`/tutorial/model-monetary-data` - Describes two methods to model monetary data in MongoDB. +:doc:`/tutorial/model-time-data` + Describes how to deal with local time in MongoDB. - :doc:`/tutorial/model-time-data` - Describes how to deal with local time in MongoDB. - - :doc:`/tutorial/model-computed-data` - Describes how to derive a value from source data and store that - value in a database. +:doc:`/tutorial/model-computed-data` + Describes how to derive a value from source data and store that + value in a database. .. toctree:: :titlesonly: diff --git a/source/applications/data-models-relationships.txt b/source/applications/data-models-relationships.txt index 2fd32d51875..cbd874eb0ce 100644 --- a/source/applications/data-models-relationships.txt +++ b/source/applications/data-models-relationships.txt @@ -10,22 +10,20 @@ Model Relationships Between Documents :depth: 1 :class: singlecol -.. class:: toc - - :doc:`/tutorial/model-embedded-one-to-one-relationships-between-documents` - Presents a data model that uses :ref:`embedded documents - ` to describe one-to-one relationships - between connected data. - - :doc:`/tutorial/model-embedded-one-to-many-relationships-between-documents` - Presents a data model that uses :ref:`embedded documents - ` to describe one-to-many relationships - between connected data. - - :doc:`/tutorial/model-referenced-one-to-many-relationships-between-documents` - Presents a data model that uses :ref:`references - ` to describe one-to-many relationships - between documents. +:doc:`/tutorial/model-embedded-one-to-one-relationships-between-documents` + Presents a data model that uses :ref:`embedded documents + ` to describe one-to-one relationships + between connected data. + +:doc:`/tutorial/model-embedded-one-to-many-relationships-between-documents` + Presents a data model that uses :ref:`embedded documents + ` to describe one-to-many relationships + between connected data. + +:doc:`/tutorial/model-referenced-one-to-many-relationships-between-documents` + Presents a data model that uses :ref:`references + ` to describe one-to-many relationships + between documents. .. toctree:: diff --git a/source/applications/data-models-tree-structures.txt b/source/applications/data-models-tree-structures.txt index 57f540bb1be..f2eb8ccc3d6 100644 --- a/source/applications/data-models-tree-structures.txt +++ b/source/applications/data-models-tree-structures.txt @@ -15,33 +15,31 @@ hierarchical or nested data relationships. .. include:: /images/data-model-tree.rst -.. class:: toc - - :doc:`/tutorial/model-tree-structures-with-parent-references` - Presents a data model that organizes documents in a tree-like - structure by storing :ref:`references ` - to "parent" nodes in "child" nodes. - - :doc:`/tutorial/model-tree-structures-with-child-references` - Presents a data model that organizes documents in a tree-like - structure by storing :ref:`references ` - to "child" nodes in "parent" nodes. - - :doc:`/tutorial/model-tree-structures-with-ancestors-array` - Presents a data model that organizes documents in a tree-like - structure by storing :ref:`references ` - to "parent" nodes and an array that stores all ancestors. - - :doc:`/tutorial/model-tree-structures-with-materialized-paths` - Presents a data model that organizes documents in a tree-like - structure by storing full relationship paths between documents. In - addition to the tree node, each document stores the ``_id`` of the - nodes ancestors or path as a string. - - :doc:`/tutorial/model-tree-structures-with-nested-sets` - Presents a data model that organizes documents in a tree-like - structure using the *Nested Sets* pattern. This optimizes - discovering subtrees at the expense of tree mutability. +:doc:`/tutorial/model-tree-structures-with-parent-references` + Presents a data model that organizes documents in a tree-like + structure by storing :ref:`references ` + to "parent" nodes in "child" nodes. + +:doc:`/tutorial/model-tree-structures-with-child-references` + Presents a data model that organizes documents in a tree-like + structure by storing :ref:`references ` + to "child" nodes in "parent" nodes. + +:doc:`/tutorial/model-tree-structures-with-ancestors-array` + Presents a data model that organizes documents in a tree-like + structure by storing :ref:`references ` + to "parent" nodes and an array that stores all ancestors. + +:doc:`/tutorial/model-tree-structures-with-materialized-paths` + Presents a data model that organizes documents in a tree-like + structure by storing full relationship paths between documents. In + addition to the tree node, each document stores the ``_id`` of the + nodes ancestors or path as a string. + +:doc:`/tutorial/model-tree-structures-with-nested-sets` + Presents a data model that organizes documents in a tree-like + structure using the *Nested Sets* pattern. This optimizes + discovering subtrees at the expense of tree mutability. .. toctree:: diff --git a/source/applications/data-models.txt b/source/applications/data-models.txt index a2ff16a24b3..1559207ce2c 100644 --- a/source/applications/data-models.txt +++ b/source/applications/data-models.txt @@ -13,7 +13,7 @@ Data Model Examples and Patterns :depth: 1 :class: singlecol -.. topic:: Building with Patterns Blog Series +.. seealso:: Building with Patterns Blog Series For additional patterns and use cases, see also: `Building with Patterns @@ -26,56 +26,54 @@ Data Model Examples and Patterns The following documents provide overviews of various data modeling patterns and common schema design considerations: -.. class:: toc - - :doc:`/applications/data-models-relationships` - Examples for modeling relationships between documents. - - :doc:`/tutorial/model-embedded-one-to-one-relationships-between-documents` - Presents a data model that uses :ref:`embedded documents - ` to describe one-to-one relationships - between connected data. - - :doc:`/tutorial/model-embedded-one-to-many-relationships-between-documents` - Presents a data model that uses :ref:`embedded documents - ` to describe one-to-many - relationships between connected data. - - :doc:`/tutorial/model-referenced-one-to-many-relationships-between-documents` - Presents a data model that uses :ref:`references - ` to describe one-to-many - relationships between documents. - - :doc:`/applications/data-models-tree-structures` - Examples for modeling tree structures. - - :doc:`/tutorial/model-tree-structures-with-parent-references` - Presents a data model that organizes documents in a tree-like - structure by storing :ref:`references - ` to "parent" nodes in "child" - nodes. - - :doc:`/tutorial/model-tree-structures-with-child-references` - Presents a data model that organizes documents in a tree-like - structure by storing :ref:`references - ` to "child" nodes in "parent" - nodes. - - See :doc:`/applications/data-models-tree-structures` for additional - examples of data models for tree structures. - - :doc:`/applications/data-models-applications` - Examples for models for specific application contexts. - - :doc:`/tutorial/model-data-for-atomic-operations` - Illustrates how embedding fields related to an atomic update - within the same document ensures that the fields are in sync. - - :doc:`/tutorial/model-data-for-keyword-search` - Describes one method for supporting keyword search by storing - keywords in an array in the same document as the text field. - Combined with a multi-key index, this pattern can support - application's keyword search operations. +:doc:`/applications/data-models-relationships` + Examples for modeling relationships between documents. + + :doc:`/tutorial/model-embedded-one-to-one-relationships-between-documents` + Presents a data model that uses :ref:`embedded documents + ` to describe one-to-one relationships + between connected data. + + :doc:`/tutorial/model-embedded-one-to-many-relationships-between-documents` + Presents a data model that uses :ref:`embedded documents + ` to describe one-to-many + relationships between connected data. + + :doc:`/tutorial/model-referenced-one-to-many-relationships-between-documents` + Presents a data model that uses :ref:`references + ` to describe one-to-many + relationships between documents. + +:doc:`/applications/data-models-tree-structures` + Examples for modeling tree structures. + + :doc:`/tutorial/model-tree-structures-with-parent-references` + Presents a data model that organizes documents in a tree-like + structure by storing :ref:`references + ` to "parent" nodes in "child" + nodes. + + :doc:`/tutorial/model-tree-structures-with-child-references` + Presents a data model that organizes documents in a tree-like + structure by storing :ref:`references + ` to "child" nodes in "parent" + nodes. + + See :doc:`/applications/data-models-tree-structures` for additional + examples of data models for tree structures. + +:doc:`/applications/data-models-applications` + Examples for models for specific application contexts. + + :doc:`/tutorial/model-data-for-atomic-operations` + Illustrates how embedding fields related to an atomic update + within the same document ensures that the fields are in sync. + + :doc:`/tutorial/model-data-for-keyword-search` + Describes one method for supporting keyword search by storing + keywords in an array in the same document as the text field. + Combined with a multi-key index, this pattern can support + application's keyword search operations. .. toctree:: diff --git a/source/applications/indexes.txt b/source/applications/indexes.txt index 393fc62fb88..cbefe083b0c 100644 --- a/source/applications/indexes.txt +++ b/source/applications/indexes.txt @@ -37,25 +37,23 @@ index, and in addition, MongoDB can use an :doc:`intersection The following documents introduce indexing strategies: -.. class:: toc - - :doc:`/tutorial/create-indexes-to-support-queries` - An index supports a query when the index contains all the fields - scanned by the query. Creating indexes that support queries - results in greatly increased query performance. - - :doc:`/tutorial/sort-results-with-indexes` - To support efficient queries, use the strategies here when you - specify the sequential order and sort order of index fields. - - :doc:`/tutorial/ensure-indexes-fit-ram` - When your index fits in RAM, the system can avoid reading the - index from disk and you get the fastest processing. - - :doc:`/tutorial/create-queries-that-ensure-selectivity` - Selectivity is the ability of a query to narrow results using the - index. Selectivity allows MongoDB to use the index for a larger - portion of the work associated with fulfilling the query. +:doc:`/tutorial/create-indexes-to-support-queries` + An index supports a query when the index contains all the fields + scanned by the query. Creating indexes that support queries + results in greatly increased query performance. + +:doc:`/tutorial/sort-results-with-indexes` + To support efficient queries, use the strategies here when you + specify the sequential order and sort order of index fields. + +:doc:`/tutorial/ensure-indexes-fit-ram` + When your index fits in RAM, the system can avoid reading the + index from disk and you get the fastest processing. + +:doc:`/tutorial/create-queries-that-ensure-selectivity` + Selectivity is the ability of a query to narrow results using the + index. Selectivity allows MongoDB to use the index for a larger + portion of the work associated with fulfilling the query. .. toctree:: diff --git a/source/applications/replication.txt b/source/applications/replication.txt index c8b256116ca..899e98e7ad1 100644 --- a/source/applications/replication.txt +++ b/source/applications/replication.txt @@ -21,18 +21,16 @@ additional read and write configurations for replica sets. replica sets provide the same operational semantics with regards to write and read operations. -.. class:: toc +:doc:`/core/replica-set-write-concern` + Write concern describes the level of acknowledgement requested + from MongoDB for write operations. - :doc:`/core/replica-set-write-concern` - Write concern describes the level of acknowledgement requested - from MongoDB for write operations. +:doc:`/core/read-preference` + Read preference specifies where (i.e. which members of the replica + set) the drivers should direct the read operations. - :doc:`/core/read-preference` - Read preference specifies where (i.e. which members of the replica - set) the drivers should direct the read operations. - - :doc:`/core/read-preference-mechanics` - Describes the mechanics of read preference. +:doc:`/core/read-preference-mechanics` + Describes the mechanics of read preference. .. toctree:: diff --git a/source/changeStreams.txt b/source/changeStreams.txt index d6e8045b847..763c4d0cd1f 100644 --- a/source/changeStreams.txt +++ b/source/changeStreams.txt @@ -1,7 +1,4 @@ -.. index:: changeStreams notification - .. _changeStreams: - .. _collection_watch: ============== @@ -98,8 +95,7 @@ You can open change streams against: documentation. See also the :binary:`~bin.mongo` shell method :method:`Mongo.watch()`. -.. admonition:: Change Stream Examples - :class: note +.. note:: Change Stream Examples The examples on this page use the MongoDB drivers to illustrate how to open a change stream cursor for a collection and work with the @@ -110,192 +106,195 @@ You can open change streams against: Open A Change Stream -------------------- +To open a change stream: + +- For a replica set, you can issue the open change stream operation + from any of the data-bearing members. + +- For a sharded cluster, you must issue the open change stream + operation from the :binary:`~bin.mongos`. + +The following example opens a change stream for a collection and +iterates over the cursor to retrieve the change stream documents. +[#start-time]_ + +.. tabs-selector:: drivers + +.. tabs-drivers:: + + .. tab:: + :tabid: python + + The Python examples below assume that you have :api:`connected to a MongoDB replica set and have accessed a database + ` that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: motor + + The examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/test_examples_motor.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: java-sync + + The Java examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/DocumentationSamples.java + :language: java + :dedent: 8 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: csharp + + The C# examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/ChangeStreamExamples.cs + :language: c# + :dedent: 12 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: c + + The C examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: c + :dedent: 3 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: nodejs + + The Node.js examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + The following example uses stream to process the change events. + + .. literalinclude:: /driver-examples/node_changestreams.js + :language: javascript + :dedent: 6 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + Alternatively, you can also use iterator to process the change events: + + .. literalinclude:: /driver-examples/node_changestreams.js + :language: javascript + :dedent: 6 + :start-after: Start Changestream Example 1 Alternative + :end-before: End Changestream Example 1 Alternative + + .. tab:: + :tabid: php + + The examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: ruby + + The examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + + .. literalinclude:: /driver-examples/change_stream_examples_spec.rb + :language: ruby + :dedent: 8 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: go + + The Go examples below assume that you have `connected to a MongoDB replica set and have accessed a database + `__ + that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :dedent: 2 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: swift-sync + + The Swift (Sync) examples below assume that you have + `connected to a MongoDB replica set and have accessed a + database + `__ + that contains an ``inventory`` collection. + + .. literalinclude:: /driver-examples/swiftSync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + + .. tab:: + :tabid: swift-async + + The Swift (Async) examples below assume that you have + `connected to a MongoDB replica set and have accessed a + database + `__ + that contains an ``inventory`` collection. -.. container:: - - .. tabs-pillstrip:: languages - - To open a change stream: - - - For a replica set, you can issue the open change stream operation - from any of the data-bearing members. - - - For a sharded cluster, you must issue the open change stream - operation from the :binary:`~bin.mongos`. - - The following example opens a change stream for a collection and - iterates over the cursor to retrieve the change stream documents. - [#start-time]_ - - .. tabs-drivers:: - - tabs: - - id: python - content: | - The Python examples below assume that you have :api:`connected to a MongoDB replica set and have accessed a database - ` that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/test_examples.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - - id: motor - content: | - The examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/test_examples_motor.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: java-sync - content: | - The Java examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/DocumentationSamples.java - :language: java - :dedent: 8 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: csharp - content: | - The C# examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/ChangeStreamExamples.cs - :language: c# - :dedent: 12 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: c - content: | - The C examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c - :language: c - :dedent: 3 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: nodejs - content: | - The Node.js examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - The following example uses stream to process the change events. - - .. literalinclude:: /driver-examples/node_changestreams.js - :language: javascript - :dedent: 6 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - Alternatively, you can also use iterator to process the change events: - - .. literalinclude:: /driver-examples/node_changestreams.js - :language: javascript - :dedent: 6 - :start-after: Start Changestream Example 1 Alternative - :end-before: End Changestream Example 1 Alternative - - - id: php - content: | - The examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/DocumentationExamplesTest.php - :language: php - :dedent: 8 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: ruby - content: | - The examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - - .. literalinclude:: /driver-examples/change_stream_examples_spec.rb - :language: ruby - :dedent: 8 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: go - content: | - The Go examples below assume that you have `connected to a MongoDB replica set and have accessed a database - `__ - that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/go_examples.go - :language: go - :dedent: 2 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: swift-sync - content: | - - The Swift (Sync) examples below assume that you have - `connected to a MongoDB replica set and have accessed a - database - `__ - that contains an ``inventory`` collection. - - - .. literalinclude:: /driver-examples/swiftSync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - id: swift-async - content: | - - The Swift (Async) examples below assume that you have - `connected to a MongoDB replica set and have accessed a - database - `__ - that contains an ``inventory`` collection. - - .. literalinclude:: /driver-examples/swiftAsync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 1 - :end-before: End Changestream Example 1 - - - To retrieve the :ref:`data change event ` from - the cursor, iterate the change stream cursor. For information on the - change stream event, see :ref:`change-stream-output`. - - While the connection to the MongoDB deployment remains - open, the cursor remains open until one of the following occurs: - - - The cursor is explicitly closed. - - - An :ref:`invalidate event ` occurs. - - - .. include:: /includes/extracts/changestream-remove-shard.rst - - .. note:: - The lifecycle of an unclosed cursor is language-dependent. + .. literalinclude:: /driver-examples/swiftAsync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 1 + :end-before: End Changestream Example 1 + +To retrieve the :ref:`data change event ` from +the cursor, iterate the change stream cursor. For information on the +change stream event, see :ref:`change-stream-output`. + +While the connection to the MongoDB deployment remains +open, the cursor remains open until one of the following occurs: + +- The cursor is explicitly closed. + +- An :ref:`invalidate event ` occurs. + +- .. include:: /includes/extracts/changestream-remove-shard.rst + +.. note:: + + The lifecycle of an unclosed cursor is language-dependent. .. [#start-time] @@ -309,167 +308,166 @@ Open A Change Stream Modify Change Stream Output --------------------------- -.. container:: - - .. tabs-pillstrip:: languages - - .. tabs-drivers:: - - tabs: - - id: python - content: | - - .. include:: /includes/fact-change-streams-modify-output.rst +.. tabs-drivers:: - .. literalinclude:: /driver-examples/test_examples.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 + .. tab:: + :tabid: python + .. include:: /includes/fact-change-streams-modify-output.rst - - id: motor - content: | + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 - .. include:: /includes/fact-change-streams-modify-output.rst - .. literalinclude:: /driver-examples/test_examples_motor.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 + .. tab:: + :tabid: motor - - id: java-sync - content: | + .. include:: /includes/fact-change-streams-modify-output.rst - .. include:: /includes/fact-change-streams-modify-output.rst + .. literalinclude:: /driver-examples/test_examples_motor.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 - .. code-block:: java + .. tab:: + :tabid: java-sync - MongoClient mongoClient = new MongoClient( new MongoClientURI("mongodb://host1:port1,host2:port2...")); + .. include:: /includes/fact-change-streams-modify-output.rst - // Select the MongoDB database and collection to open the change stream against + .. code-block:: java - MongoDatabase db = mongoClient.getDatabase("myTargetDatabase"); + MongoClient mongoClient = new MongoClient( new MongoClientURI("mongodb://host1:port1,host2:port2...")); - MongoCollection collection = db.getCollection("myTargetCollection"); + // Select the MongoDB database and collection to open the change stream against - // Create $match pipeline stage. - List pipeline = singletonList(Aggregates.match(Filters.or( - Document.parse("{'fullDocument.username': 'alice'}"), - Filters.in("operationType", asList("delete"))))); + MongoDatabase db = mongoClient.getDatabase("myTargetDatabase"); - // Create the change stream cursor, passing the pipeline to the - // collection.watch() method + MongoCollection collection = db.getCollection("myTargetCollection"); - MongoCursor cursor = collection.watch(pipeline).iterator(); + // Create $match pipeline stage. + List pipeline = singletonList(Aggregates.match(Filters.or( + Document.parse("{'fullDocument.username': 'alice'}"), + Filters.in("operationType", asList("delete"))))); - The ``pipeline`` list includes a single :pipeline:`$match` stage that - filters any operations where the ``username`` is ``alice``, or - operations where the ``operationType`` is ``delete``. + // Create the change stream cursor, passing the pipeline to the + // collection.watch() method - Passing the ``pipeline`` to the :method:`~db.collection.watch()` method directs the - change stream to return notifications after passing them through the - specified ``pipeline``. + MongoCursor cursor = collection.watch(pipeline).iterator(); - - id: csharp - content: | - .. include:: /includes/fact-change-streams-modify-output.rst + The ``pipeline`` list includes a single :pipeline:`$match` stage that + filters any operations where the ``username`` is ``alice``, or + operations where the ``operationType`` is ``delete``. - .. literalinclude:: /driver-examples/ChangeStreamExamples.cs - :language: c# - :dedent: 16 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 - - - id: c - content: | - .. include:: /includes/fact-change-streams-modify-output.rst + Passing the ``pipeline`` to the :method:`~db.collection.watch()` method directs the + change stream to return notifications after passing them through the + specified ``pipeline``. - .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c - :language: c - :dedent: 3 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 + .. tab:: + :tabid: csharp + + .. include:: /includes/fact-change-streams-modify-output.rst - - id: nodejs - content: | + .. literalinclude:: /driver-examples/ChangeStreamExamples.cs + :language: c# + :dedent: 16 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 + + .. tab:: + :tabid: c + + .. include:: /includes/fact-change-streams-modify-output.rst - .. include:: /includes/fact-change-streams-modify-output.rst + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: c + :dedent: 3 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 - The following example uses stream to process the change events. + .. tab:: + :tabid: nodejs - .. literalinclude:: /driver-examples/node_changestreams.js - :language: javascript - :dedent: 6 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 + .. include:: /includes/fact-change-streams-modify-output.rst - Alternatively, you can also use iterator to process the change events: + The following example uses stream to process the change events. - .. literalinclude:: /driver-examples/node_changestreams.js - :language: javascript - :dedent: 6 - :start-after: Start Changestream Example 4 Alternative - :end-before: End Changestream Example 4 Alternative + .. literalinclude:: /driver-examples/node_changestreams.js + :language: javascript + :dedent: 6 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 + Alternatively, you can also use iterator to process the change events: - - id: php - content: | - .. include:: /includes/fact-change-streams-modify-output.rst + .. literalinclude:: /driver-examples/node_changestreams.js + :language: javascript + :dedent: 6 + :start-after: Start Changestream Example 4 Alternative + :end-before: End Changestream Example 4 Alternative - .. literalinclude:: /driver-examples/DocumentationExamplesTest.php - :language: php - :dedent: 8 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 - - id: ruby - content: | - .. include:: /includes/fact-change-streams-modify-output.rst + .. tab:: + :tabid: php + + .. include:: /includes/fact-change-streams-modify-output.rst - - id: go - content: | + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 - .. include:: /includes/fact-change-streams-modify-output.rst + .. tab:: + :tabid: ruby + + .. include:: /includes/fact-change-streams-modify-output.rst - .. literalinclude:: /driver-examples/go_examples.go - :language: go - :dedent: 2 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 + .. tab:: + :tabid: go + + .. include:: /includes/fact-change-streams-modify-output.rst - - id: swift-sync - content: | + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :dedent: 2 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 - .. include:: /includes/fact-change-streams-modify-output.rst + .. tab:: + :tabid: swift-sync - .. literalinclude:: /driver-examples/swiftSync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 + .. include:: /includes/fact-change-streams-modify-output.rst - - id: swift-async - content: | + .. literalinclude:: /driver-examples/swiftSync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 - .. include:: /includes/fact-change-streams-modify-output.rst + .. tab:: + :tabid: swift-async + + .. include:: /includes/fact-change-streams-modify-output.rst - .. literalinclude:: /driver-examples/swiftAsync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 4 - :end-before: End Changestream Example 4 + .. literalinclude:: /driver-examples/swiftAsync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 4 + :end-before: End Changestream Example 4 - .. tip:: +.. tip:: - The :ref:`_id ` field of the change stream - event document act as the :ref:`resume token - `. Do not use the pipeline to modify or remove - the change stream event's ``_id`` field. + The :ref:`_id ` field of the change stream + event document act as the :ref:`resume token + `. Do not use the pipeline to modify or remove + the change stream event's ``_id`` field. - .. include:: /includes/extracts/4.2-changes-change-stream-modification-error.rst + .. include:: /includes/extracts/4.2-changes-change-stream-modification-error.rst See :ref:`change-stream-output` for more information on the change stream @@ -479,220 +477,215 @@ Modify Change Stream Output Lookup Full Document for Update Operations ------------------------------------------ -.. container:: - - .. tabs-pillstrip:: languages - - By default, change streams only return the delta of fields during - the update operation. However, you can configure the change stream - to return the most current majority-committed version of the updated - document. - - .. tabs-drivers:: - - tabs: - - id: python - content: | - - To return the most current majority-committed version of the updated - document, pass ``full_document='updateLookup'`` to the - :method:`db.collection.watch()` method. - - In the example below, all update operations notifications - include a ``full_document`` field that represents the *current* - version of the document affected by the update operation. - - .. literalinclude:: /driver-examples/test_examples.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 +By default, change streams only return the delta of fields during +the update operation. However, you can configure the change stream +to return the most current majority-committed version of the updated +document. +.. tabs-drivers:: - - id: motor - content: | + .. tab:: + :tabid: python - To return the most current majority-committed version of the updated - document, pass ``full_document='updateLookup'`` to the - :method:`db.collection.watch()` method. + To return the most current majority-committed version of the updated + document, pass ``full_document='updateLookup'`` to the + :method:`db.collection.watch()` method. - In the example below, all update operations notifications - include a ```full_document`` field that represents the *current* - version of the document affected by the update operation. + In the example below, all update operations notifications + include a ``full_document`` field that represents the *current* + version of the document affected by the update operation. - .. literalinclude:: /driver-examples/test_examples_motor.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 - - id: java-sync - content: | + .. tab:: + :tabid: motor - To return the most current majority-committed version of the updated - document, pass ``FullDocument.UPDATE_LOOKUP`` to the - :method:`db.collection.watch.fullDocument()` method. + To return the most current majority-committed version of the updated + document, pass ``full_document='updateLookup'`` to the + :method:`db.collection.watch()` method. - In the example below, all update operations notifications - include a ``FullDocument`` field that represents the *current* - version of the document affected by the update operation. + In the example below, all update operations notifications + include a ```full_document`` field that represents the *current* + version of the document affected by the update operation. - .. literalinclude:: /driver-examples/DocumentationSamples.java - :language: java - :dedent: 8 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 + .. literalinclude:: /driver-examples/test_examples_motor.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 - - id: c - content: | + .. tab:: + :tabid: java-sync + + To return the most current majority-committed version of the updated + document, pass ``FullDocument.UPDATE_LOOKUP`` to the + ``db.collection.watch.fullDocument()`` method. + + In the example below, all update operations notifications + include a ``FullDocument`` field that represents the *current* + version of the document affected by the update operation. + + .. literalinclude:: /driver-examples/DocumentationSamples.java + :language: java + :dedent: 8 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 - To return the most current majority-committed version of the updated - document, pass the ``"fullDocument"`` option with the ``"updateLookup"`` value to the - :method:`mongoc_collection_watch` method. - - In the example below, all update operations notifications - include a ``fullDocument`` field that represents the *current* - version of the document affected by the update operation. - - .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c - :language: c - :dedent: 3 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - - id: csharp - content: | - - To return the most current majority-committed version of the updated - document, pass ``"FullDocument = ChangeStreamFullDocumentOption.UpdateLookup"`` to the - :method:`collection.Watch()` method. - - In the example below, all update operations notifications - include a ``FullDocument`` field that represents the *current* - version of the document affected by the update operation. - - .. literalinclude:: /driver-examples/ChangeStreamExamples.cs - :language: C# - :dedent: 12 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - - - id: nodejs - content: | - - To return the most current majority-committed version of the updated - document, pass ``{ fullDocument: 'updateLookup' }`` to the - :method:`collection.watch()` method. - - In the example below, all update operations notifications - include a ``fullDocument`` field that represents the *current* - version of the document affected by the update operation. - - The following example uses stream to process the change events. - - .. literalinclude:: /driver-examples/node_changestreams.js - :language: javascript - :dedent: 6 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - Alternatively, you can also use iterator to process the change events: - - .. literalinclude:: /driver-examples/node_changestreams.js - :language: javascript - :dedent: 6 - :start-after: Start Changestream Example 2 Alternative - :end-before: End Changestream Example 2 Alternative - - - id: php - content: | - - To return the most current - majority-committed version of the updated document, pass - ``"fullDocument' => \MongoDB\Operation\ChangeStreamCommand::FULL_DOCUMENT_UPDATE_LOOKUP"`` - to the :method:`watch()` method. - - In the example below, all update operations notifications - include a ``fullDocument`` field that represents the *current* - version of the document affected by the update operation. - - .. literalinclude:: /driver-examples/DocumentationExamplesTest.php - :language: php - :dedent: 8 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - - id: ruby - content: | - To return the most current majority-committed version of the updated - document, pass ``full_document: 'updateLookup'`` to the - :method:`watch()` method. - - In the example below, all update operations notifications - include a ``full_document`` field that represents the *current* - version of the document affected by the update operation. - - .. literalinclude:: /driver-examples/change_stream_examples_spec.rb - :language: ruby - :dedent: 8 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - - id: go - content: | - - To return the most current majority-committed version of the - updated document, ``SetFullDocument(options.UpdateLookup)`` - change stream option. - - .. literalinclude:: /driver-examples/go_examples.go - :language: go - :dedent: 2 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - - id: swift-sync - content: | - - To return the most current majority-committed version of - the updated document, pass ``options: - ChangeStreamOptions(fullDocument: .updateLookup)`` to the - ``watch()`` method. - - .. literalinclude:: /driver-examples/swiftSync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - - id: swift-async - content: | - - To return the most current majority-committed version of - the updated document, pass ``options: - ChangeStreamOptions(fullDocument: .updateLookup)`` to the - ``watch()`` method. - - .. literalinclude:: /driver-examples/swiftAsync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 2 - :end-before: End Changestream Example 2 - - .. note:: - - If there are one or more majority-committed operations that modified - the updated document *after* the update operation but *before* the - lookup, the full document returned may differ significantly from the - document at the time of the update operation. - - However, the deltas included in the change stream document always - correctly describe the watched collection changes that applied to - that change stream event. - - See :ref:`change-stream-output` for more information on the change - stream response document format. + .. tab:: + :tabid: c + + To return the most current majority-committed version of the updated + document, pass the ``"fullDocument"`` option with the ``"updateLookup"`` value to the + ``mongoc_collection_watch`` method. + + In the example below, all update operations notifications + include a ``fullDocument`` field that represents the *current* + version of the document affected by the update operation. + + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: c + :dedent: 3 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + + .. tab:: + :tabid: csharp + + To return the most current majority-committed version of the updated + document, pass ``"FullDocument = ChangeStreamFullDocumentOption.UpdateLookup"`` to the + :method:`db.collection.watch()` method. + + In the example below, all update operations notifications + include a ``FullDocument`` field that represents the *current* + version of the document affected by the update operation. + + .. literalinclude:: /driver-examples/ChangeStreamExamples.cs + :language: C# + :dedent: 12 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + + + .. tab:: + :tabid: nodejs + + To return the most current majority-committed version of the updated + document, pass ``{ fullDocument: 'updateLookup' }`` to the + :method:`db.collection.watch()` method. + + In the example below, all update operations notifications + include a ``fullDocument`` field that represents the *current* + version of the document affected by the update operation. + + The following example uses stream to process the change events. + + .. literalinclude:: /driver-examples/node_changestreams.js + :language: javascript + :dedent: 6 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + + Alternatively, you can also use iterator to process the change events: + + .. literalinclude:: /driver-examples/node_changestreams.js + :language: javascript + :dedent: 6 + :start-after: Start Changestream Example 2 Alternative + :end-before: End Changestream Example 2 Alternative + + .. tab:: + :tabid: php + + To return the most current + majority-committed version of the updated document, pass + ``"fullDocument' => \MongoDB\Operation\ChangeStreamCommand::FULL_DOCUMENT_UPDATE_LOOKUP"`` + to the :method:`db.watch()` method. + + In the example below, all update operations notifications + include a ``fullDocument`` field that represents the *current* + version of the document affected by the update operation. + + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + + .. tab:: + :tabid: ruby + + To return the most current majority-committed version of the updated + document, pass ``full_document: 'updateLookup'`` to the + :method:`db.watch()` method. + + In the example below, all update operations notifications + include a ``full_document`` field that represents the *current* + version of the document affected by the update operation. + + .. literalinclude:: /driver-examples/change_stream_examples_spec.rb + :language: ruby + :dedent: 8 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + + .. tab:: + :tabid: go + + To return the most current majority-committed version of the + updated document, ``SetFullDocument(options.UpdateLookup)`` + change stream option. + + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :dedent: 2 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + + .. tab:: + :tabid: swift-sync + + To return the most current majority-committed version of + the updated document, pass ``options: + ChangeStreamOptions(fullDocument: .updateLookup)`` to the + ``watch()`` method. + + .. literalinclude:: /driver-examples/swiftSync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + + .. tab:: + :tabid: swift-async + + To return the most current majority-committed version of + the updated document, pass ``options: + ChangeStreamOptions(fullDocument: .updateLookup)`` to the + ``watch()`` method. + + .. literalinclude:: /driver-examples/swiftAsync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 2 + :end-before: End Changestream Example 2 + +.. note:: + + If there are one or more majority-committed operations that modified + the updated document *after* the update operation but *before* the + lookup, the full document returned may differ significantly from the + document at the time of the update operation. + + However, the deltas included in the change stream document always + correctly describe the watched collection changes that applied to + that change stream event. + + See :ref:`change-stream-output` for more information on the change + stream response document format. .. _change-stream-resume: @@ -708,203 +701,193 @@ Change streams are resumable by specifying a resume token to either ``resumeAfter`` for Change Streams ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +You can resume a change stream after a specific event by passing a resume token +to ``resumeAfter`` when opening the cursor. For the resume token, use the +``_id`` value of the :ref:`change stream event document `. +See :ref:`change-stream-resume-token` for more information on the resume token. - .. tabs-pillstrip:: languages +.. important:: - You can resume a change stream after a specific event by passing a resume token - to ``resumeAfter`` when opening the cursor. For the resume token, use the - ``_id`` value of the :ref:`change stream event document `. - See :ref:`change-stream-resume-token` for more information on the resume token. + - The oplog must have enough history to locate the operation + associated with the token or the timestamp, if the timestamp is in + the past. - .. important:: + - .. include:: /includes/extracts/changestream-invalid-events.rst - - The oplog must have enough history to locate the operation - associated with the token or the timestamp, if the timestamp is in - the past. +.. tabs-drivers:: - - .. include:: /includes/extracts/changestream-invalid-events.rst + .. tab:: + :tabid: python - .. tabs-drivers:: + You can use the ``resume_after`` modifier to resume + notifications after the operation specified in the resume + token. The ``resume_after`` modifier takes a value that must + resolve to a resume token, e.g. ``resume_token`` in the + example below. - tabs: - - id: python - content: | - You can use the ``resume_after`` modifier to resume - notifications after the operation specified in the resume - token. The ``resume_after`` modifier takes a value that must - resolve to a resume token, e.g. ``resume_token`` in the - example below. + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + .. tab:: + :tabid: motor - .. literalinclude:: /driver-examples/test_examples.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 + You can use the ``resume_after`` modifier to resume + notifications after the operation specified in the resume + token. The ``resume_after`` modifier takes a value that must + resolve to a resume token, e.g. ``resume_token`` in the + example below. - - id: motor - content: | + .. literalinclude:: /driver-examples/test_examples_motor.py + :language: python + :dedent: 12 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 - You can use the ``resume_after`` modifier to resume - notifications after the operation specified in the resume - token. The ``resume_after`` modifier takes a value that must - resolve to a resume token, e.g. ``resume_token`` in the - example below. + .. tab:: + :tabid: java-sync + + You can use the ``resumeAfter()`` method to resume + notifications after the operation specified in the resume + token. The ``resumeAfter()`` method takes a value that must + resolve to a resume token, e.g. ``resumeToken`` in the + example below. + + .. literalinclude:: /driver-examples/DocumentationSamples.java + :language: java + :dedent: 8 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + + .. tab:: + :tabid: csharp + + In the example below, the ``resumeToken`` is retrieved from the last change stream document + and passed to the ``Watch()`` method as an option. Passing the ``resumeToken`` + to the ``Watch()`` method directs + the change stream to attempt to resume notifications starting after the + operation specified in the resume token. - .. literalinclude:: /driver-examples/test_examples_motor.py - :language: python - :dedent: 12 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - id: java-sync - content: | - - You can use the ``resumeAfter()`` method to resume - notifications after the operation specified in the resume - token. The ``resumeAfter()`` method takes a value that must - resolve to a resume token, e.g. ``resumeToken`` in the - example below. - .. literalinclude:: /driver-examples/DocumentationSamples.java - :language: java - :dedent: 8 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 + .. literalinclude:: /driver-examples/ChangeStreamExamples.cs + :language: C# + :dedent: 14 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 - - id: csharp - content: | - - In the example below, the ``resumeToken`` is retrieved from the last change stream document - and passed to the ``Watch()`` method as an option. Passing the ``resumeToken`` - to the ``Watch()`` method directs - the change stream to attempt to resume notifications starting after the - operation specified in the resume token. - - .. class:: copyable-code - - .. literalinclude:: /driver-examples/ChangeStreamExamples.cs - :language: C# - :dedent: 14 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - - id: c - content: | - - In the example below, the ``resumeAfter`` option is appended to the stream options - to recreate the stream after it has been destroyed. Passing the ``_id`` to - the change stream attempts to resume notifications starting after the - operation specified. - - .. class:: copyable-code - - .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c - :language: C - :dedent: 3 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - - - id: nodejs - content: | - - You can use the ``resumeAfter`` option to resume - notifications after the operation specified in the resume - token. The ``resumeAfter`` option takes a value that must - resolve to a resume token, e.g. ``resumeToken`` in the - example below. - - .. literalinclude:: /driver-examples/node_changestreams.js - :language: javascript - :dedent: 6 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - - id: php - content: | - - You can use the ``resumeAfter`` option to resume - notifications after the operation specified in the resume - token. The ``resumeAfter`` option takes a value that must - resolve to a resume token, e.g. ``$resumeToken`` in the - example below. - - - .. class:: copyable-code - - .. literalinclude:: /driver-examples/DocumentationExamplesTest.php - :language: php - :dedent: 8 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - - id: ruby - content: | - - You can use the ``resume_after`` modifier to resume - notifications after the operation specified in the resume - token. The ``resume_after`` modifier takes a value that must - resolve to a resume token, e.g. ``resume_token`` in the - example below. - - .. class:: copyable-code - - .. literalinclude:: /driver-examples/change_stream_examples_spec.rb - :language: ruby - :dedent: 6 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - - id: go - content: | - - You can use `ChangeStreamOptions.SetResumeAfter - `_ - to specify the resume - token for the change stream. If the resumeAfter option is set, - the change stream resumes notifications after the operation - specified in the resume token. The ``SetResumeAfter`` takes a - value that must resolve to a resume token, e.g. - ``resumeToken`` in the example below. - - .. literalinclude:: /driver-examples/go_examples.go - :language: go - :dedent: 2 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - - id: swift-sync - content: | - - You can use the ``resumeAfter`` option to resume - notifications after the operation specified in the resume - token. The ``resumeAfter`` option takes a value that must - resolve to a resume token, e.g. ``resumeToken`` in the - example below. - - .. literalinclude:: /driver-examples/swiftSync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 - - - id: swift-async - content: | - - You can use the ``resumeAfter`` option to resume - notifications after the operation specified in the resume - token. The ``resumeAfter`` option takes a value that must - resolve to a resume token, e.g. ``resumeToken`` in the - example below. - - .. literalinclude:: /driver-examples/swiftAsync.swift - :language: swift - :dedent: 8 - :start-after: Start Changestream Example 3 - :end-before: End Changestream Example 3 + .. tab:: + :tabid: c + + In the example below, the ``resumeAfter`` option is appended to the stream options + to recreate the stream after it has been destroyed. Passing the ``_id`` to + the change stream attempts to resume notifications starting after the + operation specified. + + + + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: C + :dedent: 3 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + + + .. tab:: + :tabid: nodejs + + You can use the ``resumeAfter`` option to resume + notifications after the operation specified in the resume + token. The ``resumeAfter`` option takes a value that must + resolve to a resume token, e.g. ``resumeToken`` in the + example below. + + .. literalinclude:: /driver-examples/node_changestreams.js + :language: javascript + :dedent: 6 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + + .. tab:: + :tabid: php + + You can use the ``resumeAfter`` option to resume + notifications after the operation specified in the resume + token. The ``resumeAfter`` option takes a value that must + resolve to a resume token, e.g. ``$resumeToken`` in the + example below. + + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + + .. tab:: + :tabid: ruby + + You can use the ``resume_after`` modifier to resume + notifications after the operation specified in the resume + token. The ``resume_after`` modifier takes a value that must + resolve to a resume token, e.g. ``resume_token`` in the + example below. + + .. literalinclude:: /driver-examples/change_stream_examples_spec.rb + :language: ruby + :dedent: 6 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + + .. tab:: + :tabid: go + + You can use `ChangeStreamOptions.SetResumeAfter + `_ + to specify the resume + token for the change stream. If the resumeAfter option is set, + the change stream resumes notifications after the operation + specified in the resume token. The ``SetResumeAfter`` takes a + value that must resolve to a resume token, e.g. + ``resumeToken`` in the example below. + + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :dedent: 2 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + + .. tab:: + :tabid: swift-sync + + You can use the ``resumeAfter`` option to resume + notifications after the operation specified in the resume + token. The ``resumeAfter`` option takes a value that must + resolve to a resume token, e.g. ``resumeToken`` in the + example below. + + .. literalinclude:: /driver-examples/swiftSync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 + + .. tab:: + :tabid: swift-async + + You can use the ``resumeAfter`` option to resume + notifications after the operation specified in the resume + token. The ``resumeAfter`` option takes a value that must + resolve to a resume token, e.g. ``resumeToken`` in the + example below. + + .. literalinclude:: /driver-examples/swiftAsync.swift + :language: swift + :dedent: 8 + :start-after: Start Changestream Example 3 + :end-before: End Changestream Example 3 .. _change-stream-start-after: diff --git a/source/core/aggregation-pipeline-optimization.txt b/source/core/aggregation-pipeline-optimization.txt index a497c052c69..38a718e9d03 100644 --- a/source/core/aggregation-pipeline-optimization.txt +++ b/source/core/aggregation-pipeline-optimization.txt @@ -255,7 +255,7 @@ and MongoDB only needs to store ``n`` items in memory [#coalescence-allowDiskUse]_. See :ref:`sort-and-memory` for more information. -.. admonition:: Sequence Optimization with $skip +.. note:: Sequence Optimization with $skip If there is a :pipeline:`$skip` stage between the :pipeline:`$sort` and :pipeline:`$limit` stages, MongoDB will coalesce the @@ -418,6 +418,8 @@ transforms the sequence to the following: MongoDB increases the :pipeline:`$limit` amount with the reordering. -.. seealso:: +.. seealso:: + + :method:`explain ` option in the :method:`db.collection.aggregate()` diff --git a/source/core/aggregation-pipeline.txt b/source/core/aggregation-pipeline.txt index db872563f96..18a6de5380d 100644 --- a/source/core/aggregation-pipeline.txt +++ b/source/core/aggregation-pipeline.txt @@ -17,20 +17,6 @@ on the concept of data processing pipelines. Documents enter a multi-stage pipeline that transforms the documents into aggregated results. For example: -.. only:: website and dirhtml - - .. raw:: html - - - -.. only:: website and html and (not dirhtml) - - .. raw:: html - - - -In the example: - .. code-block:: javascript db.orders.aggregate([ @@ -76,7 +62,9 @@ updates in: .. include:: /includes/table-update-with-aggregation-availability.rst -.. seealso:: :doc:`/tutorial/update-documents-with-aggregation-pipeline` +.. seealso:: + + :doc:`/tutorial/update-documents-with-aggregation-pipeline` .. _aggregation-pipeline-expressions: diff --git a/source/core/backups.txt b/source/core/backups.txt index 0e28da957f4..143430147dd 100644 --- a/source/core/backups.txt +++ b/source/core/backups.txt @@ -4,8 +4,7 @@ MongoDB Backup Methods .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/core/bulk-write-operations.txt b/source/core/bulk-write-operations.txt index 463bef649f2..21600252262 100644 --- a/source/core/bulk-write-operations.txt +++ b/source/core/bulk-write-operations.txt @@ -212,7 +212,9 @@ consider the following modifications to your application: // now we may insert o into a sharded collection } -.. seealso:: :ref:`sharding-shard-key` for information +.. seealso:: + + :ref:`sharding-shard-key` for information on choosing a sharded key. Also see :ref:`Shard Key Internals ` (in particular, :ref:`sharding-internals-operations-and-reliability`). diff --git a/source/core/causal-consistency-read-write-concerns.txt b/source/core/causal-consistency-read-write-concerns.txt index e7ce2c2d2b3..1019dfa025c 100644 --- a/source/core/causal-consistency-read-write-concerns.txt +++ b/source/core/causal-consistency-read-write-concerns.txt @@ -89,8 +89,7 @@ five member replica set: :alt: Network partition: new primary elected on one side but old primary has not stepped down yet. :figwidth: 240px -.. admonition:: With the above partition - :class: admonition-example +.. example:: With the above partition - Writes with :writeconcern:`"majority"` write concern can complete on ``P``\ :sub:`new` but cannot complete on ``P``\ :sub:`old`. diff --git a/source/core/crud.txt b/source/core/crud.txt index aec23d11af9..5cf81e640b7 100644 --- a/source/core/crud.txt +++ b/source/core/crud.txt @@ -28,18 +28,18 @@ Query Plan, Performance, and Analysis Miscellaneous - :doc:`/core/tailable-cursors` -.. seealso:: :doc:`/core/transactions` +.. seealso:: -.. class:: hidden + :doc:`/core/transactions` - .. toctree:: - :titlesonly: +.. toctree:: + :titlesonly: - /core/write-operations-atomicity - /core/read-isolation-consistency-recency - /core/distributed-queries - /tutorial/perform-findAndModify-linearizable-reads - /core/query-plans - /core/query-optimization - /tutorial/analyze-query-plan - /core/tailable-cursors + /core/write-operations-atomicity + /core/read-isolation-consistency-recency + /core/distributed-queries + /tutorial/perform-findAndModify-linearizable-reads + /core/query-plans + /core/query-optimization + /tutorial/analyze-query-plan + /core/tailable-cursors diff --git a/source/core/data-modeling-introduction.txt b/source/core/data-modeling-introduction.txt index 228a76b8952..b3377c7b921 100644 --- a/source/core/data-modeling-introduction.txt +++ b/source/core/data-modeling-introduction.txt @@ -102,7 +102,9 @@ Multi-Document Transactions .. include:: /includes/extracts/transactions-intro.rst -.. seealso:: :ref:`Atomicity Considerations ` +.. seealso:: + + :ref:`Atomicity Considerations ` Data Use and Performance ------------------------ diff --git a/source/core/data-models.txt b/source/core/data-models.txt index 13df73d6e02..f1962cd253c 100644 --- a/source/core/data-models.txt +++ b/source/core/data-models.txt @@ -12,16 +12,14 @@ Data Modeling Concepts Consider the following aspects of data modeling in MongoDB: -.. class:: toc - - :doc:`/core/data-model-design` - Presents the different strategies that you can choose from when - determining your data model, their strengths and their weaknesses. - - :doc:`/core/data-model-operations` - Details features you should keep in mind when designing your data - model, such as lifecycle management, indexing, horizontal - scalability, and document growth. +:doc:`/core/data-model-design` + Presents the different strategies that you can choose from when + determining your data model, their strengths and their weaknesses. + +:doc:`/core/data-model-operations` + Details features you should keep in mind when designing your data + model, such as lifecycle management, indexing, horizontal + scalability, and document growth. For a general introduction to data modeling in MongoDB, see the diff --git a/source/core/distributed-queries.txt b/source/core/distributed-queries.txt index 7d5921113ea..b4917eae2c6 100644 --- a/source/core/distributed-queries.txt +++ b/source/core/distributed-queries.txt @@ -1,4 +1,4 @@ -.. index:: read operation; architecture + .. _read-operations-architecture: =================== @@ -58,7 +58,7 @@ In :term:`replica sets `, all write operations go to the set's :term:`primary`. The primary applies the write operation and records the operations on the primary's operation log or :term:`oplog`. The oplog is a reproducible sequence of operations to the data set. -:term:`Secondary` members of the set continuously replicate the oplog +:term:`secondary` members of the set continuously replicate the oplog and apply the operations to themselves in an asynchronous process. .. include:: /images/replica-set-read-write-operations-primary.rst @@ -158,8 +158,10 @@ of the sharded cluster. For more information, see :doc:`/sharding` and :doc:`/core/bulk-write-operations`. -.. seealso:: :ref:`retryable-writes` +.. seealso:: + + :ref:`retryable-writes` + + -.. index:: read operation; connection pooling -.. index:: connection pooling; read operations .. _read-operations-connection-pooling: diff --git a/source/core/document.txt b/source/core/document.txt index a20684e5c86..fcd85349021 100644 --- a/source/core/document.txt +++ b/source/core/document.txt @@ -82,11 +82,11 @@ names: .. include:: /includes/fact-document-field-name-restrictions.rst BSON documents may have more than one field with the same name. -Most :ecosystem:`MongoDB interfaces `, however, represent MongoDB +Most :driver:`MongoDB interfaces `, however, represent MongoDB with a structure (e.g. a hash table) that does not support duplicate field names. If you need to manipulate documents that have more than one -field with the same name, see the :ecosystem:`driver documentation -` for your driver. +field with the same name, see the :driver:`driver documentation +` for your driver. Some documents created by internal MongoDB processes may have duplicate fields, but *no* MongoDB process will *ever* add duplicate fields to an @@ -143,7 +143,7 @@ For examples querying arrays, see: - :update:`$[]` all positional operator for update operations, - - :update:`$[/]` filtered positional operator for update operations, + - :update:`$[\]` filtered positional operator for update operations, - :update:`$` positional operator for update operations, diff --git a/source/core/geohaystack.txt b/source/core/geohaystack.txt index 820fdd177c1..4be2a98102a 100644 --- a/source/core/geohaystack.txt +++ b/source/core/geohaystack.txt @@ -12,8 +12,8 @@ :depth: 1 :class: singlecol -.. admonition:: Deprecation - :class: important +.. important:: Deprecation + .. include:: /includes/extracts/4.4-changes-geo-deprecation.rst diff --git a/source/core/gridfs.txt b/source/core/gridfs.txt index 68c0d15134f..7020dbe2da6 100644 --- a/source/core/gridfs.txt +++ b/source/core/gridfs.txt @@ -1,4 +1,4 @@ -.. index:: GridFS + ====== GridFS @@ -81,10 +81,10 @@ remove previous versions if needed. Furthermore, if your files are all smaller than the 16 MB :limit:`BSON Document Size` limit, consider storing each file in a single document instead of using GridFS. You may use the BinData data type to store the binary data. -See your :ecosystem:`drivers ` documentation for details on +See your :driver:`drivers ` documentation for details on using BinData. -.. index:: GridFS; initialize + .. _gridfs-use: Use GridFS @@ -93,7 +93,7 @@ Use GridFS To store and retrieve files using :term:`GridFS`, use either of the following: -- A MongoDB driver. See the :ecosystem:`drivers` +- A MongoDB driver. See the :driver:`drivers` documentation for information on using GridFS with your driver. - The :binary:`~bin.mongofiles` command-line tool. See the @@ -124,7 +124,7 @@ buckets in a single database. The full collection name, which includes the bucket name, is subject to the :limit:`namespace length limit `. -.. index:: GridFS; chunks collection + .. _gridfs-chunks-collection: The ``chunks`` Collection @@ -163,7 +163,7 @@ A document from the ``chunks`` collection contains the following fields: The chunk's payload as a :term:`BSON` ``Binary`` type. -.. index:: GridFS; files collection + .. _gridfs-files-collection: The ``files`` Collection @@ -254,15 +254,16 @@ following fields: additional arbitrary fields to documents in the ``files`` collection, add them to an object in the metadata field. -.. index:: GridFS; index; indexes + .. _gridfs-indexes: GridFS Indexes -------------- GridFS uses indexes on each of the ``chunks`` and ``files`` collections -for efficiency. :ecosystem:`Drivers ` that conform to -the `GridFS specification`_ automatically create these indexes for +for efficiency. :driver:`Drivers ` that conform to +the :spec:`GridFS specification ` +automatically create these indexes for convenience. You can also create any additional indexes as desired to suit your application's needs. @@ -280,7 +281,7 @@ chunks, as demonstrated in the following example: db.fs.chunks.find( { files_id: myFileID } ).sort( { n: 1 } ) -:ecosystem:`Drivers ` that conform to the `GridFS +:driver:`Drivers ` that conform to the `GridFS specification`_ will automatically ensure that this index exists before read and write operations. See the relevant driver documentation for the specific behavior of your GridFS application. @@ -305,8 +306,8 @@ efficient retrieval of files, as shown in this example: db.fs.files.find( { filename: myFileName } ).sort( { uploadDate: 1 } ) -:ecosystem:`Drivers ` that conform to the `GridFS -specification`_ will automatically ensure that this index exists before +:driver:`Drivers ` that conform to the :spec:`GridFS +specification ` will automatically ensure that this index exists before read and write operations. See the relevant driver documentation for the specific behavior of your GridFS application. @@ -321,12 +322,10 @@ create it using the :binary:`~bin.mongo` shell: of GridFS is not related to the use of the term *chunks* in the context of sharding. -.. _`GridFS specification`: https://github.com/mongodb/specifications/blob/master/source/gridfs/gridfs-spec.rst - Sharding GridFS --------------- -There are two collections to consider with :term:`gridfs` - ``files`` and +There are two collections to consider with :term:`GridFS` - ``files`` and ``chunks``. ``chunks`` Collection @@ -334,7 +333,7 @@ There are two collections to consider with :term:`gridfs` - ``files`` and To shard the ``chunks`` collection, use either ``{ files_id : 1, n : 1 }`` or ``{ files_id : 1 }`` as the shard key index. ``files_id`` is an -:term:`objectid` and changes :ref:`monotonically`. +:term:`ObjectId` and changes :ref:`monotonically`. For MongoDB drivers that do not run :dbcommand:`filemd5` to verify successful upload (for example, MongoDB drivers that support MongoDB diff --git a/source/core/hashed-sharding.txt b/source/core/hashed-sharding.txt index fbd971e98ef..2f034c6cfd4 100644 --- a/source/core/hashed-sharding.txt +++ b/source/core/hashed-sharding.txt @@ -65,7 +65,7 @@ The field you choose as your hashed shard key should have a good Hashed keys are ideal for shard keys with fields that change :ref:`monotonically` like :term:`ObjectId` values or timestamps. A good example of this is the default ``_id`` field, assuming -it only contains :term:`ObjectID` values. +it only contains :term:`ObjectId` values. To shard a collection using a hashed shard key, see :ref:`deploy-hashed-sharded-cluster-shard-collection`. diff --git a/source/core/index-compound.txt b/source/core/index-compound.txt index edece6bce02..669b9c84a28 100644 --- a/source/core/index-compound.txt +++ b/source/core/index-compound.txt @@ -1,5 +1,5 @@ -.. index:: index; compound -.. index:: compound index + + .. _index-type-compound: ================ @@ -95,7 +95,7 @@ as well as both ``item`` and ``stock`` fields: For details, see :ref:`compound-index-prefix`. -.. index:: index; sort order + .. _index-ascending-and-descending: Sort Order diff --git a/source/core/index-creation.txt b/source/core/index-creation.txt index 3dd92aea1e9..2306ea65440 100644 --- a/source/core/index-creation.txt +++ b/source/core/index-creation.txt @@ -1,4 +1,4 @@ -.. index:: index; options + .. _index-operations: .. _index-creation-background: @@ -123,7 +123,9 @@ To mitigate the risk of this occurrence, before creating the index: - Stop all writes to the collection from applications that cannot guarantee violation-free write operations. -.. seealso:: :ref:`index-creation-index-consistency` +.. seealso:: + + :ref:`index-creation-index-consistency` Index Build Impact on Database Performance ------------------------------------------ @@ -574,7 +576,9 @@ process: - The :binary:`~bin.mongod` releases the ``X`` lock on the collection. -.. seealso:: :doc:`/faq/concurrency` +.. seealso:: + + :doc:`/faq/concurrency` .. toctree:: :titlesonly: diff --git a/source/core/index-hashed.txt b/source/core/index-hashed.txt index 945dffb6329..35ad8c251cd 100644 --- a/source/core/index-hashed.txt +++ b/source/core/index-hashed.txt @@ -1,4 +1,4 @@ -.. index:: index; hashed + .. _index-type-hashed: .. _index-hashed-index: @@ -74,7 +74,9 @@ the index: Compound hashed indexes require :ref:`featureCompatibilityVersion ` set to ``4.4``. -.. seealso:: :ref:`sharding-hashed-sharding` +.. seealso:: + + :ref:`sharding-hashed-sharding` Considerations -------------- diff --git a/source/core/index-hidden.txt b/source/core/index-hidden.txt index cb084ceae21..e13ec685b01 100644 --- a/source/core/index-hidden.txt +++ b/source/core/index-hidden.txt @@ -1,4 +1,4 @@ -.. index:: index; hidden + .. _index-type-hidden: =============== diff --git a/source/core/index-intersection.txt b/source/core/index-intersection.txt index 4b2e9e9091b..ef3c5d570f4 100644 --- a/source/core/index-intersection.txt +++ b/source/core/index-intersection.txt @@ -131,7 +131,9 @@ The choice between creating compound indexes that support your queries or relying on index intersection depends on the specifics of your system. -.. seealso:: :doc:`compound indexes `, +.. seealso:: + + :doc:`compound indexes `, :ref:`compound-key-indexes` .. _index-intersection-sort: diff --git a/source/core/index-multikey.txt b/source/core/index-multikey.txt index 37e21debc21..4f2c9a2afd2 100644 --- a/source/core/index-multikey.txt +++ b/source/core/index-multikey.txt @@ -1,4 +1,4 @@ -.. index:: index; multikey + .. _index-type-multi-key: .. _index-type-multikey: diff --git a/source/core/index-partial.txt b/source/core/index-partial.txt index 9f24fb70460..5805f64981a 100644 --- a/source/core/index-partial.txt +++ b/source/core/index-partial.txt @@ -1,4 +1,4 @@ -.. index:: index; partial + .. _index-type-partial: =============== diff --git a/source/core/index-properties.txt b/source/core/index-properties.txt index 3ffb2b7e61a..86ec3c88210 100644 --- a/source/core/index-properties.txt +++ b/source/core/index-properties.txt @@ -15,30 +15,28 @@ MongoDB supports, indexes can also have various properties. The following documents detail the index properties that you can select when building an index. -.. class:: toc +:doc:`/core/index-ttl` + The TTL index is used for TTL collections, which expire data after + a period of time. - :doc:`/core/index-ttl` - The TTL index is used for TTL collections, which expire data after - a period of time. +:doc:`/core/index-unique` + A unique index causes MongoDB to reject all documents that contain + a duplicate value for the indexed field. - :doc:`/core/index-unique` - A unique index causes MongoDB to reject all documents that contain - a duplicate value for the indexed field. +:doc:`/core/index-partial` + A partial index indexes only documents that meet specified filter + criteria. - :doc:`/core/index-partial` - A partial index indexes only documents that meet specified filter - criteria. +:doc:`/core/index-case-insensitive` + A case insensitive index disregards the case of the index key + values. - :doc:`/core/index-case-insensitive` - A case insensitive index disregards the case of the index key - values. +:doc:`/core/index-hidden` + A hidden index is not visible to the query planner. - :doc:`/core/index-hidden` - A hidden index is not visible to the query planner. - - :doc:`/core/index-sparse` - A sparse index does not index documents that do not have the - indexed field. +:doc:`/core/index-sparse` + A sparse index does not index documents that do not have the + indexed field. .. toctree:: diff --git a/source/core/index-single.txt b/source/core/index-single.txt index 16c18a7b946..929865d9082 100644 --- a/source/core/index-single.txt +++ b/source/core/index-single.txt @@ -51,7 +51,7 @@ The created index will support queries that select on the field db.records.find( { score: 2 } ) db.records.find( { score: { $gt: 10 } } ) -.. index:: index; embedded fields + .. _index-embedded-fields: .. _index-subdocuments: .. _index-embedded-documents: diff --git a/source/core/index-sparse.txt b/source/core/index-sparse.txt index eb95cf2343a..6b9fc288799 100644 --- a/source/core/index-sparse.txt +++ b/source/core/index-sparse.txt @@ -1,4 +1,4 @@ -.. index:: index; sparse + .. _index-type-sparse: ============== @@ -184,7 +184,7 @@ complete results: { "_id" : ObjectId("523b6e32fb408eea0eec2647"), "userid" : "newbie" } To use the sparse index, explicitly specify the index with -:method:`~db.cursor.hint()`: +:method:`~cursor.hint()`: .. code-block:: javascript @@ -198,7 +198,10 @@ the ``score`` field: { "_id" : ObjectId("523b6e6ffb408eea0eec2649"), "userid" : "nina", "score" : 90 } { "_id" : ObjectId("523b6e61fb408eea0eec2648"), "userid" : "abby", "score" : 82 } -.. seealso:: :method:`~cursor.explain()` and :doc:`/tutorial/analyze-query-plan` +.. seealso:: + + :method:`~cursor.explain()` and :doc:`/tutorial/analyze-query-plan` + Sparse Index with Unique Constraint ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/core/index-text.txt b/source/core/index-text.txt index b67489a437c..11068016076 100644 --- a/source/core/index-text.txt +++ b/source/core/index-text.txt @@ -159,19 +159,10 @@ and for Turkish languages, the special ``T`` case foldings as specified in `Unicode 8.0 Character Database Case Folding `_. -.. only:: (not latex) - - The case foldings expands the case insensitivity of the ``text`` - index to include characters with diacritics, such as ``é`` and - ``É``, and characters from non-Latin alphabets, such as "И" and "и" - in the Cyrillic alphabet. - -.. only:: latex - - The case foldings expands the case insensitivity of the ``text`` - index to include characters with diacritics, such as ``é`` and - ``É``, and characters from non-Latin alphabets, such as characters - from Cyrillic alphabet. +The case foldings expands the case insensitivity of the ``text`` +index to include characters with diacritics, such as ``é`` and +``É``, and characters from non-Latin alphabets, such as "И" and "и" +in the Cyrillic alphabet. Version 3 of the ``text`` index is also :ref:`diacritic insensitive `. As such, the index also does not diff --git a/source/core/index-ttl.txt b/source/core/index-ttl.txt index 39ef6c1a8a4..b2468aeacf8 100644 --- a/source/core/index-ttl.txt +++ b/source/core/index-ttl.txt @@ -1,5 +1,5 @@ -.. index:: index; TTL index -.. index:: TTL index + + .. _index-feature-ttl: =========== @@ -57,7 +57,7 @@ If the field is an array, and there are multiple date values in the index, MongoDB uses *lowest* (i.e. earliest) date value in the array to calculate the expiration threshold. -If the indexed field in a document is not a :term:`date ` +If the indexed field in a document is not a :term:`date ` or an array that holds a date value(s), the document will not expire. If a document does not contain the indexed field, the document will not @@ -87,7 +87,7 @@ Replica Sets On :term:`replica set ` members, the TTL background thread *only* deletes documents when a member is in state :term:`primary`. The TTL background -thread is idle when a member is in state :term:`secondary`. :term:`Secondary` members replicate +thread is idle when a member is in state :term:`secondary`. :term:`Secondary ` members replicate deletion operations from the primary. Support for Queries diff --git a/source/core/index-unique.txt b/source/core/index-unique.txt index 5e43bf152dd..2d5054bc071 100644 --- a/source/core/index-unique.txt +++ b/source/core/index-unique.txt @@ -1,4 +1,4 @@ -.. index:: index; unique + .. _index-type-unique: ============== @@ -18,8 +18,8 @@ values; i.e. enforces uniqueness for the indexed fields. By default, MongoDB creates a unique index on the :ref:`_id ` field during the creation of a collection. -.. admonition:: New Internal Format - :class: note +.. note:: New Internal Format + Starting in MongoDB 4.2, for :ref:`featureCompatibilityVersion ` (fCV) of 4.2 (or greater), MongoDB uses a new internal @@ -39,7 +39,7 @@ method with the ``unique`` option set to ``true``. db.collection.createIndex( , { unique: true } ) -.. index:: index; unique + .. _index-unique-index: Unique Index on a Single Field @@ -96,7 +96,9 @@ the collection since the index enforces uniqueness for the db.collection.insert( { _id: 2, a: [ { loc: "A" }, { qty: 5 } ] } ) db.collection.insert( { _id: 3, a: [ { loc: "A", qty: 10 } ] } ) -.. seealso:: :ref:`unique-separate-documents` and :ref:`unique-index-and-missing-field` +.. seealso:: + + :ref:`unique-separate-documents` and :ref:`unique-index-and-missing-field` Behavior -------- @@ -214,7 +216,9 @@ the unique constraint on the value of the field ``x``: } }) -.. seealso:: :ref:`unique-partial-indexes` +.. seealso:: + + :ref:`unique-partial-indexes` .. _unique-partial-indexes: @@ -253,8 +257,8 @@ For a ranged sharded collection, only the following indexes can be enforces the uniqueness constraint per shard **if** the ``_id`` field is **not** the shard key or the prefix of the shard key. - .. admonition:: Uniqueness and the ``_id`` Index - :class: important + .. important:: Uniqueness and the ``_id`` Index + If the ``_id`` field is not the shard key or the prefix of the shard key, ``_id`` index only enforces the uniqueness constraint diff --git a/source/core/index-wildcard.txt b/source/core/index-wildcard.txt index 1c78e919c12..f5fa59d4e1f 100644 --- a/source/core/index-wildcard.txt +++ b/source/core/index-wildcard.txt @@ -379,7 +379,9 @@ can still support queries that include explicit array indices. See :ref:`wildcard-query-support-explicit-array-indices` for more information. -.. seealso:: :limit:`Nested Depth for BSON Documents` +.. seealso:: + + :limit:`Nested Depth for BSON Documents` Restrictions ------------ @@ -482,7 +484,7 @@ MongoDB can use a wildcard index for satisfying the - The query planner selects the wildcard index for satisfying the query predicate. -- The :method:`~cusor.sort()` specifies **only** the query predicate +- The :method:`~cursor.sort()` specifies **only** the query predicate field. - The specified field is never an array. @@ -578,7 +580,9 @@ MongoDB may select the wildcard index to answer the query: - ``"parentObject.nestedArray" : "elementOne"`` - ``"parentObject.nestedArray.deeplyNestedArray" : "elementTwo"`` -.. seealso:: :limit:`Nested Depth for BSON Documents` +.. seealso:: + + :limit:`Nested Depth for BSON Documents` .. toctree:: :titlesonly: diff --git a/source/core/journaling.txt b/source/core/journaling.txt index 23ad6fd2609..33ddcf400f0 100644 --- a/source/core/journaling.txt +++ b/source/core/journaling.txt @@ -76,8 +76,8 @@ kB are buffered. .. seealso:: The :dbcommand:`serverStatus` command returns information on the - WiredTiger journal statistics in the :data:`wiredTiger.log - ` field. + WiredTiger journal statistics in the :serverstatus:`wiredTiger.log` + field. Journal Files ~~~~~~~~~~~~~ @@ -155,7 +155,9 @@ immediately acknowledged. .. include:: /includes/extracts/no-journaling-rollback.rst -.. seealso:: :ref:`In-Memory Storage Engine: Durability ` +.. seealso:: + + :ref:`In-Memory Storage Engine: Durability ` .. toctree:: :titlesonly: diff --git a/source/core/kerberos.txt b/source/core/kerberos.txt index 697d0c35a32..aa1bdc8e0ad 100644 --- a/source/core/kerberos.txt +++ b/source/core/kerberos.txt @@ -73,7 +73,9 @@ that user, see and :doc:`/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication`. -.. seealso:: :doc:`/tutorial/manage-users-and-roles` for +.. seealso:: + + :doc:`/tutorial/manage-users-and-roles` for general information regarding creating and managing users in MongoDB. @@ -189,7 +191,7 @@ The following MongoDB drivers support Kerberos authentication: - :api:`C ` - `C++ `_ -- :ecosystem:`Java ` +- :driver:`Java ` - `C# `_ - `Node.js `_ - `Perl `_ diff --git a/source/core/map-reduce.txt b/source/core/map-reduce.txt index ab4b165b563..59aff81d47d 100644 --- a/source/core/map-reduce.txt +++ b/source/core/map-reduce.txt @@ -10,8 +10,8 @@ Map-Reduce :depth: 1 :class: singlecol -.. admonition:: Aggregation Pipeline as Alternative to Map-Reduce - :class: note + +.. note:: Aggregation Pipeline as Alternative .. include:: /includes/fact-use-aggregation-not-map-reduce.rst diff --git a/source/core/query-optimization.txt b/source/core/query-optimization.txt index b0dbee75eee..34e684bd300 100644 --- a/source/core/query-optimization.txt +++ b/source/core/query-optimization.txt @@ -187,7 +187,9 @@ Restrictions on Indexed Fields - .. include:: /includes/fact-multikey-index-covered-query.rst - .. seealso:: :ref:`multikey-covering` + .. seealso:: + + :ref:`multikey-covering` .. _covered-index-sharded-collection: diff --git a/source/core/query-plans.txt b/source/core/query-plans.txt index 4fe4a731241..ca26a8cc0a2 100644 --- a/source/core/query-plans.txt +++ b/source/core/query-plans.txt @@ -1,4 +1,4 @@ -.. index:: query optimizer + .. _read-operations-query-optimization: .. _query-plans-query-optimization: @@ -139,7 +139,9 @@ Users can also: - Manually clear specific plan cache entries using the :method:`PlanCache.clearPlansByQuery()` method. -.. seealso:: :ref:`query-hash-plan-cache-key` +.. seealso:: + + :ref:`query-hash-plan-cache-key` Plan Cache Debug Info Size Limit -------------------------------- @@ -219,11 +221,11 @@ The ``queryHash`` and ``planCacheKey`` are available in: - :pipeline:`$planCacheStats` aggregation stage (*New in MongoDB 4.2*) -- :method:`PlanCache.listQueryShapes()` - method/:dbcommand:`planCacheListQueryShapes` command +- ``PlanCache.listQueryShapes()`` + method/``planCacheListQueryShapes`` command -- :method:`PlanCache.getPlansByQuery()` - method/:dbcommand:`planCacheListPlans` command +- ``PlanCache.getPlansByQuery()`` + method/``planCacheListPlans`` command .. _index-filters: diff --git a/source/core/read-isolation-consistency-recency.txt b/source/core/read-isolation-consistency-recency.txt index 568d567051d..bfbc790dfa8 100644 --- a/source/core/read-isolation-consistency-recency.txt +++ b/source/core/read-isolation-consistency-recency.txt @@ -10,8 +10,7 @@ Read Isolation, Consistency, and Recency :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + Isolation Guarantees -------------------- @@ -71,7 +70,9 @@ to perform reads and writes on a single document as if a single thread performed these operations in real time; that is, the corresponding schedule for these reads and writes is considered linearizable. -.. seealso:: :ref:`causal-consistency` +.. seealso:: + + :ref:`causal-consistency` .. _causal-consistency: diff --git a/source/core/read-preference-mechanics.txt b/source/core/read-preference-mechanics.txt index 3bf603eb97a..5556309097b 100644 --- a/source/core/read-preference-mechanics.txt +++ b/source/core/read-preference-mechanics.txt @@ -1,4 +1,4 @@ -.. index:: read preference; behavior + .. _replica-set-read-preference-behavior: ========================== @@ -23,9 +23,9 @@ Server selection occurs once per operation. .. include:: /includes/extracts/transactions-read-pref.rst -.. index:: read preference; ping time -.. index:: read preference; nearest -.. index:: read preference; member selection + + + .. _replica-set-read-preference-behavior-ping-time: .. _replica-set-read-preference-behavior-nearest: .. _replica-set-read-preference-behavior-member-selection: @@ -40,8 +40,8 @@ is re-evaluated for each operation. .. include:: /includes/extracts/server-selection-read-preference-replica-sets.rst -.. index:: read preference; sharding -.. index:: read preference; mongos + + .. _replica-set-read-preference-behavior-sharding: .. _replica-set-read-preference-behavior-mongos: diff --git a/source/core/read-preference-tags.txt b/source/core/read-preference-tags.txt index 613d391eb47..0968c21a00f 100644 --- a/source/core/read-preference-tags.txt +++ b/source/core/read-preference-tags.txt @@ -1,5 +1,5 @@ -.. index:: tag sets -.. index:: read preference; tag sets + + .. _replica-set-read-preference-tag-sets: ======================== diff --git a/source/core/read-preference.txt b/source/core/read-preference.txt index 086fb9fe790..f5f52ceb9c9 100644 --- a/source/core/read-preference.txt +++ b/source/core/read-preference.txt @@ -1,5 +1,5 @@ -.. index:: read preference -.. index:: read preference; background + + .. _read-preference: .. _replica-set-read-preference: .. _replica-set-read-preference-background: @@ -210,8 +210,8 @@ Configure Read Preference ------------------------- When using a MongoDB driver, you can specify the read preference using -the driver's read preference API. See the driver :ecosystem:`API -documentation`. You can also set the read preference (except +the driver's read preference API. See the driver :driver:`API +documentation `. You can also set the read preference (except for the hedged read option) when :ref:`connecting to the replica set or sharded cluster `. For an example, see :ref:`connection string `. diff --git a/source/core/replica-set-arbiter.txt b/source/core/replica-set-arbiter.txt index 4d3568fd016..4d4d067cfe0 100644 --- a/source/core/replica-set-arbiter.txt +++ b/source/core/replica-set-arbiter.txt @@ -1,4 +1,4 @@ -.. index:: replica set members; arbiters + .. _replica-set-arbiter-configuration: =================== @@ -49,8 +49,8 @@ number of votes to break a tie: Read Concern ``majority`` and Three-Member PSA ---------------------------------------------- -.. admonition:: For 3-Member Primary-Secondary-Arbiter Architecture* - :class: warning +.. warning:: For 3-Member Primary-Secondary-Arbiter Architecture* + If you have a three-member replica set with a primary-secondary-arbiter (PSA) architecture or a sharded cluster diff --git a/source/core/replica-set-architecture-three-members.txt b/source/core/replica-set-architecture-three-members.txt index a52f7107297..17741b118cd 100644 --- a/source/core/replica-set-architecture-three-members.txt +++ b/source/core/replica-set-architecture-three-members.txt @@ -84,4 +84,7 @@ set will elect the secondary to be primary. .. include:: /images/replica-set-w-arbiter-trigger-election.rst -.. seealso:: :doc:`/tutorial/deploy-replica-set`. +.. seealso:: + + :doc:`/tutorial/deploy-replica-set`. + diff --git a/source/core/replica-set-architectures.txt b/source/core/replica-set-architectures.txt index 7be9a6169eb..a46996a841c 100644 --- a/source/core/replica-set-architectures.txt +++ b/source/core/replica-set-architectures.txt @@ -170,7 +170,9 @@ Use :ref:`replica set tag sets ` to target read operations to specific members or to customize write concern to request acknowledgement from specific members. -.. seealso:: :doc:`/data-center-awareness` and +.. seealso:: + + :doc:`/data-center-awareness` and :doc:`/core/workload-isolation`. Use Journaling to Protect Against Power Failures @@ -198,16 +200,14 @@ patterns. Other patterns are possible and effective depending on the application's requirements. If needed, combine features of each architecture in your own deployment: -.. class:: toc - - :doc:`/core/replica-set-architecture-three-members` - Three-member replica sets provide the minimum recommended - architecture for a replica set. +:doc:`/core/replica-set-architecture-three-members` + Three-member replica sets provide the minimum recommended + architecture for a replica set. - :doc:`/core/replica-set-architecture-geographically-distributed` - Geographically distributed sets include members in multiple - locations to protect against facility-specific failures, such as - power outages. +:doc:`/core/replica-set-architecture-geographically-distributed` + Geographically distributed sets include members in multiple + locations to protect against facility-specific failures, such as + power outages. .. toctree:: diff --git a/source/core/replica-set-delayed-member.txt b/source/core/replica-set-delayed-member.txt index 65ac68ca788..bdd5a61c384 100644 --- a/source/core/replica-set-delayed-member.txt +++ b/source/core/replica-set-delayed-member.txt @@ -1,4 +1,4 @@ -.. index:: replica set members; delayed + .. _replica-set-delayed-configuration: .. _replica-set-delayed-members: .. _replica-set-delayed-replication: diff --git a/source/core/replica-set-elections.txt b/source/core/replica-set-elections.txt index 1cbdd63387b..00b0873ccda 100644 --- a/source/core/replica-set-elections.txt +++ b/source/core/replica-set-elections.txt @@ -1,6 +1,6 @@ -.. index:: replica set; network partitions -.. index:: replica set; elections -.. index:: replica set; failover + + + .. _replica-set-election-internals: .. _replica-set-elections: @@ -118,7 +118,9 @@ If possible, distribute the replica set members across data centers to maximize the likelihood that even with a loss of a data center, one of the remaining replica set members can become the new primary. -.. seealso:: :doc:`/core/replica-set-architecture-geographically-distributed` +.. seealso:: + + :doc:`/core/replica-set-architecture-geographically-distributed` Network Partition ~~~~~~~~~~~~~~~~~ @@ -131,14 +133,14 @@ partition that can communicate with a :data:`majority ` of the nodes (including itself) holds an election to become the new primary. -.. index:: replica set members; non-voting +-voting Voting Members -------------- The replica set member configuration setting :rsconf:`members[n].votes` -and member :data:`~replSetGetStatus.members.state` determine whether a +and member :data:`~replSetGetStatus.members[n].state` determine whether a member votes in an election. diff --git a/source/core/replica-set-hidden-member.txt b/source/core/replica-set-hidden-member.txt index a93c0d6d2d2..c9ff657e579 100644 --- a/source/core/replica-set-hidden-member.txt +++ b/source/core/replica-set-hidden-member.txt @@ -1,4 +1,4 @@ -.. index:: replica set members; hidden + .. _replica-set-hidden-configuration: .. _replica-set-hidden-members: diff --git a/source/core/replica-set-high-availability.txt b/source/core/replica-set-high-availability.txt index a218ffea6f1..3a98232a650 100644 --- a/source/core/replica-set-high-availability.txt +++ b/source/core/replica-set-high-availability.txt @@ -1,4 +1,4 @@ -.. index:: pair: replica set; failover +: replica set; failover .. _replica-set-failover-administration: .. _replica-set-failover: .. _failover: @@ -18,15 +18,13 @@ Replica Set High Availability Replica sets use elections to support :term:`high availability `. -.. class:: toc +:doc:`/core/replica-set-elections` + Elections occur when the primary becomes unavailable and the + replica set members autonomously select a new primary. - :doc:`/core/replica-set-elections` - Elections occur when the primary becomes unavailable and the - replica set members autonomously select a new primary. - - :doc:`/core/replica-set-rollbacks` - A rollback reverts write operations on a former primary when the - member rejoins the replica set after a failover. +:doc:`/core/replica-set-rollbacks` + A rollback reverts write operations on a former primary when the + member rejoins the replica set after a failover. .. toctree:: diff --git a/source/core/replica-set-members.txt b/source/core/replica-set-members.txt index 72d3abf7ace..17c384fbec9 100644 --- a/source/core/replica-set-members.txt +++ b/source/core/replica-set-members.txt @@ -43,16 +43,15 @@ A replica set can have up to :ref:`50 members - :data:`replSetGetStatus.writableVotingMembersCount` -.. only:: (website or singlehtml) - .. _replica-set-primary-member: +.. _replica-set-primary-member: - Primary - ------- +Primary +------- - .. include:: /core/replica-set-primary.txt - :start-after: start-content - :end-before: start-content-election-example +.. include:: /core/replica-set-primary.txt + :start-after: start-content + :end-before: start-content-election-example .. toctree:: :titlesonly: @@ -60,20 +59,18 @@ A replica set can have up to :ref:`50 members /core/replica-set-primary -.. only:: (website or singlehtml) +.. _replica-set-secondary-members: - .. _replica-set-secondary-members: +Secondaries +----------- - Secondaries - ----------- +.. include:: /core/replica-set-secondary.txt + :start-after: start-content + :end-before: start-content-election-example - .. include:: /core/replica-set-secondary.txt - :start-after: start-content - :end-before: start-content-election-example - - .. include:: /core/replica-set-secondary.txt - :start-after: end-content-election-example - :end-before: end-content +.. include:: /core/replica-set-secondary.txt + :start-after: end-content-election-example + :end-before: end-content .. toctree:: :titlesonly: @@ -81,18 +78,17 @@ A replica set can have up to :ref:`50 members /core/replica-set-secondary -.. only:: (website or singlehtml) - .. _replica-set-arbiters: +.. _replica-set-arbiters: - Arbiter - ------- +Arbiter +------- - .. include:: /core/replica-set-arbiter.txt - :start-after: start-content - :end-before: end-content +.. include:: /core/replica-set-arbiter.txt + :start-after: start-content + :end-before: end-content - For considerations when using an arbiter, see :doc:`/core/replica-set-arbiter`. +For considerations when using an arbiter, see :doc:`/core/replica-set-arbiter`. .. toctree:: :titlesonly: diff --git a/source/core/replica-set-rollbacks.txt b/source/core/replica-set-rollbacks.txt index 73c4f9a08f9..a7b9ad6c5c3 100644 --- a/source/core/replica-set-rollbacks.txt +++ b/source/core/replica-set-rollbacks.txt @@ -1,4 +1,4 @@ -.. index:: rollbacks + single: replica set; rollbacks single: consistency; rollbacks @@ -57,8 +57,8 @@ Rollback Data By default, when a rollback occurs, MongoDB writes the rollback data to :term:`BSON` files. -.. admonition:: Rollback Directory Change - :class: note +.. note:: Rollback Directory Change + Starting in Mongo 4.4, the rollback directory for a collection is named after the collection's UUID rather than the collection namespace. @@ -67,29 +67,27 @@ By default, when a rollback occurs, MongoDB writes the rollback data to .. tab:: MongoDB 4.4+ :tabid: 4.4 - - .. container:: + + For each collection whose data is rolled back, the + rollback files are located in a ``/rollback/`` + directory and have filenames of the form: - For each collection whose data is rolled back, the - rollback files are located in a ``/rollback/`` - directory and have filenames of the form: + .. code-block:: none + :copyable: false - .. code-block:: none - :copyable: false + removed..bson - removed..bson + For example, if data for the collection ``comments`` in the + ``reporting`` database rolled back: - For example, if data for the collection ``comments`` in the - ``reporting`` database rolled back: - - .. code-block:: none - :copyable: false + .. code-block:: none + :copyable: false - /rollback/20f74796-d5ea-42f5-8c95-f79b39bad190/removed.2020-02-19T04-57-11.0.bson + /rollback/20f74796-d5ea-42f5-8c95-f79b39bad190/removed.2020-02-19T04-57-11.0.bson - where ```` is the :binary:`~bin.mongod`'s :setting:`~storage.dbPath`. + where ```` is the :binary:`~bin.mongod`'s :setting:`~storage.dbPath`. - .. topic:: Collection Name + .. tip:: Collection Name To get the collection name, you can search for ``rollback file`` in the MongoDB log. For example, if the log file is @@ -124,45 +122,40 @@ By default, when a rollback occurs, MongoDB writes the rollback data to .. tab:: MongoDB 4.2-4.0 :tabid: 4.2 - - .. container:: + For each collection whose data is rolled back, the + rollback files are located in a ``/rollback/.`` + directory and have filenames of the form: - For each collection whose data is rolled back, the - rollback files are located in a ``/rollback/.`` - directory and have filenames of the form: + .. code-block:: none + :copyable: false - .. code-block:: none - :copyable: false + removed..bson - removed..bson + For example, if data for the collection ``comments`` in the + ``reporting`` database rolled back: - For example, if data for the collection ``comments`` in the - ``reporting`` database rolled back: - - .. code-block:: none - :copyable: false + .. code-block:: none + :copyable: false - /rollback/reporting.comments/removed.2019-01-31T02-57-40.0.bson + /rollback/reporting.comments/removed.2019-01-31T02-57-40.0.bson - where ```` is the :binary:`~bin.mongod`'s :setting:`~storage.dbPath`. + where ```` is the :binary:`~bin.mongod`'s :setting:`~storage.dbPath`. .. tab:: MongoDB 3.6 and earlier :tabid: 3.6 - .. container:: - - In versions 3.6 and earlier, rollback files are located directly under the - ``/rollback`` directory with the filenames of the form - ``...bson``. - - For example, if data for the collection ``comments`` in the - ``reporting`` database rolled back: + In versions 3.6 and earlier, rollback files are located directly under the + ``/rollback`` directory with the filenames of the form + ``...bson``. + + For example, if data for the collection ``comments`` in the + ``reporting`` database rolled back: - .. code-block:: none - :copyable: false + .. code-block:: none + :copyable: false - /rollbacktest.col.2020-02-19T04-46-22.0.bson + /rollbacktest.col.2020-02-19T04-46-22.0.bson Rollback Data Exclusion ~~~~~~~~~~~~~~~~~~~~~~~ @@ -261,5 +254,7 @@ In MongoDB 3.6 and earlier, the rollback time limit is not configurable. For these versions, rollback is limited by the amount of data, with a maximum of 300 megabytes. -.. seealso:: :doc:`/core/replica-set-high-availability` and +.. seealso:: + + :doc:`/core/replica-set-high-availability` and :doc:`/core/replica-set-elections`. diff --git a/source/core/replica-set-write-concern.txt b/source/core/replica-set-write-concern.txt index ddada79ba3f..93cdf826353 100644 --- a/source/core/replica-set-write-concern.txt +++ b/source/core/replica-set-write-concern.txt @@ -18,7 +18,7 @@ write operation after it has received and applied the write successfully. For replica sets, the default write concern of -:writeconcern:`w: 1 >` requires that only the primary +:writeconcern:`w: 1 <\>` requires that only the primary replica set member acknowledge the write before returning write concern acknowledgment. You can specify an integer value greater than ``1`` to require acknowledgment from the primary and @@ -116,7 +116,9 @@ the :dbcommand:`setDefaultRWConcern` command. If you issue a write operation with a specific write concern, the write operation uses its own write concern instead of the default. -.. seealso:: :doc:`/reference/write-concern` +.. seealso:: + + :doc:`/reference/write-concern` Custom Write Concerns --------------------- diff --git a/source/core/retryable-writes.txt b/source/core/retryable-writes.txt index 8d62165f375..1470ec5d3fa 100644 --- a/source/core/retryable-writes.txt +++ b/source/core/retryable-writes.txt @@ -88,7 +88,7 @@ Retryable Write Operations The following write operations are retryable when issued with acknowledged write concern; e.g., :doc:`/reference/write-concern` -cannot be :writeconcern:`{w: 0} >`. +cannot be :writeconcern:`{w: 0} <\>`. .. note:: diff --git a/source/core/schema-validation.txt b/source/core/schema-validation.txt index 806a6fad15f..7255648058b 100644 --- a/source/core/schema-validation.txt +++ b/source/core/schema-validation.txt @@ -125,8 +125,6 @@ validation with :ref:`other query operators For example, the following example specifies validator rules using the query expression: -.. cssclass:: copyable-code - .. code-block:: sh db.createCollection( "contacts", @@ -139,7 +137,9 @@ query expression: } } ) -.. seealso:: :ref:`query operators ` +.. seealso:: + + :ref:`query operators ` Behavior -------- @@ -166,8 +166,6 @@ applies the validation rules: For example, create a ``contacts`` collection with the following documents: -.. cssclass:: copyable-code - .. code-block:: json db.contacts.insert([ @@ -178,8 +176,6 @@ documents: Issue the following command to add a validator to the ``contacts`` collection: -.. cssclass:: copyable-code - .. code-block:: sh db.runCommand( { @@ -304,8 +300,6 @@ documents that violate the validation rules: For example, create a ``contacts2`` collection with the following JSON Schema validator: -.. cssclass:: copyable-code - .. code-block:: json db.createCollection( "contacts2", { @@ -424,5 +418,8 @@ validation, the authenticated user must have Additional Information ---------------------- -.. seealso:: :dbcommand:`collMod`, :method:`db.createCollection()`, +.. seealso:: + + :dbcommand:`collMod`, :method:`db.createCollection()`, + :method:`db.getCollectionInfos()`. diff --git a/source/core/security-client-side-encryption-key-management.txt b/source/core/security-client-side-encryption-key-management.txt index cbd964753ed..076850f0bf2 100644 --- a/source/core/security-client-side-encryption-key-management.txt +++ b/source/core/security-client-side-encryption-key-management.txt @@ -71,8 +71,7 @@ Key must have at least one policy with the following actions: `(reference) `__ -.. admonition:: Implement Principle of Least Privilege for KMS Access - :class: note +.. note:: Implement Principle of Least Privilege for KMS Access Consider configuring IAM user roles such that MongoDB has only the access to the actions and resources required to function. diff --git a/source/core/security-client-side-encryption.txt b/source/core/security-client-side-encryption.txt index 675834fd68d..d4d3218e172 100644 --- a/source/core/security-client-side-encryption.txt +++ b/source/core/security-client-side-encryption.txt @@ -66,7 +66,7 @@ Consider the following document: With client-side field level encryption, the application can specifically encrypt sensitive information like the ``ssn`` and ``phone``. Encrypted fields are stored as -:bsontype:`binary data ` with +:bsontype:`binary data ` with `subtype 6 `_: .. code-block:: json @@ -88,8 +88,8 @@ for client-side field level encryption, see For an end-to-end procedure for configuring field level encryption using select MongoDB 4.2-compatible drivers, see the -:ecosystem:`Client Side Field Level Encryption Guide -`. +:driver:`Client Side Field Level Encryption Guide +`. Supported Encryption Methods ---------------------------- @@ -311,7 +311,7 @@ collection. Use the :ref:`automatic encryption rule keywords ` with the :query:`$jsonSchema` validation object to indicate which fields require encryption. The server rejects any write operations to that collection -where the specified fields are not :bsontype:`Binary (BinData) ` +where the specified fields are not :bsontype:`Binary (BinData) ` subtype 6 objects. For example, the following :dbcommand:`collMod` command modifies @@ -367,7 +367,7 @@ Clients performing :ref:`automatic client-side field level encryption on the :ref:`database connection configuration `: -.. container:: +.. note:: *Automatic client-side field level encryption is available with MongoDB 4.2 Enterprise only.* @@ -424,39 +424,39 @@ the following official 4.2-compatible driver versions: - Supported Versions - Quickstarts / Tutorials - * - :ecosystem:`Node ` + * - :driverecosystem:`Node ` - ``3.4.0+`` - | `Node.js Quickstart `__ - | :ecosystem:`Client-Side Field Level Encryption Guide ` + | :driver:`Client-Side Field Level Encryption Guide ` - * - :ecosystem:`Java ` + * - :driver:`Java ` - ``3.12.0+`` - | `Java Driver Quickstart `__ | `Java Async Driver Quickstart `__ - | :ecosystem:`Client-Side Field Level Encryption Guide ` + | :driver:`Client-Side Field Level Encryption Guide ` * - `Java Reactive Streams `__ - ``1.13.0+`` - `Java RS Documentation `__ - * - :ecosystem:`Python (PyMongo) ` + * - :driver:`Python (PyMongo) ` - ``3.10.0+`` - | `Python Driver Quickstart `__ - | :ecosystem:`Client-Side Field Level Encryption Guide ` + | :driver:`Client-Side Field Level Encryption Guide ` - * - :ecosystem:`C#/.NET ` + * - :driver:`C#/.NET ` - ``2.10.0+`` - `.NET Driver Quickstart `__ - * - :ecosystem:`Go ` + * - :driver:`Go ` - ``1.2+`` - `Go Driver Quickstart `__ - * - :ecosystem:`Scala ` + * - :driver:`Scala ` - ``2.8.0+`` - `Scala Documentation `__ - * - :ecosystem:`PHP ` + * - :driver:`PHP ` - ``1.6.0+`` - `PHP Driver Quickstart `__ diff --git a/source/core/security-encryption-at-rest.txt b/source/core/security-encryption-at-rest.txt index 9ad73fcbd80..a6f9fc1b286 100644 --- a/source/core/security-encryption-at-rest.txt +++ b/source/core/security-encryption-at-rest.txt @@ -10,8 +10,7 @@ Encryption at Rest :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + Encryption at rest, when used in conjunction with transport encryption and good security policies that protect relevant accounts, passwords, @@ -37,8 +36,8 @@ read the data. Encryption Process ~~~~~~~~~~~~~~~~~~ -.. admonition:: Changed in version 4.0 - :class: note +.. note:: Changed in version 4.0 + .. include:: /includes/fact-aes.rst diff --git a/source/core/security-ldap-external.txt b/source/core/security-ldap-external.txt index 74740e3bd82..4d4625905f1 100644 --- a/source/core/security-ldap-external.txt +++ b/source/core/security-ldap-external.txt @@ -293,7 +293,7 @@ configuration file: Defaults to ``DIGEST-MD5``. - - **NO**, unless setting :setting:`~security.ldap.bindMethod` to + - **NO**, unless setting :setting:`~security.ldap.bind.method` to ``sasl``, and you need different or additional SASL mechanisms. * - :setting:`security.ldap.bind.useOSDefaults` @@ -308,10 +308,11 @@ configuration file: * - :setting:`security.ldap.userToDNMapping` - - Depending on your :setting:`~security.ldap.queryTemplate`, the - authenticated client username may require transformation to support the - LDAP query URL. :setting:`~security.ldap.userToDNMapping` allows - MongoDB to transform incoming usernames. + - Depending on your :setting:`~security.ldap.authz.queryTemplate`, + the authenticated client username may require transformation to + support the LDAP query URL. + :setting:`~security.ldap.userToDNMapping` allows MongoDB to + transform incoming usernames. - **NO**, unless client usernames require transformation into LDAP DNs. @@ -353,7 +354,9 @@ The LDAP query URL must conform to the format defined in `RFC4516 [ dn [ ? [attributes] [ ? [scope] [ ? [filter] [ ? [Extensions] ] ] ] ] ] -Consider the definition of each component, as quoted from RFC4516:: +Consider the definition of each component, as quoted from RFC4516: + +.. blockquote:: The ``dn`` is an LDAP Distinguished Name using the string format described in `RFC4514 `_. It identifies the base @@ -446,7 +449,7 @@ MongoDB Roles for LDAP Authorization ------------------------------------ MongoDB maps each returned group distinguished name (DN) returned by -the LDAP :setting:`query ` to a +the LDAP :setting:`query ` to a :ref:`role ` on the ``admin`` database. If MongoDB acquires a group whose DN **exactly** matches the name of an @@ -494,7 +497,7 @@ privileges to the user. After authenticating a user ``alice@dba.example.com`` against the ``$external`` database, the MongoDB server performs a query derived from the configured :setting:`query template - ` to retrieve the groups which include + ` to retrieve the groups which include the authenticated user as a member. In this example, the MongoDB server retrieves the following group DNs for the user: diff --git a/source/core/security-ldap.txt b/source/core/security-ldap.txt index 3fd6e9b15f5..bda71692e88 100644 --- a/source/core/security-ldap.txt +++ b/source/core/security-ldap.txt @@ -262,13 +262,14 @@ configuration file: - The password used to authenticate to an LDAP server when using :setting:`~security.ldap.bind.queryUser`. - - **NO**, unless specifying :setting:`~security.ldap.queryUser` + - **NO**, unless specifying + :setting:`~security.ldap.bind.queryUser`. * - :setting:`security.ldap.bind.useOSDefaults` - Windows MongoDB deployments can use the operating system credentials in - place of :setting:`~security.ldap.queryUser` and - :setting:`~security.ldap.queryPassword` for authenticating or binding + place of :setting:`~security.ldap.bind.queryUser` and + :setting:`~security.ldap.bind.queryPassword` for authenticating or binding as when connecting to the LDAP server. - **NO**, unless replacing :setting:`~security.ldap.bind.queryUser` and @@ -288,9 +289,10 @@ configuration file: or an LDAP query template. If you specify a :setting:`~security.ldap.userToDNMapping` - transformation that uses LDAP queries as part of the transformation, - you must also specify a :setting:`~security.ldap.queryUser` with - the appropriate level of permissions for the LDAP server + transformation that uses LDAP queries as part of the + transformation, you must also specify a + :setting:`~security.ldap.bind.queryUser` with the appropriate + level of permissions for the LDAP server - **NO**, unless client authenticate using usernames that require transformation. diff --git a/source/core/security-users.txt b/source/core/security-users.txt index 7604ac88dc2..b1ca89cf9cb 100644 --- a/source/core/security-users.txt +++ b/source/core/security-users.txt @@ -38,7 +38,9 @@ A user is uniquely identified by the user's name and associated authentication database. Starting in MongoDB 4.0.9, a users managed by MongoDB are assigned a unique ``userId``. [#userid]_ -.. seealso:: :doc:`/tutorial/create-users` +.. seealso:: + + :doc:`/tutorial/create-users` .. _authentication-database: .. _user-authentication-database: @@ -92,7 +94,7 @@ database. Do not access this collection directly but instead use the :ref:`user management commands `. -.. index:: sharding; localhost + .. _sharding-localhost: .. _sharding-security: diff --git a/source/core/sharded-cluster-components.txt b/source/core/sharded-cluster-components.txt index 47e4e8b4c8b..8726b589495 100644 --- a/source/core/sharded-cluster-components.txt +++ b/source/core/sharded-cluster-components.txt @@ -1,5 +1,5 @@ -.. index:: sharding; shards -.. index:: shards + + .. _sharding-shards: .. _sharding-production-architecture: @@ -111,7 +111,9 @@ following components: .. warning:: Use the test cluster architecture for testing and development only. -.. seealso:: :doc:`/tutorial/deploy-shard-cluster/` +.. seealso:: + + :doc:`/tutorial/deploy-shard-cluster/` .. toctree:: :titlesonly: diff --git a/source/core/sharded-cluster-config-servers.txt b/source/core/sharded-cluster-config-servers.txt index 79e11e78ff0..bedc52f667e 100644 --- a/source/core/sharded-cluster-config-servers.txt +++ b/source/core/sharded-cluster-config-servers.txt @@ -1,5 +1,5 @@ -.. index:: sharding; config servers -.. index:: config servers + + .. _sharding-config-server: .. _sharded-cluster-config-server: @@ -61,8 +61,8 @@ Replica Set Config Servers .. include:: /includes/fact-config-server-replica-set-restrictions.rst -.. index:: config databases -.. index:: database, config + +, config .. _config-server-read-write-ops: diff --git a/source/core/sharded-cluster-query-router.txt b/source/core/sharded-cluster-query-router.txt index b5a67acc571..c1fd983a579 100644 --- a/source/core/sharded-cluster-query-router.txt +++ b/source/core/sharded-cluster-query-router.txt @@ -1,4 +1,4 @@ -.. index:: mongos + .. _sharded-cluster-query-routing: .. _sharding-read-operations: @@ -76,7 +76,7 @@ retrieves the results. For more information on how the work of aggregation is split among components of a sharded cluster query, use ``explain:true`` as a - parameter to the :method:`~db.collection.aggregation()` call. The + parameter to the :method:`~db.collection.aggregate()` call. The return will include three json objects. ``mergeType`` shows where the stage of the merge happens ("primaryShard", "anyShard", or "mongos"). ``splitPipeline`` shows which operations in your pipeline have run on @@ -168,44 +168,38 @@ The additional read sent to hedge the read operation uses the Hedged Reads and Read Preference ```````````````````````````````` -.. container:: +Hedged reads are specified per operation as part of the :doc:`read +preference `. Non-``primary`` :doc:`read preferences +` support hedged reads. See :ref:`Hedged Read +Preference Option `. - Hedged reads are specified per operation as part of the :doc:`read - preference `. Non-``primary`` :doc:`read preferences - ` support hedged reads. See :ref:`Hedged Read - Preference Option `. +- To specify hedged read for a non-``primary`` read preference, + refer to the driver :driver:`read preference API + documentation`. - - To specify hedged read for a non-``primary`` read preference, - refer to the driver :ecosystem:`read preference API - documentation`. +- Read preference :readmode:`nearest` enables the hedged read option + by default. - - Read preference :readmode:`nearest` enables the hedged read option - by default. +For details on read preference and sharded clusters as well as member +selection, see :ref:`read-preference-mechanics-sharded-cluster`. - For details on read preference and sharded clusters as well as member - selection, see :ref:`read-preference-mechanics-sharded-cluster`. - Enable/Disable Support for Hedged Reads ``````````````````````````````````````` -.. container:: - - By default, :binary:`~bin.mongos` instances support using hedged - reads. To turn off a :binary:`~bin.mongos` instance's support for - hedged reads, see the :parameter:`readHedgingMode` parameter. If the - hedged read support is ``off``, :binary:`~bin.mongos` does not use - hedged reads regardless of the ``hedge`` option specified for the - read preference. +By default, :binary:`~bin.mongos` instances support using hedged +reads. To turn off a :binary:`~bin.mongos` instance's support for +hedged reads, see the :parameter:`readHedgingMode` parameter. If the +hedged read support is ``off``, :binary:`~bin.mongos` does not use +hedged reads regardless of the ``hedge`` option specified for the +read preference. Hedged Reads Diagnostics ```````````````````````` -.. container:: - - The command :dbcommand:`serverStatus` and its corresponding - :binary:`~bin.mongo` shell method :method:`db.serverStatus()` return - :serverstatus:`hedgingMetrics`. +The command :dbcommand:`serverStatus` and its corresponding +:binary:`~bin.mongo` shell method :method:`db.serverStatus()` return +:serverstatus:`hedgingMetrics`. Confirm Connection to ``mongos`` Instances ------------------------------------------ @@ -229,7 +223,7 @@ a document with a ``msg`` field that holds the string If the application is instead connected to a :binary:`~bin.mongod`, the returned document does not include the ``isdbgrid`` string. -.. index:: shard key; query isolation + .. _sharding-query-router-broadcast-targeted: .. _sharding-shard-key-query-isolation: .. _sharding-query-isolation: diff --git a/source/core/sharded-cluster-requirements.txt b/source/core/sharded-cluster-requirements.txt index 6b20ada977e..140b4c88c9b 100644 --- a/source/core/sharded-cluster-requirements.txt +++ b/source/core/sharded-cluster-requirements.txt @@ -1,4 +1,4 @@ -.. index:: fundamentals; sharding + .. _sharding-fundamentals: .. _sharding-capacity-planning: diff --git a/source/core/sharded-cluster-shards.txt b/source/core/sharded-cluster-shards.txt index 0056198af27..c4d852e3253 100644 --- a/source/core/sharded-cluster-shards.txt +++ b/source/core/sharded-cluster-shards.txt @@ -42,7 +42,7 @@ replica set. The :binary:`~bin.mongos` selects the primary shard when creating a new database by picking the shard in the cluster that has the least amount of data. :binary:`~bin.mongos` uses the ``totalSize`` field returned by the -:dbcommand:`listDatabase` command as a part of the selection criteria. +:dbcommand:`listDatabases` command as a part of the selection criteria. .. include:: /images/sharded-cluster-primary-shard.rst diff --git a/source/core/sharding-balancer-administration.txt b/source/core/sharding-balancer-administration.txt index 5bb9e2911e0..99778f073d9 100644 --- a/source/core/sharding-balancer-administration.txt +++ b/source/core/sharding-balancer-administration.txt @@ -1,4 +1,4 @@ -.. index:: balancing; migration + .. _sharding-balancing: ======================== @@ -36,7 +36,7 @@ The balancer runs on the primary of the config server replica set /tutorial/manage-sharded-cluster-balancer /tutorial/migrate-chunks-in-sharded-cluster -.. index:: balancing; internals + .. _sharding-balancing-internals: .. _sharding-internals-balancing: @@ -93,7 +93,10 @@ Window ` for details. The specification of the balancing window is relative to the local time zone of the primary of the config server replica set. -.. seealso:: :doc:`/tutorial/manage-sharded-cluster-balancer`. +.. seealso:: + + :doc:`/tutorial/manage-sharded-cluster-balancer`. + .. [#auto-distribute] @@ -124,7 +127,10 @@ to the removed shard during this process. See the :doc:`/tutorial/remove-shards-from-cluster` tutorial for instructions on safely removing a shard from a cluster. -.. seealso:: :method:`sh.balancerCollectionStatus()` +.. seealso:: + + :method:`sh.balancerCollectionStatus()` + .. _chunk-migration-procedure: @@ -175,7 +181,10 @@ All chunk migrations use the following procedure: The migration process ensures consistency and maximizes the availability of chunks during balancing. -.. seealso:: :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` +.. seealso:: + + :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` + .. _sharding-migration-thresholds: @@ -209,7 +218,10 @@ The balancer stops running on the target collection when the difference between the number of chunks on any two shards for that collection is *less than two*, or a chunk migration fails. -.. seealso:: :method:`sh.balancerCollectionStatus()` +.. seealso:: + + :method:`sh.balancerCollectionStatus()` + .. _chunk-migration-queuing: .. _asynchronous-chunk-migration-cleanup: diff --git a/source/core/sharding-data-partitioning.txt b/source/core/sharding-data-partitioning.txt index b79447bac0f..a9e44ed647f 100644 --- a/source/core/sharding-data-partitioning.txt +++ b/source/core/sharding-data-partitioning.txt @@ -35,66 +35,66 @@ Initial Chunks Populated Collection ~~~~~~~~~~~~~~~~~~~~ -.. container:: +- The sharding operation creates the initial chunk(s) to cover the + entire range of the shard key values. The number of chunks created + depends on the :ref:`configured chunk size `. - - The sharding operation creates the initial chunk(s) to cover the - entire range of the shard key values. The number of chunks created - depends on the :ref:`configured chunk size `. - - - After the initial chunk creation, the balancer migrates these initial - chunks across the shards as appropriate as well as manages the chunk - distribution going forward. +- After the initial chunk creation, the balancer migrates these initial + chunks across the shards as appropriate as well as manages the chunk + distribution going forward. .. _initial-chunks-empty-collection: Empty Collection ~~~~~~~~~~~~~~~~ -.. container:: +- If you define :doc:`zones and zone ranges ` defined + for an empty or non-existing collection (Available starting in + MongoDB 4.0.3): + + - The sharding operation creates empty chunks for the defined zone + ranges as well as any additional chunks to cover the entire range + of the shard key values and performs an initial chunk distribution + based on the zone ranges. This initial creation and distribution of + chunks allows for faster setup of zoned sharding. - - If you define :doc:`zones and zone ranges ` defined - for an empty or non-existing collection (Available starting in - MongoDB 4.0.3): + - After the initial distribution, the balancer manages the chunk + distribution going forward. - - The sharding operation creates empty chunks for the defined zone - ranges as well as any additional chunks to cover the entire range - of the shard key values and performs an initial chunk distribution - based on the zone ranges. This initial creation and distribution of - chunks allows for faster setup of zoned sharding. - - After the initial distribution, the balancer manages the chunk - distribution going forward. +- If you do not have :doc:`zones and zone ranges ` defined + for an empty or non-existing collection: + - For hashed sharding: - - If you do not have :doc:`zones and zone ranges ` defined - for an empty or non-existing collection: + - The sharding operation creates empty chunks to cover the + entire range of the shard key values and performs an initial + chunk distribution. By default, the + operation creates 2 chunks per shard and migrates across the + cluster. You can use ``numInitialChunks`` option to specify a + different number of initial chunks. This initial creation and + distribution of chunks allows for faster setup of + sharding. - - For hashed sharding: + - After the initial distribution, the balancer manages the chunk + distribution going forward. - - The sharding operation creates empty chunks to cover the - entire range of the shard key values and performs an initial - chunk distribution. By default, the - operation creates 2 chunks per shard and migrates across the - cluster. You can use ``numInitialChunks`` option to specify a - different number of initial chunks. This initial creation and - distribution of chunks allows for faster setup of - sharding. + - For ranged sharding: - - After the initial distribution, the balancer manages the chunk - distribution going forward. + - The sharding operation creates a single empty chunk to cover the + entire range of the shard key values. - - For ranged sharding: + - After the initial chunk creation, the balancer migrates the + initial chunk across the shards as appropriate as well as manages + the chunk distribution going forward. - - The sharding operation creates a single empty chunk to cover the - entire range of the shard key values. +.. seealso:: - - After the initial chunk creation, the balancer migrates the - initial chunk across the shards as appropriate as well as manages - the chunk distribution going forward. + + + :method:`sh.balancerCollectionStatus()` -.. seealso:: :method:`sh.balancerCollectionStatus()` -.. index:: sharding; chunk size .. _sharding-chunk-size: Chunk Size @@ -182,7 +182,11 @@ either: For more information on the sharded cluster :term:`balancer`, see :ref:`sharding-balancing`. -.. seealso:: :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` +.. seealso:: + + + + :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` Balancing ~~~~~~~~~ diff --git a/source/core/sharding-shard-key.txt b/source/core/sharding-shard-key.txt index 3598ebdfbe3..4519b9b1426 100644 --- a/source/core/sharding-shard-key.txt +++ b/source/core/sharding-shard-key.txt @@ -1,4 +1,4 @@ -.. index:: shard key + single: sharding; shard key .. _sharding-shard-key: @@ -11,8 +11,7 @@ Shard Keys .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -89,26 +88,24 @@ For more information on the sharding method, see Refine a Shard Key ------------------ -.. container:: +Starting in MongoDB 4.4, you can use +:dbcommand:`refineCollectionShardKey` to refine a collection's shard +key. The :dbcommand:`refineCollectionShardKey` adds a suffix field +or fields to the existing key to create the new shard key. - Starting in MongoDB 4.4, you can use - :dbcommand:`refineCollectionShardKey` to refine a collection's shard - key. The :dbcommand:`refineCollectionShardKey` adds a suffix field - or fields to the existing key to create the new shard key. +For example, you may have an existing ``orders`` collection with the +shard key ``{ customer_id: 1 }``. You can change the shard key by +adding a suffix ``order_id`` field to the shard key so that ``{ +customer_id: 1, order_id: 1 }`` becomes the new shard key. For more +information, see the :dbcommand:`refineCollectionShardKey` command. - For example, you may have an existing ``orders`` collection with the - shard key ``{ customer_id: 1 }``. You can change the shard key by - adding a suffix ``order_id`` field to the shard key so that ``{ - customer_id: 1, order_id: 1 }`` becomes the new shard key. For more - information, see the :dbcommand:`refineCollectionShardKey` command. +Refining a collection's shard key allows for a more fine-grained +data distribution and can address situations where the existing key +has led to :ref:`jumbo (i.e. indivisible) chunks ` due +to insufficient cardinality. - Refining a collection's shard key allows for a more fine-grained - data distribution and can address situations where the existing key - has led to :ref:`jumbo (i.e. indivisible) chunks ` due - to insufficient cardinality. - - In MongoDB 4.2 and earlier, the choice of shard key cannot be changed - after sharding. +In MongoDB 4.2 and earlier, the choice of shard key cannot be changed +after sharding. .. _sharding-internals-shard-key-indexes: .. _sharding-shard-key-indexes: @@ -143,56 +140,53 @@ of the shard key. For a ranged sharded collection, only the following indexes can be :doc:`unique `: -.. container:: - - - the index on the shard key +- the index on the shard key - - a :term:`compound index` where the shard key is a :ref:`prefix - ` +- a :term:`compound index` where the shard key is a :ref:`prefix + ` - - the default ``_id`` index; **however**, the ``_id`` index only - enforces the uniqueness constraint per shard **if** the ``_id`` field - is **not** the shard key or the prefix of the shard key. +- the default ``_id`` index; **however**, the ``_id`` index only + enforces the uniqueness constraint per shard **if** the ``_id`` field + is **not** the shard key or the prefix of the shard key. - .. admonition:: Uniqueness and the ``_id`` Index - :class: important + .. important:: Uniqueness and the ``_id`` Index - If the ``_id`` field is not the shard key or the prefix of the - shard key, ``_id`` index only enforces the uniqueness constraint - per shard and **not** across shards. + If the ``_id`` field is not the shard key or the prefix of the + shard key, ``_id`` index only enforces the uniqueness constraint + per shard and **not** across shards. - For example, consider a sharded collection (with shard key ``{x: - 1}``) that spans two shards A and B. Because the ``_id`` key is - not part of the shard key, the collection could have a document - with ``_id`` value ``1`` in shard A and another document with - ``_id`` value ``1`` in shard B. + For example, consider a sharded collection (with shard key ``{x: + 1}``) that spans two shards A and B. Because the ``_id`` key is + not part of the shard key, the collection could have a document + with ``_id`` value ``1`` in shard A and another document with + ``_id`` value ``1`` in shard B. - If the ``_id`` field is not the shard key nor the prefix of the - shard key, MongoDB expects applications to enforce the uniqueness - of the ``_id`` values across the shards. + If the ``_id`` field is not the shard key nor the prefix of the + shard key, MongoDB expects applications to enforce the uniqueness + of the ``_id`` values across the shards. - The unique index constraints mean that: +The unique index constraints mean that: - - For a to-be-sharded collection, you cannot shard the collection if - the collection has other unique indexes. +- For a to-be-sharded collection, you cannot shard the collection if + the collection has other unique indexes. - - For an already-sharded collection, you cannot create unique indexes - on other fields. +- For an already-sharded collection, you cannot create unique indexes + on other fields. - - A unique index stores a null value for a document missing the - indexed field; that is a missing index field is treated as another - instance of a ``null`` index key value. For more information, see - :ref:`unique-index-and-missing-field`. +- A unique index stores a null value for a document missing the + indexed field; that is a missing index field is treated as another + instance of a ``null`` index key value. For more information, see + :ref:`unique-index-and-missing-field`. - To enforce uniqueness on the shard key values, pass the ``unique`` - parameter as ``true`` to the :method:`sh.shardCollection()` method: +To enforce uniqueness on the shard key values, pass the ``unique`` +parameter as ``true`` to the :method:`sh.shardCollection()` method: - .. include:: /includes/extracts/shard-collection-unique-restriction-method.rst +.. include:: /includes/extracts/shard-collection-unique-restriction-method.rst You cannot specify a unique constraint on a :ref:`hashed index `. -.. index:: shard key; cardinality + .. _shard-key-selection-divisible: .. _sharding-internals-operations-and-reliability: @@ -417,28 +411,26 @@ missing the shard key fields. Chunk Range and Missing Shard Key Fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Missing shard keys fall within the same chunk range as shard keys with +null values. For example, if the shard key is on the fields ``{ x: 1, y: 1 +}``, then: - Missing shard keys fall within the same chunk range as shard keys with - null values. For example, if the shard key is on the fields ``{ x: 1, y: 1 - }``, then: +.. list-table:: + :header-rows: 1 + :widths: 60 60 - .. list-table:: - :header-rows: 1 - :widths: 60 60 + * - Document Missing Shard Key - * - Document Missing Shard Key + - Falls into Same Range As - - Falls into Same Range As - - * - ``{ x: "hello" }`` - - ``{ x: "hello", y: null }`` + * - ``{ x: "hello" }`` + - ``{ x: "hello", y: null }`` - * - ``{ y: "goodbye" }`` - - ``{ x: null, y: "goodbye" }`` + * - ``{ y: "goodbye" }`` + - ``{ x: null, y: "goodbye" }`` - * - ``{ z: "oops" }`` - - ``{ x: null, y: null }`` + * - ``{ z: "oops" }`` + - ``{ x: null, y: null }`` .. _shard-key-missing-read-write-ops: diff --git a/source/core/shell-types.txt b/source/core/shell-types.txt index 2d8a2e29a10..573fa044e42 100644 --- a/source/core/shell-types.txt +++ b/source/core/shell-types.txt @@ -13,7 +13,7 @@ Data Types in the ``mongo`` Shell .. include:: /includes/fact-mongosh-callout.rst MongoDB :term:`BSON` provides support for additional data types than -:term:`JSON`. :ecosystem:`Drivers ` provide native +:term:`JSON`. :driver:`Drivers ` provide native support for these data types in host languages and the :binary:`~bin.mongo` shell also provides several helper classes to support the use of these data types in the :binary:`~bin.mongo` JavaScript @@ -126,7 +126,9 @@ the following operation in the :binary:`~bin.mongo` shell: new ObjectId -.. see:: :method:`ObjectId` +.. see:: + + :method:`ObjectId` .. _shell-type-long: @@ -276,8 +278,10 @@ The value is stored in the database as follows: NumberDecimal("9999999.50000000") -.. note:: To use the ``decimal`` data type with a - :ecosystem:`MongoDB driver `, be sure to use a driver +.. note:: + + To use the ``decimal`` data type with a + :driver:`MongoDB driver `, be sure to use a driver version that supports it. Equality and Sort Order diff --git a/source/core/tailable-cursors.txt b/source/core/tailable-cursors.txt index fba959cc546..496fbab6ebe 100644 --- a/source/core/tailable-cursors.txt +++ b/source/core/tailable-cursors.txt @@ -50,5 +50,5 @@ Consider the following behaviors related to tailable cursors: A *dead* cursor has an id of ``0``. -See your :ecosystem:`driver documentation ` for the +See your :driver:`driver documentation ` for the driver-specific method to specify the tailable cursor. diff --git a/source/core/text-search-operators.txt b/source/core/text-search-operators.txt index 89c99b6ad96..6f9ce0bea86 100644 --- a/source/core/text-search-operators.txt +++ b/source/core/text-search-operators.txt @@ -19,7 +19,7 @@ Query Framework .. include:: /includes/fact-use-text-operator.rst -Use the :projection:`$meta` query operator to obtain and sort by the +Use the :expression:`$meta` query operator to obtain and sort by the relevance score of each matching document. For example, to order a list of coffee shops in order of relevance, run the following: @@ -30,14 +30,14 @@ list of coffee shops in order of relevance, run the following: { score: { $meta: "textScore" } } ).sort( { score: { $meta: "textScore" } } ) -For more information on the :query:`$text` and :projection:`$meta` +For more information on the :query:`$text` and :expression:`$meta` operators, including restrictions and behavior, see: - :query:`$text Reference Page <$text>` - :ref:`$text Query Examples ` -- :projection:`$meta` projection operator +- :expression:`$meta` projection operator Aggregation Framework diff --git a/source/core/transactions-in-applications.txt b/source/core/transactions-in-applications.txt index 45290dffc45..733bdd8d426 100644 --- a/source/core/transactions-in-applications.txt +++ b/source/core/transactions-in-applications.txt @@ -7,8 +7,7 @@ Drivers API .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -51,199 +50,107 @@ The new callback API incorporates logic: - To retry the commit operation if the commit encounters an :ref:`unknown-transaction-commit-result`. -.. container:: +.. tabs-pillstrip:: languages - .. tabs-pillstrip:: languages +.. tabs-drivers:: - .. tabs-drivers:: + tabs: - tabs: + - id: python + content: | - - id: python - content: | + .. include:: /includes/extracts/transactions-example-note.rst - .. include:: /includes/extracts/transactions-example-note.rst + The example uses the new callback API for working with + transactions, which starts a transaction, executes the + specified operations, and commits (or aborts on error). The + new callback API incorporates retry logic for + :ref:`transient-transaction-error` or + :ref:`unknown-transaction-commit-result` commit errors. - The example uses the new callback API for working with - transactions, which starts a transaction, executes the - specified operations, and commits (or aborts on error). The - new callback API incorporates retry logic for - :ref:`transient-transaction-error` or - :ref:`unknown-transaction-commit-result` commit errors. + .. literalinclude:: /driver-examples/test_examples.py + :language: python + :dedent: 8 + :start-after: Start Transactions withTxn API Example 1 + :end-before: End Transactions withTxn API Example 1 + + - id: java-sync + content: | + + .. include:: /includes/extracts/transactions-example-note.rst + + The example uses the new callback API for working with + transactions, which starts a transaction, executes the + specified operations, and commits (or aborts on error). The + new callback API incorporates retry logic for + :ref:`transient-transaction-error` or + :ref:`unknown-transaction-commit-result` commit errors. - .. literalinclude:: /driver-examples/test_examples.py - :language: python - :dedent: 8 - :start-after: Start Transactions withTxn API Example 1 - :end-before: End Transactions withTxn API Example 1 + .. code-block:: java - - id: java-sync - content: | + /* + For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g. + String uri = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/admin?replicaSet=myRepl"; + For a sharded cluster, connect to the mongos instances; e.g. + String uri = "mongodb://mongos0.example.com:27017,mongos1.example.com:27017:27017/admin"; + */ - .. include:: /includes/extracts/transactions-example-note.rst + final MongoClient client = MongoClients.create(uri); - The example uses the new callback API for working with - transactions, which starts a transaction, executes the - specified operations, and commits (or aborts on error). The - new callback API incorporates retry logic for - :ref:`transient-transaction-error` or - :ref:`unknown-transaction-commit-result` commit errors. + /* + Create collections. + */ - .. code-block:: java + client.getDatabase("mydb1").getCollection("foo") + .withWriteConcern(WriteConcern.MAJORITY).insertOne( new Document("abc", 0)); + client.getDatabase("mydb2").getCollection("bar") + .withWriteConcern(WriteConcern.MAJORITY).insertOne( new Document("xyz", 0)); - /* - For a replica set, include the replica set name and a seedlist of the members in the URI string; e.g. - String uri = "mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017/admin?replicaSet=myRepl"; - For a sharded cluster, connect to the mongos instances; e.g. - String uri = "mongodb://mongos0.example.com:27017,mongos1.example.com:27017:27017/admin"; - */ - - final MongoClient client = MongoClients.create(uri); + /* Step 1: Start a client session. */ - /* - Create collections. - */ - - client.getDatabase("mydb1").getCollection("foo") - .withWriteConcern(WriteConcern.MAJORITY).insertOne( new Document("abc", 0)); - client.getDatabase("mydb2").getCollection("bar") - .withWriteConcern(WriteConcern.MAJORITY).insertOne( new Document("xyz", 0)); + final ClientSession clientSession = client.startSession(); - /* Step 1: Start a client session. */ + /* Step 2: Optional. Define options to use for the transaction. */ - final ClientSession clientSession = client.startSession(); + TransactionOptions txnOptions = TransactionOptions.builder() + .readPreference(ReadPreference.primary()) + .readConcern(ReadConcern.LOCAL) + .writeConcern(WriteConcern.MAJORITY) + .build(); - /* Step 2: Optional. Define options to use for the transaction. */ + /* Step 3: Define the sequence of operations to perform inside the transactions. */ - TransactionOptions txnOptions = TransactionOptions.builder() - .readPreference(ReadPreference.primary()) - .readConcern(ReadConcern.LOCAL) - .writeConcern(WriteConcern.MAJORITY) - .build(); + TransactionBody txnBody = new TransactionBody() { + public String execute() { + MongoCollection coll1 = client.getDatabase("mydb1").getCollection("foo"); + MongoCollection coll2 = client.getDatabase("mydb2").getCollection("bar"); - /* Step 3: Define the sequence of operations to perform inside the transactions. */ + /* + Important:: You must pass the session to the operations.. + */ - TransactionBody txnBody = new TransactionBody() { - public String execute() { - MongoCollection coll1 = client.getDatabase("mydb1").getCollection("foo"); - MongoCollection coll2 = client.getDatabase("mydb2").getCollection("bar"); + coll1.insertOne(clientSession, new Document("abc", 1)); + coll2.insertOne(clientSession, new Document("xyz", 999)); - /* - Important:: You must pass the session to the operations.. - */ + return "Inserted into collections in different databases"; + } + }; + try { + /* + Step 4: Use .withTransaction() to start a transaction, + execute the callback, and commit (or abort on error). + */ + + clientSession.withTransaction(txnBody, txnOptions); + } catch (RuntimeException e) { + // some error handling + } finally { + clientSession.close(); + } - coll1.insertOne(clientSession, new Document("abc", 1)); - coll2.insertOne(clientSession, new Document("xyz", 999)); + - id: nodejs + content: | - return "Inserted into collections in different databases"; - } - }; - try { - /* - Step 4: Use .withTransaction() to start a transaction, - execute the callback, and commit (or abort on error). - */ - - clientSession.withTransaction(txnBody, txnOptions); - } catch (RuntimeException e) { - // some error handling - } finally { - clientSession.close(); - } - - - id: nodejs - content: | - - .. include:: /includes/extracts/transactions-example-note.rst - - The example uses the new callback API for working with - transactions, which starts a transaction, executes the - specified operations, and commits (or aborts on error). The - new callback API incorporates retry logic for - :ref:`transient-transaction-error` or - :ref:`unknown-transaction-commit-result` commit errors. - - .. literalinclude:: /driver-examples/node_transactions.js - :language: javascript - :dedent: 4 - :start-after: Start Transactions withTxn API Example 1 - :end-before: End Transactions withTxn API Example 1 - - - id: php - content: | - - .. include:: /includes/extracts/transactions-example-note.rst - - The example uses the new callback API for working with - transactions, which starts a transaction, executes the - specified operations, and commits (or aborts on error). The - new callback API incorporates retry logic for - :ref:`transient-transaction-error` or - :ref:`unknown-transaction-commit-result` commit errors. - - .. literalinclude:: /driver-examples/DocumentationExamplesTest.php - :language: php - :dedent: 8 - :start-after: Start Transactions withTxn API Example 1 - :end-before: End Transactions withTxn API Example 1 - - - id: csharp - content: | - - .. include:: /includes/extracts/transactions-example-note.rst - - The example uses the new callback API for working with - transactions, which starts a transaction, executes the - specified operations, and commits (or aborts on error). The - new callback API incorporates retry logic for - :ref:`transient-transaction-error` or - :ref:`unknown-transaction-commit-result` commit errors. - - .. literalinclude:: /driver-examples/withTxnExample1.cs - :language: c# - :dedent: 12 - :start-after: Start Transactions withTxn API Example 1 - :end-before: End Transactions withTxn API Example 1 - - - - id: c - content: | - - .. include:: /includes/extracts/transactions-example-note.rst - - The example uses the new callback API for working with - transactions, which starts a transaction, executes the - specified operations, and commits (or aborts on error). The - new callback API incorporates retry logic for - :ref:`transient-transaction-error` or - :ref:`unknown-transaction-commit-result` commit errors. - - .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c - :language: c - :start-after: Start Transactions withTxn API Example 1 - :end-before: End Transactions withTxn API Example 1 - - - id: cpp - content: | - - .. include:: /includes/extracts/transactions-example-note.rst - - The example uses the new callback API for working with - transactions, which starts a transaction, executes the - specified operations, and commits (or aborts on error). The - new callback API incorporates retry logic for - :ref:`transient-transaction-error` or - :ref:`unknown-transaction-commit-result` commit errors. - - .. literalinclude:: /driver-examples/cpp-with-transaction.cpp - :language: cpp - :dedent: 4 - :start-after: Start Transactions withTxn API Example 1 - :end-before: End Transactions withTxn API Example 1 - - - id: motor - content: | - .. include:: /includes/extracts/transactions-example-note.rst The example uses the new callback API for working with @@ -253,14 +160,14 @@ The new callback API incorporates logic: :ref:`transient-transaction-error` or :ref:`unknown-transaction-commit-result` commit errors. - .. literalinclude:: /driver-examples/test_examples_motor.py - :language: python - :dedent: 8 + .. literalinclude:: /driver-examples/node_transactions.js + :language: javascript + :dedent: 4 :start-after: Start Transactions withTxn API Example 1 :end-before: End Transactions withTxn API Example 1 - - id: ruby - content: | + - id: php + content: | .. include:: /includes/extracts/transactions-example-note.rst @@ -271,15 +178,35 @@ The new callback API incorporates logic: :ref:`transient-transaction-error` or :ref:`unknown-transaction-commit-result` commit errors. + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php + :language: php + :dedent: 8 + :start-after: Start Transactions withTxn API Example 1 + :end-before: End Transactions withTxn API Example 1 - .. literalinclude:: /driver-examples/with_transactions_examples_spec.rb - :language: ruby - :dedent: 4 + - id: csharp + content: | + + .. include:: /includes/extracts/transactions-example-note.rst + + The example uses the new callback API for working with + transactions, which starts a transaction, executes the + specified operations, and commits (or aborts on error). The + new callback API incorporates retry logic for + :ref:`transient-transaction-error` or + :ref:`unknown-transaction-commit-result` commit errors. + + .. literalinclude:: /driver-examples/withTxnExample1.cs + :language: c# + :dedent: 12 :start-after: Start Transactions withTxn API Example 1 :end-before: End Transactions withTxn API Example 1 - - id: go - content: | + + - id: c + content: | + + .. include:: /includes/extracts/transactions-example-note.rst The example uses the new callback API for working with transactions, which starts a transaction, executes the @@ -288,26 +215,96 @@ The new callback API incorporates logic: :ref:`transient-transaction-error` or :ref:`unknown-transaction-commit-result` commit errors. + .. literalinclude:: /driver-examples/test-mongoc-sample-commands.c + :language: c + :start-after: Start Transactions withTxn API Example 1 + :end-before: End Transactions withTxn API Example 1 + + - id: cpp + content: | + .. include:: /includes/extracts/transactions-example-note.rst - .. literalinclude:: /driver-examples/go_examples.go - :language: go + The example uses the new callback API for working with + transactions, which starts a transaction, executes the + specified operations, and commits (or aborts on error). The + new callback API incorporates retry logic for + :ref:`transient-transaction-error` or + :ref:`unknown-transaction-commit-result` commit errors. + + .. literalinclude:: /driver-examples/cpp-with-transaction.cpp + :language: cpp + :dedent: 4 :start-after: Start Transactions withTxn API Example 1 :end-before: End Transactions withTxn API Example 1 - - id: perl - content: | + - id: motor + content: | + + .. include:: /includes/extracts/transactions-example-note.rst + + The example uses the new callback API for working with + transactions, which starts a transaction, executes the + specified operations, and commits (or aborts on error). The + new callback API incorporates retry logic for + :ref:`transient-transaction-error` or + :ref:`unknown-transaction-commit-result` commit errors. + + .. literalinclude:: /driver-examples/test_examples_motor.py + :language: python + :dedent: 8 + :start-after: Start Transactions withTxn API Example 1 + :end-before: End Transactions withTxn API Example 1 + + - id: ruby + content: | + + .. include:: /includes/extracts/transactions-example-note.rst + + The example uses the new callback API for working with + transactions, which starts a transaction, executes the + specified operations, and commits (or aborts on error). The + new callback API incorporates retry logic for + :ref:`transient-transaction-error` or + :ref:`unknown-transaction-commit-result` commit errors. - .. note:: - - For the Perl driver, see the :ref:`txn-core-api` usage example instead. - - id: scala - content: | + .. literalinclude:: /driver-examples/with_transactions_examples_spec.rb + :language: ruby + :dedent: 4 + :start-after: Start Transactions withTxn API Example 1 + :end-before: End Transactions withTxn API Example 1 - .. note:: - - For the Scala driver, see the :ref:`txn-core-api` usage example instead. + - id: go + content: | + + The example uses the new callback API for working with + transactions, which starts a transaction, executes the + specified operations, and commits (or aborts on error). The + new callback API incorporates retry logic for + :ref:`transient-transaction-error` or + :ref:`unknown-transaction-commit-result` commit errors. + + .. include:: /includes/extracts/transactions-example-note.rst + + .. literalinclude:: /driver-examples/go_examples.go + :language: go + :start-after: Start Transactions withTxn API Example 1 + :end-before: End Transactions withTxn API Example 1 + + - id: perl + content: | + + .. note:: + + For the Perl driver, see the :ref:`txn-core-api` usage example instead. + + - id: scala + content: | + + .. note:: + + For the Scala driver, see the :ref:`txn-core-api` usage example instead. .. _txn-core-api: @@ -334,11 +331,9 @@ labeled: The following example incorporates logic to retry the transaction for transient errors and retry the commit for unknown commit error: -.. container:: - - .. tabs-pillstrip:: languages +.. tabs-pillstrip:: languages - .. include:: /includes/driver-examples/driver-example-transactions-retry-3.rst +.. include:: /includes/driver-examples/driver-example-transactions-retry-3.rst Driver Versions --------------- diff --git a/source/core/transactions-operations.txt b/source/core/transactions-operations.txt index be1f9757b23..4239ded92aa 100644 --- a/source/core/transactions-operations.txt +++ b/source/core/transactions-operations.txt @@ -6,8 +6,7 @@ Transactions and Operations .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -50,18 +49,14 @@ The following read/write operations are allowed in transactions: Count Operation ~~~~~~~~~~~~~~~ -.. container:: - - .. include:: /includes/extracts/transactions-count.rst +.. include:: /includes/extracts/transactions-count.rst .. _transactions-operations-distinct: Distinct Operation ~~~~~~~~~~~~~~~~~~ -.. container:: - - .. include:: /includes/extracts/transactions-distinct.rst +.. include:: /includes/extracts/transactions-distinct.rst .. _transactions-operations-ddl: @@ -173,4 +168,6 @@ Restricted Operations .. include:: /includes/extracts/transactions-operations-restrictions.rst -.. seealso:: :ref:`txn-prod-considerations-ddl` +.. seealso:: + + :ref:`txn-prod-considerations-ddl` diff --git a/source/core/transactions-production-consideration.txt b/source/core/transactions-production-consideration.txt index 0e3dcbc6e88..4d065e705a1 100644 --- a/source/core/transactions-production-consideration.txt +++ b/source/core/transactions-production-consideration.txt @@ -4,8 +4,7 @@ Production Considerations .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -266,7 +265,9 @@ transactions waiting behind that operation abort. That is, the value of the time required for the in-progress transaction *and* the pending DDL operation to complete. -.. seealso:: +.. seealso:: + + - :ref:`transactions-write-conflicts` @@ -301,7 +302,10 @@ In-progress Transactions and Chunk Migration .. include:: /includes/extracts/transactions-chunk-migration.rst -.. seealso:: :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` +.. seealso:: + + :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` + .. _transactions-prod-consideration-outside-reads: @@ -346,5 +350,7 @@ of MongoDB 4.2) will fail and can result in errors, including: Additional Information ---------------------- -.. seealso:: :doc:`/core/transactions-sharded-clusters` +.. seealso:: + + :doc:`/core/transactions-sharded-clusters` diff --git a/source/core/transactions-sharded-clusters.txt b/source/core/transactions-sharded-clusters.txt index ba9b1d8d34d..5f9f2753ae5 100644 --- a/source/core/transactions-sharded-clusters.txt +++ b/source/core/transactions-sharded-clusters.txt @@ -146,14 +146,19 @@ Chunk Migrations .. include:: /includes/extracts/transactions-chunk-migration.rst -.. seealso:: :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` +.. seealso:: + + :serverstatus:`shardingStatistics.countDonorMoveChunkLockTimeout` + Outside Reads During Commit --------------------------- .. include:: /includes/extracts/transactions-multi-shard-block-external-reads.rst -.. seealso:: :ref:`transactions-atomicity` +.. seealso:: + + :ref:`transactions-atomicity` Additional Information ---------------------- diff --git a/source/core/transactions.txt b/source/core/transactions.txt index 8c1c4e2d3a7..4681492c68d 100644 --- a/source/core/transactions.txt +++ b/source/core/transactions.txt @@ -4,8 +4,7 @@ Transactions .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -35,7 +34,6 @@ Transactions API The following example highlights the key components of the transactions API: - .. tabs-pillstrip:: languages .. tabs-drivers:: @@ -357,7 +355,9 @@ Multi-document transactions are atomic (i.e. provide an .. include:: /includes/extracts/transactions-usage.rst -.. seealso:: :ref:`transactions-prod-consideration-outside-reads` +.. seealso:: + + :ref:`transactions-prod-consideration-outside-reads` .. _transactions-operations: @@ -433,27 +433,25 @@ index to create must be on either: Restrictions ```````````` -.. container:: +- .. include:: /includes/extracts/transactions-cross-shard-collection-restriction.rst - - .. include:: /includes/extracts/transactions-cross-shard-collection-restriction.rst +- For explicit creation of a collection or an index inside a + transaction, the transaction read concern level must be + :readconcern:`"local"`. Explicit creation is through: - - For explicit creation of a collection or an index inside a - transaction, the transaction read concern level must be - :readconcern:`"local"`. Explicit creation is through: + .. list-table:: + :header-rows: 1 - .. list-table:: - :header-rows: 1 + * - Command + - Method - * - Command - - Method - - * - :dbcommand:`create` - - :method:`db.createCollection()` + * - :dbcommand:`create` + - :method:`db.createCollection()` - * - :dbcommand:`createIndexes` + * - :dbcommand:`createIndexes` - - | :method:`db.collection.createIndex()` - | :method:`db.collection.createIndexes()` + - | :method:`db.collection.createIndex()` + | :method:`db.collection.createIndexes()` .. seealso:: @@ -464,18 +462,14 @@ Restrictions Count Operation ~~~~~~~~~~~~~~~ -.. container:: - - .. include:: /includes/extracts/transactions-count.rst +.. include:: /includes/extracts/transactions-count.rst .. _transactions-ops-distinct: Distinct Operation ~~~~~~~~~~~~~~~~~~ -.. container:: - - .. include:: /includes/extracts/transactions-distinct.rst +.. include:: /includes/extracts/transactions-distinct.rst .. _transactions-ops-info: @@ -566,57 +560,51 @@ Transactions support the following read concern levels: ``"local"`` ``````````` -.. container:: +- Read concern :readconcern:`"local"` returns the most recent data + available from the node but can be rolled back. - - Read concern :readconcern:`"local"` returns the most recent data - available from the node but can be rolled back. +- For transactions on sharded cluster, :readconcern:`"local"` read + concern cannot guarantee that the data is from the same snapshot + view across the shards. If snapshot isolation is required, use + :ref:`transactions-read-concern-snapshot` read concern. - - For transactions on sharded cluster, :readconcern:`"local"` read - concern cannot guarantee that the data is from the same snapshot - view across the shards. If snapshot isolation is required, use - :ref:`transactions-read-concern-snapshot` read concern. - - - .. include:: /includes/extracts/transactions-create-collections-read-concern.rst +- .. include:: /includes/extracts/transactions-create-collections-read-concern.rst ``"majority"`` `````````````` -.. container:: - - - Read concern :readconcern:`"majority"` returns data that has been - acknowledged by a majority of the replica set members (i.e. data - cannot be rolled back) **if** the transaction commits with - :ref:`write concern "majority" `. +- Read concern :readconcern:`"majority"` returns data that has been + acknowledged by a majority of the replica set members (i.e. data + cannot be rolled back) **if** the transaction commits with + :ref:`write concern "majority" `. - - If the transaction does not use :ref:`write concern "majority" - ` for the commit, the - :readconcern:`"majority"` read concern provides **no** guarantees that - read operations read majority-committed data. +- If the transaction does not use :ref:`write concern "majority" + ` for the commit, the + :readconcern:`"majority"` read concern provides **no** guarantees that + read operations read majority-committed data. - - For transactions on sharded cluster, :readconcern:`"majority"` read - concern cannot guarantee that the data is from the same snapshot - view across the shards. If snapshot isolation is required, use - :ref:`transactions-read-concern-snapshot` read concern. +- For transactions on sharded cluster, :readconcern:`"majority"` read + concern cannot guarantee that the data is from the same snapshot + view across the shards. If snapshot isolation is required, use + :ref:`transactions-read-concern-snapshot` read concern. .. _transactions-read-concern-snapshot: ``"snapshot"`` `````````````` -.. container:: +- Read concern :readconcern:`"snapshot"` returns data from a + snapshot of majority committed data **if** the transaction commits + with :ref:`write concern "majority" `. - - Read concern :readconcern:`"snapshot"` returns data from a - snapshot of majority committed data **if** the transaction commits - with :ref:`write concern "majority" `. +- If the transaction does not use :ref:`write concern "majority" + ` for the commit, the + :readconcern:`"snapshot"` read concern provides **no** guarantee that + read operations used a snapshot of majority-committed data. - - If the transaction does not use :ref:`write concern "majority" - ` for the commit, the - :readconcern:`"snapshot"` read concern provides **no** guarantee that - read operations used a snapshot of majority-committed data. - - - For transactions on sharded clusters, the - :readconcern:`"snapshot"` view of the data **is** synchronized - across shards. +- For transactions on sharded clusters, the + :readconcern:`"snapshot"` view of the data **is** synchronized + across shards. .. _transactions-write-concern: @@ -656,47 +644,43 @@ values, including: ``w: 1`` ```````` -.. container:: - - - Write concern :writeconcern:`w: 1 <\>` returns - acknowledgement after the commit has been applied to the primary. +- Write concern :writeconcern:`w: 1 <\>` returns + acknowledgement after the commit has been applied to the primary. - .. important:: + .. important:: - When you commit with :writeconcern:`w: 1 <\>`, your - transaction can be :doc:`rolled back if there is a failover - `. + When you commit with :writeconcern:`w: 1 <\>`, your + transaction can be :doc:`rolled back if there is a failover + `. - - When you commit with :writeconcern:`w: 1 <\>` write - concern, transaction-level :readconcern:`"majority"` read concern - provides **no** guarantees that read operations in the transaction - read majority-committed data. +- When you commit with :writeconcern:`w: 1 <\>` write + concern, transaction-level :readconcern:`"majority"` read concern + provides **no** guarantees that read operations in the transaction + read majority-committed data. - - When you commit with :writeconcern:`w: 1 <\>` write - concern, transaction-level :readconcern:`"snapshot"` read concern - provides **no** guarantee that read operations in the transaction - used a snapshot of majority-committed data. +- When you commit with :writeconcern:`w: 1 <\>` write + concern, transaction-level :readconcern:`"snapshot"` read concern + provides **no** guarantee that read operations in the transaction + used a snapshot of majority-committed data. ``w: "majority"`` ````````````````` -.. container:: - - - Write concern :writeconcern:`w: "majority" <"majority">` returns - acknowledgement after the commit has been applied to a majority - (M) of voting members; i.e. the commit has been applied to the - primary and (M-1) voting secondaries. - - - When you commit with :writeconcern:`w: "majority" <"majority">` - write concern, transaction-level :readconcern:`"majority"` read - concern guarantees that operations have read majority-committed - data. For transactions on sharded clusters, this view of the - majority-committed data is not synchronized across shards. - - - When you commit with :writeconcern:`w: "majority" <"majority">` - write concern, transaction-level :readconcern:`"snapshot"` read - concern guarantees that operations have from a synchronized - snapshot of majority-committed data. +- Write concern :writeconcern:`w: "majority" <"majority">` returns + acknowledgement after the commit has been applied to a majority + (M) of voting members; i.e. the commit has been applied to the + primary and (M-1) voting secondaries. + +- When you commit with :writeconcern:`w: "majority" <"majority">` + write concern, transaction-level :readconcern:`"majority"` read + concern guarantees that operations have read majority-committed + data. For transactions on sharded clusters, this view of the + majority-committed data is not synchronized across shards. + +- When you commit with :writeconcern:`w: "majority" <"majority">` + write concern, transaction-level :readconcern:`"snapshot"` read + concern guarantees that operations have from a synchronized + snapshot of majority-committed data. .. note:: diff --git a/source/core/wiredtiger.txt b/source/core/wiredtiger.txt index c1e182fde43..9018780241b 100644 --- a/source/core/wiredtiger.txt +++ b/source/core/wiredtiger.txt @@ -105,7 +105,9 @@ will lose all data modifications prior to the last checkpoint. .. include:: /includes/wiredtiger-node-nojournal.rst -.. seealso:: :ref:`Journaling with WiredTiger ` +.. seealso:: + + :ref:`Journaling with WiredTiger ` .. _storage-wiredtiger-compression: diff --git a/source/core/write-operations-atomicity.txt b/source/core/write-operations-atomicity.txt index 4d76ae2e3e0..52c02352b3f 100644 --- a/source/core/write-operations-atomicity.txt +++ b/source/core/write-operations-atomicity.txt @@ -43,4 +43,6 @@ examples of use cases, see :ref:`update() and Unique Index Another approach is to specify the expected current value of a field in the query predicate for the write operations. -.. seealso:: :doc:`/core/read-isolation-consistency-recency` +.. seealso:: + + :doc:`/core/read-isolation-consistency-recency` diff --git a/source/core/write-performance.txt b/source/core/write-performance.txt index 254640d2a0f..8e7e96a3dca 100644 --- a/source/core/write-performance.txt +++ b/source/core/write-performance.txt @@ -53,7 +53,9 @@ disk readahead and RAID configurations. Solid state drives (SSDs) can outperform spinning hard disks (HDDs) by 100 times or more for random workloads. -.. see:: :doc:`/administration/production-notes` for recommendations +.. see:: + + :doc:`/administration/production-notes` for recommendations regarding additional hardware and configuration options. Journaling diff --git a/source/core/zone-sharding.txt b/source/core/zone-sharding.txt index 1d0284806a0..5b52303042e 100644 --- a/source/core/zone-sharding.txt +++ b/source/core/zone-sharding.txt @@ -125,7 +125,10 @@ Initial Chunk Distribution See :ref:`pre-define-zone-range-hashed-example` for for an example. -.. seealso:: :method:`sh.balancerCollectionStatus()` +.. seealso:: + + :method:`sh.balancerCollectionStatus()` + .. _zone-sharding-balancer: @@ -156,7 +159,10 @@ that zone. Once configured, the balancer respects zones during future :ref:`balancing rounds `. -.. seealso:: :method:`sh.balancerCollectionStatus()` +.. seealso:: + + :method:`sh.balancerCollectionStatus()` + .. _zone-sharding-shard-key: diff --git a/source/data-center-awareness.txt b/source/data-center-awareness.txt index ea3a60b31ee..3d162215ab4 100644 --- a/source/data-center-awareness.txt +++ b/source/data-center-awareness.txt @@ -25,21 +25,19 @@ The following documents, *found either in this section or other sections of this manual*, provide information on customizing a deployment for operation- and location-based separation: -.. class:: toc - - :doc:`/core/workload-isolation` - MongoDB lets you specify that certain application operations use - certain :binary:`~bin.mongod` instances. - - :doc:`/core/zone-sharding` - A zone represents one or more ranges of shard key values for a - sharded collection. MongoDB routes reads and writes for sharded - data covered by a zone only to shards inside that zone. For use in - managing data distribution and deployment patterns. - - :doc:`/tutorial/manage-shard-zone` - Administrative tasks related to configuring zones in sharded - clusters +:doc:`/core/workload-isolation` + MongoDB lets you specify that certain application operations use + certain :binary:`~bin.mongod` instances. + +:doc:`/core/zone-sharding` + A zone represents one or more ranges of shard key values for a + sharded collection. MongoDB routes reads and writes for sharded + data covered by a zone only to shards inside that zone. For use in + managing data distribution and deployment patterns. + +:doc:`/tutorial/manage-shard-zone` + Administrative tasks related to configuring zones in sharded + clusters diff --git a/source/data-modeling.txt b/source/data-modeling.txt index aaefa2db145..1470a02088f 100644 --- a/source/data-modeling.txt +++ b/source/data-modeling.txt @@ -15,27 +15,25 @@ Data in MongoDB has a *flexible schema*. :term:`Collections flexibility gives you data-modeling choices to match your application and its performance requirements. -.. class:: toc +:doc:`/core/data-modeling-introduction` + An introduction to data modeling in MongoDB. - :doc:`/core/data-modeling-introduction` - An introduction to data modeling in MongoDB. +:doc:`/core/schema-validation` + MongoDB provides the capability for schema validation during + updates and insertions. - :doc:`/core/schema-validation` - MongoDB provides the capability for schema validation during - updates and insertions. +:doc:`/core/data-models` + The core documentation detailing the decisions you must make when + determining a data model, and discussing considerations that + should be taken into account. - :doc:`/core/data-models` - The core documentation detailing the decisions you must make when - determining a data model, and discussing considerations that - should be taken into account. +:doc:`/applications/data-models` + Examples of possible data models that you can use to structure + your MongoDB documents. - :doc:`/applications/data-models` - Examples of possible data models that you can use to structure - your MongoDB documents. - - :doc:`/reference/data-models` - Reference material for data modeling for developers of MongoDB - applications. +:doc:`/reference/data-models` + Reference material for data modeling for developers of MongoDB + applications. .. toctree:: diff --git a/source/faq/concurrency.txt b/source/faq/concurrency.txt index 37277e6c1b3..18cb9df5fd5 100644 --- a/source/faq/concurrency.txt +++ b/source/faq/concurrency.txt @@ -279,7 +279,9 @@ the lock for a very short time: | :method:`db.createUser()` - -.. seealso:: :ref:`faq-concurrency-lock-multiple-dbs` +.. seealso:: + + :ref:`faq-concurrency-lock-multiple-dbs` .. _faq-concurrency-collection-lock: diff --git a/source/faq/fundamentals.txt b/source/faq/fundamentals.txt index 0679c94cb24..1052e4c62ad 100644 --- a/source/faq/fundamentals.txt +++ b/source/faq/fundamentals.txt @@ -36,7 +36,9 @@ to records or rows in a relational database table. Each document has :ref:`one or more fields `; fields are similar to the columns in a relational database table. -.. seealso:: :doc:`/reference/sql-comparison`, :doc:`/introduction` +.. seealso:: + + :doc:`/reference/sql-comparison`, :doc:`/introduction` How do I create a database and a collection? -------------------------------------------- @@ -117,7 +119,9 @@ download the `MongoDB Application Modernization Guide practices migration guide, reference schema, and other helpful resources. -.. seealso:: :doc:`/reference/sql-comparison` +.. seealso:: + + :doc:`/reference/sql-comparison` Does MongoDB support transactions? ---------------------------------- @@ -153,7 +157,7 @@ object, not a string. Thus traditional SQL injection attacks are not a problem. More details and some nuances are covered below. MongoDB represents queries as :term:`BSON` objects. Typically -:ecosystem:`client libraries ` provide a convenient, +:driver:`client libraries ` provide a convenient, injection free, process to build these objects. Consider the following C++ example: diff --git a/source/faq/replica-sets.txt b/source/faq/replica-sets.txt index 9b3eb24c1de..b2e9389ca54 100644 --- a/source/faq/replica-sets.txt +++ b/source/faq/replica-sets.txt @@ -35,7 +35,9 @@ For example, a deployment may maintain a :term:`primary` and :term:`secondary` in an East-coast data center along with a :term:`secondary` member for disaster recovery in a West-coast data center. -.. seealso:: :doc:`/tutorial/deploy-geographically-distributed-replica-set` +.. seealso:: + + :doc:`/tutorial/deploy-geographically-distributed-replica-set` Can MongoDB replicate over a "noisy" connection? ------------------------------------------------ @@ -48,7 +50,9 @@ administrator intervention. However, if the network connections among the nodes in the replica set are very slow, it might not be possible for the members of the node to keep up with the replication. -.. seealso:: :doc:`/core/replica-set-elections` +.. seealso:: + + :doc:`/core/replica-set-elections` Why use journaling if replication already provides data redundancy? ------------------------------------------------------------------- @@ -89,7 +93,9 @@ See the documentation for :doc:`/tutorial/configure-ssl` for more information. As with all MongoDB components, run arbiters on secure networks. -.. see:: The overview of +.. see:: + + The overview of :ref:`Arbiter Members of Replica Sets `. diff --git a/source/faq/sharding.txt b/source/faq/sharding.txt index dc887dbb4cc..495cab1b5a3 100644 --- a/source/faq/sharding.txt +++ b/source/faq/sharding.txt @@ -64,7 +64,9 @@ For details on updating the shard key values, see Before MongoDB 4.2, a document's shard key field value is immutable. -.. seealso:: :doc:`/core/sharding-shard-key` +.. seealso:: + + :doc:`/core/sharding-shard-key` Why are my documents not distributed across the shards? ------------------------------------------------------- diff --git a/source/faq/storage.txt b/source/faq/storage.txt index eacc7d7814b..40602f376d6 100644 --- a/source/faq/storage.txt +++ b/source/faq/storage.txt @@ -26,7 +26,9 @@ for specific workloads. For example, one storage engine might offer better performance for read-heavy workloads, and another might support a higher throughput for write operations. -.. seealso:: :doc:`/core/storage-engines` +.. seealso:: + + :doc:`/core/storage-engines` Can you mix storage engines in a replica set? --------------------------------------------- diff --git a/source/geospatial-queries.txt b/source/geospatial-queries.txt index 9c7703c0dd7..c23f6a9c052 100644 --- a/source/geospatial-queries.txt +++ b/source/geospatial-queries.txt @@ -98,7 +98,7 @@ collections: .. |geo-operation| replace:: :query:`$near` and :query:`$nearSphere` You can also query for geospatial data for a sharded cluster using -:query:`$geoWithin` and :query:`$geoIntersect`. +:query:`$geoWithin` and :query:`$geoIntersects`. Covered Queries ~~~~~~~~~~~~~~~ @@ -341,7 +341,7 @@ farthest: } ) -The following operation uses the :pipeline:`geoNear` aggregation +The following operation uses the :pipeline:`$geoNear` aggregation operation to return documents that match the query filter ``{ category: "Parks" }``, sorted in order of nearest to farthest to the specified GeoJSON point: diff --git a/source/images/agg-pipeline.gif b/source/images/agg-pipeline.gif new file mode 100644 index 00000000000..beae4e6417d Binary files /dev/null and b/source/images/agg-pipeline.gif differ diff --git a/source/includes/3.4-downgrade-path.rst b/source/includes/3.4-downgrade-path.rst index 0c3dbeeb596..abf24973b8c 100644 --- a/source/includes/3.4-downgrade-path.rst +++ b/source/includes/3.4-downgrade-path.rst @@ -1,2 +1 @@ -Once upgraded to 3.4, you cannot downgrade to a 3.2.7 or earlier -version. You can only downgrade to a 3.2.8 or later version. +Once upgraded to 3.4, you cannot downgrade to a 3.2.7 or earlier version. You can only downgrade to a 3.2.8 or later version. diff --git a/source/includes/3.4-upgrade-replacements.rst b/source/includes/3.4-upgrade-replacements.rst index 5ff70df73b5..1b7f04ff6c3 100644 --- a/source/includes/3.4-upgrade-replacements.rst +++ b/source/includes/3.4-upgrade-replacements.rst @@ -5,6 +5,6 @@ .. |olderseries| replace:: 3.0-series .. |compatibility| replace:: :doc:`/release-notes/3.4-compatibility` .. |upgradefirst| replace:: :doc:`3.2 ` -.. |downgradepath| replace:: .. include:: /includes/3.4-downgrade-path.rst +.. |downgradepath| replace:: Once upgraded to 3.4, you cannot downgrade to a 3.2.7 or earlier version. You can only downgrade to a 3.2.8 or later version. .. |installationdoc| replace:: :v3.4:`3.4 installation instructions ` \ No newline at end of file diff --git a/source/includes/3.6-upgrade-replacements.rst b/source/includes/3.6-upgrade-replacements.rst index 013b6cc1e0b..6e7dba61e27 100644 --- a/source/includes/3.6-upgrade-replacements.rst +++ b/source/includes/3.6-upgrade-replacements.rst @@ -5,7 +5,7 @@ .. |olderseries| replace:: 3.2-series .. |compatibility| replace:: :doc:`/release-notes/3.6-compatibility` .. |upgradefirst| replace:: :ref:`upgrade first to 3.4 <3.4-upgrade>` -.. |downgradepath| replace:: .. include:: /includes/3.6-downgrade-path.rst +.. |downgradepath| replace:: Once upgraded to |newversion|, if you need to downgrade, we recommend |downgrading| to the latest patch release of 3.4. .. |features| replace:: :ref:`features <3.6-compatibility-enabled>` diff --git a/source/includes/4.0-downgrade-path.rst b/source/includes/4.0-downgrade-path.rst index 3c5a2ffd359..abf384fb50e 100644 --- a/source/includes/4.0-downgrade-path.rst +++ b/source/includes/4.0-downgrade-path.rst @@ -1,2 +1 @@ Once upgraded to |newversion|, if you need to downgrade, we recommend |downgrading| to the latest patch release of |oldversion|. - diff --git a/source/includes/4.0-upgrade-replacements.rst b/source/includes/4.0-upgrade-replacements.rst index 27ebde5c05c..dc12a128666 100644 --- a/source/includes/4.0-upgrade-replacements.rst +++ b/source/includes/4.0-upgrade-replacements.rst @@ -5,7 +5,7 @@ .. |olderseries| replace:: 3.4-series .. |compatibility| replace:: :doc:`/release-notes/4.0-compatibility` .. |upgradefirst| replace:: :ref:`upgrade first to 3.6 <3.6-upgrade>` -.. |downgradepath| replace:: .. include:: /includes/4.0-downgrade-path.rst +.. |downgradepath| replace:: Once upgraded to |newversion|, if you need to downgrade, we recommend |downgrading| to the latest patch release of |oldversion|. .. |features| replace:: :ref:`features<4.0-compatibility-enabled>` .. |installationdoc| replace:: :v4.0:`4.0 installation instructions ` diff --git a/source/includes/4.2-upgrade-replacements.rst b/source/includes/4.2-upgrade-replacements.rst index 5c83d193d1c..6870216bd3a 100644 --- a/source/includes/4.2-upgrade-replacements.rst +++ b/source/includes/4.2-upgrade-replacements.rst @@ -5,7 +5,7 @@ .. |olderseries| replace:: 3.6-series .. |compatibility| replace:: :doc:`/release-notes/4.2-compatibility` .. |upgradefirst| replace:: :ref:`upgrade first to 4.0 <4.0-upgrade>` -.. |downgradepath| replace:: .. include:: /includes/downgrade-path.rst +.. |downgradepath| replace:: Once upgraded to |newversion|, if you need to downgrade, we recommend |downgrading| to the latest patch release of |downgradeversion|. .. |features| replace:: :ref:`features<4.2-compatibility-enabled>` .. |downgradeversion| replace:: 4.0 diff --git a/source/includes/4.4-upgrade-replacements.rst b/source/includes/4.4-upgrade-replacements.rst index ce1c18bade5..fe7cbcb821c 100644 --- a/source/includes/4.4-upgrade-replacements.rst +++ b/source/includes/4.4-upgrade-replacements.rst @@ -5,7 +5,8 @@ .. |olderseries| replace:: 4.0-series .. |compatibility| replace:: :doc:`/release-notes/4.4-compatibility` .. |upgradefirst| replace:: :ref:`upgrade first to 4.2 <4.2-upgrade>` -.. |downgradepath| replace:: .. include:: /includes/downgrade-path.rst +.. |downgradepath| replace:: Once upgraded to |newversion|, if you need to downgrade, we recommend |downgrading| to the latest patch release of |downgradeversion|. + .. |features| replace:: :ref:`features<4.4-compatibility-enabled>` .. |downgradeversion| replace:: 4.2 diff --git a/source/includes/access-change-password.rst b/source/includes/access-change-password.rst index ddb628cd88d..9002353fc05 100644 --- a/source/includes/access-change-password.rst +++ b/source/includes/access-change-password.rst @@ -1,3 +1,3 @@ To modify the password of another user on a database, you must have the -:authaction:`changeAnyPassword` :ref:`action ` +:authaction:`changePassword` :ref:`action ` on that database. diff --git a/source/includes/access-mongorestore-collections.rst b/source/includes/access-mongorestore-collections.rst index eff9db73519..c699da0c5a3 100644 --- a/source/includes/access-mongorestore-collections.rst +++ b/source/includes/access-mongorestore-collections.rst @@ -5,27 +5,25 @@ If the backup data includes :data:`system.profile :option:`--oplogReplay `, you need additional privileges: -.. container:: +.. list-table:: + :widths: 20 80 - .. list-table:: - :widths: 20 80 + * - ``system.profile`` - * - ``system.profile`` + - .. include:: /includes/fact-restore-role-system.profile.rst - - .. include:: /includes/fact-restore-role-system.profile.rst + Both the built-in roles :authrole:`dbAdmin` and + :authrole:`dbAdminAnyDatabase` provide the additional privileges. - Both the built-in roles :authrole:`dbAdmin` and - :authrole:`dbAdminAnyDatabase` provide the additional privileges. + * - ``--oplogReplay`` - * - ``--oplogReplay`` + - To run with :option:`--oplogReplay + `, create a + :ref:`user-defined role ` that has + :authaction:`anyAction` on :ref:`resource-anyresource`. - - To run with :option:`--oplogReplay - `, create a - :ref:`user-defined role ` that has - :authaction:`anyAction` on :ref:`resource-anyresource`. - - Grant only to users who must run :binary:`~bin.mongorestore` - with :option:`--oplogReplay `. + Grant only to users who must run :binary:`~bin.mongorestore` + with :option:`--oplogReplay `. .. COMMENT per the following commit, choosing the anyAction/anyResource over the __system role. diff --git a/source/includes/access-update-user.rst b/source/includes/access-update-user.rst index db9c1cacbe7..19087221968 100644 --- a/source/includes/access-update-user.rst +++ b/source/includes/access-update-user.rst @@ -6,5 +6,5 @@ You must have the :authaction:`grantRole` :ref:`action ` on a role's database to add a role to a user. To change another user's ``pwd`` or ``customData`` field, you must have -the :authaction:`changeAnyPassword` and :authaction:`changeAnyCustomData` +the :authaction:`changePassword` and :authaction:`changeCustomData` :ref:`actions ` respectively on that user's database. diff --git a/source/includes/admonition-config-db-is-internal.rst b/source/includes/admonition-config-db-is-internal.rst index df0a7d39f0d..fab27c026b4 100644 --- a/source/includes/admonition-config-db-is-internal.rst +++ b/source/includes/admonition-config-db-is-internal.rst @@ -1,5 +1,5 @@ -.. admonition:: Internal MongoDB Metadata +.. tip:: Internal MongoDB Metadata - The :data:`config` database is internal: applications and + The :ref:`config ` database is internal: applications and administrators should not modify or depend upon its content in the course of normal operation. diff --git a/source/includes/admonition-mac-osx-sierra-restriction.rst b/source/includes/admonition-mac-osx-sierra-restriction.rst index d99808cac13..ec51c036d91 100644 --- a/source/includes/admonition-mac-osx-sierra-restriction.rst +++ b/source/includes/admonition-mac-osx-sierra-restriction.rst @@ -1,4 +1,4 @@ -.. admonition:: macOS Sierra and Go 1.6 Incompatibility +.. note:: macOS Sierra and Go 1.6 Incompatibility Users running on macOS Sierra require the 3.2.10 or newer version of |tool-binary|. diff --git a/source/includes/admonition-wsl.rst b/source/includes/admonition-wsl.rst index 61b2371d67b..bebe5e371f5 100644 --- a/source/includes/admonition-wsl.rst +++ b/source/includes/admonition-wsl.rst @@ -1,4 +1,4 @@ -.. admonition:: Windows Subsystem for Linux (WSL) - Unsupported - :class: warning +.. warning:: Windows Subsystem for Linux (WSL) - Unsupported + MongoDB does not support the Windows Subsystem for Linux (WSL). \ No newline at end of file diff --git a/source/includes/changelogs/releases/3.2.14.rst b/source/includes/changelogs/releases/3.2.14.rst index afbbcc30034..8bc222256e4 100644 --- a/source/includes/changelogs/releases/3.2.14.rst +++ b/source/includes/changelogs/releases/3.2.14.rst @@ -47,7 +47,7 @@ Internals - :issue:`SERVER-22582` Wrap assert.soon bodies in try catch in replsettest.js - :issue:`SERVER-22921` Log network interface ASIO response at log level 2 - :issue:`SERVER-23684` async_stream_test - Expected: !(stream.isOpen()) -- :issue:`SERVER-26452` `renameCollection` should handle write conflicts +- :issue:`SERVER-26452` ``renameCollection`` should handle write conflicts - :issue:`SERVER-28109` Configure Mac OS X Builders to use toolchain OpenSSL headers - :issue:`SERVER-28323` Don't pass JavaScript scopes a function ID number - :issue:`SERVER-28466` The hang analyzer should not attach to resmoke.py in Evergreen diff --git a/source/includes/changelogs/releases/3.2.17.rst b/source/includes/changelogs/releases/3.2.17.rst index d5e0f704e24..3fce6604c4e 100644 --- a/source/includes/changelogs/releases/3.2.17.rst +++ b/source/includes/changelogs/releases/3.2.17.rst @@ -14,7 +14,7 @@ Sharding - :issue:`SERVER-29932` add asserts to mapReduce_inSharded_outSharded.js - :issue:`SERVER-30333` Segfault in 3.2 when loading chunks with unknown shard - :issue:`SERVER-30636` RangeDeleter assert failed because of replication lag -- :issue:`SERVER-31111` Add `assert.commandWorked` to migrateBig_balancer.js +- :issue:`SERVER-31111` Add ``assert.commandWorked`` to migrateBig_balancer.js Replication ~~~~~~~~~~~ diff --git a/source/includes/changelogs/releases/3.4.10.rst b/source/includes/changelogs/releases/3.4.10.rst index 361aa565f0f..5a14c3f387d 100644 --- a/source/includes/changelogs/releases/3.4.10.rst +++ b/source/includes/changelogs/releases/3.4.10.rst @@ -16,8 +16,8 @@ Sharding - :issue:`SERVER-30825` blacklist shard_existing_coll_chunk_count.js from the continuous config stepdown suite - :issue:`SERVER-31049` View with collation doesn't work as expected in sharded cluster - :issue:`SERVER-31091` The config server balancer stop command does not obey maxTimeMS -- :issue:`SERVER-31111` Add `assert.commandWorked` to migrateBig_balancer.js -- :issue:`SERVER-31204` Calling `shardCollection` after `enableSharding` may fail if executed against different mongos +- :issue:`SERVER-31111` Add ``assert.commandWorked`` to migrateBig_balancer.js +- :issue:`SERVER-31204` Calling ``shardCollection`` after ``enableSharding`` may fail if executed against different mongos Replication ~~~~~~~~~~~ diff --git a/source/includes/changelogs/releases/3.4.11.rst b/source/includes/changelogs/releases/3.4.11.rst index 32c067bf3d6..c122c69c3bc 100644 --- a/source/includes/changelogs/releases/3.4.11.rst +++ b/source/includes/changelogs/releases/3.4.11.rst @@ -109,7 +109,7 @@ Internals - :issue:`SERVER-31670` Change replica set fixture used by replica_sets_jscore_passthrough to make its secondary have zero votes - :issue:`SERVER-31717` Force C locale on Ubuntu 16.04 builders - :issue:`SERVER-31818` Add server parameter to disable MarkThread{temporary}Idle -- :issue:`SERVER-31827` Make `multi_rs.js` wait for secondary status after stepdown in `upgradePrimary` +- :issue:`SERVER-31827` Make ``multi_rs.js`` wait for secondary status after stepdown in ``upgradePrimary`` - :issue:`SERVER-31957` Remove the timeseries support from etc/system_perf.yml - :issue:`SERVER-31997` Add additional unittesting for CompatibleFirst policy - :issue:`SERVER-32044` Use parameterized branch_name in performance projects diff --git a/source/includes/changelogs/releases/3.4.12.rst b/source/includes/changelogs/releases/3.4.12.rst index 3d3075433b7..4d991262432 100644 --- a/source/includes/changelogs/releases/3.4.12.rst +++ b/source/includes/changelogs/releases/3.4.12.rst @@ -21,7 +21,7 @@ Storage Operations ~~~~~~~~~~ -- :issue:`SERVER-31437` Fix parsing of `mongo host/db` connect string +- :issue:`SERVER-31437` Fix parsing of ``mongo host/db`` connect string - :issue:`SERVER-32875` Don't stall ftdc due to running out of tickets Build and Packaging diff --git a/source/includes/changelogs/releases/3.4.14.rst b/source/includes/changelogs/releases/3.4.14.rst index 02e8b79d056..e034b14c33e 100644 --- a/source/includes/changelogs/releases/3.4.14.rst +++ b/source/includes/changelogs/releases/3.4.14.rst @@ -12,9 +12,9 @@ Sharding ~~~~~~~~ - :issue:`SERVER-29812` RangeDeleter unnecessarily waits for 'majority' write concern -- :issue:`SERVER-31979` Chunk migration statistics are not recorded in the `moveChunk.commit` changelog entries +- :issue:`SERVER-31979` Chunk migration statistics are not recorded in the ``moveChunk.commit`` changelog entries - :issue:`SERVER-32886` Unnecessary sleeps during chunk migration -- :issue:`SERVER-33228` Remove the half-implemented and unused `CollectionRangeDeleter` from the 3.4 codebase +- :issue:`SERVER-33228` Remove the half-implemented and unused ``CollectionRangeDeleter`` from the 3.4 codebase Replication ~~~~~~~~~~~ @@ -42,7 +42,7 @@ Operations ~~~~~~~~~~ - :issue:`SERVER-30114` Monitor cumulative time spent in tcmalloc spin lock -- :issue:`SERVER-33227` Using the method `connect` in a script will as a side effect update global `db`. +- :issue:`SERVER-33227` Using the method ``connect`` in a script will as a side effect update global ``db``. Build and Packaging ~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/changelogs/releases/3.4.16.rst b/source/includes/changelogs/releases/3.4.16.rst index 7bee7ba3230..253c9e043ed 100644 --- a/source/includes/changelogs/releases/3.4.16.rst +++ b/source/includes/changelogs/releases/3.4.16.rst @@ -13,7 +13,7 @@ Sharding - :issue:`SERVER-25746` Store advisoryHostFQDNs data in config.mongos collections - :issue:`SERVER-30050` top_chunk_autosplit.js should use w: majority when updating balancer settings -- :issue:`SERVER-34644` Disable `DollarPrefixedFieldName` checks for moveChunk/mergeChunks +- :issue:`SERVER-34644` Disable ``DollarPrefixedFieldName`` checks for moveChunk/mergeChunks Replication ~~~~~~~~~~~ diff --git a/source/includes/changelogs/releases/3.4.17.rst b/source/includes/changelogs/releases/3.4.17.rst index b5b01f99b66..b8be6c7314d 100644 --- a/source/includes/changelogs/releases/3.4.17.rst +++ b/source/includes/changelogs/releases/3.4.17.rst @@ -15,7 +15,7 @@ Sharding - :issue:`SERVER-27725` Use batch insert when migrating chunks - :issue:`SERVER-29702` add assert.commandWorked() around addShard in shard_insert_getlasterror_w2.js - :issue:`SERVER-33237` Optimize the Range Deleter speed -- :issue:`SERVER-34897` Introduce parameter to control whether MongoS should automatically retry failed `find` commands +- :issue:`SERVER-34897` Introduce parameter to control whether MongoS should automatically retry failed ``find`` commands - :issue:`SERVER-36132` Invariant that chunk migration is actually reflected in the metadata after successful commit - :issue:`SERVER-36232` Refresh after chunk migration commit may not see the committed metadata diff --git a/source/includes/changelogs/releases/3.4.18.rst b/source/includes/changelogs/releases/3.4.18.rst index 692b20a93c9..d406986c192 100644 --- a/source/includes/changelogs/releases/3.4.18.rst +++ b/source/includes/changelogs/releases/3.4.18.rst @@ -59,7 +59,7 @@ Internals - :issue:`SERVER-37127` Update baseline comparison for sys-perf - :issue:`SERVER-37130` Add TLS version counting to mongos - :issue:`SERVER-37367` Notification::waitFor is not interruptible in 3.4 -- :issue:`SERVER-37393` Fix destructor race in `ReplicaSetMonitorManager` +- :issue:`SERVER-37393` Fix destructor race in ```ReplicaSetMonitorManager``` - :issue:`SERVER-37424` Sys-perf: change v4.0 branch batch time to once a week - :issue:`SERVER-37425` Longevity tests -- increase batch time to once a year - :issue:`SERVER-37437` mongo longevity tests failing diff --git a/source/includes/changelogs/releases/3.4.19.rst b/source/includes/changelogs/releases/3.4.19.rst index eb3a6dbfa0a..0263c8c6898 100644 --- a/source/includes/changelogs/releases/3.4.19.rst +++ b/source/includes/changelogs/releases/3.4.19.rst @@ -8,7 +8,7 @@ Sharding - :issue:`SERVER-28716` call fsync after setup before calling collStats/dbStats in jstests/sharding/stats.js - :issue:`SERVER-30768` Primary queries using maxTimeMS cause temporary shard write unavailability if ExceededTimeLimit -- :issue:`SERVER-32568` The `migration_sets_fromMigrate_flag.js` test is not compatible with sharding continuous stepdown suite +- :issue:`SERVER-32568` The ``migration_sets_fromMigrate_flag.js`` test is not compatible with sharding continuous stepdown suite - :issue:`SERVER-37496` The balancer shouldn't register a shutdown task after the process is multithreaded - :issue:`SERVER-37616` Implement tuneable batch size for the rangedeleter - :issue:`SERVER-37902` recovering_slaveok.js should assert all writes it makes succeed diff --git a/source/includes/changelogs/releases/3.4.22.rst b/source/includes/changelogs/releases/3.4.22.rst index 72726ff8110..da5f8424104 100644 --- a/source/includes/changelogs/releases/3.4.22.rst +++ b/source/includes/changelogs/releases/3.4.22.rst @@ -30,7 +30,7 @@ Build and Packaging - :issue:`SERVER-36043` systemd unit for mongod starts before multi.user target - :issue:`SERVER-40242` Update banner inclusions for vendored tools -- :issue:`SERVER-40563` Our init scripts check /proc/[pid]/stat should validate that `(${procname})` is the process' command name. +- :issue:`SERVER-40563` Our init scripts check /proc/[pid]/stat should validate that ``(${procname})`` is the process' command name. - :issue:`SERVER-41424` scons should fail early if invoked with wrong Python interpreter - :issue:`SERVER-41443` Update Enterprise License - :issue:`SERVER-42089` Platform Support: Remove Enterprise RHEL 6.7 zSeries from 3.4 and 3.6 diff --git a/source/includes/changelogs/releases/3.4.4.rst b/source/includes/changelogs/releases/3.4.4.rst index 1fe3c00fd8f..93c6ff8d86f 100644 --- a/source/includes/changelogs/releases/3.4.4.rst +++ b/source/includes/changelogs/releases/3.4.4.rst @@ -6,7 +6,7 @@ Security ~~~~~~~~ -- :issue:`SERVER-27821` Make `large_role_chain.js` not run on DEBUG systems +- :issue:`SERVER-27821` Make ``large_role_chain.js`` not run on DEBUG systems - :issue:`SERVER-28014` When SSL mode is preferSSL, log connections that do not use SSL Sharding @@ -129,7 +129,7 @@ Internals - :issue:`SERVER-28652` Add logging to track egress connection pool size - :issue:`SERVER-28692` Move shell tarball generation to compile task - :issue:`SERVER-28748` Set virtual memory ulimit in package smoke testing for mongo shell tests -- :issue:`SERVER-28823` burn_in_tests.py does not use api server default due to missing `None` check +- :issue:`SERVER-28823` burn_in_tests.py does not use api server default due to missing ``None`` check - :issue:`WT-98` Update the current cursor value without a search - :issue:`WT-2439` Enhance reconciliation page layout - :issue:`WT-2990` checkpoint load live_open assertion failure diff --git a/source/includes/changelogs/releases/3.4.7.rst b/source/includes/changelogs/releases/3.4.7.rst index f45f894ea0f..05ef5e2777c 100644 --- a/source/includes/changelogs/releases/3.4.7.rst +++ b/source/includes/changelogs/releases/3.4.7.rst @@ -54,7 +54,7 @@ Tools Internals ~~~~~~~~~ -- :issue:`SERVER-26452` `renameCollection` should handle write conflicts +- :issue:`SERVER-26452` ``renameCollection`` should handle write conflicts - :issue:`SERVER-28046` Increase timeouts in replsets/read_committed_on_secondary.js to 10 minutes - :issue:`SERVER-28596` Upload hanging or failing tests in compile_all to S3 - :issue:`SERVER-28991` Eliminate having individual threads in resmoke.py for flushing log output to logkeeper @@ -68,7 +68,7 @@ Internals - :issue:`SERVER-30415` Exclude new "evergreen" agent binary name from automatic process killing in Evergren - :issue:`SERVER-30433` Increase Watchdog Test timeouts - :issue:`TOOLS-1542` dump and export shouldn't count views before running -- :issue:`TOOLS-1563` windows tests are failing after `use mongodb 3.4 "current" tests` +- :issue:`TOOLS-1563` windows tests are failing after ``use mongodb 3.4 "current" tests`` - :issue:`TOOLS-1577` update the readme with information about mongoreplay - :issue:`TOOLS-1713` Move mongoreplay evergreen config .evergreen.yml into common.yml - :issue:`TOOLS-1743` legacy24 and legacy26 dumprestore tests failing on master diff --git a/source/includes/changelogs/releases/3.6.1.rst b/source/includes/changelogs/releases/3.6.1.rst index d05e213be7b..b16a1263a13 100644 --- a/source/includes/changelogs/releases/3.6.1.rst +++ b/source/includes/changelogs/releases/3.6.1.rst @@ -94,7 +94,7 @@ Internals - :issue:`SERVER-32087` Run test stage of sys-perf and mongo-perf failures should lead to red evergreen boxes - :issue:`SERVER-32105` Require shard servers and config servers to be started with --replSet or 'replSetName' - :issue:`SERVER-32106` Migration of txn oplog entries can trigger fassert in secondary replication -- :issue:`SERVER-32164` Shell SRV implementation does not allow `authSource` from TXT records to be used +- :issue:`SERVER-32164` Shell SRV implementation does not allow ``authSource`` from TXT records to be used - :issue:`SERVER-32238` Revert erroneous high error codes - :issue:`TOOLS-1688` Evergreen tests broken in master - :issue:`TOOLS-1827` Implement Initial DNS Seedlist discovery spec diff --git a/source/includes/changelogs/releases/3.6.10.rst b/source/includes/changelogs/releases/3.6.10.rst index df9adc53a83..3de8257e702 100644 --- a/source/includes/changelogs/releases/3.6.10.rst +++ b/source/includes/changelogs/releases/3.6.10.rst @@ -12,7 +12,7 @@ Security Sharding ~~~~~~~~ -- :issue:`SERVER-36965` Ensure setUp writes in `safe_secondary_reads_single_migration_suspend_range_deletion.js` get propagated to the shard secondary +- :issue:`SERVER-36965` Ensure setUp writes in ``safe_secondary_reads_single_migration_suspend_range_deletion.js`` get propagated to the shard secondary - :issue:`SERVER-37051` ShardServerCatalogCacheLoader does not check the internal term after reading from the task queue - :issue:`SERVER-37080` Implement tuneable batch size for chunk migrations - :issue:`SERVER-37511` Logical session reaper and refresh threads should set up sessions collection immediately diff --git a/source/includes/changelogs/releases/3.6.11.rst b/source/includes/changelogs/releases/3.6.11.rst index 71ad180e6d8..994be667cfe 100644 --- a/source/includes/changelogs/releases/3.6.11.rst +++ b/source/includes/changelogs/releases/3.6.11.rst @@ -11,7 +11,7 @@ Security Sharding ~~~~~~~~ -- :issue:`SERVER-9043` Link `flushRouterConfig` on the config server and shards +- :issue:`SERVER-9043` Link ``flushRouterConfig`` on the config server and shards - :issue:`SERVER-31156` Admin command to update the chunk metadata for only one collection - :issue:`SERVER-36863` query_config.js assumes that config.mongos is always present - :issue:`SERVER-36901` sh.status() "Last reported error:" is actually 5th Latest error message @@ -57,7 +57,7 @@ Storage - :issue:`SERVER-35732` Hyphenated database names do not work with dbStats.fsUsedSize / TotalSize - :issue:`SERVER-38779` Build a mechanism to periodically cleanup old WT sessions from session cache -- :issue:`SERVER-38801` Cope with large BSON blobs in queryable's `listDirectory` call. +- :issue:`SERVER-38801` Cope with large BSON blobs in queryable's ``listDirectory`` call. Operations ~~~~~~~~~~ diff --git a/source/includes/changelogs/releases/3.6.14.rst b/source/includes/changelogs/releases/3.6.14.rst index a4926e80f7b..0f5f94016a9 100644 --- a/source/includes/changelogs/releases/3.6.14.rst +++ b/source/includes/changelogs/releases/3.6.14.rst @@ -55,7 +55,7 @@ Build and Packaging ~~~~~~~~~~~~~~~~~~~ - :issue:`SERVER-36043` systemd unit for mongod starts before multi.user target -- :issue:`SERVER-40563` Our init scripts check /proc/[pid]/stat should validate that `(${procname})` is the process' command name. +- :issue:`SERVER-40563` Our init scripts check /proc/[pid]/stat should validate that ``(${procname})`` is the process' command name. - :issue:`SERVER-41424` scons should fail early if invoked with wrong Python interpreter - :issue:`SERVER-41443` Update Enterprise License - :issue:`SERVER-41743` Update MSI inclusions for 3.6 @@ -73,7 +73,7 @@ Internals - :issue:`SERVER-38141` Incorrect usage of MONGO_CONFIG_HAS_SSL_SET_ECDH_AUTO prevents enabling of elliptic curve auto negotiation - :issue:`SERVER-39642` Decrement egress counter when scoped connection not returned to the pool - :issue:`SERVER-40156` Initial implementation of Split Horizon -- :issue:`SERVER-40643` Add tests for `replSetConfig` and `replSetInitiate` with Split Horizon +- :issue:`SERVER-40643` Add tests for ``replSetConfig`` and ``replSetInitiate`` with Split Horizon - :issue:`SERVER-40645` Add tests for SNI/TLS behavior of Split Horizon - :issue:`SERVER-40923` Remove npm test command from "run jstestfuzz" Evergreen function - :issue:`SERVER-40924` Add Evergreen task to sanity check fuzzer can parse JavaScript tests diff --git a/source/includes/changelogs/releases/3.6.3.rst b/source/includes/changelogs/releases/3.6.3.rst index e20925b8038..37c5a8210bd 100644 --- a/source/includes/changelogs/releases/3.6.3.rst +++ b/source/includes/changelogs/releases/3.6.3.rst @@ -20,11 +20,11 @@ Sharding - :issue:`SERVER-30152` add safe secondary reads targeted tests for mapReduce - :issue:`SERVER-30671` Don't expect operationTime to not change in causal_consistency_shell_support.js - :issue:`SERVER-31860` setFCV on a cluster can fail to call setFCV on shards if the config server primary's ShardRegistry is empty -- :issue:`SERVER-31979` Chunk migration statistics are not recorded in the `moveChunk.commit` changelog entries +- :issue:`SERVER-31979` Chunk migration statistics are not recorded in the ``moveChunk.commit`` changelog entries - :issue:`SERVER-32235` Blacklist core/drop3.js test from causally consistent workloadss - :issue:`SERVER-32368` do not perform UUID check against a shard's config cache in the sharding_csrs_continuous_config_stepdown_WT suite - :issue:`SERVER-32554` Source shard stepdown while entering critical section can trigger cloner invariant -- :issue:`SERVER-32568` The `migration_sets_fromMigrate_flag.js` test is not compatible with sharding continuous stepdown suite +- :issue:`SERVER-32568` The ``migration_sets_fromMigrate_flag.js`` test is not compatible with sharding continuous stepdown suite - :issue:`SERVER-32569` Introduce uniform way to allow config servers and shard replica sets to start in non-cluster mode - :issue:`SERVER-32592` Stepdown during migration cleanup can crash the source shard primary - :issue:`SERVER-32593` CSRS stepdown during migration commit can trigger fassert on source shard primary @@ -135,7 +135,7 @@ Internals - :issue:`SERVER-32376` Blacklist tests that manually call startSession in the retryable_writes_jscore_stepdown_passthrough suite - :issue:`SERVER-32403` Increase remote EC2 expire time to 3 hours - :issue:`SERVER-32410` Validate User::CredentialData before attempting to perform authentication -- :issue:`SERVER-32414` Remove stale `stdx::` requirements from lint. +- :issue:`SERVER-32414` Remove stale ``stdx::`` requirements from lint. - :issue:`SERVER-32429` black list regex_targeting.js from step down suites - :issue:`SERVER-32468` Use a 1-node CSRS in non-stepdown sharding passthroughs tests - :issue:`SERVER-32475` Microbenchmarks on v3.6 use master version of enterprise module diff --git a/source/includes/changelogs/releases/3.6.4.rst b/source/includes/changelogs/releases/3.6.4.rst index 24c057c7f31..20fc374eb50 100644 --- a/source/includes/changelogs/releases/3.6.4.rst +++ b/source/includes/changelogs/releases/3.6.4.rst @@ -60,7 +60,7 @@ Operations - :issue:`SERVER-30114` Monitor cumulative time spent in tcmalloc spin lock - :issue:`SERVER-30567` Break out serviceExecutorTaskStats by task type - :issue:`SERVER-32498` "desc" field in currentOp output no longer contains the thread name used in log messages -- :issue:`SERVER-33227` Using the method `connect` in a script will as a side effect update global `db`. +- :issue:`SERVER-33227` Using the method ``connect`` in a script will as a side effect update global ``db``. Build and Packaging ~~~~~~~~~~~~~~~~~~~ diff --git a/source/includes/changelogs/releases/3.6.5.rst b/source/includes/changelogs/releases/3.6.5.rst index 8210a4959b5..bc70b37e927 100644 --- a/source/includes/changelogs/releases/3.6.5.rst +++ b/source/includes/changelogs/releases/3.6.5.rst @@ -21,8 +21,8 @@ Sharding - :issue:`SERVER-34508` Prevent race condition in Migration Destination Manager from swallowing an exception - :issue:`SERVER-34571` Invariant fails in destructor of MigrationChunkClonerSourceLegacy on shutdown - :issue:`SERVER-34586` Possible double mutex acquisition in ShardServerCatalogCacheLoader -- :issue:`SERVER-34644` Disable `DollarPrefixedFieldName` checks for moveChunk/mergeChunks -- :issue:`SERVER-34683` Downgrade replicaset from 3.6.4 to 3.4.14 fails due to the presence of `config.system.sessions` +- :issue:`SERVER-34644` Disable ``DollarPrefixedFieldName`` checks for moveChunk/mergeChunks +- :issue:`SERVER-34683` Downgrade replicaset from 3.6.4 to 3.4.14 fails due to the presence of ``config.system.sessions`` - :issue:`SERVER-34746` Segmentation fault when shard is started with --shardsvr before being added to a shard Replication @@ -59,7 +59,7 @@ Aggregation Storage ~~~~~~~ -- :issue:`SERVER-32989` `repairDatabase` can race with `dropDatabase`. +- :issue:`SERVER-32989` ``repairDatabase`` can race with ``dropDatabase``. - :issue:`SERVER-33743` Use all_committed to set lastApplied on primary nodes - :issue:`SERVER-34091` Oplog visibility rules can cause cappedTruncateAfter to erroneously skip record deletion in WiredTiger - :issue:`SERVER-34423` collMod interruption may cause invariant failure diff --git a/source/includes/changelogs/releases/3.6.6.rst b/source/includes/changelogs/releases/3.6.6.rst index 635aeb7d52f..aed6ac6c8d5 100644 --- a/source/includes/changelogs/releases/3.6.6.rst +++ b/source/includes/changelogs/releases/3.6.6.rst @@ -13,14 +13,14 @@ Sharding ~~~~~~~~ - :issue:`SERVER-25746` Store advisoryHostFQDNs data in config.mongos collections -- :issue:`SERVER-33081` Reset `KeysCollectionManager` during rollback properly +- :issue:`SERVER-33081` Reset ``KeysCollectionManager`` during rollback properly - :issue:`SERVER-33327` Session::onMigrateCompletedOnPrimary should not update the lastWriteDate field - :issue:`SERVER-33538` mapReduce "replace" on a sharded output collection can lead to UUIDCatalog inconsistencies -- :issue:`SERVER-33639` Concurrent writes against non-existent database can fail due to distlock acquisition timeout at `createDatabase` time +- :issue:`SERVER-33639` Concurrent writes against non-existent database can fail due to distlock acquisition timeout at ``createDatabase`` time - :issue:`SERVER-34363` addShard shard registry reload can cause mongos to terminate -- :issue:`SERVER-34773` The `TransactionReaper` handler classes are not exception-safe +- :issue:`SERVER-34773` The ``TransactionReaper`` handler classes are not exception-safe - :issue:`SERVER-34833` Deadlock between the logical sessions' transaction reaper and MMAP V1 durability thread -- :issue:`SERVER-34857` `sharding_legacy_api_test` is flaky due to reliance on the system clock +- :issue:`SERVER-34857` ``sharding_legacy_api_test`` is flaky due to reliance on the system clock - :issue:`SERVER-35006` Do not reset KeysCollectionManager - :issue:`SERVER-35345` Test that restarted mongoses are able to connect after FCV update - :issue:`SERVER-35609` Create initial chunk on primaryShard if only writing one chunk @@ -47,7 +47,7 @@ Replication - :issue:`SERVER-34758` replSetGetStatus can deadlock with initialSyncer - :issue:`SERVER-34900` initial sync uses different batch limits from steady state replication - :issue:`SERVER-35087` "./jstests/replsets/read_concern_uninitated_set.js" and test should be disabled in evergreen for storage engines - ephemeralForTest & mmapv1. -- :issue:`SERVER-35124` Stepdown suites with MMAP V1 often fail due to `flushing mmaps` taking long time +- :issue:`SERVER-35124` Stepdown suites with MMAP V1 often fail due to ``flushing mmaps`` taking long time - :issue:`SERVER-35249` Invariant that we apply to top of oplog on 3.6 replication recovery - :issue:`SERVER-35256` Do not treat it as an error if the first batch returned by an oplog query comes back empty in master-slave - :issue:`SERVER-35340` Reduce number of iterations in update_and_bulk_insert.js FSM workload @@ -172,7 +172,7 @@ Internals - :issue:`SERVER-35588` powertest.py should call replSetReconfigure command only after successful replSetGetConfig - :issue:`SERVER-35610` Refine LDAP options parsing - :issue:`SERVER-35706` Fix race in ctor for LogicalSessionCacheImpl -- :issue:`SERVER-35834` Fix compile errors in `dns_name_test` on Microsoft compilers +- :issue:`SERVER-35834` Fix compile errors in ``dns_name_test`` on Microsoft compilers - :issue:`SERVER-35917` Blacklists tests which use resumeAfter from the sharded collections change streams passthrough - :issue:`WT-3698` Threads doing eviction can stall indefinitely when timestamps fail to advance - :issue:`WT-3892` Add timing_stress_for_test option for lookaside cleanup diff --git a/source/includes/changelogs/releases/3.6.7.rst b/source/includes/changelogs/releases/3.6.7.rst index 1cd61f23c90..1a5d81e2a24 100644 --- a/source/includes/changelogs/releases/3.6.7.rst +++ b/source/includes/changelogs/releases/3.6.7.rst @@ -17,7 +17,7 @@ Sharding - :issue:`SERVER-33237` Optimize the Range Deleter speed - :issue:`SERVER-33697` Provide sanity check on number of cached sessions - :issue:`SERVER-34843` Mongod can return operationTime greater than $clusterTime -- :issue:`SERVER-34897` Introduce parameter to control whether MongoS should automatically retry failed `find` commands +- :issue:`SERVER-34897` Introduce parameter to control whether MongoS should automatically retry failed ``find`` commands - :issue:`SERVER-35377` Operations on new clients get latest in-memory clusterTime as operationTime - :issue:`SERVER-35658` session migration is too sensitive to replica set primary elections - :issue:`SERVER-36041` Increase the size of changelog and actionlog diff --git a/source/includes/changelogs/releases/3.6.9.rst b/source/includes/changelogs/releases/3.6.9.rst index 55959bbc63b..63d25a86223 100644 --- a/source/includes/changelogs/releases/3.6.9.rst +++ b/source/includes/changelogs/releases/3.6.9.rst @@ -14,7 +14,7 @@ Sharding - :issue:`SERVER-29160` Sharding commonly uses write concern timeouts of 15 seconds and these are timing out in migration related operations and causing BFs - :issue:`SERVER-31563` Reevaluate not_allowed_on_sharded_collection_cmd.js testing -- :issue:`SERVER-31892` moveChunk with `waitForDelete` doesn't wait for majority write concern +- :issue:`SERVER-31892` moveChunk with ``waitForDelete`` doesn't wait for majority write concern - :issue:`SERVER-35222` Crash on the config server at expired session cleanup - :issue:`SERVER-35238` Drop the collection after removing the partially written chunks for mapReduce in mongos_manual_intervention_actions.js - :issue:`SERVER-35763` lastWriteDate field can get out of sync between repl set nodes during migration @@ -139,7 +139,7 @@ Internals - :issue:`SERVER-37130` Add TLS version counting to mongos - :issue:`SERVER-37149` Remove deadlock in ScheduleBeforeStartupTest - :issue:`SERVER-37353` Handle $slice value of LLONG_MIN gracefully -- :issue:`SERVER-37393` Fix destructor race in `ReplicaSetMonitorManager` +- :issue:`SERVER-37393` Fix destructor race in ``ReplicaSetMonitorManager`` - :issue:`SERVER-37410` Add standalone passthrough suites to detect errors in LogicalSessionCache - :issue:`SERVER-37424` Sys-perf: change v4.0 branch batch time to once a week - :issue:`SERVER-37425` Longevity tests -- increase batch time to once a year diff --git a/source/includes/changelogs/releases/4.0.1.rst b/source/includes/changelogs/releases/4.0.1.rst index edcd046c78d..90fa8492c11 100644 --- a/source/includes/changelogs/releases/4.0.1.rst +++ b/source/includes/changelogs/releases/4.0.1.rst @@ -14,7 +14,7 @@ Sharding - :issue:`SERVER-33237` Optimize the Range Deleter speed - :issue:`SERVER-33697` Provide sanity check on number of cached sessions -- :issue:`SERVER-34897` Introduce parameter to control whether MongoS should automatically retry failed `find` commands +- :issue:`SERVER-34897` Introduce parameter to control whether MongoS should automatically retry failed ``find`` commands - :issue:`SERVER-35609` Create initial chunk on primaryShard if only writing one chunk - :issue:`SERVER-35632` Blacklist lagged_config_secondary.js and all_config_servers_blackholed_from_mongos.js from RHEL 6.7 s390x variants - :issue:`SERVER-35691` Make all code paths returning StaleConfig error go through the StaleConfigInfo serializer @@ -33,7 +33,7 @@ Replication - :issue:`SERVER-32088` ChangeStream resumeAfter does not work on sharded collections if not all shards have chunks for the collection - :issue:`SERVER-34414` Creating a role with buildsIndexes:false node hits an fassert - :issue:`SERVER-34758` replSetGetStatus can deadlock with initialSyncer -- :issue:`SERVER-35124` Stepdown suites with MMAP V1 often fail due to `flushing mmaps` taking long time +- :issue:`SERVER-35124` Stepdown suites with MMAP V1 often fail due to ``flushing mmaps`` taking long time - :issue:`SERVER-35200` Speed up failure detection in the OplogFetcher during steady state replication - :issue:`SERVER-35388` Improve misleading error messages for aggregation stages banned in transactions - :issue:`SERVER-35488` ReplSetTest.waitForState() should ensure node has finished closing connections @@ -85,9 +85,9 @@ Storage - :issue:`SERVER-35789` check for index catalog isready mismatch for multi-doc txns - :issue:`SERVER-35859` Disable rocksdb buildvariant - :issue:`SERVER-35994` Reduce CPU load in secondary_reads_unique_indexes.js test -- :issue:`SERVER-36006` `multiInitialSyncApply` should consider setting a read timestamp of `kNoTimestamp` +- :issue:`SERVER-36006` ``multiInitialSyncApply`` should consider setting a read timestamp of ``kNoTimestamp`` - :issue:`SERVER-36025` RestartCatalogCommand can attempt to reinitialize oplog pointers on standalones -- :issue:`SERVER-36167` Add pretty printer for WT `flags` members +- :issue:`SERVER-36167` Add pretty printer for WT ``flags`` members GridFS ~~~~~~ @@ -153,7 +153,7 @@ Internals - :issue:`SERVER-35702` Stop running the agg and update fuzzer on macOS - :issue:`SERVER-35724` Remote EC2 hosts which are not accessible via ssh should fail with system error - :issue:`SERVER-35727` make the embedded sdk compile task in to a multi-task task group. -- :issue:`SERVER-35834` Fix compile errors in `dns_name_test` on Microsoft compilers +- :issue:`SERVER-35834` Fix compile errors in ``dns_name_test`` on Microsoft compilers - :issue:`SERVER-35850` Update filename suffix to v4.0-latest for nightly builds - :issue:`SERVER-35858` Error in call BF Suggestion service - :issue:`SERVER-35908` Shutdown service entry point in mongoed before shutting down embedded diff --git a/source/includes/changelogs/releases/4.0.11.rst b/source/includes/changelogs/releases/4.0.11.rst index 10c1c5ae6d2..abf831eecf7 100644 --- a/source/includes/changelogs/releases/4.0.11.rst +++ b/source/includes/changelogs/releases/4.0.11.rst @@ -86,7 +86,7 @@ Build and Packaging - :issue:`SERVER-36043` systemd unit for mongod starts before multi.user target - :issue:`SERVER-39465` Update master android builds to r19 NDK - :issue:`SERVER-40133` Create Markdown description of vendored third party libraries -- :issue:`SERVER-40563` Our init scripts check /proc/[pid]/stat should validate that `(${procname})` is the process' command name. +- :issue:`SERVER-40563` Our init scripts check /proc/[pid]/stat should validate that ``(${procname})`` is the process' command name. - :issue:`SERVER-41039` Android and java multiarch builders cannot import yaml during config expansion - :issue:`SERVER-41302` Lift restriction on publishing embedded SDKs from the 4.2 branch - :issue:`SERVER-41424` scons should fail early if invoked with wrong Python interpreter @@ -106,7 +106,7 @@ Internals - :issue:`SERVER-40052` Shutdown in mongos can trigger BatchWriteOp invariant - :issue:`SERVER-40156` Initial implementation of Split Horizon - :issue:`SERVER-40295` Add details to stage_builder.cpp invariant message -- :issue:`SERVER-40643` Add tests for `replSetConfig` and `replSetInitiate` with Split Horizon +- :issue:`SERVER-40643` Add tests for ``replSetConfig`` and ``replSetInitiate`` with Split Horizon - :issue:`SERVER-40645` Add tests for SNI/TLS behavior of Split Horizon - :issue:`SERVER-40738` Don't try to upload evergreen tarball when doing Android mobile builds - :issue:`SERVER-40923` Remove npm test command from "run jstestfuzz" Evergreen function diff --git a/source/includes/changelogs/releases/4.0.2.rst b/source/includes/changelogs/releases/4.0.2.rst index 6aac5cb74f0..ee9fb2712a8 100644 --- a/source/includes/changelogs/releases/4.0.2.rst +++ b/source/includes/changelogs/releases/4.0.2.rst @@ -19,7 +19,7 @@ Sharding - :issue:`SERVER-35722` Create internal _shardsvrShardCollection command that runs on the primary shard - :issue:`SERVER-35723` Make the collection critical section into a RAII class - :issue:`SERVER-35794` Read zone information for a collection during internal shardCollection command -- :issue:`SERVER-35849` Remove dependency of the write commands on `sharding_runtime_d` +- :issue:`SERVER-35849` Remove dependency of the write commands on ``sharding_runtime_d`` - :issue:`SERVER-36031` Move logic to create initial chunks and update metadata during shard collection to the primary shard - :issue:`SERVER-36071` Check shardsvrShardCollection response status - :issue:`SERVER-36092` Create internal command to create collection on new shard with existing uuid @@ -112,7 +112,7 @@ Storage - :issue:`SERVER-35386` Wait for the secondary's majority commit point to advance before pausing batch application in secondary_reads_timestamp_visibility.js - :issue:`SERVER-35473` Mobile SE: Fix writeConflictRetry loop with map-reduce jstests - :issue:`SERVER-35845` Add tag to noPassthrough/indexbg2.js -- :issue:`SERVER-36005` `IndexCatalogEntryImpl::_catalogIsReady` is unsafe to unconditionally call. +- :issue:`SERVER-36005` ``IndexCatalogEntryImpl::_catalogIsReady`` is unsafe to unconditionally call. - :issue:`SERVER-36062` Mobile SE: Stop running parallel and concurrent suites on mobile variants - :issue:`SERVER-36238` replica set startup fails in wt_cache_full.js, initial_sync_wt_cache_full.js, recovery_wt_cache_full.js when journaling is disabled - :issue:`SERVER-36397` Embedded Server SDK Should Return Error When TTL Index Creation is Attempted diff --git a/source/includes/changelogs/releases/4.0.3.rst b/source/includes/changelogs/releases/4.0.3.rst index bc04596ee8d..9b77da58218 100644 --- a/source/includes/changelogs/releases/4.0.3.rst +++ b/source/includes/changelogs/releases/4.0.3.rst @@ -71,7 +71,7 @@ Storage - :issue:`SERVER-34577` read_after_optime.js fails on mongoe - :issue:`SERVER-34606` Test (and possibly fix) behavior around majority commit point and oplog truncation - :issue:`SERVER-35657` Do not delay journal flushes when operations are waiting for oplog visibility -- :issue:`SERVER-35780` `renameCollection` across databases incorrectly timestamps metadata for secondary index builds +- :issue:`SERVER-35780` ``renameCollection`` across databases incorrectly timestamps metadata for secondary index builds - :issue:`SERVER-36400` Explicitly destroy the client on exiting the run body of each BackgroundJob - :issue:`SERVER-36531` Lock acquisition may throw despite presence of UninterruptibleLockGuard when WT tickets are exhausted - :issue:`SERVER-36879` write regression test for stuck cache issue during rollback @@ -133,7 +133,7 @@ Internals - :issue:`SERVER-35696` Provide a way to restore idents known by WiredTiger, but unknown to the _mdb_catalog - :issue:`SERVER-35731` Prevent a repaired node from re-joining a replica set - :issue:`SERVER-35782` Repair should move aside unsalvageable data files and create empty ones in their place -- :issue:`SERVER-35784` Fix ambiguously named test fixture in `commands_test.cpp` +- :issue:`SERVER-35784` Fix ambiguously named test fixture in ``commands_test.cpp`` - :issue:`SERVER-35800` resmoke.py should retry getting a build_id and test_id from logkeeper - :issue:`SERVER-35985` sessions_test and sharding_catalog_manager_test don't destroy all Clients before destroying the ServiceContext - :issue:`SERVER-36019` Create script to collect resource utilization of Android application @@ -165,7 +165,7 @@ Internals - :issue:`SERVER-36836` v4.0 fsm workload "yield_group.js" should accept "InternalError" as a possible outcome of the group command - :issue:`SERVER-36842` Core dump not generated after invariant failure in powercycle hosts - :issue:`SERVER-36869` fsm capped collection checks should only make 1 query for assertions -- :issue:`SERVER-36897` OplogReader.hasNext can return false -> true, confusing `checkOplogs` +- :issue:`SERVER-36897` OplogReader.hasNext can return false -> true, confusing ``checkOplogs`` - :issue:`SERVER-36906` Connection state now allowed to be kConnectionStateUnknown - :issue:`SERVER-36919` Add server setParameter tlsWithholdClientCertificate (bool) - :issue:`SERVER-36942` Differentiate invalid hostname from invalid certificate diff --git a/source/includes/changelogs/releases/4.0.4.rst b/source/includes/changelogs/releases/4.0.4.rst index 8fe027cabe5..41ad84a7e14 100644 --- a/source/includes/changelogs/releases/4.0.4.rst +++ b/source/includes/changelogs/releases/4.0.4.rst @@ -13,7 +13,7 @@ Sharding - :issue:`SERVER-29160` Sharding commonly uses write concern timeouts of 15 seconds and these are timing out in migration related operations and causing BFs - :issue:`SERVER-31563` Reevaluate not_allowed_on_sharded_collection_cmd.js testing -- :issue:`SERVER-31892` moveChunk with `waitForDelete` doesn't wait for majority write concern +- :issue:`SERVER-31892` moveChunk with ``waitForDelete`` doesn't wait for majority write concern - :issue:`SERVER-35323` sessionId matching ignores userId part of the lsid - :issue:`SERVER-35763` lastWriteDate field can get out of sync between repl set nodes during migration - :issue:`SERVER-36831` LogicalSessionCache on mongos does not correctly report active operations @@ -112,7 +112,7 @@ Internals - :issue:`SERVER-37334` Strip .jar and .aar of unnecessary shared objects - :issue:`SERVER-37353` Handle $slice value of LLONG_MIN gracefully - :issue:`SERVER-37391` plan_cache_index_create.js should wait for index build start, rather than just createIndexes command start -- :issue:`SERVER-37393` Fix destructor race in `ReplicaSetMonitorManager` +- :issue:`SERVER-37393` Fix destructor race in ``ReplicaSetMonitorManager`` - :issue:`SERVER-37410` Add standalone passthrough suites to detect errors in LogicalSessionCache - :issue:`SERVER-37411` Fix bundle identifiers in embedded Info.plist - :issue:`SERVER-37424` Sys-perf: change v4.0 branch batch time to once a week @@ -123,7 +123,7 @@ Internals - :issue:`SERVER-37495` Change Android minimum API level to 21 - :issue:`SERVER-37513` Pass along JNA exceptions from MongoEmbeddedCAPI.create - :issue:`SERVER-37561` Server startupWarnings show spurious empty lines -- :issue:`SERVER-37563` Get rid of `getGlobalAuthorizationManager` and unnecessary references to the `authorization_manager_global` library +- :issue:`SERVER-37563` Get rid of ``getGlobalAuthorizationManager`` and unnecessary references to the ``authorization_manager_global`` library - :issue:`SERVER-37583` Changes to etc/cloud_nightly.yml - :issue:`SERVER-37599` Log exit code of shell-spawned processes - :issue:`SERVER-37683` Change embedded iOS min version to 11.0 in CocoaPod podspec diff --git a/source/includes/changelogs/releases/4.0.5.rst b/source/includes/changelogs/releases/4.0.5.rst index 0cbcf735c8e..1a7f0834693 100644 --- a/source/includes/changelogs/releases/4.0.5.rst +++ b/source/includes/changelogs/releases/4.0.5.rst @@ -14,7 +14,7 @@ Sharding - :issue:`SERVER-30714` Handle step down error in ReplicationCoordinatorExternalStateImpl::_shardingOnTransitionToPrimaryHook - :issue:`SERVER-36349` Handle the ShardingOperationFailedStatus in the OperationShardingState destructor when the OperationContext is not created in a ServiceEntryPoint -- :issue:`SERVER-36965` Ensure setUp writes in `safe_secondary_reads_single_migration_suspend_range_deletion.js` get propagated to the shard secondary +- :issue:`SERVER-36965` Ensure setUp writes in ``safe_secondary_reads_single_migration_suspend_range_deletion.js`` get propagated to the shard secondary - :issue:`SERVER-36966` Sharded map reduce may fail to clean up temporary output collection - :issue:`SERVER-37051` ShardServerCatalogCacheLoader does not check the internal term after reading from the task queue - :issue:`SERVER-37080` Implement tuneable batch size for chunk migrations diff --git a/source/includes/changelogs/releases/4.0.6.rst b/source/includes/changelogs/releases/4.0.6.rst index 6b39df806e7..e5af4d6049f 100644 --- a/source/includes/changelogs/releases/4.0.6.rst +++ b/source/includes/changelogs/releases/4.0.6.rst @@ -12,7 +12,7 @@ Security Sharding ~~~~~~~~ -- :issue:`SERVER-9043` Link `flushRouterConfig` on the config server and shards +- :issue:`SERVER-9043` Link ``flushRouterConfig`` on the config server and shards - :issue:`SERVER-31156` Admin command to update the chunk metadata for only one collection - :issue:`SERVER-36863` query_config.js assumes that config.mongos is always present - :issue:`SERVER-38050` The range deleter doesn't validate it is still operating on the same collection after the deletion loop diff --git a/source/includes/changelogs/releases/4.0.7.rst b/source/includes/changelogs/releases/4.0.7.rst index f41d0f37025..25bdadb1e4c 100644 --- a/source/includes/changelogs/releases/4.0.7.rst +++ b/source/includes/changelogs/releases/4.0.7.rst @@ -14,14 +14,14 @@ Sharding ~~~~~~~~ - :issue:`SERVER-36901` sh.status() "Last reported error:" is actually 5th Latest error message -- :issue:`SERVER-36958` Parts of the `_configsvrShardCollection` command do not retry on network errors -- :issue:`SERVER-37591` MigrationSourceManager is not exception safe before `startClone` completes +- :issue:`SERVER-36958` Parts of the ``_configsvrShardCollection`` command do not retry on network errors +- :issue:`SERVER-37591` MigrationSourceManager is not exception safe before ``startClone`` completes - :issue:`SERVER-38192` Ignore duplicate key error from refreshLogicalSessionCacheNow - :issue:`SERVER-38205` Optimize splitVector for the jumbo-chunk case - :issue:`SERVER-38387` agg_out.js concurrency workload always fails to shard the output collection - :issue:`SERVER-39203` failcommand_ignores_internal.js fails against mongod 3.6 - :issue:`SERVER-39847` Migrating session info can trigger fassert when destination shard has transaction history truncated by oplog -- :issue:`SERVER-40010` Shard secondaries with 4.0 binary and 3.6 FCV are calling `_flushDatabaseCacheUpdates` +- :issue:`SERVER-40010` Shard secondaries with 4.0 binary and 3.6 FCV are calling ``_flushDatabaseCacheUpdates`` Replication ~~~~~~~~~~~ @@ -84,7 +84,7 @@ Storage - :issue:`SERVER-35732` Hyphenated database names do not work with dbStats.fsUsedSize / TotalSize - :issue:`SERVER-38555` cappedTruncateAfter must not set oldest timestamp during startup recovery when enableMajorityReadConcern=false - :issue:`SERVER-38745` MigrationDestinationManager assigns incorrect timestamps while building multiple indexes -- :issue:`SERVER-38801` Cope with large BSON blobs in queryable's `listDirectory` call. +- :issue:`SERVER-38801` Cope with large BSON blobs in queryable's ``listDirectory`` call. - :issue:`SERVER-38833` A failure to timestamp a storage transaction requires restarting the transaction - :issue:`SERVER-39106` GlobalLock acquisition should throw when ticket acquisition times out if there is a max lock timeout and no deadline - :issue:`SERVER-39259` Mobile SE: Adjust SQLite Pragmas for Improved Performance diff --git a/source/includes/changelogs/releases/4.2.2.rst b/source/includes/changelogs/releases/4.2.2.rst index 3b5f9e1a1f4..eea331073ea 100644 --- a/source/includes/changelogs/releases/4.2.2.rst +++ b/source/includes/changelogs/releases/4.2.2.rst @@ -82,7 +82,7 @@ Storage Operations ~~~~~~~~~~ -- :issue:`SERVER-42886` Fix `bypassAutoDecrypt` settings in shell +- :issue:`SERVER-42886` Fix ``bypassAutoDecrypt`` settings in shell - :issue:`SERVER-43265` Mongo Shell exits with InvalidOptions error when using URI compressors parameter - :issue:`SERVER-43884` Improve Error Formatting for mongocryptd-origin errors diff --git a/source/includes/changelogs/releases/4.2.3.rst b/source/includes/changelogs/releases/4.2.3.rst index f7f1f09934b..9067ba30408 100644 --- a/source/includes/changelogs/releases/4.2.3.rst +++ b/source/includes/changelogs/releases/4.2.3.rst @@ -106,7 +106,7 @@ Internals - :issue:`SERVER-42697` Expose tcmalloc_release_rate via setParameter - :issue:`SERVER-43210` jstests/sharding/kill_sessions.js doesn't wait for operation to be killed. - :issue:`SERVER-43246` Add a log line for when a cursor is reaped due to logical session cleanup -- :issue:`SERVER-43310` mongos tries to connect to the secondary to create the index if `rs.slaveOk()` is set. +- :issue:`SERVER-43310` mongos tries to connect to the secondary to create the index if ``rs.slaveOk()`` is set. - :issue:`SERVER-43324` Add BasicLockableAdaptor for cleaner function APIs - :issue:`SERVER-43349` Incorrect serialization for $elemMatch $not $ne - :issue:`SERVER-43623` Stop catching exceptions in NetworkInterfaceASIO diff --git a/source/includes/changelogs/releases/4.4.2.rst b/source/includes/changelogs/releases/4.4.2.rst index ad926846c36..ee01124fc15 100644 --- a/source/includes/changelogs/releases/4.4.2.rst +++ b/source/includes/changelogs/releases/4.4.2.rst @@ -139,7 +139,7 @@ Build and Packaging - :issue:`SERVER-50125` UBSAN with ccache doesn't always respect -fsanitize-blacklist options - :issue:`SERVER-50363` Promote --build-tools=next to stable - :issue:`SERVER-50648` RHEL 8.2 ARM builder's publish_packages task should not run on an ARM host. -- :issue:`SERVER-50674` Darwin --separate-debug tool should not strip with the `x` flag +- :issue:`SERVER-50674` Darwin --separate-debug tool should not strip with the ``x`` flag Internals ~~~~~~~~~ diff --git a/source/includes/collation-locale-table.rst b/source/includes/collation-locale-table.rst index 0647d7c80f4..93a7988a913 100644 --- a/source/includes/collation-locale-table.rst +++ b/source/includes/collation-locale-table.rst @@ -1,5 +1,4 @@ .. list-table:: - :class: index-table index-table-less-padding * - .. list-table:: :header-rows: 1 diff --git a/source/includes/considerations-deploying-replica-set.rst b/source/includes/considerations-deploying-replica-set.rst index 80ec4a68582..5be023f7ece 100644 --- a/source/includes/considerations-deploying-replica-set.rst +++ b/source/includes/considerations-deploying-replica-set.rst @@ -14,8 +14,9 @@ Hostnames IP Binding ~~~~~~~~~~ -Use the :setting:`bind_ip` option to ensure that MongoDB listens for -connections from applications on configured addresses. +Use the :option:`--bind_ip ` option to ensure that +MongoDB listens for connections from applications on configured +addresses. .. versionchanged:: 3.6 diff --git a/source/includes/driver-examples/driver-example-delete-55.rst b/source/includes/driver-examples/driver-example-delete-55.rst index f28f452d4e6..2175bb01330 100644 --- a/source/includes/driver-examples/driver-example-delete-55.rst +++ b/source/includes/driver-examples/driver-example-delete-55.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany( [ @@ -14,11 +14,9 @@ { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" }, ] ); - .. only:: website - - You can run the operation in the web shell below: + .. include:: /includes/fact-mws-intro.rst - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -43,7 +41,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -52,7 +50,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -61,7 +59,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -70,7 +68,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -79,7 +77,7 @@ - id: nodejs content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/node_remove.js :language: javascript :dedent: 4 @@ -88,7 +86,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -97,7 +95,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -106,7 +104,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -115,7 +113,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -124,7 +122,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-delete-56.rst b/source/includes/driver-examples/driver-example-delete-56.rst index c6c895670be..d1091f2872d 100644 --- a/source/includes/driver-examples/driver-example-delete-56.rst +++ b/source/includes/driver-examples/driver-example-delete-56.rst @@ -3,14 +3,14 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.deleteMany({}) - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -19,7 +19,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -28,7 +28,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -37,7 +37,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -46,7 +46,7 @@ - id: nodejs content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/node_remove.js :language: javascript :dedent: 6 @@ -55,7 +55,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -64,7 +64,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -73,7 +73,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -82,7 +82,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -91,7 +91,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-delete-57.rst b/source/includes/driver-examples/driver-example-delete-57.rst index 91f290d670e..b4046ed438c 100644 --- a/source/includes/driver-examples/driver-example-delete-57.rst +++ b/source/includes/driver-examples/driver-example-delete-57.rst @@ -3,14 +3,14 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.deleteMany({ status : "A" }) - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -19,7 +19,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -28,7 +28,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -37,7 +37,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -46,7 +46,7 @@ - id: nodejs content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/node_remove.js :language: javascript :dedent: 6 @@ -55,7 +55,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -64,7 +64,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -73,7 +73,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -82,7 +82,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -91,7 +91,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-delete-58.rst b/source/includes/driver-examples/driver-example-delete-58.rst index 17ba1646a45..04f5f93b9b2 100644 --- a/source/includes/driver-examples/driver-example-delete-58.rst +++ b/source/includes/driver-examples/driver-example-delete-58.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.deleteOne( { status: "D" } ) @@ -15,10 +15,7 @@ to access the :ref:`Table View `: .. figure:: /images/compass-table-btn-click-2.png - - .. raw:: html - -
+ :alt: Compass Table View button #. Use the Compass :ref:`query bar ` to locate the target document. @@ -26,50 +23,32 @@ Copy the following filter document into the query bar and click :guilabel:`Find`: - .. class:: copyable-code .. code-block:: javascript { item: "paper" } .. figure:: /images/compass-delete-paper-find.png - - .. raw:: html - -
+ :alt: Compass Find button #. Hover over the document and click the trash icon which appears on the right-hand side: - .. raw:: html - -
- .. figure:: /images/compass-delete-button-click.png - - .. raw:: html - -
+ :alt: Compass Delete Document button After clicking the delete button, the document is flagged for deletion and Compass asks for confirmation that you want to remove the document: - .. raw:: html - -
- .. figure:: /images/compass-delete-confirm.png - - .. raw:: html - -
+ :alt: Compass Confirm Deletion button #. Click :guilabel:`Delete` to confirm. Compass deletes the document from the collection. - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -78,7 +57,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -87,7 +66,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -96,7 +75,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -105,7 +84,7 @@ - id: nodejs content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/node_remove.js :language: javascript :dedent: 6 @@ -114,7 +93,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -123,7 +102,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -132,7 +111,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -141,7 +120,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -150,7 +129,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-indexes-1.rst b/source/includes/driver-examples/driver-example-indexes-1.rst index 100a20695fd..1661e7cd1d3 100644 --- a/source/includes/driver-examples/driver-example-indexes-1.rst +++ b/source/includes/driver-examples/driver-example-indexes-1.rst @@ -7,7 +7,7 @@ :doc:`Mongo Shell `, use :method:`db.collection.createIndex()`. - .. class:: copyable-code + .. code-block:: javascript db.collection.createIndex( , ) @@ -15,7 +15,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: javascript db.collection.createIndex( { name: -1 } ) @@ -42,7 +42,7 @@ :api:`Python driver `, use :py:meth:`pymongo.collection.Collection.create_index`. - .. class:: copyable-code + .. code-block:: python db.collection.create_index([()], ) @@ -50,7 +50,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: python collection.create_index([("name", pymongo.DESCENDING)]) @@ -66,7 +66,7 @@ use :py:meth:`motor.motor_asyncio.AsyncIOMotorCollection.create_index`. - .. class:: copyable-code + .. code-block:: python await db.collection.create_index([()], ) @@ -74,7 +74,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: python await collection.create_index([("name", pymongo.DESCENDING)]) @@ -90,7 +90,7 @@ use `com.mongodb.client.MongoCollection.createIndex `_. - .. class:: copyable-code + .. code-block:: java collection.createIndex( , ) @@ -98,7 +98,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: java collection.createIndex(Indexes.descending("name")); @@ -114,7 +114,7 @@ use `com.mongodb.async.client.MongoCollection.createIndex `_. - .. class:: copyable-code + .. code-block:: java collection.createIndex( , , ) @@ -122,7 +122,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: java collection.createIndex(Indexes.descending("name"), someCallbackFunction()); @@ -138,7 +138,7 @@ use `createIndex() `_. - .. class:: copyable-code + .. code-block:: javascript collection.createIndex( { }, function(err, result) { @@ -149,7 +149,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: javascript collection.createIndex( { name : -1 }, function(err, result) { @@ -167,7 +167,7 @@ `PHP driver `_, use :phpmethod:`MongoDB\\Collection::createIndex() `. - .. class:: copyable-code + .. code-block:: php $collection->createIndex(, ); @@ -175,7 +175,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: php $collection->createIndex(['name' => -1]); @@ -191,7 +191,7 @@ use `create_one() `_. - .. class:: copyable-code + .. code-block:: perl my $indexes = $db->get_collection( )->indexes; @@ -200,7 +200,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: perl my $indexes = $db->get_collection( )->indexes; @@ -216,7 +216,7 @@ `Ruby driver `_, use `Mongo::Index::View#create_one `_. - .. class:: copyable-code + .. code-block:: ruby client[:collection].indexes.create_one({ }, {options}) @@ -224,7 +224,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: ruby client[:collection].indexes.create_one({ name: -1 }) @@ -240,7 +240,7 @@ use `org.mongodb.scala.model.Indexes `_. - .. class:: copyable-code + .. code-block:: scala collection.createIndex() @@ -248,7 +248,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: scala collection.createIndex(descending("name")) @@ -264,7 +264,7 @@ use `MongoCollection.CreateIndex `_. - .. class:: copyable-code + .. code-block:: csharp collection.CreateIndex( IndexKeys., ); @@ -272,7 +272,7 @@ The following example creates a single key descending index on the ``name`` field: - .. class:: copyable-code + .. code-block:: csharp collection.CreateIndex( IndexKeys.Descending("name") ); diff --git a/source/includes/driver-examples/driver-example-indexes-2.rst b/source/includes/driver-examples/driver-example-indexes-2.rst index 8208e2f053c..058355dee97 100644 --- a/source/includes/driver-examples/driver-example-indexes-2.rst +++ b/source/includes/driver-examples/driver-example-indexes-2.rst @@ -14,8 +14,8 @@ the :doc:`Mongo Shell `. Refer to the - :hardlink:`MongoDB Compass Documentation - ` for instructions on using + :compass:`MongoDB Compass Documentation + ` for instructions on using custom collation with indexes in Compass. diff --git a/source/includes/driver-examples/driver-example-insert-1.rst b/source/includes/driver-examples/driver-example-insert-1.rst index 30935374506..62f2588a613 100644 --- a/source/includes/driver-examples/driver-example-insert-1.rst +++ b/source/includes/driver-examples/driver-example-insert-1.rst @@ -3,26 +3,25 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertOne( { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } ) - .. only:: website - - You can run the operation in the web shell below: + .. include:: /includes/fact-mws-intro.rst - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws.rst - id: compass content: | .. figure:: /images/compass-insert-document-inventory.png + :alt: Compass insert new document into collection - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +30,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +39,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +48,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -58,7 +57,7 @@ - id: nodejs content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/node_insert.js :language: javascript :dedent: 6 @@ -67,7 +66,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -76,7 +75,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -85,7 +84,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -94,7 +93,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -103,7 +102,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-insert-2.rst b/source/includes/driver-examples/driver-example-insert-2.rst index 67e4d034280..9de20737ffd 100644 --- a/source/includes/driver-examples/driver-example-insert-2.rst +++ b/source/includes/driver-examples/driver-example-insert-2.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { item: "canvas" } ) @@ -11,6 +11,7 @@ - id: compass content: | .. figure:: /images/compass-query-collection.png + :alt: Query for matching documents in a collection Specify a filter in the MongoDB Compass query bar and click :guilabel:`Find` to execute the query. @@ -25,7 +26,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -34,7 +35,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -43,7 +44,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -52,7 +53,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -69,7 +70,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -78,7 +79,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -87,7 +88,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -96,7 +97,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -105,7 +106,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-insert-3.rst b/source/includes/driver-examples/driver-example-insert-3.rst index 6ac4c949fb9..0979786edd2 100644 --- a/source/includes/driver-examples/driver-example-insert-3.rst +++ b/source/includes/driver-examples/driver-example-insert-3.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany([ @@ -12,15 +12,13 @@ { item: "mousepad", qty: 25, tags: ["gel", "blue"], size: { h: 19, w: 22.85, uom: "cm" } } ]) - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -29,7 +27,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -38,7 +36,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -47,7 +45,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -64,7 +62,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -73,7 +71,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -82,7 +80,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -91,7 +89,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -100,7 +98,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-10.rst b/source/includes/driver-examples/driver-example-query-10.rst index 39715e46e5c..1cb7601a903 100644 --- a/source/includes/driver-examples/driver-example-query-10.rst +++ b/source/includes/driver-examples/driver-example-query-10.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: { $in: [ "A", "D" ] } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { status: { $in: [ "A", "D" ] } } .. figure:: /images/compass-find-filter-query-op.png + :alt: Query using query operators - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-11.rst b/source/includes/driver-examples/driver-example-query-11.rst index a6e9b16c325..b020bf5f7e8 100644 --- a/source/includes/driver-examples/driver-example-query-11.rst +++ b/source/includes/driver-examples/driver-example-query-11.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "A", qty: { $lt: 30 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { status: "A", qty: { $lt: 30 } } .. figure:: /images/compass-find-filter-and.png + :alt: Query using multiple conditions with AND - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-12.rst b/source/includes/driver-examples/driver-example-query-12.rst index 41fe1021ba6..d5e0cc55f56 100644 --- a/source/includes/driver-examples/driver-example-query-12.rst +++ b/source/includes/driver-examples/driver-example-query-12.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { $or: [ { status: "A" }, { qty: { $lt: 30 } } ] } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { $or: [ { status: "A" }, { qty: { $lt: 30 } } ] } .. figure:: /images/compass-find-filter-or.png + :alt: Query using OR - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-13.rst b/source/includes/driver-examples/driver-example-query-13.rst index 32ba98a5233..cc28fee06d4 100644 --- a/source/includes/driver-examples/driver-example-query-13.rst +++ b/source/includes/driver-examples/driver-example-query-13.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { @@ -16,17 +16,18 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { status: "A", $or: [ { qty: { $lt: 30 } }, { item: /^p/ } ] } .. figure:: /images/compass-find-filter-and-or.png + :alt: Query using AND as well as OR - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -35,7 +36,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -44,7 +45,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -53,7 +54,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -70,7 +71,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -79,7 +80,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -88,7 +89,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -97,7 +98,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -106,7 +107,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-14.rst b/source/includes/driver-examples/driver-example-query-14.rst index 44402133010..f2ef0d0ead4 100644 --- a/source/includes/driver-examples/driver-example-query-14.rst +++ b/source/includes/driver-examples/driver-example-query-14.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany( [ @@ -14,11 +14,9 @@ { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" } ]); - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -37,7 +35,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -46,7 +44,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -55,7 +53,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -64,7 +62,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -81,7 +79,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -90,7 +88,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -99,7 +97,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -108,7 +106,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -117,7 +115,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-15.rst b/source/includes/driver-examples/driver-example-query-15.rst index 76b4ce299c9..041dd727623 100644 --- a/source/includes/driver-examples/driver-example-query-15.rst +++ b/source/includes/driver-examples/driver-example-query-15.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { size: { h: 14, w: 21, uom: "cm" } } .. figure:: /images/compass-match-embedded.png + :alt: Query embedded field - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-16.rst b/source/includes/driver-examples/driver-example-query-16.rst index 3b0d3dc465f..55f09bcef5b 100644 --- a/source/includes/driver-examples/driver-example-query-16.rst +++ b/source/includes/driver-examples/driver-example-query-16.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { size: { w: 21, h: 14, uom: "cm" } } ) @@ -11,10 +11,11 @@ - id: compass content: | .. figure:: /images/compass-find-embedded-no-match.png + :alt: Query embedded field - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -23,7 +24,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -32,7 +33,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -41,7 +42,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -58,7 +59,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -67,7 +68,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -76,7 +77,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -85,7 +86,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -94,7 +95,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-17.rst b/source/includes/driver-examples/driver-example-query-17.rst index e29641e8480..47e5dd8a677 100644 --- a/source/includes/driver-examples/driver-example-query-17.rst +++ b/source/includes/driver-examples/driver-example-query-17.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "size.uom": "in" } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "size.uom": "in" } .. figure:: /images/compass-find-nested-field.png + :alt: Query single nested field - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-18.rst b/source/includes/driver-examples/driver-example-query-18.rst index e4516c78d22..eb257d00a00 100644 --- a/source/includes/driver-examples/driver-example-query-18.rst +++ b/source/includes/driver-examples/driver-example-query-18.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "size.h": { $lt: 15 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "size.h": { $lt: 15 } } .. figure:: /images/compass-find-nested-query-op.png + :alt: Query single nested field - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-19.rst b/source/includes/driver-examples/driver-example-query-19.rst index 48455e654e9..2a56ddc6322 100644 --- a/source/includes/driver-examples/driver-example-query-19.rst +++ b/source/includes/driver-examples/driver-example-query-19.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "size.h": { $lt: 15 }, "size.uom": "in", status: "D" } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "size.h": { $lt: 15 }, "size.uom": "in", status: "D" } .. figure:: /images/compass-find-embedded-and.png + :alt: Query multiple nested fields - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-20.rst b/source/includes/driver-examples/driver-example-query-20.rst index 76654e33582..4da3011f23e 100644 --- a/source/includes/driver-examples/driver-example-query-20.rst +++ b/source/includes/driver-examples/driver-example-query-20.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany([ @@ -14,11 +14,9 @@ { item: "postcard", qty: 45, tags: ["blue"], dim_cm: [ 10, 15.25 ] } ]); - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -38,7 +36,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -47,7 +45,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -56,7 +54,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -65,7 +63,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -82,7 +80,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -91,7 +89,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -100,7 +98,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -109,7 +107,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -118,7 +116,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-21.rst b/source/includes/driver-examples/driver-example-query-21.rst index 15b93af52f9..c0a575d6277 100644 --- a/source/includes/driver-examples/driver-example-query-21.rst +++ b/source/includes/driver-examples/driver-example-query-21.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { tags: ["red", "blank"] } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { tags: ["red", "blank"] } .. figure:: /images/compass-array-match-exact.png + :alt: Query array matching exactly - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-22.rst b/source/includes/driver-examples/driver-example-query-22.rst index 9901e22caba..c45f13eb958 100644 --- a/source/includes/driver-examples/driver-example-query-22.rst +++ b/source/includes/driver-examples/driver-example-query-22.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { tags: { $all: ["red", "blank"] } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { tags: { $all: ["red", "blank"] } } .. figure:: /images/compass-array-match-all.png + :alt: Query array matching all criteria - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-23.rst b/source/includes/driver-examples/driver-example-query-23.rst index 2948b8b081d..4f481c9c291 100644 --- a/source/includes/driver-examples/driver-example-query-23.rst +++ b/source/includes/driver-examples/driver-example-query-23.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { tags: "red" } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { tags: "red" } .. figure:: /images/compass-array-elem-match.png + :alt: Query array matching multiple criteria - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-24.rst b/source/includes/driver-examples/driver-example-query-24.rst index ff8028e64ef..35e98ba5e67 100644 --- a/source/includes/driver-examples/driver-example-query-24.rst +++ b/source/includes/driver-examples/driver-example-query-24.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { dim_cm: { $gt: 25 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { dim_cm: { $gt: 25 } } .. figure:: /images/compass-array-query-op.png + :alt: Query array for at least one matching element - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-25.rst b/source/includes/driver-examples/driver-example-query-25.rst index 1657458ceef..fd21527ca1a 100644 --- a/source/includes/driver-examples/driver-example-query-25.rst +++ b/source/includes/driver-examples/driver-example-query-25.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { dim_cm: { $gt: 15, $lt: 20 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { dim_cm: { $gt: 15, $lt: 20 } } .. figure:: /images/compass-array-compound-filter.png + :alt: Query array using a compound filter - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-26.rst b/source/includes/driver-examples/driver-example-query-26.rst index 1c3633b7c2d..be53400c194 100644 --- a/source/includes/driver-examples/driver-example-query-26.rst +++ b/source/includes/driver-examples/driver-example-query-26.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { dim_cm: { $elemMatch: { $gt: 22, $lt: 30 } } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { dim_cm: { $elemMatch: { $gt: 22, $lt: 30 } } } .. figure:: /images/compass-array-compound-multiple-criteria.png + :alt: Query array by multiple conditions - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-27.rst b/source/includes/driver-examples/driver-example-query-27.rst index b28596c4a33..c4b224af31d 100644 --- a/source/includes/driver-examples/driver-example-query-27.rst +++ b/source/includes/driver-examples/driver-example-query-27.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "dim_cm.1": { $gt: 25 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "dim_cm.1": { $gt: 25 } } .. figure:: /images/compass-array-match-by-index.png + :alt: Query array by index - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-28.rst b/source/includes/driver-examples/driver-example-query-28.rst index 7c32634d02f..49df5a49853 100644 --- a/source/includes/driver-examples/driver-example-query-28.rst +++ b/source/includes/driver-examples/driver-example-query-28.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "tags": { $size: 3 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "tags": { $size: 3 } } .. figure:: /images/compass-array-query-by-size.png + :alt: Query for array by number of elements - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-29.rst b/source/includes/driver-examples/driver-example-query-29.rst index f7db2119a61..86ea5209c94 100644 --- a/source/includes/driver-examples/driver-example-query-29.rst +++ b/source/includes/driver-examples/driver-example-query-29.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany( [ @@ -14,11 +14,9 @@ { item: "postcard", instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] } ]); - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -37,7 +35,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -46,7 +44,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -55,7 +53,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -64,7 +62,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -81,7 +79,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -90,7 +88,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -99,7 +97,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -108,7 +106,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -117,7 +115,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-30.rst b/source/includes/driver-examples/driver-example-query-30.rst index 164aada91d5..33bb00c8416 100644 --- a/source/includes/driver-examples/driver-example-query-30.rst +++ b/source/includes/driver-examples/driver-example-query-30.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "instock": { warehouse: "A", qty: 5 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "instock": { warehouse: "A", qty: 5 } } .. figure:: /images/compass-find-nested-in-array.png + :alt: Query for nested array element - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-31.rst b/source/includes/driver-examples/driver-example-query-31.rst index 29a90a3ac80..468f0cf7a30 100644 --- a/source/includes/driver-examples/driver-example-query-31.rst +++ b/source/includes/driver-examples/driver-example-query-31.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "instock": { qty: 5, warehouse: "A" } } ) @@ -11,10 +11,11 @@ - id: compass content: | .. figure:: /images/compass-find-nested-array-no-match.png + :alt: Query for nested array element - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -23,7 +24,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -32,7 +33,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -41,7 +42,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -58,7 +59,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -67,7 +68,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -76,7 +77,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -85,7 +86,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -94,7 +95,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-32.rst b/source/includes/driver-examples/driver-example-query-32.rst index d5db7452a09..ddf786d967a 100644 --- a/source/includes/driver-examples/driver-example-query-32.rst +++ b/source/includes/driver-examples/driver-example-query-32.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { 'instock.0.qty': { $lte: 20 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { 'instock.0.qty': { $lte: 20 } } .. figure:: /images/compass-find-array-index-embedded-doc.png + :alt: Query for array element matching single condition - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-33.rst b/source/includes/driver-examples/driver-example-query-33.rst index 1c857da7233..64b951aa19f 100644 --- a/source/includes/driver-examples/driver-example-query-33.rst +++ b/source/includes/driver-examples/driver-example-query-33.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { 'instock.qty': { $lte: 20 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { 'instock.qty': { $lte: 20 } } .. figure:: /images/compass-find-array-embedded-field-condition.png + :alt: Query for embedded field matching single condition - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-34.rst b/source/includes/driver-examples/driver-example-query-34.rst index 29cacd10fe8..464e151e60f 100644 --- a/source/includes/driver-examples/driver-example-query-34.rst +++ b/source/includes/driver-examples/driver-example-query-34.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "instock": { $elemMatch: { qty: 5, warehouse: "A" } } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "instock": { $elemMatch: { qty: 5, warehouse: "A" } } } .. figure:: /images/compass-array-multiple-cond-single-doc.png + :alt: Query for single document matching multiple conditions - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-35.rst b/source/includes/driver-examples/driver-example-query-35.rst index 09e528c992d..d69fd03fd05 100644 --- a/source/includes/driver-examples/driver-example-query-35.rst +++ b/source/includes/driver-examples/driver-example-query-35.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "instock": { $elemMatch: { qty: { $gt: 10, $lte: 20 } } } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "instock": { $elemMatch: { qty: { $gt: 10, $lte: 20 } } } } .. figure:: /images/compass-array-multiple-cond-single-doc-2.png + :alt: Query for single document matching multiple conditions - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-36.rst b/source/includes/driver-examples/driver-example-query-36.rst index b32072da855..a039bb8ab5c 100644 --- a/source/includes/driver-examples/driver-example-query-36.rst +++ b/source/includes/driver-examples/driver-example-query-36.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "instock.qty": { $gt: 10, $lte: 20 } } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "instock.qty": { $gt: 10, $lte: 20 } } .. figure:: /images/compass-array-match-combination-of-elements.png + :alt: Query quantity value within range - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-37.rst b/source/includes/driver-examples/driver-example-query-37.rst index 90240c0ea43..cacb26bbb12 100644 --- a/source/includes/driver-examples/driver-example-query-37.rst +++ b/source/includes/driver-examples/driver-example-query-37.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { "instock.qty": 5, "instock.warehouse": "A" } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { "instock.qty": 5, "instock.warehouse": "A" } .. figure:: /images/compass-array-match-combination-of-elements-2.png + :alt: Query matching quantity and warehouse location - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-38.rst b/source/includes/driver-examples/driver-example-query-38.rst index 471adbca047..a85312e54fd 100644 --- a/source/includes/driver-examples/driver-example-query-38.rst +++ b/source/includes/driver-examples/driver-example-query-38.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany([ @@ -11,11 +11,11 @@ { _id: 2 } ]) - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -31,7 +31,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -40,7 +40,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -49,7 +49,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -58,7 +58,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -75,7 +75,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -84,7 +84,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -93,7 +93,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -102,7 +102,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -111,7 +111,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-39.rst b/source/includes/driver-examples/driver-example-query-39.rst index bed4f0b2489..c6878bd7dee 100644 --- a/source/includes/driver-examples/driver-example-query-39.rst +++ b/source/includes/driver-examples/driver-example-query-39.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { item: null } ) @@ -14,16 +14,17 @@ :ref:`query bar ` and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { item: null } .. figure:: /images/compass-find-null-field.png + :alt: Query null value or missing field - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -32,7 +33,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -41,7 +42,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -50,7 +51,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -67,7 +68,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -76,7 +77,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -85,7 +86,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -94,7 +95,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -103,7 +104,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-40.rst b/source/includes/driver-examples/driver-example-query-40.rst index 6ad73bcb49a..3777e0764b6 100644 --- a/source/includes/driver-examples/driver-example-query-40.rst +++ b/source/includes/driver-examples/driver-example-query-40.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { item : { $type: 10 } } ) @@ -14,16 +14,17 @@ :ref:`query bar ` and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { item : { $type: 10 } } .. figure:: /images/compass-find-null-type-check.png + :alt: Find null type - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -32,7 +33,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -41,7 +42,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -50,7 +51,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -67,7 +68,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -76,7 +77,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -85,7 +86,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -94,7 +95,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -103,7 +104,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-41.rst b/source/includes/driver-examples/driver-example-query-41.rst index 92ef013a36d..ec979093970 100644 --- a/source/includes/driver-examples/driver-example-query-41.rst +++ b/source/includes/driver-examples/driver-example-query-41.rst @@ -20,10 +20,11 @@ { item : { $exists: false } } .. figure:: /images/compass-find-null-existence-check.png + :alt: Query for null value - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -32,7 +33,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -41,7 +42,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -50,7 +51,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -67,7 +68,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -76,7 +77,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -85,7 +86,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -94,7 +95,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -103,7 +104,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-42.rst b/source/includes/driver-examples/driver-example-query-42.rst index 5bacd477010..0a80f615b89 100644 --- a/source/includes/driver-examples/driver-example-query-42.rst +++ b/source/includes/driver-examples/driver-example-query-42.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany( [ @@ -14,11 +14,9 @@ { item: "postcard", status: "A", size: { h: 10, w: 15.25, uom: "cm" }, instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] } ]); - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -38,7 +36,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -47,7 +45,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -56,7 +54,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -65,7 +63,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -82,7 +80,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -91,7 +89,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -100,7 +98,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -109,7 +107,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -118,7 +116,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-43.rst b/source/includes/driver-examples/driver-example-query-43.rst index 25ae07f72cc..92fb492d4af 100644 --- a/source/includes/driver-examples/driver-example-query-43.rst +++ b/source/includes/driver-examples/driver-example-query-43.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "A" } ) @@ -21,7 +21,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -30,7 +30,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -39,7 +39,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -48,7 +48,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -65,7 +65,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -74,7 +74,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -83,7 +83,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -92,7 +92,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -101,7 +101,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-44.rst b/source/includes/driver-examples/driver-example-query-44.rst index 71ae6e21814..02ffc83aba5 100644 --- a/source/includes/driver-examples/driver-example-query-44.rst +++ b/source/includes/driver-examples/driver-example-query-44.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "A" }, { item: 1, status: 1 } ) @@ -32,7 +32,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -41,7 +41,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -56,7 +56,7 @@ com.mongodb.client.model.Projections_ class to create the projection documents. - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -65,7 +65,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -82,7 +82,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -91,7 +91,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -100,7 +100,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -109,7 +109,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -118,7 +118,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-45.rst b/source/includes/driver-examples/driver-example-query-45.rst index 274c3fbc247..72c98231c12 100644 --- a/source/includes/driver-examples/driver-example-query-45.rst +++ b/source/includes/driver-examples/driver-example-query-45.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "A" }, { item: 1, status: 1, _id: 0 } ) @@ -31,7 +31,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -40,7 +40,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -55,7 +55,7 @@ com.mongodb.client.model.Projections_ class to create the projection documents. - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -64,7 +64,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -81,7 +81,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -90,7 +90,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -99,7 +99,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -108,7 +108,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -117,7 +117,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-46.rst b/source/includes/driver-examples/driver-example-query-46.rst index 9175eebcb86..be365b1e253 100644 --- a/source/includes/driver-examples/driver-example-query-46.rst +++ b/source/includes/driver-examples/driver-example-query-46.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "A" }, { status: 0, instock: 0 } ) @@ -31,7 +31,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -40,7 +40,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -55,7 +55,7 @@ com.mongodb.client.model.Projections_ class to create the projection documents. - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -64,7 +64,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -81,7 +81,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -90,7 +90,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -99,7 +99,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -108,7 +108,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -117,7 +117,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-47.rst b/source/includes/driver-examples/driver-example-query-47.rst index 791cce6f7ed..7b9cb4e70fe 100644 --- a/source/includes/driver-examples/driver-example-query-47.rst +++ b/source/includes/driver-examples/driver-example-query-47.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( @@ -34,7 +34,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -43,7 +43,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -58,7 +58,7 @@ com.mongodb.client.model.Projections_ class to create the projection documents. - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -67,7 +67,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -84,7 +84,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -93,7 +93,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -102,7 +102,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -111,7 +111,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -120,7 +120,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-48.rst b/source/includes/driver-examples/driver-example-query-48.rst index e44c1f92c51..84eec839a2e 100644 --- a/source/includes/driver-examples/driver-example-query-48.rst +++ b/source/includes/driver-examples/driver-example-query-48.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( @@ -34,7 +34,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -43,7 +43,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -58,7 +58,7 @@ com.mongodb.client.model.Projections_ class to create the projection documents. - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -67,7 +67,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -84,7 +84,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -93,7 +93,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -102,7 +102,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -111,7 +111,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -120,7 +120,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-49.rst b/source/includes/driver-examples/driver-example-query-49.rst index a63773a19c0..198ac71ad0e 100644 --- a/source/includes/driver-examples/driver-example-query-49.rst +++ b/source/includes/driver-examples/driver-example-query-49.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "A" }, { item: 1, status: 1, "instock.qty": 1 } ) @@ -31,7 +31,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -40,7 +40,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -55,7 +55,7 @@ com.mongodb.client.model.Projections_ class to create the projection documents. - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -64,7 +64,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -81,7 +81,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -90,7 +90,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -99,7 +99,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -108,7 +108,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -117,7 +117,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-50.rst b/source/includes/driver-examples/driver-example-query-50.rst index 0ea57407199..1e62f862971 100644 --- a/source/includes/driver-examples/driver-example-query-50.rst +++ b/source/includes/driver-examples/driver-example-query-50.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "A" }, { item: 1, status: 1, instock: { $slice: -1 } } ) @@ -34,7 +34,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -43,7 +43,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -58,7 +58,7 @@ com.mongodb.client.model.Projections_ class to create the projection documents. - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -67,7 +67,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -84,7 +84,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -93,7 +93,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -102,7 +102,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -111,7 +111,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -120,7 +120,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-6.rst b/source/includes/driver-examples/driver-example-query-6.rst index 617e93227cd..1d73a188a50 100644 --- a/source/includes/driver-examples/driver-example-query-6.rst +++ b/source/includes/driver-examples/driver-example-query-6.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany([ @@ -14,11 +14,9 @@ { item: "postcard", qty: 45, size: { h: 10, w: 15.25, uom: "cm" }, status: "A" } ]); - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -37,7 +35,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -46,7 +44,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -55,7 +53,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -64,7 +62,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -81,7 +79,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -90,7 +88,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -99,7 +97,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -108,7 +106,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -117,7 +115,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-7.rst b/source/includes/driver-examples/driver-example-query-7.rst index 2a9a9b83579..68eeb414057 100644 --- a/source/includes/driver-examples/driver-example-query-7.rst +++ b/source/includes/driver-examples/driver-example-query-7.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( {} ) @@ -12,10 +12,11 @@ content: | .. figure:: /images/compass-select-all.png + :alt: Compass select all documents in collection - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -24,7 +25,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -33,7 +34,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -42,7 +43,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -59,7 +60,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -68,7 +69,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -77,7 +78,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -86,7 +87,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -95,7 +96,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-query-9.rst b/source/includes/driver-examples/driver-example-query-9.rst index 7aaf2342e5d..ba9e1824dac 100644 --- a/source/includes/driver-examples/driver-example-query-9.rst +++ b/source/includes/driver-examples/driver-example-query-9.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.find( { status: "D" } ) @@ -13,16 +13,17 @@ Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { status: "D" } .. figure:: /images/compass-find-filter-inventory.png + :alt: Query using equality condition - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -31,7 +32,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -40,7 +41,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +50,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -66,7 +67,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -75,7 +76,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -84,7 +85,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -93,7 +94,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -102,7 +103,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-transactions-intro-1.rst b/source/includes/driver-examples/driver-example-transactions-intro-1.rst index 7b2659a146a..9a6f95aad91 100644 --- a/source/includes/driver-examples/driver-example-transactions-intro-1.rst +++ b/source/includes/driver-examples/driver-example-transactions-intro-1.rst @@ -4,7 +4,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 diff --git a/source/includes/driver-examples/driver-example-transactions-retry-1.rst b/source/includes/driver-examples/driver-example-transactions-retry-1.rst index 23b7a6fc9c2..e03f311dade 100644 --- a/source/includes/driver-examples/driver-example-transactions-retry-1.rst +++ b/source/includes/driver-examples/driver-example-transactions-retry-1.rst @@ -35,7 +35,7 @@ To associate read and write operations with a transaction, you **must** pass the session to each operation in the transaction. - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 diff --git a/source/includes/driver-examples/driver-example-transactions-retry-2.rst b/source/includes/driver-examples/driver-example-transactions-retry-2.rst index 807e65a3b83..948cd603402 100644 --- a/source/includes/driver-examples/driver-example-transactions-retry-2.rst +++ b/source/includes/driver-examples/driver-example-transactions-retry-2.rst @@ -73,7 +73,7 @@ To associate read and write operations with a transaction, you **must** pass the session to each operation in the transaction. - .. class:: copyable-code + .. literalinclude:: /driver-examples/perl-transactions-examples.t :language: perl :start-after: Start Transactions Retry Example 2 diff --git a/source/includes/driver-examples/driver-example-transactions-retry-3.rst b/source/includes/driver-examples/driver-example-transactions-retry-3.rst index 4e960fcbf35..c16e7933138 100644 --- a/source/includes/driver-examples/driver-example-transactions-retry-3.rst +++ b/source/includes/driver-examples/driver-example-transactions-retry-3.rst @@ -9,7 +9,7 @@ To associate read and write operations with a transaction, you **must** pass the session to each operation in the transaction. - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 diff --git a/source/includes/driver-examples/driver-example-update-51.rst b/source/includes/driver-examples/driver-example-update-51.rst index e15bfb17680..78c5fb013fa 100644 --- a/source/includes/driver-examples/driver-example-update-51.rst +++ b/source/includes/driver-examples/driver-example-update-51.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.insertMany( [ @@ -19,11 +19,9 @@ { item: "sketch pad", qty: 95, size: { h: 22.85, w: 30.5, uom: "cm" }, status: "A" } ] ); - .. only:: website - - You can run the operation in the web shell below: - - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws-intro.rst + + .. include:: /includes/fact-mws.rst - id: compass content: | @@ -47,7 +45,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -56,7 +54,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -65,7 +63,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -74,7 +72,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -91,7 +89,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -100,7 +98,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -109,7 +107,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 6 @@ -118,7 +116,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -127,7 +125,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-update-52.rst b/source/includes/driver-examples/driver-example-update-52.rst index 964f0e19abf..e2277c7d9f5 100644 --- a/source/includes/driver-examples/driver-example-update-52.rst +++ b/source/includes/driver-examples/driver-example-update-52.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.updateOne( @@ -39,7 +39,7 @@ Copy the following filter document into the query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { item: "paper" } @@ -109,7 +109,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -118,7 +118,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -129,7 +129,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -140,7 +140,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -161,7 +161,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -172,7 +172,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -183,7 +183,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -194,7 +194,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -205,7 +205,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-update-53.rst b/source/includes/driver-examples/driver-example-update-53.rst index 37d351bc61d..ecd1c7ee557 100644 --- a/source/includes/driver-examples/driver-example-update-53.rst +++ b/source/includes/driver-examples/driver-example-update-53.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.updateMany( @@ -18,7 +18,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -27,7 +27,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -38,7 +38,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -49,7 +49,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -70,7 +70,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -81,7 +81,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -92,7 +92,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -103,7 +103,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -114,7 +114,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-examples/driver-example-update-54.rst b/source/includes/driver-examples/driver-example-update-54.rst index 320af572e69..25ff83053ea 100644 --- a/source/includes/driver-examples/driver-example-update-54.rst +++ b/source/includes/driver-examples/driver-example-update-54.rst @@ -3,7 +3,7 @@ tabs: - id: shell content: | - .. class:: copyable-code + .. code-block:: javascript db.inventory.replaceOne( @@ -13,7 +13,7 @@ - id: python content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples.py :language: python :dedent: 8 @@ -22,7 +22,7 @@ - id: motor content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/test_examples_motor.py :language: python :dedent: 8 @@ -31,7 +31,7 @@ - id: java-sync content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationSamples.java :language: java :dedent: 8 @@ -40,7 +40,7 @@ - id: java-async content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/AsyncDocumentationSamples.java :language: java :dedent: 8 @@ -57,7 +57,7 @@ - id: php content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamplesTest.php :language: php :dedent: 8 @@ -66,7 +66,7 @@ - id: perl content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/driver-examples.t :language: perl :dedent: 4 @@ -75,7 +75,7 @@ - id: ruby content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/shell_examples_spec.rb :language: ruby :dedent: 8 @@ -84,7 +84,7 @@ - id: scala content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala :language: scala :dedent: 4 @@ -93,7 +93,7 @@ - id: csharp content: | - .. class:: copyable-code + .. literalinclude:: /driver-examples/DocumentationExamples.cs :language: c# :dedent: 12 diff --git a/source/includes/driver-list-collection-indexes-tabs.rst b/source/includes/driver-list-collection-indexes-tabs.rst index 02d16d43be6..cc3cd6e1c21 100644 --- a/source/includes/driver-list-collection-indexes-tabs.rst +++ b/source/includes/driver-list-collection-indexes-tabs.rst @@ -1,19 +1,18 @@ .. tabs-drivers:: - tabs: - - id: shell - content: | - List all Indexes on a Collection - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. tab:: + :tabid: shell - To return a list of all indexes on a collection, use the - :method:`db.collection.getIndexes()` method or a similar - :api:`method for your driver <>`. + List all Indexes on a Collection + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - For example, to view all indexes on the ``people`` collection, - run the following command: + To return a list of all indexes on a collection, use the + :method:`db.collection.getIndexes()` method or a similar + :api:`method for your driver <>`. - .. cssclass:: copyable-code - .. code-block:: javascript + For example, to view all indexes on the ``people`` collection, + run the following command: - db.people.getIndexes() \ No newline at end of file + .. code-block:: javascript + + db.people.getIndexes() \ No newline at end of file diff --git a/source/includes/driver-list-database-indexes-tabs.rst b/source/includes/driver-list-database-indexes-tabs.rst index d16d40e56a1..a23ca5bfc01 100644 --- a/source/includes/driver-list-database-indexes-tabs.rst +++ b/source/includes/driver-list-database-indexes-tabs.rst @@ -4,7 +4,7 @@ - id: shell content: | List All Indexes for a Database - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To list all the collection indexes in a database, you can use the following operation in the :binary:`~bin.mongo` shell: diff --git a/source/includes/driver-remove-indexes-tabs.rst b/source/includes/driver-remove-indexes-tabs.rst index 5b619a52171..8729543e574 100644 --- a/source/includes/driver-remove-indexes-tabs.rst +++ b/source/includes/driver-remove-indexes-tabs.rst @@ -18,8 +18,6 @@ For example, the following operation removes an ascending index on the ``tax-id`` field in the ``accounts`` collection: - .. cssclass:: copyable-code - .. code-block:: javascript db.accounts.dropIndex( { "tax-id": 1 } ) @@ -58,14 +56,13 @@ For example, the following command removes all indexes from the ``accounts`` collection: - .. cssclass:: copyable-code .. code-block:: javascript db.accounts.dropIndexes() These shell helpers provide wrappers around the - :dbcommand:`dropIndexes` :term:`database command`. Your :ecosystem:`client - library ` may have a different or additional + :dbcommand:`dropIndexes` :term:`database command`. Your :driver:`client + library ` may have a different or additional interface for these operations. - id: compass diff --git a/source/includes/example-objectToArray-arrayToObject.rst b/source/includes/example-objectToArray-arrayToObject.rst index d93590e2110..18e9a131f05 100644 --- a/source/includes/example-objectToArray-arrayToObject.rst +++ b/source/includes/example-objectToArray-arrayToObject.rst @@ -8,8 +8,6 @@ Consider a ``inventory`` collection with the following documents: The following aggregation pipeline operation calculates the total in stock for each item and adds to the ``instock`` document: -.. cssclass:: copyable-code - .. code-block:: javascript db.inventory.aggregate( [ diff --git a/source/includes/examples-map-reduce.rst b/source/includes/examples-map-reduce.rst index 42e8a72d96c..5ab9f382904 100644 --- a/source/includes/examples-map-reduce.rst +++ b/source/includes/examples-map-reduce.rst @@ -106,57 +106,55 @@ by the ``cust_id``, and calculate the sum of the ``price`` for each Aggregation Alternative ``````````````````````` -.. container:: +Using the available aggregation pipeline operators, you can rewrite +the map-reduce operation without defining custom functions: - Using the available aggregation pipeline operators, you can rewrite - the map-reduce operation without defining custom functions: +.. code-block:: javascript - .. code-block:: javascript + db.orders.aggregate([ + { $group: { _id: "$cust_id", value: { $sum: "$price" } } }, + { $out: "agg_alternative_1" } + ]) - db.orders.aggregate([ - { $group: { _id: "$cust_id", value: { $sum: "$price" } } }, - { $out: "agg_alternative_1" } - ]) +#. The :pipeline:`$group` stage groups by the ``cust_id`` and + calculates the ``value`` field (See also :group:`$sum`). The + ``value`` field contains the total ``price`` for each ``cust_id``. - #. The :pipeline:`$group` stage groups by the ``cust_id`` and - calculates the ``value`` field using :expression:`$sum`. The - ``value`` field contains the total ``price`` for each ``cust_id``. - - This stage outputs these documents to the next stage: + The stage output the following documents to the next stage: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - { "_id" : "Don Quis", "value" : 155 } - { "_id" : "Ant O. Knee", "value" : 95 } - { "_id" : "Cam Elot", "value" : 60 } - { "_id" : "Busby Bee", "value" : 125 } + { "_id" : "Don Quis", "value" : 155 } + { "_id" : "Ant O. Knee", "value" : 95 } + { "_id" : "Cam Elot", "value" : 60 } + { "_id" : "Busby Bee", "value" : 125 } - #. Then, the :pipeline:`$out` writes the output to the collection - ``agg_alternative_1``. Alternatively, you could use - :pipeline:`$merge` instead of :pipeline:`$out`. +#. Then, the :pipeline:`$out` writes the output to the collection + ``agg_alternative_1``. Alternatively, you could use + :pipeline:`$merge` instead of :pipeline:`$out`. - #. Query the ``agg_alternative_1`` collection to verify the results: +#. Query the ``agg_alternative_1`` collection to verify the results: - .. code-block:: javascript + .. code-block:: javascript - db.agg_alternative_1.find().sort( { _id: 1 } ) + db.agg_alternative_1.find().sort( { _id: 1 } ) - The operation returns these documents: + The operation returns the following documents: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - { "_id" : "Ant O. Knee", "value" : 95 } - { "_id" : "Busby Bee", "value" : 125 } - { "_id" : "Cam Elot", "value" : 60 } - { "_id" : "Don Quis", "value" : 155 } + { "_id" : "Ant O. Knee", "value" : 95 } + { "_id" : "Busby Bee", "value" : 125 } + { "_id" : "Cam Elot", "value" : 60 } + { "_id" : "Don Quis", "value" : 155 } - .. seealso:: +.. seealso:: - For an alternative that uses custom aggregation expressions, see - :ref:`Map-Reduce to Aggregation Pipeline Translation Examples - `. + For an alternative that uses custom aggregation expressions, see + :ref:`Map-Reduce to Aggregation Pipeline Translation Examples + `. .. map-reduce-sum-price-end @@ -293,110 +291,146 @@ Example steps: Aggregation Alternative ``````````````````````` +Using the available aggregation pipeline operators, you can rewrite +the map-reduce operation without defining custom functions: -.. container:: +.. code-block:: javascript + + db.orders.aggregate( [ + { $match: { ord_date: { $gte: new Date("2020-03-01") } } }, + { $unwind: "$items" }, + { $group: { _id: "$items.sku", qty: { $sum: "$items.qty" }, orders_ids: { $addToSet: "$_id" } } }, + { $project: { value: { count: { $size: "$orders_ids" }, qty: "$qty", avg: { $divide: [ "$qty", { $size: "$orders_ids" } ] } } } }, + { $merge: { into: "agg_alternative_3", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } + ] ) + +#. The :pipeline:`$match` stage selects only those + documents with ``ord_date`` greater than or equal to ``new + Date("2020-03-01")``. + +#. The :pipeline:`$unwind` stage breaks down the document by + the ``items`` array field to output a document for each array + element. For example: + + .. code-block:: javascript + :copyable: false - Using the available aggregation pipeline operators, you can rewrite - the map-reduce operation without defining custom functions: + { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 5, "price" : 2.5 }, "status" : "A" } + { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "apples", "qty" : 5, "price" : 2.5 }, "status" : "A" } + { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "oranges", "qty" : 8, "price" : 2.5 }, "status" : "A" } + { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } + { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "pears", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 4, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-18T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 5, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-19T00:00:00Z"), "price" : 50, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } + ... + +#. The :pipeline:`$group` stage groups by the ``items.sku``, calculating for each sku: + + - The ``qty`` field. The ``qty`` field contains the + total ``qty`` ordered per each ``items.sku`` (See :group:`$sum`). + + - The ``orders_ids`` array. The ``orders_ids`` field contains an + array of distinct order ``_id``'s for the ``items.sku`` (See + :group:`$addToSet`). .. code-block:: javascript + :copyable: false - db.orders.aggregate( [ - { $match: { ord_date: { $gte: new Date("2020-03-01") } } }, - { $unwind: "$items" }, - { $group: { _id: "$items.sku", qty: { $sum: "$items.qty" }, orders_ids: { $addToSet: "$_id" } } }, - { $project: { value: { count: { $size: "$orders_ids" }, qty: "$qty", avg: { $divide: [ "$qty", { $size: "$orders_ids" } ] } } } }, - { $merge: { into: "agg_alternative_3", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } - ] ) - - #. The :pipeline:`$match` stage selects only those - documents with ``ord_date`` greater than or equal to ``new - Date("2020-03-01")``. + { "_id" : "chocolates", "qty" : 15, "orders_ids" : [ 2, 5, 8 ] } + { "_id" : "oranges", "qty" : 63, "orders_ids" : [ 4, 7, 3, 2, 9, 1, 10 ] } + { "_id" : "carrots", "qty" : 15, "orders_ids" : [ 6, 9 ] } + { "_id" : "apples", "qty" : 35, "orders_ids" : [ 9, 8, 1, 6 ] } + { "_id" : "pears", "qty" : 10, "orders_ids" : [ 3 ] } + +#. The :pipeline:`$project` stage reshapes the output document to + mirror the map-reduce's output to have two fields ``_id`` and + ``value``. The :pipeline:`$project` sets: - #. The :pipeline:`$unwinds` stage breaks down the document by - the ``items`` array field to output a document for each array - element. For example: - - .. code-block:: javascript - :copyable: false - - { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 5, "price" : 2.5 }, "status" : "A" } - { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "apples", "qty" : 5, "price" : 2.5 }, "status" : "A" } - { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "oranges", "qty" : 8, "price" : 2.5 }, "status" : "A" } - { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } - { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } - { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "pears", "qty" : 10, "price" : 2.5 }, "status" : "A" } - { "_id" : 4, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-18T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } - { "_id" : 5, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-19T00:00:00Z"), "price" : 50, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } - ... - - #. The :pipeline:`$group` stage groups by the ``items.sku``, calculating for each sku: - - - The ``qty`` field. The ``qty`` field contains the - total ``qty`` ordered per each ``items.sku`` using - :expression:`$sum`. - - - The ``orders_ids`` array. The ``orders_ids`` field contains an - array of distinct order ``_id``'s for the ``items.sku`` using - :expression:`$addToSet`. - - .. code-block:: javascript - :copyable: false - - { "_id" : "chocolates", "qty" : 15, "orders_ids" : [ 2, 5, 8 ] } - { "_id" : "oranges", "qty" : 63, "orders_ids" : [ 4, 7, 3, 2, 9, 1, 10 ] } - { "_id" : "carrots", "qty" : 15, "orders_ids" : [ 6, 9 ] } - { "_id" : "apples", "qty" : 35, "orders_ids" : [ 9, 8, 1, 6 ] } - { "_id" : "pears", "qty" : 10, "orders_ids" : [ 3 ] } - - #. The :pipeline:`$project` stage reshapes the output document to - mirror the map-reduce's output to have two fields ``_id`` and - ``value``. The :pipeline:`$project` sets: - - - the ``value.count`` to the size of the ``orders_ids`` array - using :expression:`$size`. +#. The :pipeline:`$unwind` stage breaks down the document by + the ``items`` array field to output a document for each array + element. For example: - - the ``value.qty`` to the ``qty`` field of input document. - - - the ``value.avg`` to the average number of qty per order - using :expression:`$divide` and :expression:`$size`. + .. code-block:: javascript + :copyable: false - .. code-block:: javascript - :copyable: false + { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 5, "price" : 2.5 }, "status" : "A" } + { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "apples", "qty" : 5, "price" : 2.5 }, "status" : "A" } + { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "oranges", "qty" : 8, "price" : 2.5 }, "status" : "A" } + { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } + { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "pears", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 4, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-18T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 5, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-19T00:00:00Z"), "price" : 50, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } + ... - { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } } - { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } } - { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } } - { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } } - { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } } - - #. Finally, the :pipeline:`$merge` writes the output to the - collection ``agg_alternative_3``. If an existing document has the same - key ``_id`` as the new result, the operation overwrites the existing - document. If there is no existing document with the same key, the - operation inserts the document. +#. The :pipeline:`$group` stage groups by the ``items.sku``, calculating for each sku: + + - The ``qty`` field. The ``qty`` field contains the + total ``qty`` ordered per each ``items.sku`` using + :group:`$sum`. + + - The ``orders_ids`` array. The ``orders_ids`` field contains an + array of distinct order ``_id``'s for the ``items.sku`` using + :group:`$addToSet`. + + .. code-block:: javascript + :copyable: false + + { "_id" : "chocolates", "qty" : 15, "orders_ids" : [ 2, 5, 8 ] } + { "_id" : "oranges", "qty" : 63, "orders_ids" : [ 4, 7, 3, 2, 9, 1, 10 ] } + { "_id" : "carrots", "qty" : 15, "orders_ids" : [ 6, 9 ] } + { "_id" : "apples", "qty" : 35, "orders_ids" : [ 9, 8, 1, 6 ] } + { "_id" : "pears", "qty" : 10, "orders_ids" : [ 3 ] } + +#. The :pipeline:`$project` stage reshapes the output document to + mirror the map-reduce's output to have two fields ``_id`` and + ``value``. The :pipeline:`$project` sets: + + - the ``value.count`` to the size of the ``orders_ids`` array + using :expression:`$size`. + + - the ``value.qty`` to the ``qty`` field of input document. - #. Query the ``agg_alternative_3`` collection to verify the results: + - the ``value.avg`` to the average number of qty per order + using :expression:`$divide` and :expression:`$size`. + + .. code-block:: javascript + :copyable: false + + { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } } + { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } } + { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } } + { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } } + { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } } + +#. Finally, the :pipeline:`$merge` writes the output to the + collection ``agg_alternative_3``. If an existing document has the same + key ``_id`` as the new result, the operation overwrites the existing + document. If there is no existing document with the same key, the + operation inserts the document. + +#. Query the ``agg_alternative_3`` collection to verify the results: - .. code-block:: javascript + .. code-block:: javascript - db.agg_alternative_3.find().sort( { _id: 1 } ) + db.agg_alternative_3.find().sort( { _id: 1 } ) - The operation returns these documents: + The operation returns the following documents: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } } - { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } } - { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } } - { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } } - { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } } + { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } } + { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } } + { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } } + { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } } + { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } } - .. seealso:: +.. seealso:: - For an alternative that uses custom aggregation expressions, see - :ref:`Map-Reduce to Aggregation Pipeline Translation Examples - `. + For an alternative that uses custom aggregation expressions, see + :ref:`Map-Reduce to Aggregation Pipeline Translation Examples + `. .. map-reduce-counts-end diff --git a/source/includes/extracts-4.2-changes.yaml b/source/includes/extracts-4.2-changes.yaml index fe1223dc0b7..38ba352c6c7 100644 --- a/source/includes/extracts-4.2-changes.yaml +++ b/source/includes/extracts-4.2-changes.yaml @@ -189,12 +189,12 @@ content: | The :pipeline:`$planCacheStats` aggregation stage is preferred over the following methods and commands, which have been deprecated in 4.2: - - :method:`PlanCache.getPlansByQuery()` - method/:dbcommand:`planCacheListPlans` command, and + - ``PlanCache.getPlansByQuery()`` + method/``planCacheListPlans`` command, and - - :method:`PlanCache.listQueryShapes()` - method/:dbcommand:`planCacheListQueryShapes` command. + - ``PlanCache.listQueryShapes()`` + method/``planCacheListQueryShapes`` command. --- ref: 4.2-changes-options-tls-ssl diff --git a/source/includes/extracts-4.4-changes.yaml b/source/includes/extracts-4.4-changes.yaml index a8d7b38c9e0..bfc07bc96ec 100644 --- a/source/includes/extracts-4.4-changes.yaml +++ b/source/includes/extracts-4.4-changes.yaml @@ -138,7 +138,7 @@ content: | As of MongoDB 4.4, there is no distinction between the :expression:`$meta` aggregation operator and the - :projection:`$meta` projection operator. + :expression:`$meta` projection operator. --- ref: 4.4-changes-projection-sort-meta-list @@ -318,8 +318,8 @@ content: | ref: 4.4-changes-downgrade-floor content: | - .. admonition:: Downgrade Floor - :class: warning + .. warning:: Downgrade Floor + If you need to downgrade form version 4.4, downgrade to 4.2.6 or a later version. You cannot downgrade to 4.2.5 or an earlier @@ -334,8 +334,8 @@ content: | ref: 4.4-changes-index-builds-simultaneous-fcv content: | - .. admonition:: Requires ``featureCompatibilityVersion`` 4.4+ - :class: note + .. note:: Requires ``featureCompatibilityVersion`` 4.4+ + Each :binary:`~bin.mongod` in the replica set or sharded cluster *must* have :ref:`featureCompatibilityVersion ` set to at @@ -519,10 +519,10 @@ content: | :doc:`Windows MSI installer ` for both Community and Enterprise editions does not - include the :db-tools:`MongoDB Database Tools <>` (``mongoimport``, + include the :dbtools:`MongoDB Database Tools <>` (``mongoimport``, ``mongoexport``, etc). To download and install the MongoDB Database Tools on Windows, see - :db-tools:`Installing the MongoDB Database Tools `. + :dbtools:`Installing the MongoDB Database Tools `. If you were relying on the MongoDB 4.2 or previous MSI installer to install the Database Tools along with the MongoDB Server, you must diff --git a/source/includes/extracts-built-in-roles.yaml b/source/includes/extracts-built-in-roles.yaml index a4c0e750f70..b6cb8cc21a1 100644 --- a/source/includes/extracts-built-in-roles.yaml +++ b/source/includes/extracts-built-in-roles.yaml @@ -3,7 +3,7 @@ content: | Provides the ability to read data on all *non*-system collections and the :data:`system.js <.system.js>` collection. - .. admonition:: Aside + .. note:: Starting in MongoDB 4.2, the role no longer provides privileges to access the :data:`system.namespaces diff --git a/source/includes/extracts-changestream.yaml b/source/includes/extracts-changestream.yaml index e406579b075..d37b80482e6 100644 --- a/source/includes/extracts-changestream.yaml +++ b/source/includes/extracts-changestream.yaml @@ -1,7 +1,7 @@ ref: changestream-resume content: | - Unlike the MongoDB :ecosystem:`drivers `, the + Unlike the MongoDB :driver:`Drivers `, the :binary:`~bin.mongo` shell does not automatically attempt to resume a change stream cursor after an error. The MongoDB drivers make *one* attempt to automatically resume a change stream cursor after certain diff --git a/source/includes/extracts-client-side-field-level-encryption.yaml b/source/includes/extracts-client-side-field-level-encryption.yaml index 2b2102427f7..6bcce6d94fb 100644 --- a/source/includes/extracts-client-side-field-level-encryption.yaml +++ b/source/includes/extracts-client-side-field-level-encryption.yaml @@ -99,7 +99,7 @@ content: | } } - Use the :binary:`Mongo()` constructor to create a database connection + Use the :method:`Mongo()` constructor to create a database connection with the client-side field level encryption options. Replace the ``mongodb://myMongo.example.net`` URI with the :ref:`connection string URI ` of the target cluster. @@ -115,7 +115,7 @@ content: | ref: csfle-enterprise-atlas-only content: | - .. admonition:: Enterprise Feature + .. note:: Enterprise Feature The automatic feature of field level encryption is only available in MongoDB 4.2 Enterprise and MongoDB Atlas 4.2 clusters. diff --git a/source/includes/extracts-clone-copy-db-examples.yaml b/source/includes/extracts-clone-copy-db-examples.yaml index 781636d3cbd..6b46abf9fbf 100644 --- a/source/includes/extracts-clone-copy-db-examples.yaml +++ b/source/includes/extracts-clone-copy-db-examples.yaml @@ -4,34 +4,32 @@ content: | running on the default port 27017 to the ``examples`` database on the same instance, you can: - .. container:: - - #. Use :binary:`~bin.mongodump` to dump the ``test`` database to - an archive ``mongodump-test-db``: - - .. code-block:: sh + #. Use :binary:`~bin.mongodump` to dump the ``test`` database to + an archive ``mongodump-test-db``: + + .. code-block:: sh - mongodump --archive="mongodump-test-db" --db=test + mongodump --archive="mongodump-test-db" --db=test - #. Use :binary:`~bin.mongorestore` with :option:`--nsFrom - ` and :option:`--nsTo ` to restore (with database name change) from the - archive: + #. Use :binary:`~bin.mongorestore` with :option:`--nsFrom + ` and :option:`--nsTo ` to restore (with database name change) from the + archive: - .. code-block:: sh + .. code-block:: sh - mongorestore --archive="mongodump-test-db" --nsFrom='test.*' --nsTo='examples.*' + mongorestore --archive="mongodump-test-db" --nsFrom='test.*' --nsTo='examples.*' - .. tip:: + .. tip:: - Include additional options as necessary, such as to specify - the uri or host, username, password and authentication - database. + Include additional options as necessary, such as to specify + the uri or host, username, password and authentication + database. - Alternatively, instead of using an archive file, you can - :binary:`~bin.mongodump` the ``test`` database to the standard - output stream and pipe into :binary:`~bin.mongorestore`: + Alternatively, instead of using an archive file, you can + :binary:`~bin.mongodump` the ``test`` database to the standard + output stream and pipe into :binary:`~bin.mongorestore`: - .. code-block:: sh + .. code-block:: sh - mongodump --archive --db=test | mongorestore --archive --nsFrom='test.*' --nsTo='examples.*' + mongodump --archive --db=test | mongorestore --archive --nsFrom='test.*' --nsTo='examples.*' ... \ No newline at end of file diff --git a/source/includes/extracts-concurrency-consistency-recency.yaml b/source/includes/extracts-concurrency-consistency-recency.yaml index 8eba8848f59..e36a924845f 100644 --- a/source/includes/extracts-concurrency-consistency-recency.yaml +++ b/source/includes/extracts-concurrency-consistency-recency.yaml @@ -146,7 +146,7 @@ content: | With :rsconf:`writeConcernMajorityJournalDefault` set to ``false``, MongoDB does not wait for :writeconcern:`w: "majority" <"majority">` writes to be written to the on-disk journal before acknowledging the - writes. As such, :writeconcern:`majority` write operations could + writes. As such, :writeconcern:`"majority"` write operations could possibly roll back in the event of a transient loss (e.g. crash and restart) of a majority of nodes in a given replica set. diff --git a/source/includes/extracts-enterprise.yaml b/source/includes/extracts-enterprise.yaml index bba135f2983..3e9a01fb538 100644 --- a/source/includes/extracts-enterprise.yaml +++ b/source/includes/extracts-enterprise.yaml @@ -36,106 +36,96 @@ content: | name: Linux (Package Manager) content: | - .. container:: + If you have installed MongoDB Community using a package + manager, follow the package manager instructions for your + operating system: - If you have installed MongoDB Community using a package - manager, follow the package manager instructions for your - operating system: + - :doc:`Red Hat Enterprise or CentOS ` - - :doc:`Red Hat Enterprise or CentOS ` + - :doc:`Ubuntu ` - - :doc:`Ubuntu ` + - :doc:`Debian ` - - :doc:`Debian ` + - :doc:`SUSE ` - - :doc:`SUSE ` + - :doc:`Amazon Linux ` - - :doc:`Amazon Linux ` - - During the installation, the package manager will remove the - community packages; this will not affect the running - deployment until you restart. + During the installation, the package manager will remove the + community packages; this will not affect the running + deployment until you restart. - id: linux-manual name: Linux (Manual Download) content: | - .. container:: - - If you have not installed MongoDB using a package manager, - you can manually download the MongoDB binaries from the - `MongoDB Download Center - `__. Follow - the manual instructions, including specific prerequisites - for MongoDB Enterprise, for your operating system: - - .. important:: + If you have not installed MongoDB using a package manager, + you can manually download the MongoDB binaries from the + `MongoDB Download Center + `__. Follow + the manual instructions, including specific prerequisites + for MongoDB Enterprise, for your operating system: - Install to a location different from that of your current - Community edition. - - In the upgrade procedure, you will use the existing data - directory and, if applicable, the existing configuration - file. + .. important:: - - :doc:`Red Hat Enterprise or CentOS ` + Install to a location different from that of your current + Community edition. + + In the upgrade procedure, you will use the existing data + directory and, if applicable, the existing configuration + file. - - :doc:`Ubuntu ` + - :doc:`Red Hat Enterprise or CentOS ` - - :doc:`Debian ` + - :doc:`Ubuntu ` - - :doc:`SUSE ` + - :doc:`Debian ` - - :doc:`Amazon Linux ` + - :doc:`SUSE ` - + - :doc:`Amazon Linux ` - id: windows name: Windows content: | - .. container:: - - .. important:: - - You cannot use the ``.msi`` to install the Enterprise - edition if you have the Community edition of the same - release series installed on the same machine. That is, if - you have version 4.4.0 Community edition installed, you - cannot use the ``.msi`` to install the 4.4.0 or 4.4.1 - Enterprise edition. - - 1. Manually download the archive file from the `MongoDB - Download Center - `__. - - #. | To install, extract/unzip the file to a location - different from that of your current Community - edition. - - | In the upgrade procedure, you will use the existing - data directory and, if applicable, the existing - configuration file. + .. important:: + + You cannot use the ``.msi`` to install the Enterprise + edition if you have the Community edition of the same + release series installed on the same machine. That is, if + you have version 4.4.0 Community edition installed, you + cannot use the ``.msi`` to install the 4.4.0 or 4.4.1 + Enterprise edition. + + 1. Manually download the archive file from the `MongoDB + Download Center + `__. + + #. To install, extract/unzip the file to a location + different from that of your current Community + edition. + + In the upgrade procedure, you will use the existing + data directory and, if applicable, the existing + configuration file. - id: macos name: macOS content: | - .. container:: + Install the binaries: - Install the binaries: + 1. Manually download the archive file from the `MongoDB + Download Center + `__. - 1. Manually download the archive file from the `MongoDB - Download Center - `__. + #. Extract the files to a location different + from that of your current Community edition. For + details on extracting the files, see :doc:`macOS + `. - #. | Extract the files to a location different - from that of your current Community edition. For - details on extracting the files, see :doc:`macOS - `. + In the upgrade procedure, you will use the existing + data directory and, if applicable, the existing + configuration file. - | In the upgrade procedure, you will use the existing - data directory and, if applicable, the existing - configuration file. - ... diff --git a/source/includes/extracts-export-tools-performance-considerations-base.yaml b/source/includes/extracts-export-tools-performance-considerations-base.yaml index d93bc4999ab..3216592e7ac 100644 --- a/source/includes/extracts-export-tools-performance-considerations-base.yaml +++ b/source/includes/extracts-export-tools-performance-considerations-base.yaml @@ -25,7 +25,9 @@ content: | - Ensure that your backups are usable by restoring them to a test MongoDB deployment. - .. seealso:: :doc:`/core/backups` and :mms-docs:`MongoDB Cloud Manager Backup documentation ` + .. seealso:: + + :doc:`/core/backups` and :mms-docs:`MongoDB Cloud Manager Backup documentation ` for more information on backing up MongoDB instances. Additionally, consider the following reference documentation for the MongoDB import/export tools: diff --git a/source/includes/extracts-export-tools-performance-considerations.yaml b/source/includes/extracts-export-tools-performance-considerations.yaml index 04a0eecc601..01bec7e645c 100644 --- a/source/includes/extracts-export-tools-performance-considerations.yaml +++ b/source/includes/extracts-export-tools-performance-considerations.yaml @@ -3,10 +3,10 @@ source: file: extracts-export-tools-performance-considerations-base.yaml ref: _tools-performance-considerations replacement: - out_tool: ":binary:`~bin.mongodump`" - in_tool: ":binary:`~bin.mongorestore`" + out_tool: ":binary:`mongodump`" + in_tool: ":binary:`mongorestore`" mongoDumpBullet: | - - Use :option:`--oplog ` to capture incoming write operations during + - Use :option:`--oplog ` to capture incoming write operations during the {{out_tool}} operation to ensure that the backups reflect a consistent data state. --- @@ -15,7 +15,7 @@ source: file: extracts-export-tools-performance-considerations-base.yaml ref: _tools-performance-considerations replacement: - out_tool: "program:`mongoexport`" - in_tool: "program:`mongoimport`" + out_tool: ":program:`mongoexport`" + in_tool: ":program:`mongoimport`" mongoDumpBullet: "" ... diff --git a/source/includes/extracts-fact-aggregation-accumulator-base.yaml b/source/includes/extracts-fact-aggregation-accumulator-base.yaml index 94e1310513f..0a5df666e08 100644 --- a/source/includes/extracts-fact-aggregation-accumulator-base.yaml +++ b/source/includes/extracts-fact-aggregation-accumulator-base.yaml @@ -20,7 +20,7 @@ content: | - :pipeline:`$replaceWith` (Available starting in MongoDB 4.2) - - :pipeline:`$match` stage that includes an :expression:`$expr` expression + - :pipeline:`$match` stage that includes an :query:`$expr` expression --- ref: _fact-agg-accumulator-availability-change @@ -40,7 +40,7 @@ content: | - :pipeline:`$replaceWith` (Available starting in MongoDB 4.2) - - :pipeline:`$match` stage that includes an :expression:`$expr` expression + - :pipeline:`$match` stage that includes an :query:`$expr` expression In MongoDB 3.2 and earlier, {{accumulator}} is available in the :pipeline:`$group` stage only. diff --git a/source/includes/extracts-listCollections-auth.yaml b/source/includes/extracts-listCollections-auth.yaml index 4416c708e73..570f5364df6 100644 --- a/source/includes/extracts-listCollections-auth.yaml +++ b/source/includes/extracts-listCollections-auth.yaml @@ -12,7 +12,7 @@ content: | { resource: { db: "test", collection: "" }, actions: [ "listCollections" ] } The built-in role :authrole:`read` provides the privilege to run - :dbcommand:`listCollection` for a specific database. + :dbcommand:`listCollections` for a specific database. Starting in version 4.0, however, user without the required privilege can run the command with **both** ``authorizedCollections`` and @@ -68,7 +68,7 @@ content: | ``authorizedCollections`` and ``nameOnly`` options, - A user must have the required access to run - :dbcommand:`listCollection`. + :dbcommand:`listCollections`. - If a user does not have required access and runs ``show collections``, MongoDB uses the diff --git a/source/includes/extracts-mongo-shell-deprecated-meta-operator.yaml b/source/includes/extracts-mongo-shell-deprecated-meta-operator.yaml index 69996a7837c..ae43c095fac 100644 --- a/source/includes/extracts-mongo-shell-deprecated-meta-operator.yaml +++ b/source/includes/extracts-mongo-shell-deprecated-meta-operator.yaml @@ -1,8 +1,8 @@ ref: _mongo-shell-deprecated-meta-operator content: | - .. admonition:: Deprecated since {{version}} - :class: note + .. note:: Deprecated since {{version}} + Starting in v3.2, the {{op}} operator is deprecated in the :binary:`~bin.mongo` shell. In the :binary:`~bin.mongo` shell, diff --git a/source/includes/extracts-parent-admonition-js-prevalence.yaml b/source/includes/extracts-parent-admonition-js-prevalence.yaml index 5d2c2243ac7..09bf4911816 100644 --- a/source/includes/extracts-parent-admonition-js-prevalence.yaml +++ b/source/includes/extracts-parent-admonition-js-prevalence.yaml @@ -2,10 +2,10 @@ ref: _admonition-js-prevalence content: | - .. admonition:: JavaScript in MongoDB + .. note:: JavaScript in MongoDB Although {{javascriptUsingOperation}} JavaScript, most interactions with MongoDB do not use JavaScript but use an - :ecosystem:`idiomatic driver ` in the language + :driver:`idiomatic driver ` in the language of the interacting application. ... \ No newline at end of file diff --git a/source/includes/extracts-parent-fact-count-on-sharded-clusters.yaml b/source/includes/extracts-parent-fact-count-on-sharded-clusters.yaml index 33b3ff3979b..85bdd1d7f91 100644 --- a/source/includes/extracts-parent-fact-count-on-sharded-clusters.yaml +++ b/source/includes/extracts-parent-fact-count-on-sharded-clusters.yaml @@ -26,6 +26,9 @@ content: | { $project: { _id: 0 } } ] ) - .. seealso:: :pipeline:`$collStats` to return an approximate count based on the collection's metadata. + .. seealso:: + + :pipeline:`$collStats` to return an approximate count based on the collection's metadata. + ... \ No newline at end of file diff --git a/source/includes/extracts-projection.yaml b/source/includes/extracts-projection.yaml index 9145279a98a..3671fee1fa1 100644 --- a/source/includes/extracts-projection.yaml +++ b/source/includes/extracts-projection.yaml @@ -287,8 +287,8 @@ content: | ref: projection-language-consistency-admonition content: | - .. admonition:: Language Consistency - :class: important + .. important:: Language Consistency + Starting in MongoDB 4.4, as part of making :method:`~db.collection.find` and diff --git a/source/includes/extracts-server-status-projection-base.yaml b/source/includes/extracts-server-status-projection-base.yaml index cdd328b8130..f0eb28331d9 100644 --- a/source/includes/extracts-server-status-projection-base.yaml +++ b/source/includes/extracts-server-status-projection-base.yaml @@ -137,7 +137,7 @@ content: | - Starting in MongoDB 4.2.1 (and 4.0.13), {{operationName}} includes: - - :serverstatus:`electionMetrics` + - :ref:`electionMetrics ` - Starting in MongoDB 4.2, {{operationName}}: diff --git a/source/includes/extracts-transactions.yaml b/source/includes/extracts-transactions.yaml index ab1de4e5b4a..3c5a53db99a 100644 --- a/source/includes/extracts-transactions.yaml +++ b/source/includes/extracts-transactions.yaml @@ -485,7 +485,7 @@ content: | If the transaction writes to multiple shards, then during the commit attempt across the shards - - Outside reads that use read concern :readconcern:`snapshot` or + - Outside reads that use read concern :readconcern:`"snapshot"` or :readconcern:`"linearizable"`, or are part of causally consistent sessions (i.e. include :ref:`afterClusterTime `) wait for all writes of a transaction to be visible. @@ -606,7 +606,9 @@ content: | In MongoDB 4.2 and earlier, the operation must be run on an existing collection. - .. seealso:: :ref:`transactions-create-collections-indexes` + .. seealso:: + + :ref:`transactions-create-collections-indexes` --- ref: transactions-insert-implicit-collection-creation content: | @@ -623,7 +625,9 @@ content: | In MongoDB 4.4 and earlier, the operation must be run on an existing collection. - .. seealso:: :ref:`transactions-create-collections-indexes` + .. seealso:: + + :ref:`transactions-create-collections-indexes` --- ref: transactions-explicit-ddl @@ -637,6 +641,8 @@ content: | concern :readconcern:`"local"`. If you specify a read concern level other than :readconcern:`"local"`, the transaction fails. - .. seealso:: :ref:`transactions-create-collections-indexes` + .. seealso:: + + :ref:`transactions-create-collections-indexes` ... diff --git a/source/includes/extracts-views.yaml b/source/includes/extracts-views.yaml index 186ae74f9ca..f68bc2673db 100644 --- a/source/includes/extracts-views.yaml +++ b/source/includes/extracts-views.yaml @@ -118,7 +118,7 @@ content: | - :projection:`$` - :projection:`$elemMatch` - :projection:`$slice` - - :projection:`$meta` + - :expression:`$meta` --- ref: _views-unsupported-projection content: | @@ -150,7 +150,7 @@ inherit: ref: _views-unsupported-projection file: extracts-views.yaml replacement: - projection: ":projection:`$meta`" + projection: ":expression:`$meta`" --- ref: views-collation-behavior content: | diff --git a/source/includes/fact-agg-memory-limit.rst b/source/includes/fact-agg-memory-limit.rst index d835f256f5a..f77dd6a65a7 100644 --- a/source/includes/fact-agg-memory-limit.rst +++ b/source/includes/fact-agg-memory-limit.rst @@ -16,4 +16,7 @@ aggregation pipeline stages to write data to temporary files. .. include:: /includes/extracts/4.2-changes-usedDisk.rst -.. seealso:: :ref:`sort-memory-limit` and :ref:`group-memory-limit`. +.. seealso:: + + :ref:`sort-memory-limit` and :ref:`group-memory-limit`. + diff --git a/source/includes/fact-atlas-banner.rst b/source/includes/fact-atlas-banner.rst index 408bec4b5b3..008a16e2c11 100644 --- a/source/includes/fact-atlas-banner.rst +++ b/source/includes/fact-atlas-banner.rst @@ -1,8 +1,5 @@ -.. admonition:: MongoDB Atlas - :class: note +.. note:: MongoDB Atlas - .. container:: - - `MongoDB Atlas `_ - is a hosted MongoDB service option in the cloud which requires no - installation overhead and offers a free tier to get started. + `MongoDB Atlas `_ + is a hosted MongoDB service option in the cloud which requires no + installation overhead and offers a free tier to get started. diff --git a/source/includes/fact-atlas-search-banner.rst b/source/includes/fact-atlas-search-banner.rst index fc46272d1e5..9edcceed366 100644 --- a/source/includes/fact-atlas-search-banner.rst +++ b/source/includes/fact-atlas-search-banner.rst @@ -1,5 +1,5 @@ -.. admonition:: MongoDB Atlas Search - :class: note +.. note:: MongoDB Atlas Search + :atlas:`Atlas Search ` makes it easy to build fast, relevance-based search capabilities on top of your MongoDB data. Try diff --git a/source/includes/fact-bulk-operation-batches.rst b/source/includes/fact-bulk-operation-batches.rst index 1bf08e06914..31129bfbc68 100644 --- a/source/includes/fact-bulk-operation-batches.rst +++ b/source/includes/fact-bulk-operation-batches.rst @@ -1,8 +1,8 @@ -Each group of operations can have at most :limit:`1000 operations `. If a group exceeds this :limit:`limit -`, MongoDB will divide the group into -smaller groups of 1000 or less. For example, if the bulk operations list -consists of 2000 insert operations, MongoDB creates 2 groups, each with -1000 operations. +Each group of operations can have at most :limit:`1000 operations `. If a group exceeds this +:limit:`limit `, MongoDB will divide +the group into smaller groups of 1000 or less. For example, if the bulk +operations list consists of 2000 insert operations, MongoDB creates 2 +groups, each with 1000 operations. The sizes and grouping mechanics are internal performance details and are subject to change in future versions. diff --git a/source/includes/fact-bulkwrite-operation-batches.rst b/source/includes/fact-bulkwrite-operation-batches.rst index ba64f975ef5..1ac92e29f53 100644 --- a/source/includes/fact-bulkwrite-operation-batches.rst +++ b/source/includes/fact-bulkwrite-operation-batches.rst @@ -4,7 +4,7 @@ the database. As of MongoDB 3.6, this value is ``100,000``. This value is shown in the :data:`isMaster.maxWriteBatchSize` field. This limit prevents issues with oversized error messages. If a group -exceeds this :limit:`limit`, +exceeds this :limit:`limit `, the client driver divides the group into smaller groups with counts less than or equal to the value of the limit. For example, with the ``maxWriteBatchSize`` value of ``100,000``, if the queue consists of @@ -25,4 +25,4 @@ string. Currently, begins once there are at least 2 error messages with total size greater than ``1MB``. The sizes and grouping mechanics are internal performance details and -are subject to change in future versions. \ No newline at end of file +are subject to change in future versions. diff --git a/source/includes/fact-config-server-replica-set-restrictions.rst b/source/includes/fact-config-server-replica-set-restrictions.rst index 088a319a20b..f685efd9636 100644 --- a/source/includes/fact-config-server-replica-set-restrictions.rst +++ b/source/includes/fact-config-server-replica-set-restrictions.rst @@ -7,5 +7,4 @@ for config servers: `. - Must build indexes (i.e. no member should have - :data:`~replSetGetConfig.members[n].buildIndexes` setting set to - false). + :rsconf:`members[n].buildIndexes` setting set to false). diff --git a/source/includes/fact-document-max-size.rst b/source/includes/fact-document-max-size.rst index 21bda658d97..df7d1d8a174 100644 --- a/source/includes/fact-document-max-size.rst +++ b/source/includes/fact-document-max-size.rst @@ -4,5 +4,5 @@ The maximum document size helps ensure that a single document cannot use excessive amount of RAM or, during transmission, excessive amount of bandwidth. To store documents larger than the maximum size, MongoDB provides the GridFS API. See :binary:`~bin.mongofiles` and the -documentation for your :ecosystem:`driver ` for more +documentation for your :driver:`driver ` for more information about GridFS. diff --git a/source/includes/fact-download-mongo-shell.rst b/source/includes/fact-download-mongo-shell.rst index 0954611b0da..53108a76a33 100644 --- a/source/includes/fact-download-mongo-shell.rst +++ b/source/includes/fact-download-mongo-shell.rst @@ -21,29 +21,27 @@ a standalone package by following these steps: 3. Select the :guilabel:`Package` to download according to your platform: - .. container:: + .. list-table:: + :header-rows: 1 + :widths: 15 85 - .. list-table:: - :header-rows: 1 - :widths: 15 85 + * - Platform + - Download Package - * - Platform - - Download Package + * - *Windows* - * - *Windows* + - Select the ``zip`` package to download an archive which + includes the :binary:`~bin.mongo` shell. - - Select the ``zip`` package to download an archive which - includes the :binary:`~bin.mongo` shell. + * - *macOS* - * - *macOS* + - Select the ``tgz`` package to download an archive which + includes the :binary:`~bin.mongo` shell. - - Select the ``tgz`` package to download an archive which - includes the :binary:`~bin.mongo` shell. + * - *Linux* - * - *Linux* - - - Select the ``tgz`` package to download the - :binary:`~bin.mongo` shell. + - Select the ``tgz`` package to download the + :binary:`~bin.mongo` shell. 4. Copy the :binary:`~bin.mongo` shell from the archive to a location on your filesystem. diff --git a/source/includes/fact-enterprise-only-admonition.rst b/source/includes/fact-enterprise-only-admonition.rst index 139be75557c..6d1daf9c37b 100644 --- a/source/includes/fact-enterprise-only-admonition.rst +++ b/source/includes/fact-enterprise-only-admonition.rst @@ -1,3 +1,3 @@ -.. admonition:: Enterprise Feature +.. note:: Enterprise Feature Available in MongoDB Enterprise only. diff --git a/source/includes/fact-explain-methods-differences.rst b/source/includes/fact-explain-methods-differences.rst index cfd8fd9a85a..669bcedf2f7 100644 --- a/source/includes/fact-explain-methods-differences.rst +++ b/source/includes/fact-explain-methods-differences.rst @@ -1,12 +1,12 @@ -:method:`db.collection.explain().find()` is similar to +:method:`db.collection.explain().find() ` is similar to :method:`db.collection.find().explain() ` with the following key differences: -- The :method:`db.collection.explain().find()` construct allows for the +- The :method:`db.collection.explain().find() ` construct allows for the additional chaining of query modifiers. For list of query modifiers, see :ref:`db.collection.explain().find().help() `. -- The :method:`db.collection.explain().find()` returns a cursor, which +- The :method:`db.collection.explain().find() ` returns a cursor, which requires a call to ``.next()``, or its alias ``.finish()``, to return the ``explain()`` results. If run interactively in the :binary:`~bin.mongo` shell, the diff --git a/source/includes/fact-log-slow-queries.rst b/source/includes/fact-log-slow-queries.rst index ddec121c616..1514b50f1e7 100644 --- a/source/includes/fact-log-slow-queries.rst +++ b/source/includes/fact-log-slow-queries.rst @@ -1,16 +1,16 @@ .. COMMENT: When included as part of options/settings, this is used by mongod and configuration file and not mongos. For mongos, see options-mongos.yaml. This file is however included in other files where distinction between mongod/mongos is sufficient. -When :setting:`~param.logLevel` is set to ``0``, MongoDB records *slow* +When :parameter:`logLevel` is set to ``0``, MongoDB records *slow* operations to the diagnostic log at a rate determined by :setting:`~operationProfiling.slowOpSampleRate`. Starting in MongoDB 4.2, the secondaries of replica sets log :ref:`all oplog entry messages that take longer than the slow operation threshold to apply ` regardless of the sample rate. -At higher :setting:`~param.logLevel` settings, all operations appear in +At higher :parameter:`logLevel` settings, all operations appear in the diagnostic log regardless of their latency with the following exception: the logging of :ref:`slow oplog entry messages by the secondaries `. The secondaries log only the slow oplog -entries; increasing the :setting:`~param.logLevel` does not log all +entries; increasing the :parameter:`logLevel` does not log all oplog entries. \ No newline at end of file diff --git a/source/includes/fact-meta-operator-disambiguation.rst b/source/includes/fact-meta-operator-disambiguation.rst index b0ea6a55e6b..2acd4818746 100644 --- a/source/includes/fact-meta-operator-disambiguation.rst +++ b/source/includes/fact-meta-operator-disambiguation.rst @@ -1,4 +1,4 @@ -The behavior and requirements of the :projection:`$meta` projection +The behavior and requirements of the :expression:`$meta` projection operator differ from that of the :expression:`$meta` aggregation operator. For details on the :expression:`$meta` aggregation operator, see the :expression:`$meta` aggregation operator reference page. diff --git a/source/includes/fact-mongo-shell-method-toc.rst b/source/includes/fact-mongo-shell-method-toc.rst index 0202d69ab82..de9cbc54114 100644 --- a/source/includes/fact-mongo-shell-method-toc.rst +++ b/source/includes/fact-mongo-shell-method-toc.rst @@ -1,5 +1,5 @@ The methods listed on this table of contents page refer to the :binary:`~bin.mongo` shell methods, and *not* to the MongoDB Node.js driver (or any other driver) methods. For corresponding MongoDB driver -API, refer to your specific :ecosystem:`MongoDB driver ` +API, refer to your specific :driver:`MongoDB driver ` documentation instead. diff --git a/source/includes/fact-mongo-shell-method.rst b/source/includes/fact-mongo-shell-method.rst index 8b4989a81be..2320429354e 100644 --- a/source/includes/fact-mongo-shell-method.rst +++ b/source/includes/fact-mongo-shell-method.rst @@ -1,7 +1,7 @@ -.. admonition:: ``mongo`` Shell Method - :class: important +.. important:: ``mongo`` Shell Method + This page documents the :binary:`~bin.mongo` shell method, and does *not* refer to the MongoDB Node.js driver (or any other driver) method. For corresponding MongoDB driver API, refer to your specific - :ecosystem:`MongoDB driver ` documentation instead. + :driver:`MongoDB driver ` documentation instead. diff --git a/source/includes/fact-mws-intro.rst b/source/includes/fact-mws-intro.rst new file mode 100644 index 00000000000..f0f7330978b --- /dev/null +++ b/source/includes/fact-mws-intro.rst @@ -0,0 +1 @@ +You can run the operation in the web shell below: diff --git a/source/includes/fact-mws.rst b/source/includes/fact-mws.rst index 22dae3d8ba1..ac43e033852 100644 --- a/source/includes/fact-mws.rst +++ b/source/includes/fact-mws.rst @@ -1,3 +1,2 @@ -.. raw:: html - - +.. mongo-web-shell:: + :version: 4.2 diff --git a/source/includes/fact-olson-tz-behavior.rst b/source/includes/fact-olson-tz-behavior.rst index 555c2460140..6a0d8df9a64 100644 --- a/source/includes/fact-olson-tz-behavior.rst +++ b/source/includes/fact-olson-tz-behavior.rst @@ -19,7 +19,6 @@ offset for the Olson Timezone Identifier. The example uses the :expression:`$hour` and :expression:`$minute` operators to return the corresponding portions of the ``date`` field: -.. cssclass:: copyable-code .. code-block:: javascript db.sales.aggregate([ diff --git a/source/includes/fact-query-min-max.rst b/source/includes/fact-query-min-max.rst index dbd46a76c04..2e234a461e0 100644 --- a/source/includes/fact-query-min-max.rst +++ b/source/includes/fact-query-min-max.rst @@ -1,7 +1,7 @@ -The :operator:`min` and :operator:`max` operators indicate that the system +The :operator:`$min` and :operator:`$max` operators indicate that the system should avoid normal query planning. Instead they construct an index scan where the index bounds are explicitly specified by the values given in -:operator:`min` and :operator:`max`. +:operator:`$min` and :operator:`$max`. .. warning:: diff --git a/source/includes/fact-replica-set-sync-prefers-non-hidden.rst b/source/includes/fact-replica-set-sync-prefers-non-hidden.rst index 668f4df3cad..f18452ce963 100644 --- a/source/includes/fact-replica-set-sync-prefers-non-hidden.rst +++ b/source/includes/fact-replica-set-sync-prefers-non-hidden.rst @@ -7,4 +7,6 @@ resort. If you want a secondary to sync from a hidden member, use the sync target. See the documentation for :dbcommand:`replSetSyncFrom` before using the command. -.. seealso:: :doc:`/tutorial/manage-chained-replication` +.. seealso:: + + :doc:`/tutorial/manage-chained-replication` diff --git a/source/includes/fact-rs-status-init-sync-availability.rst b/source/includes/fact-rs-status-init-sync-availability.rst index c66e5b38c67..9d3719845c4 100644 --- a/source/includes/fact-rs-status-init-sync-availability.rst +++ b/source/includes/fact-rs-status-init-sync-availability.rst @@ -1,5 +1,5 @@ -.. admonition:: Availability - :class: important +.. important:: Availability + Starting in MongoDB 4.2.1, :data:`replSetGetStatus.initialSyncStatus` metrics are only diff --git a/source/includes/fact-selinux-redhat-options.rst b/source/includes/fact-selinux-redhat-options.rst index 4b20bd4d2b2..b3a0cfcb395 100644 --- a/source/includes/fact-selinux-redhat-options.rst +++ b/source/includes/fact-selinux-redhat-options.rst @@ -6,50 +6,48 @@ Permit Access to ``cgroup`` +++++++++++++++++++++++++++ -.. container:: - - The current SELinux Policy does not allow the MongoDB process to - access ``/sys/fs/cgroup``, which is required to determine - the available memory on your system. If you intend to run SELinux in - ``enforcing`` mode, you will need to make the following adjustment - to your SELinux policy: +The current SELinux Policy does not allow the MongoDB process to +access ``/sys/fs/cgroup``, which is required to determine +the available memory on your system. If you intend to run SELinux in +``enforcing`` mode, you will need to make the following adjustment +to your SELinux policy: - #. Ensure your system has the ``checkpolicy`` package installed: +#. Ensure your system has the ``checkpolicy`` package installed: - .. code-block:: sh + .. code-block:: sh - sudo yum install checkpolicy + sudo yum install checkpolicy - #. Create a custom policy file :file:`mongodb_cgroup_memory.te`: +#. Create a custom policy file :file:`mongodb_cgroup_memory.te`: - .. code-block:: sh + .. code-block:: sh - cat > mongodb_cgroup_memory.te < mongodb_cgroup_memory.te < + sudo semanage fcontext -a -t - where specify one of the following types as appropriate: + where specify one of the following types as appropriate: - - ``mongod_var_lib_t`` for data directory + - ``mongod_var_lib_t`` for data directory - - ``mongod_log_t`` for log file directory + - ``mongod_log_t`` for log file directory - - ``mongod_var_run_t`` for pid file directory + - ``mongod_var_run_t`` for pid file directory - .. note:: + .. note:: - Be sure to include the ``.*`` at the end of the directory. + Be sure to include the ``.*`` at the end of the directory. - #. Update the SELinux user policy for the new directory: +#. Update the SELinux user policy for the new directory: - .. code-block:: sh + .. code-block:: sh - sudo chcon -Rv -u system_u -t + sudo chcon -Rv -u system_u -t - where specify one of the following types as appropriate: + where specify one of the following types as appropriate: - - ``mongod_var_lib_t`` for data directory + - ``mongod_var_lib_t`` for data directory - - ``mongod_log_t`` for log directory + - ``mongod_log_t`` for log directory - - ``mongod_var_run_t`` for pid file directory + - ``mongod_var_run_t`` for pid file directory - #. Apply the updated SELinux policies to the directory: +#. Apply the updated SELinux policies to the directory: - .. code-block:: sh + .. code-block:: sh - restorecon -R -v + restorecon -R -v - For example: +For example: - .. tip:: +.. tip:: - Be sure to include the ``.*`` at the end of the directory for the - ``semanage fcontext`` operations. + Be sure to include the ``.*`` at the end of the directory for the + ``semanage fcontext`` operations. - - If using a non-default MongoDB data path of ``/mongodb/data``: +- If using a non-default MongoDB data path of ``/mongodb/data``: - .. code-block:: sh + .. code-block:: sh - sudo semanage fcontext -a -t mongod_var_lib_t '/mongodb/data.*' - sudo chcon -Rv -u system_u -t mongod_var_lib_t '/mongodb/data' - restorecon -R -v '/mongodb/data' + sudo semanage fcontext -a -t mongod_var_lib_t '/mongodb/data.*' + sudo chcon -Rv -u system_u -t mongod_var_lib_t '/mongodb/data' + restorecon -R -v '/mongodb/data' - - If using a non-default MongoDB log directory of ``/mongodb/log`` - (e.g. if the log file path is ``/mongodb/log/mongod.log``): +- If using a non-default MongoDB log directory of ``/mongodb/log`` + (e.g. if the log file path is ``/mongodb/log/mongod.log``): - .. code-block:: sh + .. code-block:: sh - sudo semanage fcontext -a -t mongod_log_t '/mongodb/log.*' - sudo chcon -Rv -u system_u -t mongod_log_t '/mongodb/log' - restorecon -R -v '/mongodb/log' + sudo semanage fcontext -a -t mongod_log_t '/mongodb/log.*' + sudo chcon -Rv -u system_u -t mongod_log_t '/mongodb/log' + restorecon -R -v '/mongodb/log' Using a Custom MongoDB Port +++++++++++++++++++++++++++ -.. container:: - - .. code-block:: sh +.. code-block:: sh - sudo semanage port -a -t mongod_port_t -p tcp + sudo semanage port -a -t mongod_port_t -p tcp diff --git a/source/includes/fact-snmp-run-mongodb-as-snmp-master.rst b/source/includes/fact-snmp-run-mongodb-as-snmp-master.rst index 8c15c779152..7389f2e0b87 100644 --- a/source/includes/fact-snmp-run-mongodb-as-snmp-master.rst +++ b/source/includes/fact-snmp-run-mongodb-as-snmp-master.rst @@ -1,4 +1,5 @@ -You can run |mongod-program| with the :setting:`snmp-master` -option for testing purposes. To do this, use the SNMP master -configuration file instead of the subagent configuration file. From -the directory containing the unpacked MongoDB installation files: +You can run |mongod-program| with the +:option:`snmp-master ` option for testing +purposes. To do this, use the SNMP master configuration file instead of +the subagent configuration file. From the directory containing the +unpacked MongoDB installation files: diff --git a/source/includes/fact-sparse-index-hint-count.rst b/source/includes/fact-sparse-index-hint-count.rst index 98325edf1be..09ef941daa7 100644 --- a/source/includes/fact-sparse-index-hint-count.rst +++ b/source/includes/fact-sparse-index-hint-count.rst @@ -1,4 +1,4 @@ -If you include a :method:`~db.cursor.hint()` that specifies a +If you include a :method:`~cursor.hint()` that specifies a :ref:`sparse index ` when you perform a :method:`~cursor.count()` of all documents in a collection (i.e. with an empty query predicate), the sparse index is used even if the sparse @@ -11,7 +11,7 @@ index results in an incorrect count. db.collection.find().hint( { x: 1 } ).count(); -To obtain the correct count, do not :method:`~db.cursor.hint()` with a +To obtain the correct count, do not :method:`~cursor.hint()` with a :ref:`sparse index ` when performing a count of all documents in a collection. diff --git a/source/includes/fact-support.rst b/source/includes/fact-support.rst index 2a08d941d06..33a22085c1b 100644 --- a/source/includes/fact-support.rst +++ b/source/includes/fact-support.rst @@ -1,27 +1,21 @@ MongoDB Community ~~~~~~~~~~~~~~~~~ -.. container:: - - For questions, discussions, or general technical support, visit the - `MongoDB Community Forums - `_. - The MongoDB Community Forums are a centralized place to connect with - other MongoDB users, ask questions, and get answers. +For questions, discussions, or general technical support, visit the +`MongoDB Community Forums +`_. +The MongoDB Community Forums are a centralized place to connect with +other MongoDB users, ask questions, and get answers. MongoDB Atlas or Cloud Manager ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - For technical support questions, please log into your `MongoDB Cloud - account `_ and open a - support ticket. +For technical support questions, please log into your `MongoDB Cloud +account `_ and open a +support ticket. MongoDB Enterprise or Ops Manager ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - For technical support questions, please file a ticket through the - `MongoDB Support Portal `_. +For technical support questions, please file a ticket through the +`MongoDB Support Portal `_. diff --git a/source/includes/fact-systemd-vs-initd.rst b/source/includes/fact-systemd-vs-initd.rst index 252285e8a98..2a07cea3501 100644 --- a/source/includes/fact-systemd-vs-initd.rst +++ b/source/includes/fact-systemd-vs-initd.rst @@ -7,11 +7,9 @@ the ``service`` command). If you are unsure which init system your platform uses, run the following command: -.. container:: +.. code-block:: sh - .. code-block:: sh - - ps --no-headers -o comm 1 + ps --no-headers -o comm 1 Then select the appropriate tab below based on the result: diff --git a/source/includes/fact-tcp-keepalive-linux.rst b/source/includes/fact-tcp-keepalive-linux.rst index 6a39e5f7aab..7e4261303c5 100644 --- a/source/includes/fact-tcp-keepalive-linux.rst +++ b/source/includes/fact-tcp-keepalive-linux.rst @@ -1,48 +1,44 @@ - To view the keepalive setting on Linux, use one of the following commands: - .. container:: + .. code-block:: sh - .. code-block:: sh + sysctl net.ipv4.tcp_keepalive_time - sysctl net.ipv4.tcp_keepalive_time + Or: - Or: + .. code-block:: sh - .. code-block:: sh + cat /proc/sys/net/ipv4/tcp_keepalive_time - cat /proc/sys/net/ipv4/tcp_keepalive_time + The value is measured in seconds. - The value is measured in seconds. + .. note:: - .. note:: - - Although the setting name includes ``ipv4``, the - ``tcp_keepalive_time`` value applies to both IPv4 and IPv6. + Although the setting name includes ``ipv4``, the + ``tcp_keepalive_time`` value applies to both IPv4 and IPv6. - To change the ``tcp_keepalive_time`` value, you can use one of the following commands, supplying a ** in seconds: - .. container:: - - .. code-block:: sh + .. code-block:: sh - sudo sysctl -w net.ipv4.tcp_keepalive_time= + sudo sysctl -w net.ipv4.tcp_keepalive_time= - Or: + Or: - .. code-block:: sh + .. code-block:: sh - echo | sudo tee /proc/sys/net/ipv4/tcp_keepalive_time + echo | sudo tee /proc/sys/net/ipv4/tcp_keepalive_time - These operations do not persist across system reboots. To persist - the setting, add the following line to ``/etc/sysctl.conf``, - supplying a ** in seconds, and reboot the machine: + These operations do not persist across system reboots. To persist + the setting, add the following line to ``/etc/sysctl.conf``, + supplying a ** in seconds, and reboot the machine: - .. code-block:: sh + .. code-block:: sh - net.ipv4.tcp_keepalive_time = + net.ipv4.tcp_keepalive_time = - Keepalive values greater than ``300`` seconds, - (5 minutes) will be overridden on :binary:`~bin.mongod` and - :binary:`~bin.mongos` sockets and set to ``300`` seconds. + Keepalive values greater than ``300`` seconds, + (5 minutes) will be overridden on :binary:`~bin.mongod` and + :binary:`~bin.mongos` sockets and set to ``300`` seconds. diff --git a/source/includes/fact-text-index-weight.rst b/source/includes/fact-text-index-weight.rst index 2e90280b9f5..d887bb95c42 100644 --- a/source/includes/fact-text-index-weight.rst +++ b/source/includes/fact-text-index-weight.rst @@ -4,7 +4,7 @@ of the text search score. For each indexed field in the document, MongoDB multiplies the number of matches by the weight and sums the results. Using this sum, MongoDB -then calculates the score for the document. See :projection:`$meta` +then calculates the score for the document. See :expression:`$meta` operator for details on returning and sorting by text scores. The default weight is 1 for the indexed fields. To adjust the weights diff --git a/source/includes/fact-timezone-description.rst b/source/includes/fact-timezone-description.rst index 9bb6393c01b..77a12b5033a 100644 --- a/source/includes/fact-timezone-description.rst +++ b/source/includes/fact-timezone-description.rst @@ -13,17 +13,17 @@ If no ``timezone`` is provided, the result is displayed in ``UTC``. * - ``Format`` - ``Examples`` - * - `Olson Timezone Identifier` + * - ``Olson Timezone Identifier`` - - :: + - .. code-block:: none "America/New_York" "Europe/London" "GMT" - * - `UTC Offset` + * - ``UTC Offset`` - - :: + - .. code-block:: none +/-[hh]:[mm], e.g. "+04:45" +/-[hh][mm], e.g. "-0530" diff --git a/source/includes/in-dev.rst b/source/includes/in-dev.rst index 351fba776ec..e15d5c9af0b 100644 --- a/source/includes/in-dev.rst +++ b/source/includes/in-dev.rst @@ -1,6 +1,6 @@ -.. admonition:: MongoDB {+version-dev+} Release Candidates - :class: warning +.. warning:: MongoDB {+version-dev+} Release Candidates + While the {+version-dev+} release candidates are available, these versions of MongoDB are for **testing purposes only and not for production use**. diff --git a/source/includes/limits-sharding-unique-indexes.rst b/source/includes/limits-sharding-unique-indexes.rst index 161a3483307..f9ffcb94911 100644 --- a/source/includes/limits-sharding-unique-indexes.rst +++ b/source/includes/limits-sharding-unique-indexes.rst @@ -3,6 +3,8 @@ the unique index contains the full shard key as a prefix of the index. In these situations MongoDB will enforce uniqueness across the full key, not a single field. -.. see:: :ref:`shard-key-arbitrary-uniqueness` +.. see:: + + :ref:`shard-key-arbitrary-uniqueness` for an alternate approach. diff --git a/source/includes/list-mongodb-enterprise-packages.rst b/source/includes/list-mongodb-enterprise-packages.rst index 577276ee798..f078aa6aa3f 100644 --- a/source/includes/list-mongodb-enterprise-packages.rst +++ b/source/includes/list-mongodb-enterprise-packages.rst @@ -1,61 +1,59 @@ MongoDB Enterprise Edition is available from its own dedicated repository, and contains the following officially-supported packages: -.. container:: +.. list-table:: + :header-rows: 1 + :widths: 35 65 - .. list-table:: - :header-rows: 1 - :widths: 35 65 + * - Package Name + - Description - * - Package Name - - Description + * - ``{+package-name-enterprise+}`` + - A ``metapackage`` that automatically installs the component + packages listed below. - * - ``{+package-name-enterprise+}`` - - A ``metapackage`` that automatically installs the component - packages listed below. + * - ``{+package-name-enterprise+}-server`` + - Contains the :binary:`~bin.mongod` daemon and associated + configuration and init scripts. - * - ``{+package-name-enterprise+}-server`` - - Contains the :binary:`~bin.mongod` daemon and associated - configuration and init scripts. + * - ``{+package-name-enterprise+}-mongos`` + - Contains the :binary:`~bin.mongos` daemon. - * - ``{+package-name-enterprise+}-mongos`` - - Contains the :binary:`~bin.mongos` daemon. + * - ``{+package-name-enterprise+}-shell`` + - Contains the :binary:`~bin.mongo` shell. - * - ``{+package-name-enterprise+}-shell`` - - Contains the :binary:`~bin.mongo` shell. + * - ``{+package-name-enterprise+}-cryptd`` + - Contains the :ref:`mongocryptd ` + binary - * - ``{+package-name-enterprise+}-cryptd`` - - Contains the :ref:`mongocryptd ` - binary + * - ``{+package-name-enterprise+}-tools`` + - A ``metapackage`` that automatically installs the component + packages listed below: - * - ``{+package-name-enterprise+}-tools`` - - A ``metapackage`` that automatically installs the component - packages listed below: + .. list-table:: + :header-rows: 1 + :widths: 50 50 - .. list-table:: - :header-rows: 1 - :widths: 50 50 + * - Package Name + - Description - * - Package Name - - Description + * - ``mongodb-database-tools`` + - Contains the following MongoDB database tools: - * - ``mongodb-database-tools`` - - Contains the following MongoDB database tools: + - :binary:`~bin.mongodump` + - :binary:`~bin.mongorestore` + - :binary:`~bin.bsondump` + - :binary:`~bin.mongoimport` + - :binary:`~bin.mongoexport` + - :binary:`~bin.mongostat` + - :binary:`~bin.mongotop` + - :binary:`~bin.mongofiles` - - :binary:`~bin.mongodump` - - :binary:`~bin.mongorestore` - - :binary:`~bin.bsondump` - - :binary:`~bin.mongoimport` - - :binary:`~bin.mongoexport` - - :binary:`~bin.mongostat` - - :binary:`~bin.mongotop` - - :binary:`~bin.mongofiles` + * - ``{+package-name-enterprise+}-database-tools-extra`` + - Contains the following MongoDB support tools: - * - ``{+package-name-enterprise+}-database-tools-extra`` - - Contains the following MongoDB support tools: - - - :binary:`~bin.mongoldap` - - :binary:`~bin.mongokerberos` - - :ref:`install-compass` script - - ``mongodecrypt`` binary + - :binary:`~bin.mongoldap` + - :binary:`~bin.mongokerberos` + - :ref:`install-compass` script + - ``mongodecrypt`` binary diff --git a/source/includes/list-mongodb-org-packages.rst b/source/includes/list-mongodb-org-packages.rst index ab0d2e80e7e..9a4f6446994 100644 --- a/source/includes/list-mongodb-org-packages.rst +++ b/source/includes/list-mongodb-org-packages.rst @@ -4,56 +4,54 @@ MongoDB Community Edition is available from its own dedicated repository, and contains the following officially-supported packages: -.. container:: - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - - * - Package Name - - Description - - * - ``{+package-name-org+}`` - - A ``metapackage`` that automatically installs the component - packages listed below. - - * - ``{+package-name-org+}-server`` - - - Contains the :binary:`~bin.mongod` daemon, associated init - script, and a :ref:`configuration file - ` (``/etc/mongod.conf``). You - can use the initialization script to start :binary:`~bin.mongod` - with the configuration file. For details, see `Run MongoDB - Community Edition`_. - - * - ``{+package-name-org+}-mongos`` - - Contains the :binary:`~bin.mongos` daemon. - - * - ``{+package-name-org+}-shell`` - - Contains the :binary:`~bin.mongo` shell. - - * - ``{+package-name-org+}-tools`` - - A ``metapackage`` that automatically installs the component - packages listed below: - - .. list-table:: - :header-rows: 1 - :widths: 50 50 - - * - Package Name - - Description - - * - ``mongodb-database-tools`` - - Contains the following MongoDB database tools: - - - :binary:`~bin.mongodump` - - :binary:`~bin.mongorestore` - - :binary:`~bin.bsondump` - - :binary:`~bin.mongoimport` - - :binary:`~bin.mongoexport` - - :binary:`~bin.mongostat` - - :binary:`~bin.mongotop` - - :binary:`~bin.mongofiles` - - * - ``{+package-name-org+}-database-tools-extra`` - - Contains the :ref:`install-compass` script +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - Package Name + - Description + + * - ``{+package-name-org+}`` + - A ``metapackage`` that automatically installs the component + packages listed below. + + * - ``{+package-name-org+}-server`` + + - Contains the :binary:`~bin.mongod` daemon, associated init + script, and a :ref:`configuration file + ` (``/etc/mongod.conf``). You + can use the initialization script to start :binary:`~bin.mongod` + with the configuration file. For details, see `Run MongoDB + Community Edition`_. + + * - ``{+package-name-org+}-mongos`` + - Contains the :binary:`~bin.mongos` daemon. + + * - ``{+package-name-org+}-shell`` + - Contains the :binary:`~bin.mongo` shell. + + * - ``{+package-name-org+}-tools`` + - A ``metapackage`` that automatically installs the component + packages listed below: + + .. list-table:: + :header-rows: 1 + :widths: 50 50 + + * - Package Name + - Description + + * - ``mongodb-database-tools`` + - Contains the following MongoDB database tools: + + - :binary:`~bin.mongodump` + - :binary:`~bin.mongorestore` + - :binary:`~bin.bsondump` + - :binary:`~bin.mongoimport` + - :binary:`~bin.mongoexport` + - :binary:`~bin.mongostat` + - :binary:`~bin.mongotop` + - :binary:`~bin.mongofiles` + + * - ``{+package-name-org+}-database-tools-extra`` + - Contains the :ref:`install-compass` script diff --git a/source/includes/list-table-3.0-driver-compatibility.rst b/source/includes/list-table-3.0-driver-compatibility.rst index c0eb0ebdfeb..e3420c82239 100644 --- a/source/includes/list-table-3.0-driver-compatibility.rst +++ b/source/includes/list-table-3.0-driver-compatibility.rst @@ -6,39 +6,38 @@ - Driver Language - |driver-compatibility-heading| - * - :ecosystem:`C ` + * - :driver:`C ` - `1.1.0 `_ - - :ecosystem:`Perl ` + - :driver:`Perl ` - `1.0.0 `__ * - `C++ `_ - `1.0.0 `__ - - :ecosystem:`PHP ` + - :driver:`PHP ` - `1.0 `_ - * - :ecosystem:`C# ` + * - :driver:`C# ` - `1.10 `_ - - :ecosystem:`Python ` + - :driver:`Python ` - `2.8 `_ - * - :ecosystem:`Java ` + * - :driver:`Java ` - `2.13 `_ - - :ecosystem:`Motor ` + - :driver:`Motor ` - `0.4 `_ - * - :ecosystem:`Node.js ` + * - :driver:`Node.js ` - `1.4.29 `_ - - - :ecosystem:`Ruby ` + - :driver:`Ruby ` - `1.12 `_ * - - - - :ecosystem:`Scala ` + - :driver:`Scala ` - `2.8.0 `_ diff --git a/source/includes/list-text-search-restrictions-in-agg.rst b/source/includes/list-text-search-restrictions-in-agg.rst index 0fec4572c51..78c6ddb4de5 100644 --- a/source/includes/list-text-search-restrictions-in-agg.rst +++ b/source/includes/list-text-search-restrictions-in-agg.rst @@ -1,9 +1,9 @@ - The :pipeline:`$match` stage that includes a :query:`$text` must be the **first** stage in the pipeline. -- A :query:`text` operator can only occur once in the stage. +- A :query:`$text` operator can only occur once in the stage. -- The :query:`text` operator expression cannot appear in +- The :query:`$text` operator expression cannot appear in :expression:`$or` or :expression:`$not` expressions. - The text search, by default, does not return the matching documents diff --git a/source/includes/note-deb-and-rpm-default-to-localhost.rst b/source/includes/note-deb-and-rpm-default-to-localhost.rst index 983384c25fd..bb5fbd21294 100644 --- a/source/includes/note-deb-and-rpm-default-to-localhost.rst +++ b/source/includes/note-deb-and-rpm-default-to-localhost.rst @@ -4,5 +4,5 @@ |mongodb-package| installed from official :doc:`.deb ` and :doc:`.rpm ` packages -have the :setting:`bind_ip` configuration set to ``127.0.0.1`` by +have the ``bind_ip`` configuration set to ``127.0.0.1`` by default. diff --git a/source/includes/stepdown-intro.rst b/source/includes/stepdown-intro.rst index 444c3bcf39a..02133883992 100644 --- a/source/includes/stepdown-intro.rst +++ b/source/includes/stepdown-intro.rst @@ -3,7 +3,7 @@ Instructs the :term:`primary` of the replica set to become a hold an :ref:`election for primary `. The |command-method| does not immediately step down the primary. If no -:data:`electable <~replSetGetConfig.members[n].priority>` secondaries +:rsconf:`electable ` secondaries are up to date with the primary, the primary waits up to ``secondaryCatchUpPeriodSecs`` (by default 10 seconds) for a secondary to catch up. Once an electable secondary is diff --git a/source/includes/steps-2.6-downgrade-authorization-prereq.yaml b/source/includes/steps-2.6-downgrade-authorization-prereq.yaml index ccc35375252..a13e9ca8598 100644 --- a/source/includes/steps-2.6-downgrade-authorization-prereq.yaml +++ b/source/includes/steps-2.6-downgrade-authorization-prereq.yaml @@ -13,7 +13,7 @@ title: stepnum: 2 ref: create-role-with-required-privileges pre: | - Using the :method:`db.createRole` method, create a + Using the :method:`db.createRole()` method, create a :ref:`role ` with the required privileges. action: language: javascript diff --git a/source/includes/steps-2.6-upgrade-authorization.yaml b/source/includes/steps-2.6-upgrade-authorization.yaml index 253328c0c69..73d2bd347f4 100644 --- a/source/includes/steps-2.6-upgrade-authorization.yaml +++ b/source/includes/steps-2.6-upgrade-authorization.yaml @@ -15,7 +15,7 @@ title: ref: upgrade-authz-schema stepnum: 2 pre: | - Use the :dbcommand:`authSchemaUpgrade` command in the ``admin`` + Use the ``authSchemaUpgrade`` command in the ``admin`` database to update the user data using the :binary:`~bin.mongo` shell. action: - heading: @@ -26,12 +26,12 @@ action: db.adminCommand({authSchemaUpgrade: 1 }); post: | In case of error, you may safely rerun the - :dbcommand:`authSchemaUpgrade` command. + ``authSchemaUpgrade`` command. - heading: text: Sharded cluster ``authSchemaUpgrade`` consideration. character: "'" pre: | - For a sharded cluster, :dbcommand:`authSchemaUpgrade` will + For a sharded cluster, ``authSchemaUpgrade`` will upgrade the authorization data of the shards as well and the upgrade is complete. You can, however, override this behavior by including ``upgradeShards: false`` in the command, as in the @@ -42,7 +42,7 @@ action: upgradeShards: false }); post: | If you override the behavior, after running - :dbcommand:`authSchemaUpgrade` on a :binary:`~bin.mongos` instance, + ``authSchemaUpgrade`` on a :binary:`~bin.mongos` instance, you will need to connect to the primary for each shard and repeat the upgrade process after upgrading on the :binary:`~bin.mongos`. diff --git a/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml b/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml index ed176b719a1..b0f6bab0e3e 100644 --- a/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml +++ b/source/includes/steps-3.0-upgrade-mongodb-cr-to-scram.yaml @@ -28,11 +28,11 @@ action: db.adminCommand({authSchemaUpgrade: 1}); post: | In case of error, you may safely rerun the - :dbcommand:`authSchemaUpgrade` command. + ``authSchemaUpgrade`` command. - heading: Sharded cluster ``authSchemaUpgrade`` consideration. pre: | For a sharded cluster *without* :ref:`shard local users - `, :dbcommand:`authSchemaUpgrade` will, by + `, ``authSchemaUpgrade`` will, by default, upgrade the authorization data of the shards as well, completing the upgrade. @@ -46,7 +46,7 @@ action: ); post: | If you override the default behavior or your cluster has shard - local users, after running :dbcommand:`authSchemaUpgrade` on a + local users, after running ``authSchemaUpgrade`` on a :binary:`~bin.mongos` instance, you will need to connect to the primary for each shard and repeat the upgrade process after upgrading on the :binary:`~bin.mongos`. diff --git a/source/includes/steps-3.6-upgrade-sharded-cluster.yaml b/source/includes/steps-3.6-upgrade-sharded-cluster.yaml index cfa4eab505b..78061ccbc6d 100644 --- a/source/includes/steps-3.6-upgrade-sharded-cluster.yaml +++ b/source/includes/steps-3.6-upgrade-sharded-cluster.yaml @@ -7,8 +7,6 @@ content: | the sharded cluster, and run :method:`sh.stopBalancer()` to disable the balancer: - .. cssclass:: copyable-code - .. code-block:: javascript sh.stopBalancer() @@ -24,8 +22,6 @@ content: | :method:`sh.getBalancerState()`, which returns false if the balancer is disabled: - .. cssclass:: copyable-code - .. code-block:: javascript sh.getBalancerState() @@ -50,7 +46,6 @@ content: |- .. include:: /includes/fact-bind-ip-sharded-clusters.rst - .. cssclass:: copyable-code .. code-block:: sh mongod --configsvr --replSet --port --dbpath --bind_ip localhost, @@ -62,7 +57,6 @@ content: |- :setting:`net.port`, and :setting:`net.bindIp`, then start the |newversion| binary: - .. cssclass:: copyable-code .. code-block:: yaml sharding: @@ -89,7 +83,6 @@ content: |- :method:`rs.stepDown()` to step down the primary and force an election of a new primary: - .. cssclass:: copyable-code .. code-block:: javascript rs.stepDown() @@ -104,7 +97,6 @@ content: |- options. Include any optional command line options used by the previous deployment: - .. cssclass:: copyable-code .. code-block:: sh mongod --configsvr --replSet --port --dbpath --bind_ip localhost, @@ -118,7 +110,6 @@ content: |- :setting:`net.port`, and :setting:`net.bindIp`, then start the |newversion| binary: - .. cssclass:: copyable-code .. code-block:: yaml sharding: @@ -152,7 +143,6 @@ content: |- options. Include any optional command line options used by the previous deployment: - .. cssclass:: copyable-code .. code-block:: sh mongod --shardsvr --replSet --port --dbpath --bind_ip localhost, @@ -165,7 +155,6 @@ content: |- :setting:`replication.replSetName`, :setting:`net.port`, and :setting:`net.bindIp`, then start the |newversion| binary: - .. cssclass:: copyable-code .. code-block:: yaml sharding: @@ -193,7 +182,6 @@ content: |- :method:`rs.stepDown()` to step down the primary and force an election of a new primary: - .. cssclass:: copyable-code .. code-block:: javascript rs.stepDown() @@ -210,7 +198,6 @@ content: |- options. Include any optional command line options used by the previous deployment: - .. cssclass:: copyable-code .. code-block:: sh mongod --shardsvr --replSet --port --dbpath --bind_ip localhost, @@ -224,7 +211,6 @@ content: |- :setting:`net.port`, and :setting:`net.bindIp`, then start the |newversion| binary: - .. cssclass:: copyable-code .. code-block:: yaml sharding: @@ -249,7 +235,6 @@ content: |- .. include:: /includes/fact-bind-ip-sharded-clusters.rst - .. cssclass:: copyable-code .. code-block:: sh mongos --configdb csReplSet/,, --bind_ip localhost, @@ -263,7 +248,6 @@ content: |- :binary:`~bin.mongos` in the cluster and run :method:`sh.setBalancerState()` to re-enable the balancer: - .. cssclass:: copyable-code .. code-block:: javascript sh.setBalancerState(true) diff --git a/source/includes/steps-change-own-password-and-custom-data-prereq.yaml b/source/includes/steps-change-own-password-and-custom-data-prereq.yaml index cfa879b630c..8441d398af6 100644 --- a/source/includes/steps-change-own-password-and-custom-data-prereq.yaml +++ b/source/includes/steps-change-own-password-and-custom-data-prereq.yaml @@ -19,7 +19,7 @@ stepnum: 2 title: Create a role with appropriate privileges. ref: create-role pre: | - In the ``admin`` database, :method:`create ` a new + In the ``admin`` database, :method:`create ` a new role with :authaction:`changeOwnPassword` and :authaction:`changeOwnCustomData`. action: @@ -42,7 +42,7 @@ stepnum: 3 title: Add a user with this role. ref: add-user pre: | - In the ``test`` database, :method:`create ` a new user with + In the ``test`` database, :method:`create ` a new user with the created ``"changeOwnPasswordCustomDataRole"`` role. For example, the following operation creates a user with both the built-in role :authrole:`readWrite` and the user-created ``"changeOwnPasswordCustomDataRole"``. diff --git a/source/includes/steps-compass-manual-queries.yaml b/source/includes/steps-compass-manual-queries.yaml index 0f0e9adedbd..cec87ce5ace 100644 --- a/source/includes/steps-compass-manual-queries.yaml +++ b/source/includes/steps-compass-manual-queries.yaml @@ -10,6 +10,7 @@ action: "JFK". .. figure:: /images/compass/manual-query.png + :alt: Compass query bar with query entered When a valid query is entered, the bar is colored green and can be executed. Invalid queries are colored red. The UI will automatically update @@ -27,6 +28,7 @@ action: matching documents. .. figure:: /images/compass/manual-query-results.png + :alt: Compass Apply button executes query To clear a query, use the Reset button. ... diff --git a/source/includes/steps-compass-query-builder.yaml b/source/includes/steps-compass-query-builder.yaml deleted file mode 100644 index 845594e6e54..00000000000 --- a/source/includes/steps-compass-query-builder.yaml +++ /dev/null @@ -1,44 +0,0 @@ -title: Select values from charts -level: 4 -ref: select-values -action: - pre: | - Charts in Compass are fully interactive. Clicking on a chart value or bar - will automatically build a MongoDB query that matches the documents - pertaining to that section of the chart. - - In the example below, clicking on the "JFK" bar builds a query matching all - documents whose ``departureAirportFsCode`` field matches "JFK". - - .. figure:: /images/compass/query-builder-jfk.png - - Clicking on other field values adds them to the selection, creating a more - complex query. - - Continuing with the example, this selects a particular ``flightId`` in - addition to departures from JFK Airport. - - .. figure:: /images/compass/query-builder-jfk-flight-code.png - - To select multiple values within the same field, click and drag the mouse - over a selection of values. Alternatively, hold the Shift key while - selecting the desired values. - - .. figure:: /images/compass/query-builder-multi-select.png - - To deselect a previously-selected value, hold the Shift key while clicking - on the selection. - - .. figure:: /images/compass/query-builder-deselect.png ---- -title: Apply the query -level: 4 -ref: apply -action: - pre: | - After building a query, run it by clicking the Apply button. To clear the - query, use the Reset button. - - Note that composing "OR" queries is **not yet possible** with the automatic - query builder. -... diff --git a/source/includes/steps-configure-ldap-sasl-activedirectory-authentication.yaml b/source/includes/steps-configure-ldap-sasl-activedirectory-authentication.yaml index 73111742a95..6dc819a0e27 100644 --- a/source/includes/steps-configure-ldap-sasl-activedirectory-authentication.yaml +++ b/source/includes/steps-configure-ldap-sasl-activedirectory-authentication.yaml @@ -44,7 +44,7 @@ pre: | :setting:`security.ldap.servers`. You must also enable LDAP authentication by setting - :setting:`security.authorization` to `enabled` and :setting:`setParameter` + :setting:`security.authorization` to ``enabled`` and :setting:`setParameter` :parameter:`authenticationMechanisms` to ``PLAIN`` .. example:: @@ -308,7 +308,7 @@ pre: | prompts for the password. :abbr:`Windows (Microsoft Windows)` MongoDB deployments must use - :binary:`~bin.mongo.exe` instead of :binary:`~bin.mongo`. + :binary:`mongo.exe ` instead of :binary:`~bin.mongo`. Given the configured :ref:`Active Directory users `, the user authenticates successfully and diff --git a/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml b/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml index 5a445e6edfa..db9142fe576 100644 --- a/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml +++ b/source/includes/steps-control-access-to-mongodb-windows-with-kerberos-authentication.yaml @@ -2,12 +2,12 @@ title: Start ``mongod.exe`` without Kerberos. stepnum: 1 ref: start-mongod-exe-without-kerberos-support pre: | - For the initial addition of Kerberos users, start :binary:`~bin.mongod.exe` - without Kerberos support. + For the initial addition of Kerberos users, start + :binary:`~bin.mongod.exe` without Kerberos support. post: | If a Kerberos user is already in MongoDB and has the :ref:`privileges required to create a user - `, you can start + `, you can start :binary:`~bin.mongod.exe` with Kerberos support. Include additional settings as appropriate to your deployment. @@ -20,7 +20,7 @@ title: Connect to ``mongod``. stepnum: 2 ref: connect-to-mongod pre: | - Connect via the :binary:`~bin.mongo.exe` shell to the :binary:`~bin.mongod.exe` + Connect via the :binary:`~bin.mongo` shell to the :binary:`~bin.mongod.exe` instance. If :binary:`~bin.mongod.exe` has :option:`--auth ` enabled, ensure you connect with the :ref:`privileges required to create a user `. @@ -91,18 +91,18 @@ title: Connect ``mongo.exe`` shell to ``mongod.exe`` and authenticate. stepnum: 5 ref: authenticate-a-user-within-mongo-shell pre: | - Connect the :binary:`~bin.mongo.exe` shell client as the Kerberos + Connect the :binary:`mongo.exe ` shell client as the Kerberos principal ``application@EXAMPLE.NET``. action: - pre: | You can connect and authenticate from the command line. - Using :binary:`~bin.cmd.exe`: + Using ``cmd.exe``: language: sh code: | mongo.exe --host hostname.example.net --authenticationMechanism=GSSAPI --authenticationDatabase=$external --username reportingapp@EXAMPLE.NET - pre: | - Using :binary:`~bin.Windows PowerShell`: + Using ``Windows PowerShell``: language: sh code: | mongo.exe --host hostname.example.net --authenticationMechanism=GSSAPI --authenticationDatabase='$external' --username reportingapp@EXAMPLE.NET @@ -116,10 +116,11 @@ action: match the Kerberos name, use :option:`--gssapiHostName ` to specify the Kerberos FQDN that it responds to. - pre: | - Alternatively, you can first connect :binary:`~bin.mongo.exe` to the - :binary:`~bin.mongod.exe`, and then from the :binary:`~bin.mongo.exe` shell, use - the :method:`db.auth()` method to authenticate in the - ``$external`` database. + Alternatively, you can first connect :binary:`mongo.exe + ` to the :binary:`~bin.mongod.exe`, and then from the + :binary:`mongo.exe ` shell, use the + :method:`db.auth()` method to authenticate in the ``$external`` + database. language: javascript code: | use $external diff --git a/source/includes/steps-convert-replica-set-add-new-shard.yaml b/source/includes/steps-convert-replica-set-add-new-shard.yaml index 5e3294aea92..5c7a3d29047 100644 --- a/source/includes/steps-convert-replica-set-add-new-shard.yaml +++ b/source/includes/steps-convert-replica-set-add-new-shard.yaml @@ -4,9 +4,11 @@ title: ref: start-mongod pre: | For each member, start a :binary:`~bin.mongod`, specifying the replica - set name through the :setting:`replSet` option and its role as a - shard with the :option:`--shardsvr ` option. Specify additional options, - such as :option:`--bind_ip `, as appropriate. + set name through the :option:`--replSet ` option + and its role as a shard with the + :option:`--shardsvr ` option. Specify additional + options, such as :option:`--bind_ip `, as + appropriate. .. include:: /includes/warning-bind-ip-security-considerations.rst diff --git a/source/includes/steps-enable-authentication-in-replica-set-no-downtime.yaml b/source/includes/steps-enable-authentication-in-replica-set-no-downtime.yaml index 4297d551116..fa29b40d561 100644 --- a/source/includes/steps-enable-authentication-in-replica-set-no-downtime.yaml +++ b/source/includes/steps-enable-authentication-in-replica-set-no-downtime.yaml @@ -165,7 +165,7 @@ action: - pre: | If your application uses a MongoDB driver, see the associated - :ecosystem:`driver ` documentation for instructions on + :driver:`driver ` documentation for instructions on creating an authenticated connection. post: | @@ -304,7 +304,7 @@ action: shut down the old primary :binary:`~bin.mongod`. From a :binary:`~bin.mongo` shell connected to the old primary, issue the - :method:`db.shutdownServer()` on the `admin` database. + :method:`db.shutdownServer()` on the ``admin`` database. language: javascript code: | @@ -372,8 +372,8 @@ action: - heading: Shut down the secondary or arbiter members pre: | - Connect to a :binary:`~bin.mongo` shell to the secondary or arbiter, and - issue the :method:`db.shutdownServer()` on the `database`. + Connect a :binary:`~bin.mongo` shell to the secondary or arbiter, and + issue the :method:`db.shutdownServer()` on the ``admin`` database. language: javascript code: | @@ -461,7 +461,7 @@ action: shut down the old primary :binary:`~bin.mongod`. From a :binary:`~bin.mongo` shell connected to the old primary, issue the - :method:`db.shutdownServer()` on the `admin` database. + :method:`db.shutdownServer()` on the ``admin`` database. language: javascript code: | diff --git a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml index 4985842babc..579ac7c9f22 100644 --- a/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml +++ b/source/includes/steps-enable-authentication-in-shardcluster-nodowntime-uac.yaml @@ -101,6 +101,6 @@ pre: | --authenticationDatabase "marketing" --host mongos1.example.net:27017 If your application uses a MongoDB driver, see the associated - :ecosystem:`driver ` documentation for instructions on creating + :driver:`driver ` documentation for instructions on creating an authenticated connection. ... diff --git a/source/includes/steps-install-mongodb-enterprise-with-docker.yaml b/source/includes/steps-install-mongodb-enterprise-with-docker.yaml index dc9c4dc6488..be4c6cdec38 100644 --- a/source/includes/steps-install-mongodb-enterprise-with-docker.yaml +++ b/source/includes/steps-install-mongodb-enterprise-with-docker.yaml @@ -11,8 +11,8 @@ pre: | with the following commands. Set ``MONGODB_VERSION`` to your major version of choice. - .. admonition:: Docker Hub Mongo Project - :class: note + .. note:: Docker Hub Mongo Project + The Docker Hub mongo project is *not* maintained by MongoDB. Any support requests should go to `Docker `__. diff --git a/source/includes/steps-install-mongodb-on-windows-unattended.yaml b/source/includes/steps-install-mongodb-on-windows-unattended.yaml index 15361029155..4dd901de023 100644 --- a/source/includes/steps-install-mongodb-on-windows-unattended.yaml +++ b/source/includes/steps-install-mongodb-on-windows-unattended.yaml @@ -51,25 +51,30 @@ pre: | - Binaries Included in the Component Set * - ``ServerNoService`` - - ``mongod.exe`` + - :binary:`~bin.mongod.exe` * - ``ServerService`` - - Set up ``mongod.exe`` as a Windows service. + - Set up :binary:`~bin.mongod.exe` as a Windows service. * - ``Router`` - - ``mongos.exe`` + - :binary:`~bin.mongos.exe` * - ``Client`` - - ``mongo.exe`` + - :binary:`mongo.exe ` * - ``MonitoringTools`` - - ``mongostat.exe``, ``mongotop.exe`` + - :binary:`mongostat.exe `, + :binary:`mongotop.exe ` * - ``ImportExportTools`` - - ``mongodump.exe``, ``mongorestore.exe``, ``mongoexport.exe``, ``mongoimport.exe`` + - :binary:`mongodump.exe `, + :binary:`mongorestore.exe `, + :binary:`mongoexport.exe `, + :binary:`mongoimport.exe ` * - ``MiscellaneousTools`` - - ``bsondump.exe``, ``mongofiles.exe`` + - :binary:`bsondump.exe `, + :binary:`mongofiles.exe ` For example, to install just the MongoDB server - (``mongod.exe``) and the ``mongo.exe`` shell as well as - set up the MongoDB server as a Windows service, run: + (:binary:`~bin.mongod.exe`) and the :binary:`mongo.exe ` + shell as well as set up the MongoDB server as a Windows service, run: .. include:: {{release_specification_service}} diff --git a/source/includes/steps-kerberos-auth-activedirectory-authz.yaml b/source/includes/steps-kerberos-auth-activedirectory-authz.yaml index 308d5cba865..ae659047447 100644 --- a/source/includes/steps-kerberos-auth-activedirectory-authz.yaml +++ b/source/includes/steps-kerberos-auth-activedirectory-authz.yaml @@ -113,7 +113,7 @@ pre: | .. note:: For :abbr:`Windows (Microsoft Windows)` MongoDB deployments, you should replace :binary:`~bin.mongo` with - :binary:`~bin.mongo.exe` + :binary:`mongo.exe ` --- title: Create user administrative role. @@ -232,7 +232,7 @@ level: 4 pre: | In the MongoDB configuration file, set :setting:`security.authorization` to - `enabled` and :setting:`setParameter` :parameter:`authenticationMechanisms` + ``enabled`` and :setting:`setParameter` :parameter:`authenticationMechanisms` to ``GSSAPI`` @@ -504,7 +504,7 @@ pre: | prompts for the password. :abbr:`Windows (Microsoft Windows)` MongoDB deployments must use - :binary:`~bin.mongo.exe` instead of :binary:`~bin.mongo`. + :binary:`mongo.exe ` instead of :binary:`~bin.mongo`. Given the configured :ref:`Active Directory users `, the user authenticates successfully and diff --git a/source/includes/steps-monitor-with-snmp-windows.yaml b/source/includes/steps-monitor-with-snmp-windows.yaml index 0e74578369f..6cb721926df 100644 --- a/source/includes/steps-monitor-with-snmp-windows.yaml +++ b/source/includes/steps-monitor-with-snmp-windows.yaml @@ -30,7 +30,8 @@ title: Start MongoDB. stepnum: 2 ref: start-with-snmp pre: | - Start |mongod-program| with the :setting:`snmp-subagent` to send data + Start |mongod-program| with the + :option:`snmp-subagent ` to send data to the SNMP master. action: language: powershell diff --git a/source/includes/steps-monitor-with-snmp.yaml b/source/includes/steps-monitor-with-snmp.yaml index c31be1fc6fb..19c55fa38f9 100644 --- a/source/includes/steps-monitor-with-snmp.yaml +++ b/source/includes/steps-monitor-with-snmp.yaml @@ -184,8 +184,9 @@ title: Start MongoDB. stepnum: 4 ref: start-with-snmp pre: | - Start |mongod-program| with the :setting:`snmp-subagent` to send data - to the SNMP master. + Start |mongod-program| with the + :option:`snmp-subagent ` to send data to the + SNMP master. action: language: sh code: mongod --snmp-subagent diff --git a/source/includes/steps-replace-disabled-config-server.yaml b/source/includes/steps-replace-disabled-config-server.yaml index e3bbcc29e5f..ce5d3db5c28 100644 --- a/source/includes/steps-replace-disabled-config-server.yaml +++ b/source/includes/steps-replace-disabled-config-server.yaml @@ -44,7 +44,6 @@ content: | state. To check the state of the replica set members, run :method:`rs.status()`: - .. cssclass:: copyable-code .. code-block:: javascript rs.status() diff --git a/source/includes/steps-restore-primary-from-backup.yaml b/source/includes/steps-restore-primary-from-backup.yaml index a11ef0604e2..b09c250500a 100644 --- a/source/includes/steps-restore-primary-from-backup.yaml +++ b/source/includes/steps-restore-primary-from-backup.yaml @@ -17,7 +17,7 @@ title: "Drop the ``local`` database if it exists in the backup." ref: drop-local pre: | If you are restoring from a filesystem backup (or any backup with - the `local` database), drop the ``local`` database. + the ``local`` database), drop the ``local`` database. action: - heading: Start a standalone :binary:`~bin.mongod` using the data files from the backup as the data path. language: sh diff --git a/source/includes/steps-restore-sharded-config-primary-from-backup.yaml b/source/includes/steps-restore-sharded-config-primary-from-backup.yaml index b34b6e97ce6..6ac3bfb9d3d 100644 --- a/source/includes/steps-restore-sharded-config-primary-from-backup.yaml +++ b/source/includes/steps-restore-sharded-config-primary-from-backup.yaml @@ -111,8 +111,8 @@ content: | mongod --config /path/to/mongodb/mongod.conf - .. admonition:: Cloud Manager or Ops Manager Only - :class: note + .. note:: Cloud Manager or Ops Manager Only + If performing a manual restoration of a Cloud Manager or Ops Manager backup, you must specify the @@ -289,9 +289,9 @@ content: | {{code}} If you want to add the member with specific replica - :rsconf:`member ` configuration settings, you can pass a + :rsconf:`member ` configuration settings, you can pass a document to :method:`rs.add()` that defines the member hostname - and any :rsconf:`members[n]` settings your deployment requires. + and any :rsconf:`members` settings your deployment requires. {{morecode}} diff --git a/source/includes/steps-restore-sharded-shard-primary-from-backup.yaml b/source/includes/steps-restore-sharded-shard-primary-from-backup.yaml index 8bcf0f9ba9e..3e4b4b92b46 100644 --- a/source/includes/steps-restore-sharded-shard-primary-from-backup.yaml +++ b/source/includes/steps-restore-sharded-shard-primary-from-backup.yaml @@ -113,8 +113,8 @@ content: | mongod --config /path/to/mongodb/mongod.conf - .. admonition:: Cloud Manager or Ops Manager Only - :class: note + .. note:: Cloud Manager or Ops Manager Only + If performing a manual restoration of a Cloud Manager or Ops Manager backup, you must specify the diff --git a/source/includes/steps-run-mongodb-on-a-linux-distribution-systemd.yaml b/source/includes/steps-run-mongodb-on-a-linux-distribution-systemd.yaml index 598c4e62399..a699b6f447a 100644 --- a/source/includes/steps-run-mongodb-on-a-linux-distribution-systemd.yaml +++ b/source/includes/steps-run-mongodb-on-a-linux-distribution-systemd.yaml @@ -14,9 +14,7 @@ action: If you receive an error similar to the following when starting :binary:`~bin.mongod`: - .. container:: - - ``Failed to start mongod.service: Unit mongod.service not found.`` + ``Failed to start mongod.service: Unit mongod.service not found.`` Run the following command first: language: sh diff --git a/source/includes/steps-run-mongodb-on-debian-systemd.yaml b/source/includes/steps-run-mongodb-on-debian-systemd.yaml index bc1a0263058..5c50f426ddc 100644 --- a/source/includes/steps-run-mongodb-on-debian-systemd.yaml +++ b/source/includes/steps-run-mongodb-on-debian-systemd.yaml @@ -13,10 +13,8 @@ action: - pre: | If you receive an error similar to the following when starting :binary:`~bin.mongod`: - - .. container:: - ``Failed to start mongod.service: Unit mongod.service not found.`` + ``Failed to start mongod.service: Unit mongod.service not found.`` Run the following command first: language: sh diff --git a/source/includes/steps-run-mongodb-on-osx.yaml b/source/includes/steps-run-mongodb-on-osx.yaml index a18e9208ac3..75ce914cc41 100644 --- a/source/includes/steps-run-mongodb-on-osx.yaml +++ b/source/includes/steps-run-mongodb-on-osx.yaml @@ -77,8 +77,8 @@ action: code: | mongod --config /usr/local/etc/mongod.conf post: | - .. admonition:: macOS Prevents ``mongod`` From Opening - :class: note + .. note:: macOS Prevents ``mongod`` From Opening + .. include:: /includes/extracts/macos-prevent-launch-mongod.rst @@ -111,8 +111,8 @@ action: code: | mongo post: | - .. admonition:: macOS Prevents ``mongo`` From Opening - :class: note + .. note:: macOS Prevents ``mongo`` From Opening + .. include:: /includes/extracts/macos-prevent-launch-mongo.rst diff --git a/source/includes/steps-starting-compass.yaml b/source/includes/steps-starting-compass.yaml deleted file mode 100644 index 7bd294035ce..00000000000 --- a/source/includes/steps-starting-compass.yaml +++ /dev/null @@ -1,61 +0,0 @@ -title: Run and connect to MongoDB -level: 4 -ref: run-connect -action: - pre: | - When Compass is run for the first time, it presents the following initial - connection dialog: - - .. figure:: /images/compass/new-connection-form.png - - The following information is requested: - - a. Hostname: The hostname of the machine where :binary:`~bin.mongod` is running. - b. Port: The port of the machine where :binary:`~bin.mongod` is running. - c. Authentication: The authentication mechanism to connect to the target - host. Supported authentication mechanisms include: - - - MongoDB-CR (*Removed in MongoDB 4.0*) - - SCRAM-SHA-1 - - SCRAM-SHA-256 (*Added in MongoDB 4.0*) - - Kerberos - - LDAP - - You cannot specify MongoDB-CR when connecting to MongoDB 4.0 deployments. - - d. SSL: Whether or not Compass should connect to the target host with TLS/SSL. - Several TLS/SSL options are available: - - - Unvalidated: If this option is used, the server cerficiate is not - validated and no client certificate will be provided. The server must be - set up to allow connections without valid certificates. - - Server Validation: The server certificate will be validated, but no - client certificate will be provided. The server must be set up to allow - connections without valid certificates. - - Server and Client Validation: The server certificate will be validated - and a client certificate must be provided. - - e. Favorite Name (Optional): A nickname for the connection. Previous - connections are saved in Compass; a descriptive name simplifies - re-establishing the connection on future runs. - - .. figure:: /images/compass/favorite-connections.png - - After providing the requested information, click "Connect" to launch the - main Compass window. ---- -title: Select a database and collection -level: 4 -ref: select-db-coll -action: - pre: | - Use the navigation pane to select a database and collection to analyze. - - .. figure:: /images/compass/select-collection.png - - After making a selection, Compass will begin analyzing documents and present - a summary screen. Below is an example; results will vary based on the - contents of the collection. - - .. figure:: /images/compass/analysis-page.png -... diff --git a/source/includes/table-transactions-operations.rst b/source/includes/table-transactions-operations.rst index 79db035933a..cc1d965c6d2 100644 --- a/source/includes/table-transactions-operations.rst +++ b/source/includes/table-transactions-operations.rst @@ -68,7 +68,9 @@ In MongoDB 4.2 and earlier, if ``upsert: true``, the operation must be run on an existing collection. - .. seealso:: :ref:`transactions-operations-ddl` + .. seealso:: + + :ref:`transactions-operations-ddl` * - | :method:`db.collection.insertMany()` | :method:`db.collection.insertOne()` @@ -82,7 +84,9 @@ In MongoDB 4.2 and earlier, the operation must be run on an existing collection. - .. seealso:: :ref:`transactions-operations-ddl` + .. seealso:: + + :ref:`transactions-operations-ddl` * - :method:`db.collection.save()` - @@ -92,7 +96,9 @@ In MongoDB 4.2 and earlier, the operation must be run on an existing collection. - .. seealso:: :ref:`transactions-operations-ddl` + .. seealso:: + + :ref:`transactions-operations-ddl` * - | :method:`db.collection.updateOne()` | :method:`db.collection.updateMany()` @@ -107,7 +113,9 @@ In MongoDB 4.2 and earlier, the operation must be run on an existing collection. - .. seealso:: :ref:`transactions-operations-ddl` + .. seealso:: + + :ref:`transactions-operations-ddl` * - | :method:`db.collection.bulkWrite()` | Various :doc:`/reference/method/js-bulk` @@ -118,4 +126,6 @@ In MongoDB 4.2 and earlier, the operation must be run on an existing collection. - .. seealso:: :ref:`transactions-operations-ddl` + .. seealso:: + + :ref:`transactions-operations-ddl` diff --git a/source/includes/warning-document-duplicate-key-names.rst b/source/includes/warning-document-duplicate-key-names.rst index db5b61b274b..276f08876a3 100644 --- a/source/includes/warning-document-duplicate-key-names.rst +++ b/source/includes/warning-document-duplicate-key-names.rst @@ -1,5 +1,5 @@ -.. admonition:: MongoDB does not support duplicate field names - :class: warning +.. warning:: MongoDB does not support duplicate field names + The MongoDB Query Language is undefined over documents with duplicate field names. BSON builders may support creating a BSON diff --git a/source/index.txt b/source/index.txt index 9c5046340eb..5fb9d70a51f 100644 --- a/source/index.txt +++ b/source/index.txt @@ -6,8 +6,7 @@ The MongoDB |version| Manual .. default-domain:: mongodb -.. admonition:: MongoDB 4.4 Released Jul 30, 2020 - :class: note +.. note:: MongoDB 4.4 Released Jul 30, 2020 For new features in MongoDB 4.4, see :doc:`/release-notes/4.4`. @@ -168,23 +167,22 @@ For information on MongoDB licensing, see `MongoDB Licensing Additional Resources -------------------- -.. class:: toc - `MongoDB, Inc.`_ - The company behind MongoDB. +`MongoDB, Inc.`_ + The company behind MongoDB. - `MongoDB Atlas `_ - Database as a service. +`MongoDB Atlas `_ + Database as a service. - |mms-home| - A cloud-based hosted operations management solution for MongoDB. +|mms-home| + A cloud-based hosted operations management solution for MongoDB. - `MongoDB Ops Manager `_ - Enterprise operations management solution for MongoDB: includes - Automation, Backup, and Monitoring. +`MongoDB Ops Manager `_ + Enterprise operations management solution for MongoDB: includes + Automation, Backup, and Monitoring. - `MongoDB Drivers `_ - The documentation available for the drivers for use with MongoDB. +`MongoDB Drivers `_ + The documentation available for the drivers for use with MongoDB. .. _`MongoDB, Inc.`: https://www.mongodb.com?tck=docs_server diff --git a/source/indexes.txt b/source/indexes.txt index 7c0009ac53e..889c114ea59 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -6,12 +6,6 @@ Indexes .. default-domain:: mongodb -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: twocols - Indexes support the efficient execution of queries in MongoDB. Without indexes, MongoDB must perform a *collection scan*, i.e. scan every document in a collection, to select those documents that match the @@ -37,10 +31,10 @@ database systems. MongoDB defines indexes at the :term:`collection` level and supports indexes on any field or sub-field of the documents in a MongoDB collection. -.. index:: _id index -.. index:: _id -.. index:: index; _id -.. index:: index types; primary key + + + + .. _index-type-id: Default ``_id`` Index @@ -67,7 +61,7 @@ Create an Index .. [#b-tree] MongoDB indexes use a B-tree data structure. -.. index:: index; name + .. _index-names: Index Names diff --git a/source/installation.txt b/source/installation.txt index 2fc72739b5d..2eace79ece3 100644 --- a/source/installation.txt +++ b/source/installation.txt @@ -13,10 +13,10 @@ Install MongoDB :depth: 1 :class: singlecol -.. index:: tutorials; installation -.. index:: installation tutorials -.. index:: installation guides -.. index:: installation + + + + MongoDB is available in two server editions: *Community* and *Enterprise*. diff --git a/source/meta/aggregation-quick-reference.txt b/source/meta/aggregation-quick-reference.txt index 4e17e818dbd..ec0307b298a 100644 --- a/source/meta/aggregation-quick-reference.txt +++ b/source/meta/aggregation-quick-reference.txt @@ -60,7 +60,9 @@ For the updates, the pipeline can consist of the following stages: .. include:: /includes/list-update-agg-stages.rst -.. seealso:: :doc:`/tutorial/update-documents-with-aggregation-pipeline` +.. seealso:: + + :doc:`/tutorial/update-documents-with-aggregation-pipeline` .. _aggregation-expressions: diff --git a/source/mongo.txt b/source/mongo.txt index 1af0424700e..5b84517a9f0 100644 --- a/source/mongo.txt +++ b/source/mongo.txt @@ -440,13 +440,11 @@ supported by ``mongosh``, see - :binary:`~bin.mongo` Reference Page - :mongosh:`mongosh Documentation ` -.. class:: hidden - - .. toctree:: - :titlesonly: - - /tutorial/configure-mongo-shell - /tutorial/access-mongo-shell-help - /tutorial/write-scripts-for-the-mongo-shell - /core/shell-types - /reference/mongo-shell +.. toctree:: + :titlesonly: + + /tutorial/configure-mongo-shell + /tutorial/access-mongo-shell-help + /tutorial/write-scripts-for-the-mongo-shell + /core/shell-types + /reference/mongo-shell diff --git a/source/reference.txt b/source/reference.txt index bb98ed04302..dea3f8dbcdd 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -10,76 +10,75 @@ Reference :depth: 1 :class: singlecol -.. class:: toc +:doc:`/reference/operator` + Documentation of query, update, projection, and aggregation + framework operators. - :doc:`/reference/operator` - Documentation of query, update, projection, and aggregation - framework operators. +:doc:`/reference/command` + Documentation of all MongoDB :term:`database commands ` operations, syntax, and use. - :doc:`/reference/command` - Documentation of all MongoDB :term:`database commands ` operations, syntax, and use. +:doc:`/reference/method` + Documentation of all JavaScript methods and helpers in the + :binary:`~bin.mongo` shell. - :doc:`/reference/method` - Documentation of all JavaScript methods and helpers in the - :binary:`~bin.mongo` shell. +:doc:`/reference/program` + Documentation of :binary:`~bin.mongod` and :binary:`~bin.mongos` + and all other tools distributed with MongoDB. - :doc:`/reference/program` - Documentation of :binary:`~bin.mongod` and :binary:`~bin.mongos` - and all other tools distributed with MongoDB. +:doc:`/reference/configuration-options` + Full documentation of the configuration file and available + run-time operations. - :doc:`/reference/configuration-options` - Full documentation of the configuration file and available - run-time operations. +:doc:`/reference/parameters` + Documentation of all :binary:`~bin.mongod` and + :binary:`~bin.mongos` parameters that are available in the + :dbcommand:`setParameter` (command) and :setting:`setParameter` + run-time interface. - :doc:`/reference/parameters` - Documentation of all :binary:`~bin.mongod` and - :binary:`~bin.mongos` parameters that are available in the - :dbcommand:`setParameter` (command) and :setting:`setParameter` - run-time interface. +:doc:`/reference/limits` + A list of important limits and thresholds imposed by MongoDB. - :doc:`/reference/limits` - A list of important limits and thresholds imposed by MongoDB. +:doc:`/reference/explain-results` + Documentation on information returned from explain operations. - :doc:`/reference/explain-results` - Documentation on information returned from explain operations. +:doc:`/reference/system-collections` + Describes the collections that MongoDB reserves for internal use. - :doc:`/reference/system-collections` - Describes the collections that MongoDB reserves for internal use. +:doc:`/reference/connection-string` + The complete specification of the MongoDB connection string format + that the drivers use to describe connections to MongoDB + deployments. - :doc:`/reference/connection-string` - The complete specification of the MongoDB connection string format - that the drivers use to describe connections to MongoDB - deployments. +:doc:`/reference/collation` + Description of collation fields as well as supported languages and + associated locales for collation. - :doc:`/reference/collation` - Description of collation fields as well as supported languages and - associated locales for collation. +:doc:`/reference/mongodb-wire-protocol` + Description of the MongoDB Wire Protocol. - :doc:`/reference/mongodb-wire-protocol` - Description of the MongoDB Wire Protocol. +:doc:`/reference/log-messages` + Describes the components of log messages. - :doc:`/reference/log-messages` - Describes the components of log messages. +:doc:`/reference/exit-codes` + Details the codes and statuses that MongoDB returns when exiting. - :doc:`/reference/exit-codes` - Details the codes and statuses that MongoDB returns when exiting. +:doc:`/reference/glossary` + A glossary of common terms and concepts specific to MongoDB. - :doc:`/reference/glossary` - A glossary of common terms and concepts specific to MongoDB. +:doc:`/reference/default-mongodb-port` + List of default ports used by MongoDB. - :doc:`/reference/default-mongodb-port` - List of default ports used by MongoDB. +:doc:`/reference/mongodb-defaults` + List of default read and write concerns. - :doc:`/reference/mongodb-defaults` - List of default read and write concerns. +:doc:`/reference/server-sessions` + Describes server sessions. - :doc:`/reference/server-sessions` - Describes server sessions. +.. seealso:: -.. seealso:: The :ref:`genindex` may provide useful insight into the - reference material in this manual. The + The :doc:`/reference/data-models`, :doc:`/reference/sharding`, :doc:`/reference/replication`, and :doc:`/reference/security` contain additional reference material. diff --git a/source/reference/aggregation-variables.txt b/source/reference/aggregation-variables.txt index 5bf409503ca..2efa2226884 100644 --- a/source/reference/aggregation-variables.txt +++ b/source/reference/aggregation-variables.txt @@ -87,7 +87,7 @@ MongoDB offers the following system variables: * - .. variable:: REMOVE - A variable which evaluates to the missing value. Allows for the - conditional exclusion of fields. In a :pipeline:`$projection`, a + conditional exclusion of fields. In a :pipeline:`$project`, a field set to the variable :variable:`REMOVE` is excluded from the output. @@ -107,4 +107,6 @@ MongoDB offers the following system variables: - One of the allowed results of a :pipeline:`$redact` expression. -.. seealso:: :expression:`$let`, :pipeline:`$redact`, :expression:`$map` +.. seealso:: + + :expression:`$let`, :pipeline:`$redact`, :expression:`$map` diff --git a/source/reference/aggregation.txt b/source/reference/aggregation.txt index 7ca569f4b66..b0f0ab2d2a6 100644 --- a/source/reference/aggregation.txt +++ b/source/reference/aggregation.txt @@ -12,30 +12,28 @@ Aggregation Reference :depth: 1 :class: singlecol -.. class:: toc +:doc:`/meta/aggregation-quick-reference` + Quick reference card for aggregation pipeline. - :doc:`/meta/aggregation-quick-reference` - Quick reference card for aggregation pipeline. +:doc:`/reference/operator/aggregation/interface` + The reference for the data aggregation commands, which provide the + interfaces to MongoDB's aggregation capability. - :doc:`/reference/operator/aggregation/interface` - The reference for the data aggregation commands, which provide the - interfaces to MongoDB's aggregation capability. +:doc:`/reference/aggregation-commands-comparison` + A comparison of :dbcommand:`mapReduce` and :dbcommand:`aggregate` + commands. - :doc:`/reference/aggregation-commands-comparison` - A comparison of :dbcommand:`mapReduce` and :dbcommand:`aggregate` - commands. +:doc:`/reference/operator/aggregation` + Aggregation pipeline operations have a collection of operators + available to define and manipulate documents in pipeline stages. - :doc:`/reference/operator/aggregation` - Aggregation pipeline operations have a collection of operators - available to define and manipulate documents in pipeline stages. +:doc:`/reference/aggregation-variables` + Use of variables in aggregation pipeline expressions. - :doc:`/reference/aggregation-variables` - Use of variables in aggregation pipeline expressions. - - :doc:`/reference/sql-aggregation-comparison` - An overview common aggregation operations in SQL and MongoDB using - the aggregation pipeline and operators in MongoDB and common SQL - statements. +:doc:`/reference/sql-aggregation-comparison` + An overview common aggregation operations in SQL and MongoDB using + the aggregation pipeline and operators in MongoDB and common SQL + statements. .. toctree:: diff --git a/source/reference/bson-types.txt b/source/reference/bson-types.txt index ac92056de41..4233dab8a80 100644 --- a/source/reference/bson-types.txt +++ b/source/reference/bson-types.txt @@ -67,7 +67,9 @@ benefits: .. important:: .. include:: /includes/fact-ObjectId-timestamp-order.rst -.. seealso:: :method:`ObjectId()` +.. seealso:: + + :method:`ObjectId()` .. _document-bson-type-string: diff --git a/source/reference/built-in-roles.txt b/source/reference/built-in-roles.txt index 176baeec989..03f0d9c8937 100644 --- a/source/reference/built-in-roles.txt +++ b/source/reference/built-in-roles.txt @@ -127,7 +127,7 @@ Every database includes the following database administration roles: - :authaction:`listIndexes` - :authaction:`planCacheRead` - .. admonition:: Aside + .. note:: Aside Starting in version 4.2, MongoDB removes the :data:`system.indexes <.system.indexes>` and @@ -321,7 +321,7 @@ Cluster Administration Roles - :authaction:`listIndexes` - :authaction:`planCacheRead` - .. admonition:: Aside + .. note:: Aside Starting in version 4.2, MongoDB removes the :data:`system.indexes <.system.indexes>` and @@ -456,7 +456,7 @@ Cluster Administration Roles | :authaction:`planCacheRead` - .. admonition:: Aside + .. note:: Aside Starting in version 4.2, MongoDB removes the :data:`system.indexes <.system.indexes>` and @@ -555,7 +555,7 @@ Cluster Administration Roles - :authaction:`touch` - :authaction:`unlock` - .. admonition:: 4.4 Change + .. versionchanged:: 4.4 Starting in version 4.4, :authrole:`hostManager` no longer provides the :authrole:`cpuProfiler` privilege action on the @@ -710,7 +710,7 @@ Backup and Restoration Roles modification operations, *only* modify these data using the :ref:`user management methods `. - .. admonition:: Aside + .. note:: Aside Starting in version 4.2, MongoDB removes the :data:`system.namespaces <.system.namespaces>` diff --git a/source/reference/change-events.txt b/source/reference/change-events.txt index c58497e5712..1d240b68aca 100644 --- a/source/reference/change-events.txt +++ b/source/reference/change-events.txt @@ -1,4 +1,3 @@ -.. index:: changeStreams notification .. _change-events: ============= diff --git a/source/reference/command.txt b/source/reference/command.txt index 5747fc13aab..3a28c7c04ac 100644 --- a/source/reference/command.txt +++ b/source/reference/command.txt @@ -37,8 +37,6 @@ User Commands Aggregation Commands ~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -73,8 +71,6 @@ Aggregation Commands Geospatial Commands ~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -99,8 +95,6 @@ Geospatial Commands Query and Write Operation Commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -153,8 +147,6 @@ Query and Write Operation Commands Query Plan Cache Commands ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -193,8 +185,6 @@ Database Operations Authentication Commands ~~~~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -227,8 +217,6 @@ Authentication Commands User Management Commands ~~~~~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -277,8 +265,6 @@ User Management Commands Role Management Commands ~~~~~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -337,8 +323,6 @@ Role Management Commands Replication Commands ~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -402,14 +386,14 @@ Replication Commands /reference/command/nav-replication -.. seealso:: :doc:`/replication` for more information regarding +.. seealso:: + + :doc:`/replication` for more information regarding replication. Sharding Commands ~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -552,7 +536,9 @@ Sharding Commands /reference/command/nav-sharding -.. seealso:: :doc:`/sharding` for more information about MongoDB's +.. seealso:: + + :doc:`/sharding` for more information about MongoDB's sharding functionality. .. _session-commands: @@ -560,9 +546,7 @@ Sharding Commands Session Commands ~~~~~~~~~~~~~~~~ -.. only:: website - - .. include:: /includes/table-sessions-commands.rst +.. include:: /includes/table-sessions-commands.rst .. toctree:: :titlesonly: @@ -575,8 +559,6 @@ Session Commands Administration Commands ~~~~~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30 70 :header-rows: 1 @@ -725,8 +707,6 @@ Administration Commands Diagnostic Commands ~~~~~~~~~~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -796,7 +776,7 @@ Diagnostic Commands - Returns data that reflects the underlying host system. - * - :dbcommand:`isSelf` + * - :dbcommand:`_isSelf` - Internal command to support testing. @@ -855,17 +835,15 @@ Diagnostic Commands Free Monitoring Commands ~~~~~~~~~~~~~~~~~~~~~~~~ -.. only:: website +.. list-table:: - .. list-table:: - - * - Name + * - Name - - Description + - Description - * - :dbcommand:`setFreeMonitoring` + * - :dbcommand:`setFreeMonitoring` - - Enables/disables free monitoring during runtime. + - Enables/disables free monitoring during runtime. .. toctree:: :titlesonly: @@ -876,8 +854,6 @@ Free Monitoring Commands Auditing Commands ----------------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 diff --git a/source/reference/command/aggregate.txt b/source/reference/command/aggregate.txt index 5ba43d2eb64..69db812e58b 100644 --- a/source/reference/command/aggregate.txt +++ b/source/reference/command/aggregate.txt @@ -270,7 +270,7 @@ Session Idle Timeout For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit session -using :method:`Session.startSession()` and periodically refresh the +using :method:`Mongo.startSession()` and periodically refresh the session using the :dbcommand:`refreshSessions` command. See :limit:`Session Idle Timeout` for more information. @@ -386,7 +386,7 @@ and the second stage filters the results of that operation. .. note:: The :dbcommand:`aggregate` command does not specify a collection and - instead takes the form `{aggregate: 1}`. This is because the initial + instead takes the form ``{aggregate: 1}``. This is because the initial :pipeline:`$currentOp` stage does not draw input from a collection. It produces its own data that the rest of the pipeline uses. @@ -413,7 +413,10 @@ to ``true`` to return information about the aggregation operation. .. note:: The ``explain`` output is subject to change between releases. -.. seealso:: :method:`db.collection.aggregate()` method +.. seealso:: + + :method:`db.collection.aggregate()` method + Aggregate Data using External Sort ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -434,7 +437,10 @@ temporary files, as in the following example: .. include:: /includes/extracts/4.2-changes-usedDisk.rst -.. seealso:: :method:`db.collection.aggregate()` +.. seealso:: + + :method:`db.collection.aggregate()` + Aggregate Data Specifying Batch Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -577,4 +583,7 @@ the :ref:`let ` option. } ) -.. seealso:: :method:`db.collection.aggregate()` +.. seealso:: + + :method:`db.collection.aggregate()` + diff --git a/source/reference/command/clearJumboFlag.txt b/source/reference/command/clearJumboFlag.txt index 96daa98ed0d..8d375e1c033 100644 --- a/source/reference/command/clearJumboFlag.txt +++ b/source/reference/command/clearJumboFlag.txt @@ -131,182 +131,182 @@ Example Clear Jumbo Flag for a Chunk (Range-Based Shard Key) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +The :method:`sh.status()` includes the following +:data:`sh.status.databases..chunk-details` for the +``test.jumbo`` collection. - The :method:`sh.status()` includes the following - :data:`sh.status.databases..chunk-details` for the - ``test.jumbo`` collection. +.. code-block:: javascript + :copyable: false + :emphasize-lines: 11-12 + + ... // Content omitted for brevity + + test.jumbo + shard key: { "x" : 1 } + unique: false + balancing: true + chunks: + shardA 2 + shardB 2 + { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shardB Timestamp(3, 0) + { "x" : 1 } -->> { "x" : 2 } on : shardA Timestamp(6, 1) jumbo + { "x" : 2 } -->> { "x" : 3 } on : shardA Timestamp(5, 1) jumbo + { "x" : 3 } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(6, 0) + +The following :dbcommand:`clearJumboFlag` command specifies the +:ref:`bounds ` of the ``{ "x" : 1 } -->> { "x" : +2 }`` chunk: - .. code-block:: javascript - :copyable: false - :emphasize-lines: 11-12 +.. code-block:: javascript - ... // Content omitted for brevity - - test.jumbo - shard key: { "x" : 1 } - unique: false - balancing: true - chunks: - shardA 2 - shardB 2 - { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shardB Timestamp(3, 0) - { "x" : 1 } -->> { "x" : 2 } on : shardA Timestamp(6, 1) jumbo - { "x" : 2 } -->> { "x" : 3 } on : shardA Timestamp(5, 1) jumbo - { "x" : 3 } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(6, 0) - - The following :dbcommand:`clearJumboFlag` command specifies the - :ref:`bounds ` of the ``{ "x" : 1 } -->> { "x" : - 2 }`` chunk: - - .. code-block:: javascript - - db.adminCommand( { - clearJumboFlag: "test.jumbo", - bounds: [{ "x" : 1 }, { "x" : 2 }] - } ) - - Upon success, the command returns ``"ok": 1`` in its output: - - .. code-block:: javascript - :copyable: false - - { - "ok" : 1, - "operationTime" : Timestamp(1580190080, 5), - "$clusterTime" : { - "clusterTime" : Timestamp(1580190080, 5), - "signature" : { - "hash" : BinData(0,"0cYT49s72MHUYV1F2WpoEwlyeVs="), - "keyId" : NumberLong("6786859092951433239") - } + db.adminCommand( { + clearJumboFlag: "test.jumbo", + bounds: [{ "x" : 1 }, { "x" : 2 }] + } ) + +Upon success, the command returns ``"ok": 1`` in its output: + +.. code-block:: javascript + :copyable: false + + { + "ok" : 1, + "operationTime" : Timestamp(1580190080, 5), + "$clusterTime" : { + "clusterTime" : Timestamp(1580190080, 5), + "signature" : { + "hash" : BinData(0,"0cYT49s72MHUYV1F2WpoEwlyeVs="), + "keyId" : NumberLong("6786859092951433239") } } + } - The following :dbcommand:`clearJumboFlag` command specifies the - :ref:`find ` field to find the chunk that - contains the shard key ``{ "x" : 2 }`` : +The following :dbcommand:`clearJumboFlag` command specifies the +:ref:`find ` field to find the chunk that +contains the shard key ``{ "x" : 2 }`` : - .. code-block:: javascript - - db.adminCommand( { - clearJumboFlag: "test.jumbo", - find: { "x" : 2 } - } ) +.. code-block:: javascript - Upon success, the command returns ``"ok": 1`` in its output: + db.adminCommand( { + clearJumboFlag: "test.jumbo", + find: { "x" : 2 } + } ) - .. code-block:: javascript - :copyable: false +Upon success, the command returns ``"ok": 1`` in its output: - { - "ok" : 1, - "operationTime" : Timestamp(1580191819, 5), - "$clusterTime" : { - "clusterTime" : Timestamp(1580191819, 5), - "signature" : { - "hash" : BinData(0,"N6x6drN7HUq5MR5ezUJns1rfeqY="), - "keyId" : NumberLong("6786859092951433239") - } +.. code-block:: javascript + :copyable: false + + { + "ok" : 1, + "operationTime" : Timestamp(1580191819, 5), + "$clusterTime" : { + "clusterTime" : Timestamp(1580191819, 5), + "signature" : { + "hash" : BinData(0,"N6x6drN7HUq5MR5ezUJns1rfeqY="), + "keyId" : NumberLong("6786859092951433239") } } - - To verify the operation, run :method:`sh.status()` again. The ``jumbo`` - flag should no longer appear in its output. + } - .. code-block:: javascript - :copyable: false - :emphasize-lines: 11-12 +To verify the operation, run :method:`sh.status()` again. The ``jumbo`` +flag should no longer appear in its output. - ... // Content omitted for brevity - - test.jumbo - shard key: { "x" : 1 } - unique: false - balancing: true - chunks: - shardA 2 - shardB 2 - { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shardB Timestamp(3, 0) - { "x" : 1 } -->> { "x" : 2 } on : shardA Timestamp(7, 0) - { "x" : 2 } -->> { "x" : 3 } on : shardA Timestamp(8, 0) - { "x" : 3 } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(6, 0) +.. code-block:: javascript + :copyable: false + :emphasize-lines: 11-12 + + ... // Content omitted for brevity + + test.jumbo + shard key: { "x" : 1 } + unique: false + balancing: true + chunks: + shardA 2 + shardB 2 + { "x" : { "$minKey" : 1 } } -->> { "x" : 1 } on : shardB Timestamp(3, 0) + { "x" : 1 } -->> { "x" : 2 } on : shardA Timestamp(7, 0) + { "x" : 2 } -->> { "x" : 3 } on : shardA Timestamp(8, 0) + { "x" : 3 } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(6, 0) Clear Jumbo Flag for a Chunk (Hashed Shard Key) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +The :method:`sh.status()` includes the following +:data:`sh.status.databases..chunk-details` for the +``test.jumboHashed`` collection. The collection uses a hashed shard +key. - The :method:`sh.status()` includes the following - :data:`sh.status.databases..chunk-details` for the - ``test.jumboHashed`` collection. The collection uses a hashed shard - key. +.. code-block:: javascript + :copyable: false + :emphasize-lines: 12 + + ... // Content omitted for brevity + + test.jumboHashed + shard key: { "x" : "hashed" } + unique: false + balancing: true + chunks: + shardA 2 + shardB 2 + { "x" : { "$minKey" : 1 } } -->> { "x" : NumberLong(0) } on : shardA Timestamp(1, 0) + { "x" : NumberLong(0) } -->> { "x" : NumberLong("848411777775835583") } on : shardA Timestamp(4, 0) + { "x" : NumberLong("848411777775835583") } -->> { "x" : NumberLong("5902408780260971510") } on : shardB Timestamp(4, 1) jumbo + { "x" : NumberLong("5902408780260971510") } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(2, 2) + +To clear the ``jumbo`` flag for a chunk if the collection uses a +:term:`hashed shard key`, use :dbcommand:`clearJumboFlag` with the +:ref:`bounds ` field: - .. code-block:: javascript - :copyable: false - :emphasize-lines: 12 +.. code-block:: javascript - ... // Content omitted for brevity - - test.jumboHashed - shard key: { "x" : "hashed" } - unique: false - balancing: true - chunks: - shardA 2 - shardB 2 - { "x" : { "$minKey" : 1 } } -->> { "x" : NumberLong(0) } on : shardA Timestamp(1, 0) - { "x" : NumberLong(0) } -->> { "x" : NumberLong("848411777775835583") } on : shardA Timestamp(4, 0) - { "x" : NumberLong("848411777775835583") } -->> { "x" : NumberLong("5902408780260971510") } on : shardB Timestamp(4, 1) jumbo - { "x" : NumberLong("5902408780260971510") } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(2, 2) - - To clear the ``jumbo`` flag for a chunk if the collection uses a - :term:`hashed shard key`, use :dbcommand:`clearJumboFlag` with the - :ref:`bounds ` field: - - .. code-block:: javascript - - db.adminCommand( { - clearJumboFlag: "test.jumboHashed", - bounds: [{ "x" : NumberLong("848411777775835583") }, { "x" : NumberLong("5902408780260971510") }] - } ) - - Upon success, the command returns ``"ok": 1`` in its output: - - .. code-block:: javascript - :copyable: false - - { - "ok" : 1, - "operationTime" : Timestamp(1580194290, 5), - "$clusterTime" : { - "clusterTime" : Timestamp(1580194290, 5), - "signature" : { - "hash" : BinData(0,"nWCqOYVrab7NEGHWoo2NYENqHR4="), - "keyId" : NumberLong("6786875525496307742") - } + db.adminCommand( { + clearJumboFlag: "test.jumboHashed", + bounds: [{ "x" : NumberLong("848411777775835583") }, { "x" : NumberLong("5902408780260971510") }] + } ) + +Upon success, the command returns ``"ok": 1`` in its output: + +.. code-block:: javascript + :copyable: false + + { + "ok" : 1, + "operationTime" : Timestamp(1580194290, 5), + "$clusterTime" : { + "clusterTime" : Timestamp(1580194290, 5), + "signature" : { + "hash" : BinData(0,"nWCqOYVrab7NEGHWoo2NYENqHR4="), + "keyId" : NumberLong("6786875525496307742") } } + } - To verify the operation, run :method:`sh.status()` again. The - ``jumbo`` flag should no longer appear in its output. +To verify the operation, run :method:`sh.status()` again. The +``jumbo`` flag should no longer appear in its output. + +.. code-block:: javascript + :copyable: false + :emphasize-lines: 12 - .. code-block:: javascript - :copyable: false - :emphasize-lines: 12 + ... // Content omitted for brevity - ... // Content omitted for brevity + test.jumboHashed + shard key: { "x" : "hashed" } + unique: false + balancing: true + chunks: + shardA 2 + shardB 2 + { "x" : { "$minKey" : 1 } } -->> { "x" : NumberLong(0) } on : shardA Timestamp(1, 0) + { "x" : NumberLong(0) } -->> { "x" : NumberLong("848411777775835583") } on : shardA Timestamp(4, 0) + { "x" : NumberLong("848411777775835583") } -->> { "x" : NumberLong("5902408780260971510") } on : shardB Timestamp(5, 0) + { "x" : NumberLong("5902408780260971510") } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(2, 2) + +.. seealso:: + + - test.jumboHashed - shard key: { "x" : "hashed" } - unique: false - balancing: true - chunks: - shardA 2 - shardB 2 - { "x" : { "$minKey" : 1 } } -->> { "x" : NumberLong(0) } on : shardA Timestamp(1, 0) - { "x" : NumberLong(0) } -->> { "x" : NumberLong("848411777775835583") } on : shardA Timestamp(4, 0) - { "x" : NumberLong("848411777775835583") } -->> { "x" : NumberLong("5902408780260971510") } on : shardB Timestamp(5, 0) - { "x" : NumberLong("5902408780260971510") } -->> { "x" : { "$maxKey" : 1 } } on : shardB Timestamp(2, 2) - -.. seealso:: :doc:`/tutorial/clear-jumbo-flag` + :doc:`/tutorial/clear-jumbo-flag` diff --git a/source/reference/command/collMod.txt b/source/reference/command/collMod.txt index c6b387a798b..5cb077fcdbd 100644 --- a/source/reference/command/collMod.txt +++ b/source/reference/command/collMod.txt @@ -27,8 +27,8 @@ Definition The command takes the following prototype form: - .. admonition:: Starting in MongoDB 4.2 - :class: note + .. note:: Starting in MongoDB 4.2 + - MongoDB removes the MMAPv1 storage engine and the MMAPv1 specific options ``noPadding`` and ``usePowerOf2Sizes`` for @@ -59,7 +59,7 @@ Options Index Options ~~~~~~~~~~~~~ -.. index:: expireAfterSeconds + .. collflag:: index The :collflag:`index` option can change the following properties of @@ -111,7 +111,9 @@ Index Options Modifying the index option ``hidden`` resets the :pipeline:`$indexStats` for the index if the value changes. - .. seealso:: + .. seealso:: + + :method:`db.collection.hideIndex()` and :method:`db.collection.unhideIndex()`. @@ -136,7 +138,9 @@ Index Options If the index does not exist, the command errors with the message ``"cannot find index for ns "``. - .. seealso:: + .. seealso:: + + - :doc:`/core/index-hidden` - :method:`db.collection.hideIndex()` @@ -350,7 +354,9 @@ old and new value for the changed property: To hide a text index, you must specify the index by ``name`` and not by ``keyPattern``. -.. seealso:: +.. seealso:: + + - :doc:`/core/index-hidden` - :method:`db.collection.hideIndex()` diff --git a/source/reference/command/compact.txt b/source/reference/command/compact.txt index bae092cf52d..1650aa546f3 100644 --- a/source/reference/command/compact.txt +++ b/source/reference/command/compact.txt @@ -29,8 +29,8 @@ Definition :dbcommand:`compact` takes the following fields: - .. admonition:: Starting in MongoDB 4.2 - :class: note + .. note:: Starting in MongoDB 4.2 + MongoDB removes the MMAPv1 storage engine and the MMAPv1 specific options ``paddingFactor``, ``paddingBytes``, ``preservePadding`` diff --git a/source/reference/command/connPoolStats.txt b/source/reference/command/connPoolStats.txt index 752c9b08e2c..4f77fb1a2db 100644 --- a/source/reference/command/connPoolStats.txt +++ b/source/reference/command/connPoolStats.txt @@ -420,11 +420,13 @@ Output Displays connection statics related to TaskExecutor pools. Typically, there will be one TaskExecutorPool per core, e.g. - :data:`~connPoolStats.pools.NetworkInterfaceTL-TaskExecutorPool-0` ... - :data:`~connPoolStats.pools.NetworkInterfaceTL-TaskExecutorPool-7` + ``pools.NetworkInterfaceTL-TaskExecutorPool-0`` ... + ``pools.NetworkInterfaceTL-TaskExecutorPool-7`` for an 8-core processor. - .. seealso:: :parameter:`taskExecutorPoolSize` + .. seealso:: + + :parameter:`taskExecutorPoolSize` .. data:: connPoolStats.pools.NetworkInterfaceTL-ShardRegistry @@ -508,26 +510,26 @@ Output .. data:: connPoolStats.replicaSets.[replicaSet].hosts[n].ismaster Reports ``true`` if this - :data:`~connPoolStats.replicaSets.[replicaSet].host` is the + :data:`host ` is the :term:`primary` member of the :term:`replica set`. .. data:: connPoolStats.replicaSets.[replicaSet].hosts[n].hidden Reports ``true`` if this - :data:`~connPoolStats.replicaSets.[replicaSet].host` is a + :data:`host ` is a :term:`hidden member` of the :term:`replica set`. .. data:: connPoolStats.replicaSets.[replicaSet].hosts[n].secondary Reports ``true`` if this - :data:`~connPoolStats.replicaSets.[replicaSet].host` is a + :data:`host ` is a :term:`secondary` member of the :term:`replica set`. .. data:: connPoolStats.replicaSets.[replicaSet].hosts[n].pingTimeMillis Reports the ping time in milliseconds from the :binary:`~bin.mongos` or :binary:`~bin.mongod` to this - :data:`~connPoolStats.replicaSets.[replicaSet].host`. + :data:`host `. .. data:: connPoolStats.replicaSets.[replicaSet].hosts[n].tags @@ -536,3 +538,6 @@ Output See also :ref:`command-response` for details on the ``ok`` status field, the ``operationTime`` field and the ``$clusterTime`` field. + + +:data:`host ` \ No newline at end of file diff --git a/source/reference/command/convertToCapped.txt b/source/reference/command/convertToCapped.txt index fdb46f816c6..de13e3e370e 100644 --- a/source/reference/command/convertToCapped.txt +++ b/source/reference/command/convertToCapped.txt @@ -12,8 +12,8 @@ convertToCapped .. dbcommand:: convertToCapped - .. admonition:: Do Not Run This Command In Sharded Clusters - :class: warning + .. warning:: Do Not Run This Command In Sharded Clusters + MongoDB does **not** support the :dbcommand:`convertToCapped` command in a sharded cluster. @@ -142,4 +142,6 @@ MongoDB will return the following: .. include:: /includes/fact-convertToCapped-indexes.rst -.. seealso:: :dbcommand:`create` +.. seealso:: + + :dbcommand:`create` diff --git a/source/reference/command/create.txt b/source/reference/command/create.txt index b6e11843915..2ed3f483f2a 100644 --- a/source/reference/command/create.txt +++ b/source/reference/command/create.txt @@ -25,8 +25,8 @@ Definition :dbcommand:`create` has the following form: - .. admonition:: Starting in MongoDB 4.2 - :class: note + .. note:: Starting in MongoDB 4.2 + MongoDB removes the MMAPv1 storage engine and the MMAPv1 specific option ``flags`` for :dbcommand:`create`. @@ -407,7 +407,10 @@ The following operation creates a ``managementRatings`` view with the .. include:: /includes/extracts/views-public-definition.rst -.. seealso:: :method:`db.createView()` +.. seealso:: + + :method:`db.createView()` + .. _create-collation-example: @@ -460,7 +463,9 @@ The same operation on a collection that uses simple binary collation { "_id" : 2, "category" : "cafe" } { "_id" : 1, "category" : "café" } -.. seealso:: :ref:`create-view-w-collation`, :ref:`ref-collation-and-views` +.. seealso:: + + :ref:`create-view-w-collation`, :ref:`ref-collation-and-views` Specify Storage Engine Options ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/command/createIndexes.txt b/source/reference/command/createIndexes.txt index 31b3c1d3de2..b36f6aafcdb 100644 --- a/source/reference/command/createIndexes.txt +++ b/source/reference/command/createIndexes.txt @@ -523,8 +523,8 @@ Considerations Index Names ~~~~~~~~~~~ -.. admonition:: Changed in MongoDB 4.2 - :class: note +.. note:: Changed in MongoDB 4.2 + .. include:: /includes/extracts/4.2-changes-index-names.rst @@ -677,7 +677,9 @@ For example, db.restaurants.unhideIndex( { borough: 1, city: 1 } ); -.. seealso:: :doc:`/core/index-hidden` +.. seealso:: + + :doc:`/core/index-hidden` .. _createIndexes-command-wildcard-behavior: diff --git a/source/reference/command/currentOp.txt b/source/reference/command/currentOp.txt index 8c0f3bb1b06..0052882ab13 100644 --- a/source/reference/command/currentOp.txt +++ b/source/reference/command/currentOp.txt @@ -100,7 +100,9 @@ operations without the :authaction:`inprog` privilege action. db.adminCommand( { currentOp: 1, "$ownOps": 1 } ) -.. seealso:: :ref:`create-role-to-manage-ops` +.. seealso:: + + :ref:`create-role-to-manage-ops` .. _currentOp-examples: @@ -250,8 +252,7 @@ Output Fields .. data:: currentOp.appName - A string with information about the type of client which made the - request. + .. include:: /includes/fact-client-appname.rst .. data:: currentOp.clientMetadata @@ -273,7 +274,10 @@ Output Fields operation. Each user document contains the ``user`` name and the authentication ``db``. - .. seealso:: :data:`currentOp.runBy` + .. seealso:: + + :data:`currentOp.runBy` + .. versionadded:: 4.2 @@ -377,11 +381,11 @@ Output Fields The duration of the transaction in microseconds. - The :data:`~currentOp.transaction.parameters.timeActiveMicros` + The :data:`~currentOp.transaction.timeActiveMicros` value added to the - :data:`~currentOp.transaction.parameters.timeInactiveMicros` + :data:`~currentOp.transaction.timeInactiveMicros` should equal the - :data:`~currentOp.transaction.parameters.timeOpenMicros`. + :data:`~currentOp.transaction.timeOpenMicros`. Only present if the operation is part of a multi-document transaction. @@ -393,11 +397,11 @@ Output Fields i.e. when the transaction had operations running. The - :data:`~currentOp.transaction.parameters.timeActiveMicros` + :data:`~currentOp.transaction.timeActiveMicros` value added to the - :data:`~currentOp.transaction.parameters.timeInactiveMicros` + :data:`~currentOp.transaction.timeInactiveMicros` should equal the - :data:`~currentOp.transaction.parameters.timeOpenMicros`. + :data:`~currentOp.transaction.timeOpenMicros`. Only present if the operation is part of a multi-document transaction. @@ -409,11 +413,11 @@ Output Fields inactive; i.e. when the transaction had no operations running. The - :data:`~currentOp.transaction.parameters.timeInactiveMicros` + :data:`~currentOp.transaction.timeInactiveMicros` value added to the - :data:`~currentOp.transaction.parameters.timeActiveMicros` + :data:`~currentOp.transaction.timeActiveMicros` should equal the - :data:`~currentOp.transaction.parameters.timeOpenMicros`. + :data:`~currentOp.transaction.timeOpenMicros`. Only present if the operation is part of a multi-document transaction. @@ -733,7 +737,7 @@ Output Fields ``"command"`` operations include most :doc:`commands ` such as the - :dbcommand:`createIndexes` and :dbcommand:`findandmodify`. + :dbcommand:`createIndexes` and :dbcommand:`findAndModify`. .. data:: currentOp.ns @@ -824,7 +828,10 @@ Output Fields - If false, the cursor will time out when idle. - .. seealso:: :method:`cursor.addOption()` + .. seealso:: + + :method:`cursor.addOption()` + .. data:: currentOp.cursor.tailable @@ -892,17 +899,6 @@ Output Fields Only present if the cursor is not idle. -.. data:: currentOp.client - - The IP address (or hostname) and the ephemeral port of the client - connection where the operation originates. If your ``inprog`` - array has operations from many different clients, use this string - to relate operations to clients. - -.. data:: currentOp.appName - - .. include:: /includes/fact-client-appname.rst - .. data:: currentOp.waitingForLatch The :data:`~currentOp.waitingForLatch` document is only diff --git a/source/reference/command/delete.txt b/source/reference/command/delete.txt index f330a073188..e31ce61c3d8 100644 --- a/source/reference/command/delete.txt +++ b/source/reference/command/delete.txt @@ -204,7 +204,7 @@ Definition - :return: + :returns: A document that contains the status of the operation. See :ref:`delete-command-output` for details. diff --git a/source/reference/command/distinct.txt b/source/reference/command/distinct.txt index d36beace0d6..fe8afae211a 100644 --- a/source/reference/command/distinct.txt +++ b/source/reference/command/distinct.txt @@ -204,7 +204,9 @@ contains the distinct ``sku`` values: "ok" : 1 } -.. seealso:: :ref:`document-dot-notation` for information on accessing fields +.. seealso:: + + :ref:`document-dot-notation` for information on accessing fields within embedded documents .. _distinct-command-array: diff --git a/source/reference/command/dropDatabase.txt b/source/reference/command/dropDatabase.txt index 4efe7ad775b..acc927888a4 100644 --- a/source/reference/command/dropDatabase.txt +++ b/source/reference/command/dropDatabase.txt @@ -137,4 +137,6 @@ the ``temp`` database: .. write-lock -.. seealso:: :dbcommand:`dropAllUsersFromDatabase` +.. seealso:: + + :dbcommand:`dropAllUsersFromDatabase` diff --git a/source/reference/command/dropIndexes.txt b/source/reference/command/dropIndexes.txt index b095c57af5c..28bdac3e150 100644 --- a/source/reference/command/dropIndexes.txt +++ b/source/reference/command/dropIndexes.txt @@ -192,4 +192,7 @@ Examples db.runCommand( { dropIndexes: "collection", index: [ "age_1", "age_1_status_1" ] } ) -.. seealso:: :method:`db.collection.dropIndexes()` and :method:`db.collection.dropIndex()` +.. seealso:: + + :method:`db.collection.dropIndexes()` and :method:`db.collection.dropIndex()` + diff --git a/source/reference/command/enableSharding.txt b/source/reference/command/enableSharding.txt index c0dac783489..d18fd05edb1 100644 --- a/source/reference/command/enableSharding.txt +++ b/source/reference/command/enableSharding.txt @@ -84,8 +84,8 @@ The command takes the following fields: the primary shard, it is recommended to let the balancer select the primary shard instead. - .. admonition:: Tip - :class: warning + .. warning:: Tip + In general, you should not need to specify the primary shard. Allow the balancer to select the primary shard instead. diff --git a/source/reference/command/explain.txt b/source/reference/command/explain.txt index e5ff16a05f0..893d6e4193c 100644 --- a/source/reference/command/explain.txt +++ b/source/reference/command/explain.txt @@ -115,28 +115,22 @@ returned depend on the ``verbosity`` mode. name: "queryPlanner Mode" content: | - .. container:: - - .. include:: /includes/fact-explain-verbosity-queryPlanner.rst + .. include:: /includes/fact-explain-verbosity-queryPlanner.rst - id: executionstats name: "executionStats Mode" content: | - .. container:: - - .. include:: /includes/fact-explain-verbosity-executionStats.rst + .. include:: /includes/fact-explain-verbosity-executionStats.rst - id: allplans name: "allPlansExecution Mode (Default)" content: | - .. container:: - - By default, :dbcommand:`explain` runs in - ``"allPlansExecution"`` verbosity mode. + By default, :dbcommand:`explain` runs in + ``"allPlansExecution"`` verbosity mode. - .. include:: /includes/fact-explain-verbosity-allPlansExecution.rst + .. include:: /includes/fact-explain-verbosity-allPlansExecution.rst Explain and Write Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/command/find.txt b/source/reference/command/find.txt index e3eafc95d6c..adb9274cb79 100644 --- a/source/reference/command/find.txt +++ b/source/reference/command/find.txt @@ -315,8 +315,8 @@ The command accepts the following fields: oplogReplay: true, filter: { ts: { $gte: new Timestamp(1514764800, 0) } } } - .. admonition:: Deprecated - :class: note + .. note:: Deprecated + .. versionchanged:: 4.4 @@ -521,7 +521,7 @@ Session Idle Timeout For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit session -using :method:`Session.startSession()` and periodically refresh the +using :method:`Mongo.startSession()` and periodically refresh the session using the :dbcommand:`refreshSessions` command. See :limit:`Session Idle Timeout` for more information. @@ -646,5 +646,6 @@ For the syntax, see :ref:`let `. let : { targetFlavor: "chocolate" } } ) - -.. seealso:: :ref:`3.2-driver-compatibility` +.. seealso:: + + :ref:`3.2-driver-compatibility` diff --git a/source/reference/command/findAndModify.txt b/source/reference/command/findAndModify.txt index 4bf8640c280..873e065cc49 100644 --- a/source/reference/command/findAndModify.txt +++ b/source/reference/command/findAndModify.txt @@ -430,53 +430,49 @@ filter must include an equality condition on the shard key. Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +.. include:: /includes/shard-key-modification-warning.rst - .. include:: /includes/shard-key-modification-warning.rst +To modify the **existing** shard key value with +:dbcommand:`findAndModify`: - To modify the **existing** shard key value with - :dbcommand:`findAndModify`: - - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. - - - You :red:`must` include an equality filter on the full shard key. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. + +- You :red:`must` include an equality filter on the full shard key. .. _cmd-findAndModify-missing-shard-key: Missing Shard Key ````````````````` -.. container:: +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:dbcommand:`findAndModify` to set the document's **missing** shard +key: - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :dbcommand:`findAndModify` to set the document's **missing** shard - key: +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + ` if the new shard key value is not + ``null``. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - ` if the new shard key value is not - ``null``. +- You :red:`must` include an equality filter on the full shard key. - - You :red:`must` include an equality filter on the full shard key. +.. tip:: - .. tip:: + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst +See also: - See also: - - - :ref:`shard-key-missing` +- :ref:`shard-key-missing` Document Validation @@ -544,14 +540,14 @@ This command performs the following actions: #. The ``query`` finds a document in the ``people`` collection where the ``name`` field has the value ``Tom``, the ``state`` field has the value ``active`` and the ``rating`` field has a value - :operator:`greater than <$gt>` 10. + :expression:`greater than <$gt>` 10. #. The ``sort`` orders the results of the query in ascending order. If multiple documents meet the ``query`` condition, the command will select for modification the first document as ordered by this ``sort``. -#. The ``update`` :operator:`increments <$inc>` the value of the +#. The ``update`` :update:`increments <$inc>` the value of the ``score`` field by 1. #. The command returns a document with the following fields: @@ -823,8 +819,6 @@ Update Elements Match ``arrayFilters`` Criteria Create a collection ``students`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.insert([ @@ -837,8 +831,6 @@ To modify all elements that are greater than or equal to ``100`` in the ``grades`` array, use the positional :update:`$[\]` operator with the ``arrayFilters`` option: -.. cssclass:: copyable-code - .. code-block:: javascript db.runCommand( @@ -1080,5 +1072,6 @@ For the syntax, see :ref:`let `. let: { targetFlavor: "cherry" } } ) +.. seealso:: -.. seealso:: :ref:`perform-findAndModify-linearizable-reads` + :ref:`perform-findAndModify-linearizable-reads` diff --git a/source/reference/command/geoSearch.txt b/source/reference/command/geoSearch.txt index 65d29256d6d..901132e6c31 100644 --- a/source/reference/command/geoSearch.txt +++ b/source/reference/command/geoSearch.txt @@ -12,8 +12,8 @@ geoSearch .. dbcommand:: geoSearch - .. admonition:: Deprecation - :class: important + .. important:: Deprecation + .. include:: /includes/extracts/4.4-changes-geo-deprecation.rst diff --git a/source/reference/command/getDefaultRWConcern.txt b/source/reference/command/getDefaultRWConcern.txt index d527ece20db..bce4c579889 100644 --- a/source/reference/command/getDefaultRWConcern.txt +++ b/source/reference/command/getDefaultRWConcern.txt @@ -140,13 +140,15 @@ Definition informational and should not be used for any recency comparisons. -.. seealso:: :dbcommand:`setDefaultRWConcern` +.. seealso:: + + :dbcommand:`setDefaultRWConcern` Behavior -------- -.. admonition:: Requires ``featureCompatibilityVersion`` 4.4+ - :class: note +.. note:: Requires ``featureCompatibilityVersion`` 4.4+ + Each :binary:`~bin.mongod` in the replica set or sharded cluster *must* have :ref:`featureCompatibilityVersion ` set to diff --git a/source/reference/command/getFreeMonitoringStatus.txt b/source/reference/command/getFreeMonitoringStatus.txt index 0aa47bc5eb2..f65c98b21ce 100644 --- a/source/reference/command/getFreeMonitoringStatus.txt +++ b/source/reference/command/getFreeMonitoringStatus.txt @@ -87,4 +87,7 @@ The command returns a document with the following fields: - For details on these fields, see :ref:`command-response`. -.. seealso:: :serverstatus:`freeMonitoring` field returned from :method:`db.serverStatus()` +.. seealso:: + + :serverstatus:`freeMonitoring` field returned from :method:`db.serverStatus()` + diff --git a/source/reference/command/getLastError.txt b/source/reference/command/getLastError.txt index 67cf3e7cf85..d01732d7515 100644 --- a/source/reference/command/getLastError.txt +++ b/source/reference/command/getLastError.txt @@ -89,14 +89,16 @@ Definition .. versionadded:: 4.4 - .. seealso:: :doc:`/reference/write-concern` + .. seealso:: + + :doc:`/reference/write-concern` .. _getLastError-output: Output ------ -Each :dbcommand:`~db.collection.getLastError()` command returns a document containing a +Each :dbcommand:`getLastError` command returns a document containing a subset of the fields listed below. .. data:: getLastError.ok @@ -206,7 +208,9 @@ subset of the fields listed below. If set, ``wnote`` indicates that the preceding operation's error relates to using the ``w`` parameter to :dbcommand:`getLastError`. - .. see:: :doc:`/reference/write-concern` for more information about + .. see:: + + :doc:`/reference/write-concern` for more information about ``w`` values. .. data:: getLastError.wtimeout @@ -227,7 +231,7 @@ subset of the fields listed below. :data:`getLastError.wtime` is the number of milliseconds spent waiting for the preceding operation to complete. If :dbcommand:`getLastError` timed out, :data:`~getLastError.wtime` and - :dbcommand:`getLastError.waited` are equal. + :data:`~getLastError.waited` are equal. .. data:: getLastError.writtenTo @@ -247,7 +251,7 @@ Confirm Replication to Two Replica Set Members The following example ensures the preceding operation has replicated to two members (the primary and one other member). The command also specifies a timeout of ``5000`` milliseconds to ensure that -the:dbcommand:`getLastError` command does not block forever if MongoDB +the :dbcommand:`getLastError` command does not block forever if MongoDB cannot satisfy the requested write concern: .. code-block:: javascript @@ -260,7 +264,7 @@ Confirm Replication to a Majority of a Replica Set The following example ensures the write operation has replicated to a majority of the voting members of the replica set. The command also specifies a timeout of ``5000`` milliseconds to ensure that -the:dbcommand:`getLastError` command does not block forever if MongoDB +the :dbcommand:`getLastError` command does not block forever if MongoDB cannot satisfy the requested write concern: .. code-block:: javascript diff --git a/source/reference/command/getLog.txt b/source/reference/command/getLog.txt index d35c9e958f9..a060c586fd3 100644 --- a/source/reference/command/getLog.txt +++ b/source/reference/command/getLog.txt @@ -35,32 +35,30 @@ The :dbcommand:`getLog` command has the following syntax: Command Fields ~~~~~~~~~~~~~~ -.. container:: +The possible values for :dbcommand:`getLog` are: - The possible values for :dbcommand:`getLog` are: +.. list-table:: + :header-rows: 1 + :widths: 20 80 - .. list-table:: - :header-rows: 1 - :widths: 20 80 - - * - Value - - Description + * - Value + - Description - * - ``*`` + * - ``*`` - - Returns a list of the available values to the - :dbcommand:`getLog` command. + - Returns a list of the available values to the + :dbcommand:`getLog` command. - * - ``global`` - - - Returns the combined output of all recent log entries. + * - ``global`` - * - ``startupWarnings`` - - - Returns log entries that *may* contain errors or warnings - from MongoDB's log from when the current process started. If - :binary:`~bin.mongod` started without warnings, this filter - may return an empty array. + - Returns the combined output of all recent log entries. + + * - ``startupWarnings`` + + - Returns log entries that *may* contain errors or warnings + from MongoDB's log from when the current process started. If + :binary:`~bin.mongod` started without warnings, this filter + may return an empty array. .. note:: @@ -75,21 +73,19 @@ Command Fields Output ~~~~~~ -.. container:: - - If specified ``*``, then the command returns a document with the - names of the other acceptable values. +If specified ``*``, then the command returns a document with the +names of the other acceptable values. - Otherwise, the command returns a document that includes the following - fields: +Otherwise, the command returns a document that includes the following +fields: - - ``totalLinesWritten`` field that contains the number of log events +- ``totalLinesWritten`` field that contains the number of log events - - ``log`` field that contains an array of log events +- ``log`` field that contains an array of log events - - A :method:`db.adminCommand()` :ref:`response document - `, containing status and timestamp - information. +- A :method:`db.adminCommand()` :ref:`response document + `, containing status and timestamp + information. Behavior -------- diff --git a/source/reference/command/getParameter.txt b/source/reference/command/getParameter.txt index 71828d9ed35..cbe1172042e 100644 --- a/source/reference/command/getParameter.txt +++ b/source/reference/command/getParameter.txt @@ -47,7 +47,7 @@ getParameter - Specify a value of: - ``'*'`` to return all parameters available to - :dbcommand:`getParameters`, ignoring the ```` field. + :dbcommand:`getParameter`, ignoring the ```` field. - any numerical value to return the value for the specified ````. @@ -121,6 +121,9 @@ The following operation runs :dbcommand:`getParameter` with a value of The output may vary depending on the version of MongoDB and the specific configuration of the running MongoDB instance. -.. seealso:: :dbcommand:`setParameter` for more about these parameters. +.. seealso:: + + :dbcommand:`setParameter` for more about these parameters. + .. slave-ok, admin-only diff --git a/source/reference/command/insert.txt b/source/reference/command/insert.txt index f54750c7ed3..667ab30c969 100644 --- a/source/reference/command/insert.txt +++ b/source/reference/command/insert.txt @@ -104,7 +104,7 @@ Definition .. versionadded:: 4.4 - :return: + :returns: A document that contains the status of the operation. See :ref:`insert-command-output` for details. diff --git a/source/reference/command/isMaster.txt b/source/reference/command/isMaster.txt index ad576698a70..cec56f6fa2e 100644 --- a/source/reference/command/isMaster.txt +++ b/source/reference/command/isMaster.txt @@ -315,7 +315,10 @@ of a replica set: .. include:: /includes/fact-tags-field.rst - .. seealso:: :rsconf:`members[n].tags` + .. seealso:: + + :rsconf:`members[n].tags` + .. data:: isMaster.me diff --git a/source/reference/command/killAllSessions.txt b/source/reference/command/killAllSessions.txt index cc918db62f0..b312ad06c10 100644 --- a/source/reference/command/killAllSessions.txt +++ b/source/reference/command/killAllSessions.txt @@ -36,7 +36,9 @@ to kill all sessions for all users in the system. [#exception]_ To view existing sessions, see :pipeline:`$listSessions` operation or :pipeline:`$listLocalSessions`. -.. seealso:: :dbcommand:`killAllSessionsByPattern` +.. seealso:: + + :dbcommand:`killAllSessionsByPattern` .. |command| replace:: :dbcommand:`killAllSessions` diff --git a/source/reference/command/killAllSessionsByPattern.txt b/source/reference/command/killAllSessionsByPattern.txt index 77c5f2ff921..b514813cb64 100644 --- a/source/reference/command/killAllSessionsByPattern.txt +++ b/source/reference/command/killAllSessionsByPattern.txt @@ -65,7 +65,9 @@ Specify an empty array to kill all sessions. [#exception]_ To view existing sessions, see :pipeline:`$listSessions` operation or :pipeline:`$listLocalSessions`. -.. seealso:: :dbcommand:`killAllSessions` +.. seealso:: + + :dbcommand:`killAllSessions` .. [#exception] diff --git a/source/reference/command/listCollections.txt b/source/reference/command/listCollections.txt index 795600f78cb..91aaea77691 100644 --- a/source/reference/command/listCollections.txt +++ b/source/reference/command/listCollections.txt @@ -135,7 +135,7 @@ Locks .. versionchanged:: 4.0 -The :dbcommand:`listCollection` command takes Intent Shared lock on the +The :dbcommand:`listCollections` command takes Intent Shared lock on the database. In previous versions, the command takes Shared lock on the database. @@ -252,4 +252,7 @@ to return information for all collections in the ``records`` database: use records db.getCollectionInfos(); -.. seealso:: :method:`db.getCollectionInfos()` +.. seealso:: + + :method:`db.getCollectionInfos()` + diff --git a/source/reference/command/listDatabases.txt b/source/reference/command/listDatabases.txt index f6b3ee0e612..fee4927d006 100644 --- a/source/reference/command/listDatabases.txt +++ b/source/reference/command/listDatabases.txt @@ -130,8 +130,8 @@ Behavior When :doc:`authentication ` is enabled: -.. admonition:: show dbs - :class: note +.. note:: show dbs + For :binary:`~bin.mongo` shell version 4.0.6+ connected to earlier versions of MongoDB deployment (e.g. 3.6.10), @@ -284,7 +284,7 @@ the ``filter`` option to only list databases that match the specified filter cri For example, the following specifies a filter such that :dbcommand:`listDatabases` only returns information on databases whose -name matches the specified :query:`regular expression `: +name matches the specified :query:`regular expression <$regex>`: .. code-block:: javascript @@ -345,6 +345,9 @@ For example: "ok" : 1 } -.. seealso:: :doc:`/tutorial/use-database-commands`. +.. seealso:: + + :doc:`/tutorial/use-database-commands`. + .. |checkmark| unicode:: U+2713 diff --git a/source/reference/command/mapReduce.txt b/source/reference/command/mapReduce.txt index f5fec23893e..81d93ebe2ed 100644 --- a/source/reference/command/mapReduce.txt +++ b/source/reference/command/mapReduce.txt @@ -57,284 +57,279 @@ The :dbcommand:`mapReduce` command has the following syntax: Command Fields ~~~~~~~~~~~~~~ -.. container:: - - The command takes the following fields as arguments: - - - .. list-table:: - :header-rows: 1 - :widths: 20 20 80 - - * - Field - - - Type - - - Description - - * - :ref:`mapReduce ` - - - string - - - .. _cmd-mapreduce-collection: - - The name of the collection on which you want to perform map-reduce. - This collection will be filtered using ``query`` before being processed - by the ``map`` function. - - .. note:: - - .. include:: /includes/extracts/views-unsupported-mapReduce.rst - - - * - :ref:`map ` - - - JavaScript or String - - - .. _cmd-mapreduce-map: - - A JavaScript function that associates or "maps" a ``value`` - with a ``key`` and emits the ``key`` and value ``pair``. You - can specify the function as BSON type JavaScript (i.e. - :doc:`BSON type 13 `) or String (i.e. - :doc:`BSON type 2 `). - - See :ref:`mapReduce-map-cmd` for more information. - - - - * - :ref:`reduce ` - - - JavaScript or String - - - .. _cmd-mapreduce-reduce: - - A JavaScript function that "reduces" to a single object all - the ``values`` associated with a particular ``key``. You can - specify the function as BSON type JavaScript (i.e. - :doc:`BSON type 13 `) or String (i.e. - :doc:`BSON type 2 `). - - See :ref:`mapReduce-reduce-cmd` for more information. - - - - * - :ref:`out ` - - - string or document - - - .. _cmd-mapreduce-out: - - Specifies where to output the result of the map-reduce operation. You - can either output to a collection or return the result inline. On a - :term:`primary` member of a replica set you can output either to a collection - or inline, but on a :term:`secondary`, only inline output is - possible. - - See :ref:`mapReduce-out-cmd` for more information. - - - - * - :ref:`query ` - - - document - - - .. _cmd-mapreduce-query: - - Optional. Specifies the selection criteria using :doc:`query operators - ` for determining the documents input to the - ``map`` function. - - - - * - :ref:`sort ` - - - document - - - .. _cmd-mapreduce-sort: - - Optional. Sorts the *input* documents. This option is useful for - optimization. For example, specify the sort key to be the same as - the emit key so that there are fewer reduce operations. The sort key - must be in an existing index for this collection. - - - - * - :ref:`limit ` - - - number - - - .. _cmd-mapreduce-limit: - - Optional. Specifies a maximum number of documents for the input into the - ``map`` function. - - - - * - :ref:`finalize ` - - - JavaScript or String - - - .. _cmd-mapreduce-finalize: - - Optional. A JavaScript function that modifies the output after - the ``reduce`` function. You can specify the function as - BSON type JavaScript (i.e. - :doc:`BSON type 13 `) or String (i.e. - :doc:`BSON type 2 `). - - See :ref:`mapReduce-finalize-cmd` for more information. - - - - * - :ref:`scope ` - - - document - - - .. _cmd-mapreduce-scope: - - Optional. Specifies global variables that are accessible in the ``map``, - ``reduce`` and ``finalize`` functions. - - - - * - :ref:`jsMode ` - - - boolean - - - .. _cmd-mapreduce-jsMode: - - Optional. Specifies whether to convert intermediate data into BSON - format between the execution of the ``map`` and ``reduce`` - functions. - - Defaults to ``false``. - - If ``false``: - - - Internally, MongoDB converts the JavaScript objects emitted - by the ``map`` - function to BSON objects. These BSON - objects are then converted back to JavaScript objects when - calling the ``reduce`` function. - - - The map-reduce operation places the intermediate BSON objects - in temporary, on-disk storage. This allows the map-reduce - operation to execute over arbitrarily large data sets. - - If ``true``: - - - Internally, the JavaScript objects emitted during ``map`` - function remain as JavaScript objects. There is no need to - convert the objects for the ``reduce`` function, which - can result in faster execution. - - - You can only use ``jsMode`` for result sets with fewer than - 500,000 distinct ``key`` arguments to the mapper's ``emit()`` - function. - - - - * - :ref:`verbose ` - - - boolean - - - .. _cmd-mapreduce-verbose: - - Optional. Specifies whether to include the ``timing`` information in the - result information. Set ``verbose`` to ``true`` to include - the ``timing`` information. - - Defaults to ``false``. - - Starting in MongoDB 4.4, this option is ignored. The result - information always excludes the ``timing`` information. - You can view timing information by running - :dbcommand:`explain` with the :dbcommand:`mapReduce` command - in the ``"executionStats"`` or ``"allPlansExecution"`` - ``verbosity`` modes. - - * - :ref:`bypassDocumentValidation ` - - - boolean - - - .. _cmd-mapreduce-bypassDocumentValidation: - - Optional. Enables :dbcommand:`mapReduce` to bypass document validation - during the operation. This lets you insert documents that do not - meet the validation requirements. - - .. versionadded:: 3.2 - - - .. note:: - - If the :ref:`output option ` is set to - ``inline``, no :doc:`document validation - ` occurs. If the output goes to - a collection, :dbcommand:`mapReduce` observes any validation - rules which the collection has and does not insert any invalid - documents unless the ``bypassDocumentValidation`` parameter is - set to true. - - - - - * - :ref:`collation ` - - - document - - - .. _cmd-mapreduce-collation: - - Optional. - - .. include:: /includes/extracts/collation-option.rst - - - - * - :ref:`writeConcern ` - - - document - - - .. _cmd-mapreduce-writeConcern: - - Optional. A document that expresses the :doc:`write concern - ` to use when outputing to a collection. - Omit to use the default write concern. - - - * - ``comment`` - - - any - - - .. include:: /includes/extracts/comment-content.rst - - .. versionadded:: 4.4 - +The command takes the following fields as arguments: + +.. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Field + + - Type + + - Description + + * - :ref:`mapReduce ` + + - string + + - .. _cmd-mapreduce-collection: + + The name of the collection on which you want to perform map-reduce. + This collection will be filtered using ``query`` before being processed + by the ``map`` function. + + .. note:: + + .. include:: /includes/extracts/views-unsupported-mapReduce.rst + + + * - :ref:`map ` + + - JavaScript or String + + - .. _cmd-mapreduce-map: + + A JavaScript function that associates or "maps" a ``value`` + with a ``key`` and emits the ``key`` and value ``pair``. You + can specify the function as BSON type JavaScript (i.e. + :doc:`BSON type 13 `) or String (i.e. + :doc:`BSON type 2 `). + + See :ref:`mapreduce-map-cmd` for more information. + + + + * - :ref:`reduce ` + + - JavaScript or String + + - .. _cmd-mapreduce-reduce: + + A JavaScript function that "reduces" to a single object all + the ``values`` associated with a particular ``key``. You can + specify the function as BSON type JavaScript (i.e. + :doc:`BSON type 13 `) or String (i.e. + :doc:`BSON type 2 `). + + See :ref:`mapreduce-reduce-cmd` for more information. + + + + * - :ref:`out ` + + - string or document + + - .. _cmd-mapreduce-out: + + Specifies where to output the result of the map-reduce operation. You + can either output to a collection or return the result inline. On a + :term:`primary` member of a replica set you can output either to a collection + or inline, but on a :term:`secondary`, only inline output is + possible. + + See :ref:`mapreduce-out-cmd` for more information. + + + + * - :ref:`query ` + + - document + + - .. _cmd-mapreduce-query: + + Optional. Specifies the selection criteria using :doc:`query operators + ` for determining the documents input to the + ``map`` function. + + + + * - :ref:`sort ` + + - document + + - .. _cmd-mapreduce-sort: + + Optional. Sorts the *input* documents. This option is useful for + optimization. For example, specify the sort key to be the same as + the emit key so that there are fewer reduce operations. The sort key + must be in an existing index for this collection. + + + + * - :ref:`limit ` + + - number + + - .. _cmd-mapreduce-limit: + + Optional. Specifies a maximum number of documents for the input into the + ``map`` function. + + + + * - :ref:`finalize ` + + - JavaScript or String + + - .. _cmd-mapreduce-finalize: + + Optional. A JavaScript function that modifies the output after + the ``reduce`` function. You can specify the function as + BSON type JavaScript (i.e. + :doc:`BSON type 13 `) or String (i.e. + :doc:`BSON type 2 `). + + See :ref:`mapreduce-finalize-cmd` for more information. + + + + * - :ref:`scope ` + + - document + + - .. _cmd-mapreduce-scope: + + Optional. Specifies global variables that are accessible in the ``map``, + ``reduce`` and ``finalize`` functions. + + + + * - :ref:`jsMode ` + + - boolean + + - .. _cmd-mapreduce-jsMode: + + Optional. Specifies whether to convert intermediate data into BSON + format between the execution of the ``map`` and ``reduce`` + functions. + + Defaults to ``false``. + + If ``false``: + + - Internally, MongoDB converts the JavaScript objects emitted + by the ``map`` + function to BSON objects. These BSON + objects are then converted back to JavaScript objects when + calling the ``reduce`` function. + + - The map-reduce operation places the intermediate BSON objects + in temporary, on-disk storage. This allows the map-reduce + operation to execute over arbitrarily large data sets. + + If ``true``: + + - Internally, the JavaScript objects emitted during ``map`` + function remain as JavaScript objects. There is no need to + convert the objects for the ``reduce`` function, which + can result in faster execution. + + - You can only use ``jsMode`` for result sets with fewer than + 500,000 distinct ``key`` arguments to the mapper's ``emit()`` + function. + + + + * - :ref:`verbose ` + + - boolean + + - .. _cmd-mapreduce-verbose: + + Optional. Specifies whether to include the ``timing`` information in the + result information. Set ``verbose`` to ``true`` to include + the ``timing`` information. + + Defaults to ``false``. + + Starting in MongoDB 4.4, this option is ignored. The result + information always excludes the ``timing`` information. + You can view timing information by running + :dbcommand:`explain` with the :dbcommand:`mapReduce` command + in the ``"executionStats"`` or ``"allPlansExecution"`` + ``verbosity`` modes. + + * - :ref:`bypassDocumentValidation ` + + - boolean + + - .. _cmd-mapreduce-bypassDocumentValidation: + + Optional. Enables :dbcommand:`mapReduce` to bypass document validation + during the operation. This lets you insert documents that do not + meet the validation requirements. + + .. versionadded:: 3.2 + + + .. note:: + + If the :ref:`output option ` is set to + ``inline``, no :doc:`document validation + ` occurs. If the output goes to + a collection, :dbcommand:`mapReduce` observes any validation + rules which the collection has and does not insert any invalid + documents unless the ``bypassDocumentValidation`` parameter is + set to true. + + + + + * - :ref:`collation ` + + - document + + - .. _cmd-mapreduce-collation: + + Optional. + + .. include:: /includes/extracts/collation-option.rst + + + + * - :ref:`writeConcern ` + + - document + + - .. _cmd-mapreduce-writeConcern: + + Optional. A document that expresses the :doc:`write concern + ` to use when outputing to a collection. + Omit to use the default write concern. + + + * - ``comment`` + + - any + + - .. include:: /includes/extracts/comment-content.rst + + .. versionadded:: 4.4 + Usage ~~~~~ -.. container:: - - The following is a prototype usage of the :dbcommand:`mapReduce` - command: +The following is a prototype usage of the :dbcommand:`mapReduce` +command: - .. code-block:: javascript +.. code-block:: javascript - var mapFunction = function() { ... }; - var reduceFunction = function(key, values) { ... }; + var mapFunction = function() { ... }; + var reduceFunction = function(key, values) { ... }; - db.runCommand( - { - mapReduce: , - map: mapFunction, - reduce: reduceFunction, - out: { merge: }, - query: - } - ) + db.runCommand( + { + mapReduce: , + map: mapFunction, + reduce: reduceFunction, + out: { merge: }, + query: + } + ) - .. include:: /includes/extracts/admonition-js-prevalence-mapReduce.rst +.. include:: /includes/extracts/admonition-js-prevalence-mapReduce.rst .. _mapreduce-map-cmd: @@ -417,7 +412,7 @@ For more information and examples, see the Output ------ -If you set the :ref:`out ` parameter to write the +If you set the :ref:`out ` parameter to write the results to a collection, the :dbcommand:`mapReduce` command returns a document in the following form: @@ -447,7 +442,7 @@ document in the following form: "ok" : , } -If you set the :ref:`out ` parameter to output the +If you set the :ref:`out ` parameter to output the results inline, the :dbcommand:`mapReduce` command returns a document in the following form: @@ -496,11 +491,11 @@ in the following form: For output sent to a collection, this value is either: - - a string for the collection name if :ref:`out ` + - a string for the collection name if :ref:`out ` did not specify the database name, or - a document with both ``db`` and ``collection`` fields if :ref:`out - ` specified both a database and collection name. + ` specified both a database and collection name. .. data:: mapReduce.results diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 1f4114189c2..5b414795c8c 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -179,7 +179,10 @@ Definition The :ref:`chunk migration ` section describes how chunks move between shards on MongoDB. -.. seealso:: :dbcommand:`split`, :method:`sh.moveChunk()`, +.. seealso:: + + :dbcommand:`split`, :method:`sh.moveChunk()`, + :method:`sh.splitAt()`, and :method:`sh.splitFind()`. Considerations diff --git a/source/reference/command/nav-diagnostic.txt b/source/reference/command/nav-diagnostic.txt index a43f22943f4..a9605ee70b1 100644 --- a/source/reference/command/nav-diagnostic.txt +++ b/source/reference/command/nav-diagnostic.txt @@ -81,7 +81,7 @@ Diagnostic Commands - Returns data that reflects the underlying host system. - * - :dbcommand:`isSelf` + * - :dbcommand:`_isSelf` - Internal command to support testing. diff --git a/source/reference/command/reIndex.txt b/source/reference/command/reIndex.txt index 7fca3318602..5424c370f30 100644 --- a/source/reference/command/reIndex.txt +++ b/source/reference/command/reIndex.txt @@ -71,5 +71,7 @@ operations on the database until finished. For more information on locking in MongoDB, see :doc:`/faq/concurrency`. -.. see:: :doc:`/core/index-creation` for more information on the +.. see:: + + :doc:`/core/index-creation` for more information on the behavior of indexing operations in MongoDB. diff --git a/source/reference/command/refineCollectionShardKey.txt b/source/reference/command/refineCollectionShardKey.txt index aeb40713f08..cbe7f602187 100644 --- a/source/reference/command/refineCollectionShardKey.txt +++ b/source/reference/command/refineCollectionShardKey.txt @@ -4,8 +4,7 @@ refineCollectionShardKey .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -114,7 +113,9 @@ The :dbcommand:`refineCollectionShardKey` command has the following fields: supported by a unique index since hashed indexes :ref:`do not support uniqueness constraint `. -.. seealso:: :doc:`/core/sharding-shard-key` +.. seealso:: + + :doc:`/core/sharding-shard-key` Access Control -------------- @@ -191,132 +192,130 @@ Index Considerations Examples -------- -.. container:: - - To set up the example in the ``test`` database: +To set up the example in the ``test`` database: - a. Enable sharding on the database, if sharding is not already enabled: +a. Enable sharding on the database, if sharding is not already enabled: - .. code-block:: javascript + .. code-block:: javascript - sh.enableSharding("test") + sh.enableSharding("test") - #. Use following :dbcommand:`shardCollection` operation to shard the - ``orders`` collection in the ``test`` database. The operation - uses the ``customer_id`` field as the initial :ref:`shard key - `: +#. Use following :dbcommand:`shardCollection` operation to shard the + ``orders`` collection in the ``test`` database. The operation + uses the ``customer_id`` field as the initial :ref:`shard key + `: - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { shardCollection: "test.orders", key: { customer_id: 1 } } ) + db.adminCommand( { shardCollection: "test.orders", key: { customer_id: 1 } } ) - To modify the shard key to be the ``customer_id`` field and the - ``order_id`` field ``{ customer_id: 1, order_id: 1 }``, +To modify the shard key to be the ``customer_id`` field and the +``order_id`` field ``{ customer_id: 1, order_id: 1 }``, - #. :method:`Create the index ` to - support the new shard key if the index does not already exist. +#. :method:`Create the index ` to + support the new shard key if the index does not already exist. - .. code-block:: javascript + .. code-block:: javascript - db.getSiblingDB("test").orders.createIndex( { customer_id: 1, order_id: 1 } ) + db.getSiblingDB("test").orders.createIndex( { customer_id: 1, order_id: 1 } ) - #. Run :dbcommand:`refineCollectionShardKey` command to add the ``order_id`` - field as a suffix: +#. Run :dbcommand:`refineCollectionShardKey` command to add the ``order_id`` + field as a suffix: - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { - refineCollectionShardKey: "test.orders", - key: { customer_id: 1, order_id: 1 } - } ) + db.adminCommand( { + refineCollectionShardKey: "test.orders", + key: { customer_id: 1, order_id: 1 } + } ) - Upon successful completion of the command, the shard key for the - collection has changed to ``{ customer_id: 1, order_id: 1 }``. To verify, - you can run :method:`sh.status()`. +Upon successful completion of the command, the shard key for the +collection has changed to ``{ customer_id: 1, order_id: 1 }``. To verify, +you can run :method:`sh.status()`. - .. tip:: +.. tip:: - After you refine the shard key, it may be that not all documents in - the collection have the suffix field(s). To populate the missing - shard key field(s), see :ref:`shard-key-missing`. + After you refine the shard key, it may be that not all documents in + the collection have the suffix field(s). To populate the missing + shard key field(s), see :ref:`shard-key-missing`. - Before refining the shard key, ensure that all or most documents in - the collection have the suffix fields, if possible, to avoid having - to populate the field afterwards. + Before refining the shard key, ensure that all or most documents in + the collection have the suffix fields, if possible, to avoid having + to populate the field afterwards. Collection with non-``simple`` Collation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +To set up the example in the ``test`` database: - To set up the example in the ``test`` database: +a. Enable sharding on the database, if sharding is not already enabled: - a. Enable sharding on the database, if sharding is not already enabled: + .. code-block:: javascript - .. code-block:: javascript + sh.enableSharding("test") - sh.enableSharding("test") +#. Create the ``cafés`` collection in the ``test`` database, + specifying French ``fr`` as the default :doc:`collation `. - #. Create the ``cafés`` collection in the ``test`` database, - specifying French ``fr`` as the default :doc:`collation `. + .. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("test").createCollection( "cafés", { collation: { locale: "fr" } } ); - db.getSiblingDB("test").createCollection( "cafés", { collation: { locale: "fr" } } ); +#. Shard the collection using ``customer_id`` field as the initial + :ref:`shard key `. Because the collection has a default ``fr`` + collation and not a ``simple`` collation, the + :dbcommand:`shardCollection` command must include a ``collation: + { locale: "simple" }`` option: - #. Shard the collection using ``customer_id`` field as the initial - :ref:`shard key `. Because the collection has a default ``fr`` - collation and not a ``simple`` collation, the - :dbcommand:`shardCollection` command must include a ``collation: - { locale: "simple" }`` option: + .. code-block:: javascript - .. code-block:: javascript + db.adminCommand( { + shardCollection: "test.cafés", + key: { customer_id: 1 }, + collation: { locale: "simple" } + } ) - db.adminCommand( { - shardCollection: "test.cafés", - key: { customer_id: 1 }, - collation: { locale: "simple" } - } ) +To modify the shard key to be both the ``customer_id`` field and the +``order_id`` field ``{ customer_id: 1, order_id: 1 }``, - To modify the shard key to be both the ``customer_id`` field and the - ``order_id`` field ``{ customer_id: 1, order_id: 1 }``, +#. :method:`Create the index ` to + support the new shard key if the index does not already exist. + Because the collection uses a non-simple :doc:`collation + `, the index must include the ``collation: + { locale: "simple" }`` option. - #. :method:`Create the index ` to - support the new shard key if the index does not already exist. - Because the collection uses a non-simple :doc:`collation - `, the index must include the ``collation: - { locale: "simple" }`` option. + .. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("test").cafés.createIndex( + { customer_id: 1, order_id: 1 }, + { collation: { locale: "simple" } } + ) - db.getSiblingDB("test").cafés.createIndex( - { customer_id: 1, order_id: 1 }, - { collation: { locale: "simple" } } - ) +#. Run :dbcommand:`refineCollectionShardKey` command to add the ``order_id`` + field as a suffix: - #. Run :dbcommand:`refineCollectionShardKey` command to add the ``order_id`` - field as a suffix: + .. code-block:: javascript - .. code-block:: javascript + db.adminCommand( { + refineCollectionShardKey: "test.cafés", + key: { customer_id: 1, order_id: 1 } + } ) - db.adminCommand( { - refineCollectionShardKey: "test.cafés", - key: { customer_id: 1, order_id: 1 } - } ) +Upon successful completion of the command, the shard key for the +collection has changed to ``{ customer_id: 1, order_id: 1 }``. To verify, +you can run :method:`sh.status()`. - Upon successful completion of the command, the shard key for the - collection has changed to ``{ customer_id: 1, order_id: 1 }``. To verify, - you can run :method:`sh.status()`. +.. tip:: - .. tip:: + After you refine the shard key, it may be that not all documents in + the collection have the suffix field(s). To populate the missing + shard key field(s), see :ref:`shard-key-missing`. - After you refine the shard key, it may be that not all documents in - the collection have the suffix field(s). To populate the missing - shard key field(s), see :ref:`shard-key-missing`. + Before refining the shard key, ensure that all or most documents in + the collection have the suffix fields, if possible, to avoid having + to populate the field afterwards. - Before refining the shard key, ensure that all or most documents in - the collection have the suffix fields, if possible, to avoid having - to populate the field afterwards. +.. seealso:: -.. seealso:: :doc:`/core/sharding-shard-key/` + :doc:`/core/sharding-shard-key/` diff --git a/source/reference/command/removeShard.txt b/source/reference/command/removeShard.txt index 691db196132..3ca6284afe6 100644 --- a/source/reference/command/removeShard.txt +++ b/source/reference/command/removeShard.txt @@ -60,7 +60,9 @@ Chunk Balancing .. include:: /includes/fact-remove-shard-balance-order.rst -.. seealso:: :dbcommand:`balancerCollectionStatus` +.. seealso:: + + :dbcommand:`balancerCollectionStatus` Write Concern ~~~~~~~~~~~~~ diff --git a/source/reference/command/renameCollection.txt b/source/reference/command/renameCollection.txt index f4af7db4892..3d226413a74 100644 --- a/source/reference/command/renameCollection.txt +++ b/source/reference/command/renameCollection.txt @@ -212,13 +212,13 @@ equivalent to the previous example: Exceptions ---------- -:exception 10026: +exception 10026 Raised if the ``source`` namespace does not exist. -:exception 10027: +exception 10027 Raised if the ``target`` namespace exists and ``dropTarget`` is either ``false`` or unspecified. -:exception 15967: +exception 15967 Raised if the ``target`` namespace is an invalid collection name. diff --git a/source/reference/command/replSetGetConfig.txt b/source/reference/command/replSetGetConfig.txt index eb440805088..f8ca736b293 100644 --- a/source/reference/command/replSetGetConfig.txt +++ b/source/reference/command/replSetGetConfig.txt @@ -213,4 +213,7 @@ command run with :ref:`commitmentStatus: true details. -.. seealso:: :method:`rs.conf()`, :method:`rs.reconfig()` +.. seealso:: + + :method:`rs.conf()`, :method:`rs.reconfig()` + diff --git a/source/reference/command/replSetGetStatus.txt b/source/reference/command/replSetGetStatus.txt index d5f261b3c52..f14ceaea5ec 100644 --- a/source/reference/command/replSetGetStatus.txt +++ b/source/reference/command/replSetGetStatus.txt @@ -1404,11 +1404,6 @@ following fields: :doc:`/core/replica-set-high-availability` for more information about elections. - .. data:: replSetGetStatus.members[n].self - - Indicates which replica set member processed the - :command:`replSetGetStatus` command. - .. data:: replSetGetStatus.members[n].lastHeartbeat An :term:`ISODate` formatted date and time that reflects the last @@ -1416,7 +1411,7 @@ following fields: command received a response from a heartbeat that it sent to this member (``members[n]``). Compare this value to the values of the :data:`~replSetGetStatus.date` and - :data:`~replSetGetStatus.members[n].lastHeartBeatRecv` fields to + :data:`~replSetGetStatus.members[n].lastHeartbeatRecv` fields to track latency between these replica set members. This value is only available for replica set members other than the server specified by :data:`replSetGetStatus.members[n].self`. @@ -1429,7 +1424,7 @@ following fields: (``members[n]``). Compare this value to the values of the :data:`~replSetGetStatus.date` and - :data:`~replSetGetStatus.members[n].lastHeartBeat` fields to track + :data:`~replSetGetStatus.members[n].lastHeartbeat` fields to track latency between these replica set members. This value is only available for replica set members other than the server specified by :data:`replSetGetStatus.members[n].self`. diff --git a/source/reference/command/replSetInitiate.txt b/source/reference/command/replSetInitiate.txt index 5d0e03e7562..2625f92d1e2 100644 --- a/source/reference/command/replSetInitiate.txt +++ b/source/reference/command/replSetInitiate.txt @@ -78,6 +78,8 @@ documents such as the ``arbiterOnly`` setting in this example. .. slave-ok, admin-only -.. seealso:: :doc:`/reference/replica-configuration`, +.. seealso:: + + :doc:`/reference/replica-configuration`, :doc:`/administration/replica-set-deployment`, and :ref:`Replica Set Reconfiguration `. diff --git a/source/reference/command/replSetResizeOplog.txt b/source/reference/command/replSetResizeOplog.txt index 450c81025ce..0632401aed0 100644 --- a/source/reference/command/replSetResizeOplog.txt +++ b/source/reference/command/replSetResizeOplog.txt @@ -103,7 +103,9 @@ Definition .. versionadded:: 4.4 -.. seealso:: +.. seealso:: + + - :option:`--oplogSize ` / :setting:`replication.oplogSizeMB` @@ -252,7 +254,7 @@ oplog size of this member to 16384 megabytes: db.adminCommand({ "replSetResizeOplog": 1, size: 16384}) -To verify the new oplog size, rerun the :dbcommand:`stats` command: +To verify the new oplog size, rerun the :method:`db.collection.stats()` method: .. code-block:: javascript diff --git a/source/reference/command/replSetStepDown.txt b/source/reference/command/replSetStepDown.txt index 5be985e3ca1..5c10befeb3f 100644 --- a/source/reference/command/replSetStepDown.txt +++ b/source/reference/command/replSetStepDown.txt @@ -145,7 +145,7 @@ does not step down and the command errors. .. include:: /includes/extracts/rs-stepdown-write-fail.rst -.. class:: copyable-code + .. code-block:: javascript db.adminCommand( { replSetStepDown: 120 } ) @@ -160,7 +160,7 @@ the primary does not step down and the command errors. .. include:: /includes/extracts/rs-stepdown-write-fail.rst -.. class:: copyable-code + .. code-block:: javascript db.adminCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15 } ) @@ -175,11 +175,14 @@ option, the primary steps down even if no suitable secondary exists. .. include:: /includes/extracts/rs-stepdown-write-fail.rst -.. class:: copyable-code + .. code-block:: javascript db.adminCommand( { replSetStepDown: 120, secondaryCatchUpPeriodSecs: 15, force: true } ) -.. seealso:: :method:`rs.stepDown()` +.. seealso:: + + :method:`rs.stepDown()` + .. slave-ok, admin-only diff --git a/source/reference/command/resetError.txt b/source/reference/command/resetError.txt index 30e5987da97..83babe6bbba 100644 --- a/source/reference/command/resetError.txt +++ b/source/reference/command/resetError.txt @@ -16,5 +16,6 @@ resetError The :dbcommand:`resetError` command resets the last error status. - .. seealso:: :method:`db.resetError()` (*also removed in MongoDB - 5.0*) +.. seealso:: + + :method:`db.resetError()` (*also removed in MongoDB 5.0*) diff --git a/source/reference/command/serverStatus.txt b/source/reference/command/serverStatus.txt index d1cf98f25db..8ec3f0ba513 100644 --- a/source/reference/command/serverStatus.txt +++ b/source/reference/command/serverStatus.txt @@ -516,7 +516,7 @@ primary: .. serverstatus:: electionMetrics.priorityTakeover Metrics on elections that were called by the :binary:`~bin.mongod` - instance because its :rsconf:`~members.[n].priority` is higher + instance because its :rsconf:`~members[n].priority` is higher than the primary's. The :serverstatus:`electionMetrics.priorityTakeover` includes both the number of @@ -532,7 +532,10 @@ primary: The :serverstatus:`~electionMetrics.catchUpTakeover` includes both the number of elections called and the number of elections that succeeded. - .. seealso:: :rsconf:`settings.catchUpTakeoverDelayMillis` + .. seealso:: + + :rsconf:`settings.catchUpTakeoverDelayMillis` + *Available starting in 4.2.1 (and 4.0.13)* @@ -545,7 +548,9 @@ primary: The :serverstatus:`~electionMetrics.electionTimeout` includes both the number of elections called and the number of elections that succeeded. - .. seealso:: :rsconf:`settings.electionTimeoutMillis` + .. seealso:: + + :rsconf:`settings.electionTimeoutMillis` *Available starting in 4.2.1 (and 4.0.13)* @@ -738,8 +743,8 @@ flowControl .. serverstatus:: flowControl.locksPerKiloOp - .. admonition:: Starting in MongoDB 4.4 - :class: note + .. note:: Starting in MongoDB 4.4 + :serverstatus:`~flowControl.locksPerKiloOp` replaces :serverstatus:`~flowControl.locksPerOp` field. @@ -755,8 +760,8 @@ flowControl .. serverstatus:: flowControl.locksPerOp - .. admonition:: Available on MongoDB 4.2 only - :class: note + .. note:: Available on MongoDB 4.2 only + MongoDB 4.4 replaces :serverstatus:`~flowControl.locksPerOp` with :serverstatus:`flowControl.locksPerKiloOp`. @@ -1124,18 +1129,21 @@ logicalSessionRecordCache :binary:`~bin.mongod` or :binary:`~bin.mongos` instance since the last refresh period. - .. seealso:: + .. seealso:: + + - :pipeline:`$listLocalSessions` - :parameter:`logicalSessionRefreshMillis` - - :parameter:`logicalSessionRefreshMinutes` .. serverstatus:: logicalSessionRecordCache.sessionsCollectionJobCount The number that tracks the number of times the refresh process has run on the :data:`config.system.sessions` collection. - .. seealso:: :parameter:`logicalSessionRefreshMinutes` + .. seealso:: + + :parameter:`logicalSessionRefreshMillis` .. serverstatus:: logicalSessionRecordCache.lastSessionsCollectionJobDurationMillis @@ -1180,7 +1188,7 @@ logicalSessionRecordCache .. serverstatus:: logicalSessionRecordCache.sessionCatalogSize - For a :binary:`~bin.mongod` instance, - The size of its in-memory cache of the `config.transactions` + The size of its in-memory cache of the ``config.transactions`` entries. This corresponds to retryable writes or transactions whose sessions have not expired within the :parameter:`localLogicalSessionTimeoutMinutes`. @@ -1248,7 +1256,7 @@ locks .. serverstatus:: locks..acquireWaitCount - Number of times the :serverstatus:`locks.acquireCount` lock + Number of times the :serverstatus:`locks..acquireCount` lock acquisitions encountered waits because the locks were held in a conflicting mode. @@ -1256,8 +1264,8 @@ locks Cumulative wait time in microseconds for the lock acquisitions. - :serverstatus:`locks.timeAcquiringMicros` divided by - :serverstatus:`locks.acquireWaitCount` gives an + :serverstatus:`locks..timeAcquiringMicros` divided by + :serverstatus:`locks..acquireWaitCount` gives an approximate average wait time for the particular lock mode. .. serverstatus:: locks..deadlockCount @@ -1292,22 +1300,27 @@ mirroredReads .. serverstatus:: mirroredReads.seen + .. versionadded:: 4.4 + The number of :ref:`operations that support mirroring ` received by this member. - .. seealso:: :parameter:`mirrorReads` Parameter + .. seealso:: - .. versionadded:: 4.4 + :parameter:`mirrorReads` Parameter .. serverstatus:: mirroredReads.sent + .. versionadded:: 4.4 + The number of mirrored reads sent by this member when primary. For example, if a read is mirrored and sent to two secondaries, the number of mirrored reads is ``2``. - .. seealso:: :parameter:`mirrorReads` Parameter + .. seealso:: + + :parameter:`mirrorReads` Parameter - .. versionadded:: 4.4 .. _server-status-network: @@ -1560,8 +1573,7 @@ opLatencies opReadConcernCounters ~~~~~~~~~~~~~~~~~~~~~ -.. admonition:: Removed - :class: warning +.. warning:: Removed Starting in version 5.0, :serverstatus:`opReadConcernCounters` is replaced by :serverstatus:`readConcernCounters`. @@ -2357,7 +2369,7 @@ repl .. serverstatus:: repl.rbid - :term:`Rollback` identifier. Used to determine if a rollback has + :term:`Rollback ` identifier. Used to determine if a rollback has happened for this :binary:`~bin.mongod` instance. .. serverstatus:: repl.replicationProgress @@ -4461,7 +4473,9 @@ wiredTiger A document that returns statistics on WiredTiger's write ahead log (i.e. the journal). - .. seealso:: :ref:`journaling-wiredTiger` + .. seealso:: + + :ref:`journaling-wiredTiger` .. serverstatus:: wiredTiger.reconciliation @@ -5030,7 +5044,10 @@ metrics :serverstatus:`metrics.repl.apply.ops` is incremented after each operation. - .. seealso:: :serverstatus:`metrics.repl.apply.batchSize` + .. seealso:: + + :serverstatus:`metrics.repl.apply.batchSize` + .. serverstatus:: metrics.repl.buffer diff --git a/source/reference/command/setDefaultRWConcern.txt b/source/reference/command/setDefaultRWConcern.txt index 3400b321405..c722130a8df 100644 --- a/source/reference/command/setDefaultRWConcern.txt +++ b/source/reference/command/setDefaultRWConcern.txt @@ -23,7 +23,7 @@ Definition against the ``admin`` database. - For replica sets, issue the :dbcommand:`setDefaultRWConcern` - command on the :term:`primary` :binary:`~binary.mongod`. + command on the :term:`primary` :binary:`~bin.mongod`. - For sharded clusters, issue the :dbcommand:`setDefaultRWConcern` on a :binary:`~bin.mongos`. @@ -150,8 +150,8 @@ the returned fields. Behavior -------- -.. admonition:: Requires ``featureCompatibilityVersion`` 4.4+ - :class: note +.. note:: Requires ``featureCompatibilityVersion`` 4.4+ + Each :binary:`~bin.mongod` in the replica set or sharded cluster *must* have :ref:`featureCompatibilityVersion ` set to diff --git a/source/reference/command/setFeatureCompatibilityVersion.txt b/source/reference/command/setFeatureCompatibilityVersion.txt index 1ee94f31c0c..24ba51366e9 100644 --- a/source/reference/command/setFeatureCompatibilityVersion.txt +++ b/source/reference/command/setFeatureCompatibilityVersion.txt @@ -228,279 +228,269 @@ on the tab for the appropriate MongoDB version. Set Feature Compatibility Version on MongoDB 4.4 Deployments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: enable-4.4 - name: Enable 4.4 Backwards Incompatible Features - content: | + - id: enable-4.4 + name: Enable 4.4 Backwards Incompatible Features + content: | - To enable the :ref:`4.4 features that persist data incompatible with - MongoDB 4.2 <4.4-compatibility-enabled>`, set the feature compatibility - to ``"4.4"`` on the MongoDB 4.4 deployment: + To enable the :ref:`4.4 features that persist data incompatible with + MongoDB 4.2 <4.4-compatibility-enabled>`, set the feature compatibility + to ``"4.4"`` on the MongoDB 4.4 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "4.4" } ) - - id: disable-4.4 - name: Disable 4.4 Backwards Incompatible Features - content: | + - id: disable-4.4 + name: Disable 4.4 Backwards Incompatible Features + content: | - To disable the :ref:`4.4 features that persist data incompatible with - MongoDB 4.2 <4.4-compatibility-enabled>`, set the feature compatibility - to ``"4.2"`` on the MongoDB 4.4 deployment: + To disable the :ref:`4.4 features that persist data incompatible with + MongoDB 4.2 <4.4-compatibility-enabled>`, set the feature compatibility + to ``"4.2"`` on the MongoDB 4.4 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - - ``"4.2"`` featureCompatibilityVersion is supported on MongoDB - 4.2 and MongoDB 4.4 deployments only. + - ``"4.2"`` featureCompatibilityVersion is supported on MongoDB + 4.2 and MongoDB 4.4 deployments only. - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } ) - If run as part of the downgrade process from MongoDB 4.4 to MongoDB - 4.2, you must also remove all persisted features that are - :ref:`incompatible <4.4-compatibility-enabled>` with 4.2. See the - appropriate downgrade procedures. + If run as part of the downgrade process from MongoDB 4.4 to MongoDB + 4.2, you must also remove all persisted features that are + :ref:`incompatible <4.4-compatibility-enabled>` with 4.2. See the + appropriate downgrade procedures. Set Feature Compatibility Version on MongoDB 4.2 Deployments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: enable-4.2 - name: Enable 4.2 Backwards Incompatible Features - content: | + - id: enable-4.2 + name: Enable 4.2 Backwards Incompatible Features + content: | - To enable the :ref:`4.2 features that persist data incompatible with - MongoDB 4.0 <4.2-compatibility-enabled>`, set the feature compatibility - to ``"4.2"`` on the MongoDB 4.2 deployment: + To enable the :ref:`4.2 features that persist data incompatible with + MongoDB 4.0 <4.2-compatibility-enabled>`, set the feature compatibility + to ``"4.2"`` on the MongoDB 4.2 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "4.2" } ) - - id: disable-4.2 - name: Disable 4.2 Backwards Incompatible Features - content: | + - id: disable-4.2 + name: Disable 4.2 Backwards Incompatible Features + content: | - To disable the :ref:`4.2 features that persist data incompatible with - MongoDB 4.0 <4.2-compatibility-enabled>`, set the feature compatibility - to ``"4.0"`` on the MongoDB 4.2 deployment: + To disable the :ref:`4.2 features that persist data incompatible with + MongoDB 4.0 <4.2-compatibility-enabled>`, set the feature compatibility + to ``"4.0"`` on the MongoDB 4.2 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - - ``"4.0"`` featureCompatibilityVersion is supported on MongoDB - 4.0 and MongoDB 4.2 deployments only. + - ``"4.0"`` featureCompatibilityVersion is supported on MongoDB + 4.0 and MongoDB 4.2 deployments only. - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } ) - If run as part of the downgrade process from MongoDB 4.2 to MongoDB - 4.0, you must also remove all persisted features that are - :ref:`incompatible <4.2-compatibility-enabled>` with 4.0. See the - appropriate downgrade procedures. + If run as part of the downgrade process from MongoDB 4.2 to MongoDB + 4.0, you must also remove all persisted features that are + :ref:`incompatible <4.2-compatibility-enabled>` with 4.0. See the + appropriate downgrade procedures. Set Feature Compatibility Version on MongoDB 4.0 Deployments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: enable-4.0 - name: Enable 4.0 Backwards Incompatible Features - content: | - To enable the :ref:`4.0 features that persist data incompatible with - MongoDB 3.6 <4.0-compatibility-enabled>`, set the feature compatibility - to ``"4.0"`` on the MongoDB 4.0 deployment: + - id: enable-4.0 + name: Enable 4.0 Backwards Incompatible Features + content: | + To enable the :ref:`4.0 features that persist data incompatible with + MongoDB 3.6 <4.0-compatibility-enabled>`, set the feature compatibility + to ``"4.0"`` on the MongoDB 4.0 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } ) - - id: disable-4.0 - name: Disable 4.0 Backwards Incompatible Features - content: | - To disable the :ref:`4.0 features that persist data incompatible with - MongoDB 3.6 <4.0-compatibility-enabled>`, set the feature compatibility - to ``"3.6"`` on the MongoDB 4.0 deployment: + - id: disable-4.0 + name: Disable 4.0 Backwards Incompatible Features + content: | + To disable the :ref:`4.0 features that persist data incompatible with + MongoDB 3.6 <4.0-compatibility-enabled>`, set the feature compatibility + to ``"3.6"`` on the MongoDB 4.0 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - - ``"3.6"`` featureCompatibilityVersion is supported on MongoDB - 3.6 and MongoDB 4.0 Deployments Only. + - ``"3.6"`` featureCompatibilityVersion is supported on MongoDB + 3.6 and MongoDB 4.0 Deployments Only. - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) - If run as part of the downgrade process from MongoDB 4.0 to MongoDB - 3.6, you must also remove all persisted features that are - :ref:`incompatible <4.0-compatibility-enabled>` with 3.6. See the - appropriate downgrade procedures. + If run as part of the downgrade process from MongoDB 4.0 to MongoDB + 3.6, you must also remove all persisted features that are + :ref:`incompatible <4.0-compatibility-enabled>` with 3.6. See the + appropriate downgrade procedures. Set Feature Compatibility Version on MongoDB 3.6 Deployments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: enable-3.6 - name: Enable 3.6 Backwards Incompatible Features - content: | + - id: enable-3.6 + name: Enable 3.6 Backwards Incompatible Features + content: | - To enable the :ref:`3.6 features that persist data incompatible with - MongoDB 3.4 <3.6-compatibility-enabled>`, set the feature compatibility - to ``"3.6"`` on the MongoDB 3.6 deployment: + To enable the :ref:`3.6 features that persist data incompatible with + MongoDB 3.4 <3.6-compatibility-enabled>`, set the feature compatibility + to ``"3.6"`` on the MongoDB 3.6 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) - - id: disable-3.6 - name: Disable 3.6 Backwards Incompatible Features - content: | + - id: disable-3.6 + name: Disable 3.6 Backwards Incompatible Features + content: | - To disable the :ref:`3.6 features that persist data incompatible with - MongoDB 3.4 <3.6-compatibility-enabled>`, set the feature compatibility - to ``"3.4"`` on the MongoDB 3.6 deployment: + To disable the :ref:`3.6 features that persist data incompatible with + MongoDB 3.4 <3.6-compatibility-enabled>`, set the feature compatibility + to ``"3.4"`` on the MongoDB 3.6 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - - ``"3.4"`` featureCompatibilityVersion is supported on MongoDB - 3.6 and MongoDB 3.4 Deployments Only. + - ``"3.4"`` featureCompatibilityVersion is supported on MongoDB + 3.6 and MongoDB 3.4 Deployments Only. - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) - If run as part of the downgrade process from MongoDB 3.6 to MongoDB - 3.4, you must also remove all persisted features that are - :ref:`incompatible <3.6-compatibility-enabled>` with 3.4. See the - appropriate downgrade procedures. + If run as part of the downgrade process from MongoDB 3.6 to MongoDB + 3.4, you must also remove all persisted features that are + :ref:`incompatible <3.6-compatibility-enabled>` with 3.4. See the + appropriate downgrade procedures. Set Feature Compatibility Version on MongoDB 3.4 Deployments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: enable-3.4 - name: Enable 3.4 Backwards Incompatible Features - content: | + - id: enable-3.4 + name: Enable 3.4 Backwards Incompatible Features + content: | - .. warning:: + .. warning:: - .. include:: /includes/3.4-featureCompatibility-caveat.rst + .. include:: /includes/3.4-featureCompatibility-caveat.rst - To enable the 3.4 features that are :ref:`backward incompatible - <3.4-compatibility-enabled>`, set the feature compatibility - to ``"3.4"`` on the MongoDB 3.4 deployment: + To enable the 3.4 features that are :ref:`backward incompatible + <3.4-compatibility-enabled>`, set the feature compatibility + to ``"3.4"`` on the MongoDB 3.4 deployment: - .. note:: + .. note:: - Run the :dbcommand:`setFeatureCompatibilityVersion` command against - the ``admin`` database. + Run the :dbcommand:`setFeatureCompatibilityVersion` command against + the ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) - - id: disable-3.4 - name: Disable 3.4 Backwards Incompatible Features - content: | + - id: disable-3.4 + name: Disable 3.4 Backwards Incompatible Features + content: | - To disable the :ref:`3.4 backwards-incompatible features - <3.4-compatibility-enabled>`, set the feature compatibility - to ``"3.2"`` on the MongoDB 3.4 deployment: + To disable the :ref:`3.4 backwards-incompatible features + <3.4-compatibility-enabled>`, set the feature compatibility + to ``"3.2"`` on the MongoDB 3.4 deployment: - .. note:: + .. note:: - Run the ``setFeatureCompatibilityVersion`` command against the - ``admin`` database. + Run the ``setFeatureCompatibilityVersion`` command against the + ``admin`` database. - .. include:: /includes/list-run-command-targets.rst + .. include:: /includes/list-run-command-targets.rst - - ``"3.2"`` featureCompatibilityVersion is supported on MongoDB - 3.4 and MongoDB 3.2 Deployments Only. + - ``"3.2"`` featureCompatibilityVersion is supported on MongoDB + 3.4 and MongoDB 3.2 Deployments Only. - .. code-block:: javascript + .. code-block:: javascript - db.adminCommand( { setFeatureCompatibilityVersion: "3.2" } ) + db.adminCommand( { setFeatureCompatibilityVersion: "3.2" } ) - Setting the ``featureCompatibilityVersion`` to ``"3.2"`` disables the - use of these features but does not remove existing usage of these - features. + Setting the ``featureCompatibilityVersion`` to ``"3.2"`` disables the + use of these features but does not remove existing usage of these + features. - If performed as part of a downgrade to 3.2 procedure, you must also - manually remove the existing usage before downgrading the binaries. For - details, see :ref:`3.4-downgrade-features-prereq`. + If performed as part of a downgrade to 3.2 procedure, you must also + manually remove the existing usage before downgrading the binaries. For + details, see :ref:`3.4-downgrade-features-prereq`. diff --git a/source/reference/command/shardCollection.txt b/source/reference/command/shardCollection.txt index d4594f82ba1..d78b03c584c 100644 --- a/source/reference/command/shardCollection.txt +++ b/source/reference/command/shardCollection.txt @@ -212,7 +212,9 @@ Use the form ``field: "hashed"`` to specify a hashed shard key field. .. include:: /includes/note-hashed-shard-key-during-chunk-migration.rst -.. seealso:: :doc:`/core/hashed-sharding` +.. seealso:: + + :doc:`/core/hashed-sharding` .. _shardCollection-zones: @@ -244,7 +246,9 @@ have been defined for the empty collection *and* See :ref:`pre-define-zone-range-hashed-example` for an example. -.. seealso:: +.. seealso:: + + - :ref:`initial-chunks` diff --git a/source/reference/command/shardConnPoolStats.txt b/source/reference/command/shardConnPoolStats.txt index e81cf2c1d7e..ae219eed572 100644 --- a/source/reference/command/shardConnPoolStats.txt +++ b/source/reference/command/shardConnPoolStats.txt @@ -104,7 +104,10 @@ Output .. include:: /includes/fact-tags-field.rst - .. seealso:: :rsconf:`members[n].tags` + .. seealso:: + + :rsconf:`members[n].tags` + .. data:: shardConnPoolStats.createdByType diff --git a/source/reference/command/shutdown.txt b/source/reference/command/shutdown.txt index c4c31b1379b..f0b6b0e583c 100644 --- a/source/reference/command/shutdown.txt +++ b/source/reference/command/shutdown.txt @@ -79,7 +79,10 @@ shutdown .. versionadded:: 4.4 -.. seealso:: :method:`db.shutdownServer()` +.. seealso:: + + :method:`db.shutdownServer()` + Behavior -------- diff --git a/source/reference/command/split.txt b/source/reference/command/split.txt index 58c8e2ee8bf..e6c68c03a48 100644 --- a/source/reference/command/split.txt +++ b/source/reference/command/split.txt @@ -105,7 +105,7 @@ the command cannot use the ``find`` or the ``bounds`` option to split an empty chunk since an empty chunk has no median. To create splits in empty chunks, use either the ``middle`` option with -the :dbcommand:`split` command or use the :dbcommand:`splitAt` command. +the :dbcommand:`split` command or use the :method:`sh.splitAt()` command. Command Formats --------------- @@ -138,7 +138,10 @@ this purpose. .. include:: /includes/warning-splitting-chunks.rst -.. seealso:: :dbcommand:`moveChunk`, :method:`sh.moveChunk()`, +.. seealso:: + + :dbcommand:`moveChunk`, :method:`sh.moveChunk()`, + :method:`sh.splitAt()`, and :method:`sh.splitFind()`, which wrap the functionality of :dbcommand:`split`. diff --git a/source/reference/command/splitChunk.txt b/source/reference/command/splitChunk.txt index dc852f7d27f..ebe1bf66185 100644 --- a/source/reference/command/splitChunk.txt +++ b/source/reference/command/splitChunk.txt @@ -23,7 +23,10 @@ Definition .. admin-only. - .. seealso:: :dbcommand:`moveChunk` and :method:`sh.moveChunk()`. + .. seealso:: + + :dbcommand:`moveChunk` and :method:`sh.moveChunk()`. + The :dbcommand:`splitChunk` command takes a document with the following fields: diff --git a/source/reference/command/startSession.txt b/source/reference/command/startSession.txt index b80decd8d24..78611967c4a 100644 --- a/source/reference/command/startSession.txt +++ b/source/reference/command/startSession.txt @@ -39,7 +39,10 @@ Definition ``featureCompatibilityVersion`` must be 3.6 or greater to use the :dbcommand:`startSession` command. - .. seealso:: :method:`Mongo.startSession()` + .. seealso:: + + :method:`Mongo.startSession()` + Behavior -------- diff --git a/source/reference/command/update.txt b/source/reference/command/update.txt index 1680b797f2b..3dc1fe5c2bb 100644 --- a/source/reference/command/update.txt +++ b/source/reference/command/update.txt @@ -4,8 +4,7 @@ update .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -471,86 +470,82 @@ replacement document. Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +To modify the **existing** shard key value with +:dbcommand:`update`: - To modify the **existing** shard key value with - :dbcommand:`update`: +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. +- You :red:`must` specify ``multi: false``. - - You :red:`must` specify ``multi: false``. - - - You :red:`must` include an equality :ref:`query filter - ` on the full shard key. +- You :red:`must` include an equality :ref:`query filter + ` on the full shard key. - .. tip:: +.. tip:: - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - See also :ref:`cmd-update-sharded-upsert`. +See also :ref:`cmd-update-sharded-upsert`. .. _cmd-update-missing-shard-key: Missing Shard Key ````````````````` -.. container:: +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:dbcommand:`update` to set the document's +**missing** shard key, you :red:`must` run on a +:binary:`~bin.mongos`. Do :red:`not` issue the operation directly on +the shard. - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :dbcommand:`update` to set the document's - **missing** shard key, you :red:`must` run on a - :binary:`~bin.mongos`. Do :red:`not` issue the operation directly on - the shard. +In addition, the following requirements also apply: - In addition, the following requirements also apply: - - .. list-table:: - :header-rows: 1 - :widths: 30 70 +.. list-table:: + :header-rows: 1 + :widths: 30 70 - * - + * - - - Requirements + - Requirements - * - To set to ``null`` + * - To set to ``null`` - - - Can specify ``multi: true``. + - - Can specify ``multi: true``. - - Requires equality filter on the full shard key if ``upsert: - true`` is specified. + - Requires equality filter on the full shard key if ``upsert: + true`` is specified. - * - To set to a non-``null`` value: + * - To set to a non-``null`` value: - - - :red:`Must` be performed either inside a :doc:`transaction - ` or as a :doc:`retryable write - `. + - - :red:`Must` be performed either inside a :doc:`transaction + ` or as a :doc:`retryable write + `. - - :red:`Must` specify ``multi: false``. + - :red:`Must` specify ``multi: false``. - - Requires equality filter on the full shard key if either: + - Requires equality filter on the full shard key if either: - - ``upsert: true``, or + - ``upsert: true``, or - - if using a replacement document and the new shard key - value belongs to a different shard. + - if using a replacement document and the new shard key + value belongs to a different shard. - .. tip:: +.. tip:: - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - See also: +See also: - - :ref:`method-update-sharded-upsert` +- :ref:`method-update-sharded-upsert` - - :ref:`shard-key-missing` +- :ref:`shard-key-missing` Transactions ~~~~~~~~~~~~ @@ -569,8 +564,6 @@ Write Concerns and Transactions .. include:: /includes/extracts/transactions-operations-write-concern.rst - - .. |operation| replace:: :dbcommand:`update` Examples @@ -820,7 +813,7 @@ calculated grade average and letter grade. First Stage The :pipeline:`$set` stage calculates a new field ``average`` based - on the average of the ``tests`` field. See :expression:`$avg` for + on the average of the ``tests`` field. See :group:`$avg` for more information on the ``$avg`` aggregation operator. Second Stage @@ -921,8 +914,6 @@ Update Elements Match ``arrayFilters`` Criteria Create a collection ``students`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.insert([ diff --git a/source/reference/config-database.txt b/source/reference/config-database.txt index c9cf7bb189b..1aecc18c631 100644 --- a/source/reference/config-database.txt +++ b/source/reference/config-database.txt @@ -1,6 +1,6 @@ -.. index:: internals; config database -.. index:: sharding; config database + + .. _config-database: =============== diff --git a/source/reference/configuration-options.txt b/source/reference/configuration-options.txt index a408f9a78c5..181d315012a 100644 --- a/source/reference/configuration-options.txt +++ b/source/reference/configuration-options.txt @@ -716,8 +716,8 @@ Core Options specified, the process does not create a PID file. This option is generally only useful in combination with the :setting:`processManagement.fork` setting. - .. admonition:: Linux - :class: note + .. note:: Linux + On Linux, PID file management is generally the responsibility of your distro's init system: usually a service file in the ``/etc/init.d`` @@ -726,8 +726,8 @@ Core Options systems. For more information, please see the respective :doc:`Installation Guide ` for your operating system. - .. admonition:: macOS - :class: note + .. note:: macOS + On macOS, PID file management is generally handled by ``brew``. Only use the :setting:`processManagement.pidFilePath` option if you are not using ``brew`` on your macOS system. @@ -1237,7 +1237,7 @@ Core Options The password to de-crypt the certificate-key file (i.e. :setting:`~net.tls.certificateKeyFile`). Use the - :setting:`net.tls.certificateKeyPassword` option only if the + :setting:`net.tls.certificateKeyFilePassword` option only if the certificate-key file is encrypted. In all cases, the :binary:`~bin.mongos` or :binary:`~bin.mongod` will redact the password from all logging and reporting output. @@ -1596,7 +1596,9 @@ Core Options Members of replica sets and sharded clusters must speak at least one protocol in common. - .. seealso:: :ref:`ssl-disallow-protocols` + .. seealso:: + + :ref:`ssl-disallow-protocols` .. setting:: net.tls.FIPSMode @@ -2137,7 +2139,9 @@ Core Options Members of replica sets and sharded clusters must speak at least one protocol in common. - .. seealso:: :ref:`ssl-disallow-protocols` + .. seealso:: + + :ref:`ssl-disallow-protocols` .. setting:: net.ssl.FIPSMode @@ -2602,7 +2606,9 @@ Key Management Configuration Options .. include:: /includes/fact-enterprise-only-admonition.rst - .. seealso:: :ref:`kmip-master-key-rotation` + .. seealso:: + + :ref:`kmip-master-key-rotation` @@ -2968,7 +2974,8 @@ Key Management Configuration Options .. versionadded:: 3.4 Available in MongoDB Enterprise only. The method :binary:`~bin.mongod` or :binary:`~bin.mongos` uses to authenticate to an LDAP server. - Use with :setting:`~security.ldap.queryUser` and :setting:`~security.ldap.queryPassword` to + Use with :setting:`~security.ldap.bind.queryUser` and + :setting:`~security.ldap.bind.queryPassword` to connect to the LDAP server. :setting:`~security.ldap.bind.method` supports the following values: @@ -3419,7 +3426,7 @@ LDAP Parameters ``storage`` Options ~~~~~~~~~~~~~~~~~~~ -.. admonition:: Starting in version 4.4 +.. versionchanged:: 4.4 - MongoDB removes the ``storage.indexBuildRetry`` option and the corresponding ``--noIndexBuildRetry`` command-line option. @@ -3468,8 +3475,8 @@ LDAP Parameters The :setting:`storage.dbPath` setting is available only for :binary:`~bin.mongod`. - .. admonition:: Configuration Files - :class: note + .. note:: Configuration Files + The default ``mongod.conf`` configuration file included with package manager installations uses the following platform-specific @@ -3795,8 +3802,8 @@ LDAP Parameters *Type*: float - .. admonition:: Deprecated in MongoDB 4.4 - :class: note + .. note:: Deprecated in MongoDB 4.4 + MongoDB deprecates the ``storage.wiredTiger.engineConfig.maxCacheOverflowFileSizeGB`` @@ -4112,7 +4119,7 @@ LDAP Parameters Starting in MongoDB 4.0: - The setting :setting:`replication.replSetName` cannot be used in conjunction with - :setting:`storage.indexBuildRetry`. + ``storage.indexBuildRetry``. - For the WiredTiger storage engine, :setting:`storage.journal.enabled: false @@ -4412,8 +4419,7 @@ LDAP Parameters The ping time, in milliseconds, that :binary:`~bin.mongos` uses to determine which secondary replica set members to pass read operations from clients. The default value of ``15`` corresponds to - the default value in all of the client :ecosystem:`drivers - `. + the default value in all of the client :driver:`drivers `. When :binary:`~bin.mongos` receives a request that permits reads to :term:`secondary` members, the :binary:`~bin.mongos` will: diff --git a/source/reference/connection-string.txt b/source/reference/connection-string.txt index 9260e0028ff..0705fdaf28d 100644 --- a/source/reference/connection-string.txt +++ b/source/reference/connection-string.txt @@ -1,4 +1,4 @@ -.. index:: connections + .. _mongodb-uri: @@ -16,8 +16,8 @@ Connection String URI Format This document describes the URI formats for defining connections between applications and MongoDB instances in the official MongoDB -:ecosystem:`drivers `. For a list of drivers and links to -driver documentation, see :ecosystem:`drivers `. +:driver:`Drivers `. For a list of drivers and links to +driver documentation, see :driver:`Drivers `. Connection String Formats ------------------------- @@ -28,7 +28,7 @@ You can specify the MongoDB connection string using either: - the :ref:`connections-dns-seedlist`. -.. index:: connections; connection string format + .. _connections-standard-connection-string-format: Standard Connection String Format @@ -47,162 +47,158 @@ The standard URI connection scheme has the form: Examples ```````` -.. container:: +.. tabs:: - .. tabs:: - - tabs: - - - id: standalone - name: Standalone - content: | + tabs: - - For a standalone: + - id: standalone + name: Standalone + content: | - .. code-block:: sh + - For a standalone: - mongodb://mongodb0.example.com:27017 + .. code-block:: sh - - For a standalone that :doc:`enforces access control - `: + mongodb://mongodb0.example.com:27017 - .. code-block:: sh + - For a standalone that :doc:`enforces access control + `: - mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/?authSource=admin + .. code-block:: sh - .. include:: /includes/fact-pct-encode-uri.rst + mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017/?authSource=admin - - id: repl - name: Replica Set - content: | + .. include:: /includes/fact-pct-encode-uri.rst - .. note:: + - id: repl + name: Replica Set + content: | - .. include:: /includes/fact-uri-rs-hostnames.rst + .. note:: - For a replica set, include the :urioption:`replicaSet` - option. + .. include:: /includes/fact-uri-rs-hostnames.rst - - For a replica set: + For a replica set, include the :urioption:`replicaSet` + option. - .. code-block:: sh + - For a replica set: - mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?replicaSet=myRepl - - - For a replica set that :doc:`enforces access control - `, include - user credentials: + .. code-block:: sh - .. code-block:: sh + mongodb://mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?replicaSet=myRepl + + - For a replica set that :doc:`enforces access control + `, include + user credentials: - mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl + .. code-block:: sh - .. include:: /includes/fact-pct-encode-uri.rst + mongodb://myDBReader:D1fficultP%40ssw0rd@mongodb0.example.com:27017,mongodb1.example.com:27017,mongodb2.example.com:27017/?authSource=admin&replicaSet=myRepl - - id: sharded - name: Sharded Cluster - content: | + .. include:: /includes/fact-pct-encode-uri.rst - .. note:: + - id: sharded + name: Sharded Cluster + content: | - For a connection string to a sharded cluster, specify - :binary:`~bin.mongos` hosts in the connection string. + .. note:: - - For a sharded cluster: + For a connection string to a sharded cluster, specify + :binary:`~bin.mongos` hosts in the connection string. - .. code-block:: sh + - For a sharded cluster: - mongodb://mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017 + .. code-block:: sh - - For a sharded cluster that :doc:`enforces access - control `, include - user credentials: + mongodb://mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017 - .. code-block:: sh + - For a sharded cluster that :doc:`enforces access + control `, include + user credentials: - mongodb://myDBReader:D1fficultP%40ssw0rd@mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin + .. code-block:: sh - .. include:: /includes/fact-pct-encode-uri.rst + mongodb://myDBReader:D1fficultP%40ssw0rd@mongos0.example.com:27017,mongos1.example.com:27017,mongos2.example.com:27017/?authSource=admin - For more examples, see :ref:`connections-connection-examples`. + .. include:: /includes/fact-pct-encode-uri.rst + +For more examples, see :ref:`connections-connection-examples`. Components `````````` -.. container:: +The standard URI connection string includes the following components: + +.. list-table:: + :widths: 20 80 + :header-rows: 1 - The standard URI connection string includes the following components: + * - Component + - Description - .. list-table:: - :widths: 20 80 - :header-rows: 1 - - * - Component - - Description + * - ``mongodb://`` - * - ``mongodb://`` + - A required prefix to identify that this is a string in the + standard connection format. - - A required prefix to identify that this is a string in the - standard connection format. + * - ``username:password@`` - * - ``username:password@`` + - Optional. Authentication credentials. + + If specified, the client will attempt to authenticate the + user to the :urioption:`authSource`. If + :urioption:`authSource` is unspecified, the client will + attempt to authenticate the user to the ``defaultauthdb``. + And if the ``defaultauthdb`` is unspecified, to the ``admin`` + database. - - Optional. Authentication credentials. - - If specified, the client will attempt to authenticate the - user to the :urioption:`authSource`. If - :urioption:`authSource` is unspecified, the client will - attempt to authenticate the user to the ``defaultauthdb``. - And if the ``defaultauthdb`` is unspecified, to the ``admin`` - database. + .. include:: /includes/fact-pct-encode-uri.rst - .. include:: /includes/fact-pct-encode-uri.rst + See also :urioption:`authSource`. - See also :urioption:`authSource`. + * - ``host[:port]`` - * - ``host[:port]`` + - The host (and optional port number) where the + :binary:`~bin.mongod` instance (or :binary:`~bin.mongos` + instance for a sharded cluster) is running. You can specify a + hostname, IP address, or UNIX domain socket. Specify as many + hosts as appropriate for your deployment topology: - - The host (and optional port number) where the - :binary:`~bin.mongod` instance (or :binary:`~bin.mongos` - instance for a sharded cluster) is running. You can specify a - hostname, IP address, or UNIX domain socket. Specify as many - hosts as appropriate for your deployment topology: + - For a standalone, specify the hostname of the standalone + :binary:`~bin.mongod` instance. - - For a standalone, specify the hostname of the standalone - :binary:`~bin.mongod` instance. + - .. include:: /includes/fact-uri-rs-hostnames.rst - - .. include:: /includes/fact-uri-rs-hostnames.rst + - For a sharded cluster, specify the hostname(s) of the + :binary:`~bin.mongos` instance(s). - - For a sharded cluster, specify the hostname(s) of the - :binary:`~bin.mongos` instance(s). + If the port number is not specified, the default port ``27017`` + is used. - If the port number is not specified, the default port ``27017`` - is used. + * - ``/defaultauthdb`` + + - Optional. The authentication database to use if the + connection string includes ``username:password@`` + authentication credentials but the :urioption:`authSource` option + is unspecified. - * - ``/defaultauthdb`` - - - Optional. The authentication database to use if the - connection string includes ``username:password@`` - authentication credentials but the :urioption:`authSource` option - is unspecified. + If both :urioption:`authSource` and ``defaultauthdb`` are + unspecified, the client will attempt to authenticate the + specified user to the ``admin`` database. - If both :urioption:`authSource` and ``defaultauthdb`` are - unspecified, the client will attempt to authenticate the - specified user to the ``admin`` database. + * - ``?`` - * - ``?`` + - Optional. A query string that specifies connection specific + options as ``=`` pairs. See + :ref:`connections-connection-options` for a full description of + these options. - - Optional. A query string that specifies connection specific - options as ``=`` pairs. See - :ref:`connections-connection-options` for a full description of - these options. + If the connection string does not specify a database/ you must + specify a slash (``/``) between the last ``host`` and the + question mark (``?``) that begins the string of options. - If the connection string does not specify a database/ you must - specify a slash (``/``) between the last ``host`` and the - question mark (``?``) that begins the string of options. - -.. index:: connections; dns-seedlist +-seedlist .. _connections-dns-seedlist: DNS Seed List Connection Format @@ -322,7 +318,7 @@ string in the standard format would be: connecting the :binary:`~bin.mongo` shell to a replica set using the DNS Seed list Connection Format. -.. index:: connections; options + .. _connections-connection-options: Connection String Options @@ -351,7 +347,7 @@ connection includes the :urioption:`replicaSet` and mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000 -.. admonition:: Semi-colon separator for connection string arguments +.. note:: Semi-colon separator for connection string arguments To provide backwards compatibility, drivers currently accept semi-colons (i.e. ``;``) as option separators. @@ -382,8 +378,8 @@ members running on the specified hosts: When connecting to a replica set, provide a :term:`seed list` of the replica set member(s) to the ``host[:port]`` component of the - uri. For specific details, refer to your :ecosystem:`driver - ` documentation. + uri. For specific details, refer to your :driver:`driver ` + documentation. Connection Options ~~~~~~~~~~~~~~~~~~ @@ -393,276 +389,269 @@ Connection Options TLS Options ``````````` -.. container:: - - The following connection string to a replica set includes - :urioption:`tls=true ` option (available starting in MongoDB 4.2): +The following connection string to a replica set includes +:urioption:`tls=true ` option (available starting in MongoDB 4.2): - .. code-block:: none +.. code-block:: none - mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&tls=true + mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&tls=true - Alternatively, you can also use the equivalent :urioption:`ssl=true - ` option: +Alternatively, you can also use the equivalent :urioption:`ssl=true +` option: - .. code-block:: none +.. code-block:: none - mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true + mongodb://db0.example.com,db1.example.com,db2.example.com/?replicaSet=myRepl&ssl=true - .. list-table:: - :header-rows: 1 - :widths: 30 70 +.. list-table:: + :header-rows: 1 + :widths: 30 70 - * - Connection Option - - Description + * - Connection Option + - Description - * - .. urioption:: tls + * - .. urioption:: tls - - Enables or disables TLS/SSL for the connection: + - Enables or disables TLS/SSL for the connection: - - ``true``: Initiate the connection with TLS/SSL. Default for - :ref:`connections-dns-seedlist`. + - ``true``: Initiate the connection with TLS/SSL. Default for + :ref:`connections-dns-seedlist`. - - ``false``: Initiate the connection without TLS/SSL. Default for - :ref:`connections-standard-connection-string-format`. + - ``false``: Initiate the connection without TLS/SSL. Default for + :ref:`connections-standard-connection-string-format`. - .. note:: + .. note:: - The :urioption:`tls` option is equivalent to the - :urioption:`ssl` option. + The :urioption:`tls` option is equivalent to the + :urioption:`ssl` option. - If the :binary:`mongo` shell specifies additional - :ref:`tls/ssl ` options from the - command-line, use the :option:`--tls ` - command-line option instead. - - .. versionadded:: 4.2 + If the :binary:`mongo` shell specifies additional + :ref:`tls/ssl ` options from the + command-line, use the :option:`--tls ` + command-line option instead. + + .. versionadded:: 4.2 - * - .. urioption:: ssl + * - .. urioption:: ssl - - A boolean to enable or disables TLS/SSL for the connection: - - - ``true``: Initiate the connection with TLS/SSL. Default for - :ref:`connections-dns-seedlist`. - - - ``false``: Initiate the connection without TLS/SSL. Default - for :ref:`connections-standard-connection-string-format`. + - A boolean to enable or disables TLS/SSL for the connection: + + - ``true``: Initiate the connection with TLS/SSL. Default for + :ref:`connections-dns-seedlist`. + + - ``false``: Initiate the connection without TLS/SSL. Default + for :ref:`connections-standard-connection-string-format`. - .. note:: + .. note:: - The :urioption:`ssl` option is equivalent to the - :urioption:`tls` option. + The :urioption:`ssl` option is equivalent to the + :urioption:`tls` option. - If the :binary:`mongo` shell specifies additional - :ref:`tls/ssl ` options from the - command-line, use the :option:`--ssl ` - command-line option instead. + If the :binary:`mongo` shell specifies additional + :ref:`tls/ssl ` options from the + command-line, use the :option:`--ssl ` + command-line option instead. - * - .. urioption:: tlsCertificateKeyFile + * - .. urioption:: tlsCertificateKeyFile - - Specifies the location of a local :file:`.pem` file that - contains either the client's TLS/SSL X.509 certificate or the - client's TLS/SSL certificate and key. + - Specifies the location of a local :file:`.pem` file that + contains either the client's TLS/SSL X.509 certificate or the + client's TLS/SSL certificate and key. - The client presents this file to the - :binary:`~bin.mongod`/:binary:`~bin.mongos` instance. + The client presents this file to the + :binary:`~bin.mongod`/:binary:`~bin.mongos` instance. - .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst + .. include:: /includes/extracts/4.4-changes-certificate-expiry-warning.rst - This option is not supported by all drivers. Refer to the - :ecosystem:`drivers ` documentation. - - .. include:: /includes/fact-uri-option-availability.rst + This option is not supported by all drivers. Refer to the + :driver:`Drivers ` documentation. + + .. include:: /includes/fact-uri-option-availability.rst - .. versionadded:: 4.2 + .. versionadded:: 4.2 - * - .. urioption:: tlsCertificateKeyFilePassword + * - .. urioption:: tlsCertificateKeyFilePassword - - Specifies the password to de-crypt the - :urioption:`tlsCertificateKeyFile`. + - Specifies the password to de-crypt the + :urioption:`tlsCertificateKeyFile`. - This option is not supported by all drivers. Refer to the - :ecosystem:`drivers ` documentation. + This option is not supported by all drivers. Refer to the + :driver:`Drivers ` documentation. - .. include:: /includes/fact-uri-option-availability.rst + .. include:: /includes/fact-uri-option-availability.rst - .. versionadded:: 4.2 + .. versionadded:: 4.2 - * - .. urioption:: tlsCAFile + * - .. urioption:: tlsCAFile - - Specifies the location of a local :file:`.pem` file that - contains the root certificate chain from the Certificate - Authority. This file is used to validate the certificate - presented by the :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. + - Specifies the location of a local :file:`.pem` file that + contains the root certificate chain from the Certificate + Authority. This file is used to validate the certificate + presented by the :binary:`~bin.mongod`/:binary:`~bin.mongos` + instance. - This option is not supported by all drivers. Refer to the - :ecosystem:`drivers ` documentation. + This option is not supported by all drivers. Refer to the + :driver:`Drivers ` documentation. - .. include:: /includes/fact-uri-option-availability.rst + .. include:: /includes/fact-uri-option-availability.rst - .. versionadded:: 4.2 + .. versionadded:: 4.2 - * - .. urioption:: tlsAllowInvalidCertificates - - - Bypasses validation of the certificates presented by the - :binary:`~bin.mongod`/:binary:`~bin.mongos` instance + * - .. urioption:: tlsAllowInvalidCertificates + + - Bypasses validation of the certificates presented by the + :binary:`~bin.mongod`/:binary:`~bin.mongos` instance - Set to ``true`` to connect to MongoDB instances even if the - server's present invalid certificates. + Set to ``true`` to connect to MongoDB instances even if the + server's present invalid certificates. - This option is not supported by all drivers. Refer to the - :ecosystem:`drivers ` documentation. + This option is not supported by all drivers. Refer to the + :driver:`Drivers ` documentation. - .. include:: /includes/fact-uri-option-availability.rst + .. include:: /includes/fact-uri-option-availability.rst - .. warning:: + .. warning:: - Disabling certificate validation creates a vulnerability. + Disabling certificate validation creates a vulnerability. - .. versionadded:: 4.2 + .. versionadded:: 4.2 - * - .. urioption:: tlsAllowInvalidHostnames + * - .. urioption:: tlsAllowInvalidHostnames - - Disables hostname validation of the certificate presented by - the :binary:`~bin.mongod`/:binary:`~bin.mongos` instance. + - Disables hostname validation of the certificate presented by + the :binary:`~bin.mongod`/:binary:`~bin.mongos` instance. - Set to ``true`` to connect to MongoDB instances even if the - hostname in the server certificates do not match the server's - host. + Set to ``true`` to connect to MongoDB instances even if the + hostname in the server certificates do not match the server's + host. - This option is not supported by all drivers. Refer to the - :ecosystem:`drivers ` documentation. + This option is not supported by all drivers. Refer to the + :driver:`Drivers ` documentation. - .. include:: /includes/fact-uri-option-availability.rst + .. include:: /includes/fact-uri-option-availability.rst - .. warning:: + .. warning:: - Disabling certificate validation creates a vulnerability. + Disabling certificate validation creates a vulnerability. - .. versionadded:: 4.2 + .. versionadded:: 4.2 - * - .. urioption:: tlsInsecure + * - .. urioption:: tlsInsecure - - Disables various certificate validations. - - Set to ``true`` to disable certificate validations. The exact - validatations disabled vary by drivers. Refer to the - :ecosystem:`drivers ` documentation. + - Disables various certificate validations. + + Set to ``true`` to disable certificate validations. The exact + validatations disabled vary by drivers. Refer to the + :driver:`Drivers ` documentation. - .. include:: /includes/fact-uri-option-availability.rst + .. include:: /includes/fact-uri-option-availability.rst - .. warning:: + .. warning:: - Disabling certificate validation creates a vulnerability. + Disabling certificate validation creates a vulnerability. - .. versionadded:: 4.2 - + .. versionadded:: 4.2 Timeout Options ```````````````` -.. container:: - - .. list-table:: - :header-rows: 1 - :widths: 30 70 +.. list-table:: + :header-rows: 1 + :widths: 30 70 - * - Connection Option - - Description + * - Connection Option + - Description - * - .. urioption:: connectTimeoutMS + * - .. urioption:: connectTimeoutMS - - The time in milliseconds to attempt a connection before timing - out. The default is never to timeout, though different drivers - might vary. See the :ecosystem:`driver ` - documentation. + - The time in milliseconds to attempt a connection before timing + out. The default is never to timeout, though different drivers + might vary. See the :driver:`driver ` + documentation. - * - .. urioption:: socketTimeoutMS + * - .. urioption:: socketTimeoutMS - - The time in milliseconds to attempt a send or receive on a - socket before the attempt times out. The default is never to - timeout, though different drivers might vary. See the - :ecosystem:`driver ` documentation. + - The time in milliseconds to attempt a send or receive on a + socket before the attempt times out. The default is never to + timeout, though different drivers might vary. See the + :driver:`driver ` documentation. Compression Options ``````````````````` -.. container:: - - .. list-table:: - :header-rows: 1 - :widths: 30 70 +.. list-table:: + :header-rows: 1 + :widths: 30 70 - * - Connection Option - - Description + * - Connection Option + - Description - * - .. urioption:: compressors + * - .. urioption:: compressors - - Comma-delimited string of compressors to enable - network compression for communication between this - client and a :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. + - Comma-delimited string of compressors to enable + network compression for communication between this + client and a :binary:`~bin.mongod`/:binary:`~bin.mongos` + instance. - You can specify the following compressors: + You can specify the following compressors: - - :term:`snappy` + - :term:`snappy` - - :term:`zlib` (Available in MongoDB 3.6 or greater) + - :term:`zlib` (Available in MongoDB 3.6 or greater) - - :term:`zstd` (Available in MongoDB 4.2 or greater) + - :term:`zstd` (Available in MongoDB 4.2 or greater) - If you specify multiple compressors, then the order in which you list - the compressors matter as well as the communication initiator. For - example, if the client specifies the following network - compressors ``"zlib,snappy"`` and the :binary:`~bin.mongod` specifies - ``"snappy,zlib"``, messages between the client and the - :binary:`~bin.mongod` uses ``zlib``. + If you specify multiple compressors, then the order in which you list + the compressors matter as well as the communication initiator. For + example, if the client specifies the following network + compressors ``"zlib,snappy"`` and the :binary:`~bin.mongod` specifies + ``"snappy,zlib"``, messages between the client and the + :binary:`~bin.mongod` uses ``zlib``. - .. important:: + .. important:: - Messages are compressed when both parties enable network - compression. Otherwise, messages between the parties are - uncompressed. + Messages are compressed when both parties enable network + compression. Otherwise, messages between the parties are + uncompressed. - If the parties do not share at least one common compressor, - messages between the parties are uncompressed. + If the parties do not share at least one common compressor, + messages between the parties are uncompressed. - Starting in MongoDB 4.0.5 (and MongoDB 3.6.10), the - :binary:`~bin.mongo` shell supports the uri connection string - option :urioption:`compressors`. + Starting in MongoDB 4.0.5 (and MongoDB 3.6.10), the + :binary:`~bin.mongo` shell supports the uri connection string + option :urioption:`compressors`. - * - .. urioption:: zlibCompressionLevel + * - .. urioption:: zlibCompressionLevel - - An integer that specifies the compression level if using - :term:`zlib` for :urioption:`network compression `. + - An integer that specifies the compression level if using + :term:`zlib` for :urioption:`network compression `. - You can specify an integer value ranging from ``-1`` to ``9``: + You can specify an integer value ranging from ``-1`` to ``9``: - .. list-table:: - :header-rows: 1 - :widths: 25 75 + .. list-table:: + :header-rows: 1 + :widths: 25 75 - * - Value - - Notes + * - Value + - Notes - * - ``-1`` + * - ``-1`` - - Default compression level, usually level ``6`` compression. + - Default compression level, usually level ``6`` compression. - * - ``0`` - - No compression + * - ``0`` + - No compression - * - ``1`` - ``9`` + * - ``1`` - ``9`` - - Increasing level of compression but at the cost of speed, with: + - Increasing level of compression but at the cost of speed, with: - - ``1`` providing the best speed but least compression, and + - ``1`` providing the best speed but least compression, and - - ``9`` providing the best compression but at the slowest speed. + - ``9`` providing the best compression but at the slowest speed. - Not supported by the :binary:`~bin.mongo` shell. + Not supported by the :binary:`~bin.mongo` shell. .. _connection-pool-options: @@ -671,7 +660,7 @@ Connection Pool Options Most drivers implement some kind of connection pool handling. Some drivers do not support connection -pools. See your :ecosystem:`driver ` documentation +pools. See your :driver:`driver ` documentation for more information on the connection pooling implementation. These options allow applications to configure the connection pool when connecting to the MongoDB deployment. @@ -696,7 +685,7 @@ connecting to the MongoDB deployment. .. note:: The :urioption:`minPoolSize` option is not supported by all drivers. For information on your driver, see the - :ecosystem:`drivers ` documentation. + :driver:`Drivers ` documentation. * - .. urioption:: maxIdleTimeMS @@ -710,7 +699,7 @@ connecting to the MongoDB deployment. - A number that the driver multiplies the :urioption:`maxPoolSize` value to, to provide the maximum number of threads allowed to wait for a connection to become available from the pool. For - default values, see the :ecosystem:`/drivers` + default values, see the :driver:`driver ` documentation. This option is not supported by all drivers. @@ -719,7 +708,7 @@ connecting to the MongoDB deployment. - The maximum time in milliseconds that a thread can wait for a connection to become available. For default values, see the - :ecosystem:`/drivers` documentation. + :driver:`driver ` documentation. This option is not supported by all drivers. @@ -1287,13 +1276,13 @@ Miscellaneous Configuration ``pythonLegacy`` The default representation for the Python driver. - For the default, see the :ecosystem:`drivers ` + For the default, see the :driver:`Drivers ` documentation for your driver. .. note:: Not all drivers support the :urioption:`uuidRepresentation` - option. For information on your driver, see the :ecosystem:`drivers - ` documentation. + option. For information on your driver, see the :driver:`drivers + ` documentation. .. _connections-connection-examples: @@ -1346,7 +1335,7 @@ The following connects to a UNIX domain socket with file path mongodb://%2Ftmp%2Fmongodb-27017.sock .. note:: Not all drivers support UNIX domain sockets. For information - on your driver, see the :ecosystem:`drivers ` + on your driver, see the :driver:`Drivers ` documentation. Replica Set with Members on Different Machines diff --git a/source/reference/data-models.txt b/source/reference/data-models.txt index e37da680f34..5ca94a6f917 100644 --- a/source/reference/data-models.txt +++ b/source/reference/data-models.txt @@ -10,11 +10,9 @@ Data Model Reference :depth: 1 :class: singlecol -.. class:: toc - - :doc:`/reference/database-references` - Discusses manual references and DBRefs, which MongoDB can use to - represent relationships between documents. +:doc:`/reference/database-references` + Discusses manual references and DBRefs, which MongoDB can use to + represent relationships between documents. .. toctree:: diff --git a/source/reference/database-profiler.txt b/source/reference/database-profiler.txt index 1d8b5be1580..899b6cad566 100644 --- a/source/reference/database-profiler.txt +++ b/source/reference/database-profiler.txt @@ -365,7 +365,7 @@ operation. .. data:: system.profile.nMatched - The number of documents that match the :data:`system.profile.query` + The number of documents that match the query condition for the update operation. .. data:: system.profile.nModified diff --git a/source/reference/database-references.txt b/source/reference/database-references.txt index 0f97052ad2c..a35f4ea439e 100644 --- a/source/reference/database-references.txt +++ b/source/reference/database-references.txt @@ -1,6 +1,6 @@ -.. index:: DBRef -.. index:: database references -.. index:: references + + + .. _database-references: =================== @@ -37,29 +37,29 @@ This page outlines alternative procedures that predate the MongoDB applications use one of two methods for relating documents: -- :ref:`Manual references ` where you save the - ``_id`` field of one document in another document as a reference. - Then your application can run a second query to return the related - data. These references are simple and sufficient for most use - cases. - -- :ref:`DBRefs ` are references from one document to another - using the value of the first document's ``_id`` field, collection name, - and, optionally, its database name. By including these names, DBRefs - allow documents located in multiple collections to be more easily linked - with documents from a single collection. - - To resolve DBRefs, your application - must perform additional queries to return the referenced - documents. Many :ecosystem:`drivers ` have helper - methods that form the query for the DBRef automatically. The - drivers [#official-driver]_ do not *automatically* resolve DBRefs - into documents. - - DBRefs provide a common format and type to represent relationships among - documents. The DBRef format also provides common semantics for representing - links between documents if your database must interact with - multiple frameworks and tools. +- :ref:`Manual references ` where you save the + ``_id`` field of one document in another document as a reference. + Then your application can run a second query to return the related + data. These references are simple and sufficient for most use + cases. + +- :ref:`DBRefs ` are references from one document to another + using the value of the first document's ``_id`` field, collection name, + and, optionally, its database name. By including these names, DBRefs + allow documents located in multiple collections to be more easily linked + with documents from a single collection. + + To resolve DBRefs, your application + must perform additional queries to return the referenced + documents. Many :driver:`Drivers ` have helper + methods that form the query for the DBRef automatically. The + drivers [#official-driver]_ do not *automatically* resolve DBRefs + into documents. + + DBRefs provide a common format and type to represent relationships among + documents. The DBRef format also provides common semantics for representing + links between documents if your database must interact with + multiple frameworks and tools. Unless you have a compelling reason to use DBRefs, use manual references instead. @@ -217,7 +217,7 @@ Driver Support for DBRefs - Supported - - Please see the :ecosystem:`C# driver page ` + - Please see the :driver:`C# driver page ` for more information. * - **Haskell** @@ -230,21 +230,21 @@ Driver Support for DBRefs - Supported - - Please see the :ecosystem:`Java driver page ` + - Please see the :driver:`Java driver page ` for more information. * - **Node.js** - Supported - - Please see the :ecosystem:`Node.js driver page ` + - Please see the :driver:`Node.js driver page ` for more information. * - **Perl** - Supported - - Please see the :ecosystem:`Perl driver page ` + - Please see the :driver:`Perl driver page ` for more information. * - **PHP** @@ -257,7 +257,7 @@ Driver Support for DBRefs - Supported - - Please see the :ecosystem:`PyMongo driver page ` + - Please see the :driver:`PyMongo driver page ` for more information. * - **Ruby** diff --git a/source/reference/explain-results.txt b/source/reference/explain-results.txt index dd46c0640e6..1d97a122d2e 100644 --- a/source/reference/explain-results.txt +++ b/source/reference/explain-results.txt @@ -72,285 +72,325 @@ the ``explain`` operation. ``queryPlanner`` ~~~~~~~~~~~~~~~~ -.. container:: +:data:`~explain.queryPlanner` information details the plan selected by +the :doc:`query optimizer `. - :data:`~explain.queryPlanner` information details the plan selected by - the :doc:`query optimizer `. +.. tabs:: - .. tabs:: + tabs: - tabs: + - id: unsharded + name: "Unsharded Collections" + content: | - - id: unsharded - name: "Unsharded Collections" - content: | + For unsharded collections, ``explain`` returns the following + ``queryPlanner`` information: - For unsharded collections, ``explain`` returns the following - ``queryPlanner`` information: + .. code-block:: none - .. code-block:: none - - "queryPlanner" : { - "plannerVersion" : , - "namespace" : , - "indexFilterSet" : , - "parsedQuery" : { - ... - }, - "queryHash" : , - "planCacheKey" : , - "optimizedPipeline" : , // Starting in MongoDB 4.2, only appears if true - "winningPlan" : { - "stage" : , + "queryPlanner" : { + "plannerVersion" : , + "namespace" : , + "indexFilterSet" : , + "parsedQuery" : { + ... + }, + "queryHash" : , + "planCacheKey" : , + "optimizedPipeline" : , // Starting in MongoDB 4.2, only appears if true + "winningPlan" : { + "stage" : , + ... + "inputStage" : { + "stage" : , ... "inputStage" : { - "stage" : , ... - "inputStage" : { - ... - } } - }, - "rejectedPlans" : [ - , + } + }, + "rejectedPlans" : [ + , + ... + ] + } + + - id: sharded + name: "Sharded Collections" + content: | + For sharded collections, ``explain`` includes the core + query planner and server information for each accessed + shard in the ``shards`` field: + + .. code-block:: none + + "queryPlanner" : { + "mongosPlannerVersion" : , + "winningPlan" : { + "stage" : , + "shards" : [ + { + "shardName" : , + "connectionString" : , + "serverInfo" : { + "host" : , + "port" : , + "version" : , + "gitVersion" : + }, + "plannerVersion" : , + "namespace" : , + "parsedQuery" : , + "queryHash" : , + "planCacheKey" : , + "optimizedPipeline" : , // Starting in MongoDB 4.2, only appears if true + "winningPlan" : { + "stage" : , + "inputStage" : { + "stage" : + ..., + } + }, + "rejectedPlans" : [ + , + ... + ] + }, ... ] } - - - id: sharded - name: "Sharded Collections" - content: | - For sharded collections, ``explain`` includes the core - query planner and server information for each accessed - shard in the ``shards`` field: - - .. code-block:: none - - "queryPlanner" : { - "mongosPlannerVersion" : , - "winningPlan" : { - "stage" : , - "shards" : [ - { - "shardName" : , - "connectionString" : , - "serverInfo" : { - "host" : , - "port" : , - "version" : , - "gitVersion" : - }, - "plannerVersion" : , - "namespace" : , - "parsedQuery" : , - "queryHash" : , - "planCacheKey" : , - "optimizedPipeline" : , // Starting in MongoDB 4.2, only appears if true - "winningPlan" : { - "stage" : , - "inputStage" : { - "stage" : - ..., - } - }, - "rejectedPlans" : [ - , - ... - ] - }, - ... - ] - } - } + } - .. data:: explain.queryPlanner +.. data:: explain.queryPlanner - Contains information on the selection of the query plan by the - :doc:`query optimizer `. + Contains information on the selection of the query plan by the + :doc:`query optimizer `. - .. data:: explain.queryPlanner.namespace + .. data:: explain.queryPlanner.namespace - A string that specifies the namespace (i.e., - ``.``) against which the query is run. + A string that specifies the namespace (i.e., + ``.``) against which the query is run. - .. data:: explain.queryPlanner.indexFilterSet + .. data:: explain.queryPlanner.indexFilterSet - A boolean that specifies whether MongoDB applied an :ref:`index - filter ` for the :term:`query shape`. + A boolean that specifies whether MongoDB applied an :ref:`index + filter ` for the :term:`query shape`. - .. data:: explain.queryPlanner.queryHash + .. data:: explain.queryPlanner.queryHash - A hexadecimal string that represents the hash of the - :term:`query shape` and is dependent only on the query shapes. - ``queryHash`` can help identify slow queries (including the - query filter of write operations) with the same query shape. + A hexadecimal string that represents the hash of the + :term:`query shape` and is dependent only on the query shapes. + ``queryHash`` can help identify slow queries (including the + query filter of write operations) with the same query shape. - .. note:: + .. note:: - As with any hash function, two different query shapes may result - in the same hash value. However, the occurrence of hash - collisions between different query shapes is unlikely. + As with any hash function, two different query shapes may result + in the same hash value. However, the occurrence of hash + collisions between different query shapes is unlikely. - For more information on ``queryHash`` and ``planCacheKey``, - see :ref:`query-hash-plan-cache-key`. + For more information on ``queryHash`` and ``planCacheKey``, + see :ref:`query-hash-plan-cache-key`. - .. versionadded:: 4.2 + .. versionadded:: 4.2 - .. data:: explain.queryPlanner.planCacheKey + .. data:: explain.queryPlanner.planCacheKey - A hash of the key for the plan cache entry associated with the - query. + A hash of the key for the plan cache entry associated with the + query. - Unlike the :data:`~explain.queryPlanner.queryHash`, the - :data:`~explain.queryPlanner.planCacheKey` is a function of - both the query shape and the currently available indexes for - that shape. That is, if indexes that can support the query - shape are added/dropped, the ``planCacheKey`` value may change - whereas the ``queryHash`` value would not change. + Unlike the :data:`~explain.queryPlanner.queryHash`, the + :data:`~explain.queryPlanner.planCacheKey` is a function of + both the query shape and the currently available indexes for + that shape. That is, if indexes that can support the query + shape are added/dropped, the ``planCacheKey`` value may change + whereas the ``queryHash`` value would not change. - For more information on ``queryHash`` and ``planCacheKey``, - see :ref:`query-hash-plan-cache-key`. + For more information on ``queryHash`` and ``planCacheKey``, + see :ref:`query-hash-plan-cache-key`. - .. versionadded:: 4.2 + .. versionadded:: 4.2 - .. data:: explain.queryPlanner.optimizedPipeline + .. data:: explain.queryPlanner.optimizedPipeline - A boolean that indicates that the entire aggregation pipeline - operation was optimized away, and instead, fulfilled by a tree - of query plan execution stages. + A boolean that indicates that the entire aggregation pipeline + operation was optimized away, and instead, fulfilled by a tree + of query plan execution stages. - For example, starting in MongodB 4.2, the following - aggregation operation can be fulfilled by the tree of query - plan execution rather than using the aggregation pipeline. - - .. code-block:: javascript + For example, starting in MongodB 4.2, the following + aggregation operation can be fulfilled by the tree of query + plan execution rather than using the aggregation pipeline. + + .. code-block:: javascript - db.example.aggregate([ { $match: { someFlag: true } } ] ) + db.example.aggregate([ { $match: { someFlag: true } } ] ) - The field is only present if the value is ``true`` and only - applies to explain on aggregation pipeline operations. When - ``true``, because the pipeline was optimized away, no - aggregation stage information appears in the output. + The field is only present if the value is ``true`` and only + applies to explain on aggregation pipeline operations. When + ``true``, because the pipeline was optimized away, no + aggregation stage information appears in the output. - .. versionadded:: 4.2 + .. versionadded:: 4.2 - .. data:: explain.queryPlanner.winningPlan + .. data:: explain.queryPlanner.winningPlan - A document that details the plan selected by the :doc:`query - optimizer `. MongoDB presents the plan as a - tree of stages; i.e. a stage can have an - :data:`~explain.queryPlanner.winningPlan.inputStage` or, if the - stage has multiple child stages, - :data:`~explain.queryPlanner.winningPlan.inputStages`. + A document that details the plan selected by the :doc:`query + optimizer `. MongoDB presents the plan as a + tree of stages; i.e. a stage can have an + :data:`~explain.queryPlanner.winningPlan.inputStage` or, if the + stage has multiple child stages, + :data:`~explain.queryPlanner.winningPlan.inputStages`. - .. data:: explain.queryPlanner.winningPlan.stage + .. data:: explain.queryPlanner.winningPlan.stage - A string that denotes the name of the stage. + A string that denotes the name of the stage. - Each stage consists of information specific to the stage. For - instance, an ``IXSCAN`` stage will include the index bounds - along with other data specific to the index scan. If a stage - has a child stage or multiple child stages, the stage will have an - inputStage or inputStages. + Each stage consists of information specific to the stage. For + instance, an ``IXSCAN`` stage will include the index bounds + along with other data specific to the index scan. If a stage + has a child stage or multiple child stages, the stage will have an + inputStage or inputStages. - .. data:: explain.queryPlanner.winningPlan.inputStage + .. data:: explain.queryPlanner.winningPlan.inputStage - A document that describes the child stage, which provides the - documents or index keys to its parent. The field is present - *if* the parent stage has only one child. + A document that describes the child stage, which provides the + documents or index keys to its parent. The field is present + *if* the parent stage has only one child. - .. data:: explain.queryPlanner.winningPlan.inputStages + .. data:: explain.queryPlanner.winningPlan.inputStages - An array of documents describing the child stages. Child - stages provide the documents or index keys to the parent - stage. The field is present *if* the parent stage has multiple - child nodes. For example, stages for :ref:`$or expressions - ` or :ref:`index intersection - ` consume input from - multiple sources. + An array of documents describing the child stages. Child + stages provide the documents or index keys to the parent + stage. The field is present *if* the parent stage has multiple + child nodes. For example, stages for :ref:`$or expressions + ` or :ref:`index intersection + ` consume input from + multiple sources. - .. data:: explain.queryPlanner.rejectedPlans + .. data:: explain.queryPlanner.rejectedPlans - Array of candidate plans considered and rejected by the - query optimizer. The array can be empty if there were no other - candidate plans. + Array of candidate plans considered and rejected by the + query optimizer. The array can be empty if there were no other + candidate plans. .. _executionStats: ``executionStats`` ~~~~~~~~~~~~~~~~~~ -.. container:: - - The returned :data:`~explain.executionStats` information details the - execution of the winning plan. In order to include - ``executionStats`` in the results, you must run the explain in either: +The returned :data:`~explain.executionStats` information details the +execution of the winning plan. In order to include +``executionStats`` in the results, you must run the explain in either: - - :ref:`executionStats ` or +- :ref:`executionStats ` or - - :ref:`allPlansExecution ` - verbosity mode. Use ``allPlansExecution`` mode to include partial - execution data captured during :ref:`plan selection - `. +- :ref:`allPlansExecution ` + verbosity mode. Use ``allPlansExecution`` mode to include partial + execution data captured during :ref:`plan selection + `. - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: unsharded - name: "Unsharded Collections" - content: | + - id: unsharded + name: "Unsharded Collections" + content: | - For unsharded collections, ``explain`` returns the following - ``executionStats`` information: + For unsharded collections, ``explain`` returns the following + ``executionStats`` information: - .. code-block:: none + .. code-block:: none - "executionStats" : { - "executionSuccess" : , + "executionStats" : { + "executionSuccess" : , + "nReturned" : , + "executionTimeMillis" : , + "totalKeysExamined" : , + "totalDocsExamined" : , + "executionStages" : { + "stage" : "nReturned" : , - "executionTimeMillis" : , - "totalKeysExamined" : , - "totalDocsExamined" : , - "executionStages" : { - "stage" : + "executionTimeMillisEstimate" : , + "works" : , + "advanced" : , + "needTime" : , + "needYield" : , + "saveState" : , + "restoreState" : , + "isEOF" : , + ... + "inputStage" : { + "stage" : , "nReturned" : , "executionTimeMillisEstimate" : , - "works" : , - "advanced" : , - "needTime" : , - "needYield" : , - "saveState" : , - "restoreState" : , - "isEOF" : , ... "inputStage" : { - "stage" : , + ... + } + } + }, + "allPlansExecution" : [ + { + "nReturned" : , + "executionTimeMillisEstimate" : , + "totalKeysExamined" : , + "totalDocsExamined" :, + "executionStages" : { + "stage" : , "nReturned" : , "executionTimeMillisEstimate" : , ... "inputStage" : { + "stage" : , ... + "inputStage" : { + ... + } } } }, - "allPlansExecution" : [ + ... + ] + } + + - id: sharded + name: "Sharded Collections" + content: | + + For sharded collections, ``explain`` includes the execution + statistics for each accessed shard. + + .. code-block:: javascript + + "executionStats" : { + "nReturned" : , + "executionTimeMillis" : , + "totalKeysExamined" : , + "totalDocsExamined" : , + "executionStages" : { + "stage" : + "nReturned" : , + "executionTimeMillis" : , + "totalKeysExamined" : , + "totalDocsExamined" : , + "totalChildMillis" : , + "shards" : [ { - "nReturned" : , - "executionTimeMillisEstimate" : , - "totalKeysExamined" : , - "totalDocsExamined" :, + "shardName" : , + "executionSuccess" : , "executionStages" : { - "stage" : , + "stage" : , "nReturned" : , "executionTimeMillisEstimate" : , ... + "chunkSkips" : , "inputStage" : { - "stage" : , + "stage" : , ... "inputStage" : { - ... + ... } } } @@ -358,322 +398,275 @@ the ``explain`` operation. ... ] } - - - id: sharded - name: "Sharded Collections" - content: | - - For sharded collections, ``explain`` includes the execution - statistics for each accessed shard. - - .. code-block:: javascript - - "executionStats" : { - "nReturned" : , - "executionTimeMillis" : , - "totalKeysExamined" : , - "totalDocsExamined" : , - "executionStages" : { - "stage" : - "nReturned" : , - "executionTimeMillis" : , - "totalKeysExamined" : , - "totalDocsExamined" : , - "totalChildMillis" : , - "shards" : [ + "allPlansExecution" : [ + { + "shardName" : , + "allPlans" : [ { - "shardName" : , - "executionSuccess" : , + "nReturned" : , + "executionTimeMillisEstimate" : , + "totalKeysExamined" : , + "totalDocsExamined" :, "executionStages" : { - "stage" : , + "stage" : , "nReturned" : , "executionTimeMillisEstimate" : , ... - "chunkSkips" : , "inputStage" : { - "stage" : , + "stage" : , ... "inputStage" : { - ... + ... } } } }, ... ] - } - "allPlansExecution" : [ - { - "shardName" : , - "allPlans" : [ - { - "nReturned" : , - "executionTimeMillisEstimate" : , - "totalKeysExamined" : , - "totalDocsExamined" :, - "executionStages" : { - "stage" : , - "nReturned" : , - "executionTimeMillisEstimate" : , - ... - "inputStage" : { - "stage" : , - ... - "inputStage" : { - ... - } - } - } - }, - ... - ] - }, - { - "shardName" : , - "allPlans" : [ - ... - ] - }, - ... - ] - } + }, + { + "shardName" : , + "allPlans" : [ + ... + ] + }, + ... + ] + } - .. data:: explain.executionStats +.. data:: explain.executionStats - Contains statistics that describe the completed query execution for - the winning plan. For write operations, completed query execution - refers to the modifications that *would* be performed, but does - *not* apply the modifications to the database. + Contains statistics that describe the completed query execution for + the winning plan. For write operations, completed query execution + refers to the modifications that *would* be performed, but does + *not* apply the modifications to the database. - .. data:: explain.executionStats.nReturned + .. data:: explain.executionStats.nReturned - Number of documents that match the query condition. - :data:`~explain.nReturned` corresponds to the ``n`` field - returned by ``cursor.explain()`` in earlier versions of MongoDB. + Number of documents that match the query condition. + :data:`~explain.executionStats.nReturned` corresponds to the ``n`` field + returned by ``cursor.explain()`` in earlier versions of MongoDB. - .. data:: explain.executionStats.executionTimeMillis + .. data:: explain.executionStats.executionTimeMillis - Total time in milliseconds required for query plan selection and - query execution. :data:`~explain.executionTimeMillis` corresponds - to the ``millis`` field returned by ``cursor.explain()`` in - earlier versions of MongoDB. + Total time in milliseconds required for query plan selection and + query execution. :data:`~explain.executionStats.executionTimeMillis` corresponds + to the ``millis`` field returned by ``cursor.explain()`` in + earlier versions of MongoDB. - .. data:: explain.executionStats.totalKeysExamined + .. data:: explain.executionStats.totalKeysExamined - Number of index entries scanned. - :data:`~explain.executionStats.totalKeysExamined` corresponds to the - ``nscanned`` field returned by ``cursor.explain()`` in - earlier versions of MongoDB. + Number of index entries scanned. + :data:`~explain.executionStats.totalKeysExamined` corresponds to the + ``nscanned`` field returned by ``cursor.explain()`` in + earlier versions of MongoDB. - .. data:: explain.executionStats.totalDocsExamined + .. data:: explain.executionStats.totalDocsExamined - Number of documents examined during query execution. Common - query execution stages that examine documents are ``COLLSCAN`` - and ``FETCH``. + Number of documents examined during query execution. Common + query execution stages that examine documents are ``COLLSCAN`` + and ``FETCH``. - .. note:: + .. note:: - :data:`~explain.executionStats.totalDocsExamined` refers to - the total number of documents examined and *not* to the - number of documents returned. For example, a stage can - examine a document in order to apply a filter. If the - document is filtered out, then it has been examined but - will not be returned as part of the query result set. + :data:`~explain.executionStats.totalDocsExamined` refers to + the total number of documents examined and *not* to the + number of documents returned. For example, a stage can + examine a document in order to apply a filter. If the + document is filtered out, then it has been examined but + will not be returned as part of the query result set. - If a document is examined multiple times during query - execution, - :data:`~explain.executionStats.totalDocsExamined` counts - each examination. That is, - :data:`~explain.executionStats.totalDocsExamined` is *not* a - count of the total number of *unique* documents examined. + If a document is examined multiple times during query + execution, + :data:`~explain.executionStats.totalDocsExamined` counts + each examination. That is, + :data:`~explain.executionStats.totalDocsExamined` is *not* a + count of the total number of *unique* documents examined. - .. data:: explain.executionStats.executionStages + .. data:: explain.executionStats.executionStages - Details the completed execution of the winning plan as a tree of - stages; i.e. a stage can have an ``inputStage`` or multiple - ``inputStages``. + Details the completed execution of the winning plan as a tree of + stages; i.e. a stage can have an ``inputStage`` or multiple + ``inputStages``. - Each stage consists of execution information specific to the - stage. + Each stage consists of execution information specific to the + stage. - .. data:: explain.executionStats.executionStages.executionTimeMillisEstimate + .. data:: explain.executionStats.executionStages.executionTimeMillisEstimate - The estimated amount of time in milliseconds for query execution. + The estimated amount of time in milliseconds for query execution. - .. data:: explain.executionStats.executionStages.works + .. data:: explain.executionStats.executionStages.works - Specifies the number of "work units" performed by the query - execution stage. Query execution divides its work into small - units. A "work unit" might consist of examining a single index key, - fetching a single document from the collection, applying a - projection to a single document, or doing a piece of internal - bookkeeping. + Specifies the number of "work units" performed by the query + execution stage. Query execution divides its work into small + units. A "work unit" might consist of examining a single index key, + fetching a single document from the collection, applying a + projection to a single document, or doing a piece of internal + bookkeeping. - .. data:: explain.executionStats.executionStages.advanced + .. data:: explain.executionStats.executionStages.advanced - The number of intermediate results returned, or *advanced*, by - this stage to its parent stage. + The number of intermediate results returned, or *advanced*, by + this stage to its parent stage. - .. data:: explain.executionStats.executionStages.needTime + .. data:: explain.executionStats.executionStages.needTime - The number of work cycles that did not advance an intermediate - result to its parent stage (see - :data:`explain.executionStats.executionStages.advanced`). For - instance, an index scan stage may spend a work cycle seeking to a - new position in the index as opposed to returning an index - key; this work cycle would count towards - :data:`explain.executionStats.executionStages.needTime` rather - than :data:`explain.executionStats.executionStages.advanced`. + The number of work cycles that did not advance an intermediate + result to its parent stage (see + :data:`explain.executionStats.executionStages.advanced`). For + instance, an index scan stage may spend a work cycle seeking to a + new position in the index as opposed to returning an index + key; this work cycle would count towards + :data:`explain.executionStats.executionStages.needTime` rather + than :data:`explain.executionStats.executionStages.advanced`. - .. data:: explain.executionStats.executionStages.needYield + .. data:: explain.executionStats.executionStages.needYield - The number of times that the storage layer requested that the - query stage suspend processing and yield its locks. + The number of times that the storage layer requested that the + query stage suspend processing and yield its locks. - .. data:: explain.executionStats.executionStages.saveState + .. data:: explain.executionStats.executionStages.saveState - The number of times that the query stage suspended processing - and saved its current execution state, for example in - preparation for yielding its locks. + The number of times that the query stage suspended processing + and saved its current execution state, for example in + preparation for yielding its locks. - .. data:: explain.executionStats.executionStages.restoreState + .. data:: explain.executionStats.executionStages.restoreState - The number of times that the query stage restored a saved - execution state, for example after recovering locks that it had - previously yielded. + The number of times that the query stage restored a saved + execution state, for example after recovering locks that it had + previously yielded. - .. data:: explain.executionStats.executionStages.isEOF + .. data:: explain.executionStats.executionStages.isEOF - Specifies whether the execution stage has reached end of stream: + Specifies whether the execution stage has reached end of stream: - - If ``true`` or ``1``, the execution stage has reached - end-of-stream. + - If ``true`` or ``1``, the execution stage has reached + end-of-stream. - - If ``false`` or ``0``, the stage may still have results to - return. For example, consider a query with a limit whose - execution stages consists of a ``LIMIT`` stage with an - input stage of ``IXSCAN`` for the query. If the query - returns more than the specified limit, the ``LIMIT`` stage - will report ``isEOF: 1``, but its underlying ``IXSCAN`` stage - will report ``isEOF: 0``. + - If ``false`` or ``0``, the stage may still have results to + return. For example, consider a query with a limit whose + execution stages consists of a ``LIMIT`` stage with an + input stage of ``IXSCAN`` for the query. If the query + returns more than the specified limit, the ``LIMIT`` stage + will report ``isEOF: 1``, but its underlying ``IXSCAN`` stage + will report ``isEOF: 0``. - .. data:: explain.executionStats.executionStages.inputStage.keysExamined + .. data:: explain.executionStats.executionStages.inputStage.keysExamined - For query execution stages that scan an index (e.g. IXSCAN), - ``keysExamined`` is the total number of in-bounds and out-of-bounds - keys that are examined in the process of the index scan. If the - index scan consists of a single contiguous range of keys, only - in-bounds keys need to be examined. If the index bounds consists of - several key ranges, the index scan execution process may examine - out-of-bounds keys in order to skip from the end of one range to the - beginning of the next. + For query execution stages that scan an index (e.g. IXSCAN), + ``keysExamined`` is the total number of in-bounds and out-of-bounds + keys that are examined in the process of the index scan. If the + index scan consists of a single contiguous range of keys, only + in-bounds keys need to be examined. If the index bounds consists of + several key ranges, the index scan execution process may examine + out-of-bounds keys in order to skip from the end of one range to the + beginning of the next. - Consider the following example, where there is an index of field - ``x`` and the collection contains 100 documents with ``x`` values - 1 through 100: + Consider the following example, where there is an index of field + ``x`` and the collection contains 100 documents with ``x`` values + 1 through 100: - .. code-block:: javascript + .. code-block:: javascript - db.keys.find( { x : { $in : [ 3, 4, 50, 74, 75, 90 ] } } ).explain( "executionStats" ) + db.keys.find( { x : { $in : [ 3, 4, 50, 74, 75, 90 ] } } ).explain( "executionStats" ) - The query will scan keys ``3`` and ``4``. It will then scan the key - ``5``, detect that it is out-of-bounds, and skip to the next key - ``50``. + The query will scan keys ``3`` and ``4``. It will then scan the key + ``5``, detect that it is out-of-bounds, and skip to the next key + ``50``. - Continuing this process, the query scans keys - 3, 4, 5, 50, 51, 74, 75, 76, 90, and 91. Keys - ``5``, ``51``, ``76``, and ``91`` are out-of-bounds keys that are - still examined. The value of ``keysExamined`` is 10. + Continuing this process, the query scans keys + 3, 4, 5, 50, 51, 74, 75, 76, 90, and 91. Keys + ``5``, ``51``, ``76``, and ``91`` are out-of-bounds keys that are + still examined. The value of ``keysExamined`` is 10. - .. data:: explain.executionStats.executionStages.inputStage.docsExamined + .. data:: explain.executionStats.executionStages.inputStage.docsExamined - Specifies the number of documents scanned during the - query execution stage. + Specifies the number of documents scanned during the + query execution stage. - Present for the ``COLLSCAN`` stage, as well as for stages that - retrieve documents from the collection (e.g. ``FETCH``) + Present for the ``COLLSCAN`` stage, as well as for stages that + retrieve documents from the collection (e.g. ``FETCH``) - .. data:: explain.executionStats.executionStages.inputStage.seeks + .. data:: explain.executionStats.executionStages.inputStage.seeks - .. versionadded:: 3.4 + .. versionadded:: 3.4 - For index scan (``IXSCAN``) stages only. + For index scan (``IXSCAN``) stages only. - The number of times that we had to seek the index cursor to - a new position in order to complete the index scan. + The number of times that we had to seek the index cursor to + a new position in order to complete the index scan. - .. data:: explain.executionStats.allPlansExecution + .. data:: explain.executionStats.allPlansExecution - Contains *partial* execution information captured during the - :ref:`plan selection phase ` for - both the winning and rejected plans. The field is present only if - ``explain`` runs in ``allPlansExecution`` verbosity mode. + Contains *partial* execution information captured during the + :ref:`plan selection phase ` for + both the winning and rejected plans. The field is present only if + ``explain`` runs in ``allPlansExecution`` verbosity mode. .. _serverInfo: ``serverInfo`` ~~~~~~~~~~~~~~ -.. container:: - - .. tabs:: - - tabs: - - - id: unsharded - name: "Unsharded Collections" - content: | - - For unsharded collections, ``explain`` returns the following - ``serverInfo`` information for the MongoDB instance: - - .. code-block:: none - - "serverInfo" : { - "host" : , - "port" : , - "version" : , - "gitVersion" : - } - - - id: sharded - name: "Sharded Collections" - content: | - - For sharded collections, ``explain`` returns the - ``serverInfo`` for each accessed shard, and a top-level - ``serverInfo`` object for the :binary:`~bin.mongos`. - - .. code-block:: none - - "queryPlanner" : { - ... - "winningPlan" : { - "stage" : , - "shards" : [ - { - "shardName" : , - "connectionString" : , - "serverInfo" : { - "host" : , - "port" : , - "version" : , - "gitVersion" : - }, - ... - } +.. tabs:: + + tabs: + + - id: unsharded + name: "Unsharded Collections" + content: | + + For unsharded collections, ``explain`` returns the following + ``serverInfo`` information for the MongoDB instance: + + .. code-block:: none + + "serverInfo" : { + "host" : , + "port" : , + "version" : , + "gitVersion" : + } + + - id: sharded + name: "Sharded Collections" + content: | + + For sharded collections, ``explain`` returns the + ``serverInfo`` for each accessed shard, and a top-level + ``serverInfo`` object for the :binary:`~bin.mongos`. + + .. code-block:: none + + "queryPlanner" : { + ... + "winningPlan" : { + "stage" : , + "shards" : [ + { + "shardName" : , + "connectionString" : , + "serverInfo" : { + "host" : , + "port" : , + "version" : , + "gitVersion" : + }, ... - ] - } - }, - "serverInfo" : { // serverInfo for mongos - "host" : , - "port" : , - "version" : , - "gitVersion" : - } - ... - + } + ... + ] + } + }, + "serverInfo" : { // serverInfo for mongos + "host" : , + "port" : , + "version" : , + "gitVersion" : + } + ... 3.0 Format Change ----------------- @@ -716,7 +709,8 @@ return the results. When an index covers a query, the explain result has an ``IXSCAN`` stage that is **not** a descendant of a ``FETCH`` stage, and in the -:ref:`executionStats`, the :data:`~explain.totalDocsExamined` is ``0``. +:ref:`executionStats`, the :data:`~explain.executionStats.totalDocsExamined` +is ``0``. In earlier versions of MongoDB, ``cursor.explain()`` returned the ``indexOnly`` field to indicate whether the index covered a query. @@ -758,7 +752,7 @@ intersections. If MongoDB uses indexes for an :query:`$or` expression, the result will include the ``OR`` stage with an -:data:`~explain.winningPlan.inputStages` array that +:data:`~explain.queryPlanner.winningPlan.inputStages` array that details the indexes; e.g.: .. code-block:: javascript diff --git a/source/reference/glossary.txt b/source/reference/glossary.txt index 24732f449a5..4d8b858c442 100644 --- a/source/reference/glossary.txt +++ b/source/reference/glossary.txt @@ -214,7 +214,7 @@ Glossary data partition A distributed system architecture that splits data into ranges. - :term:`Sharding` uses partitioning. See + :term:`Sharding ` uses partitioning. See :ref:`sharding-data-partitioning`. data-center awareness @@ -271,7 +271,7 @@ Glossary driver A client library for interacting with MongoDB in a particular - language. See :ecosystem:`/drivers`. + language. See :driver:`driver `. durable A write operation is durable when it will persist across a @@ -671,8 +671,7 @@ Glossary MongoDB allocates space for each :term:`document`, in an effort to maximize storage reuse and to reduce fragmentation. This is the default for :doc:`TTL Collections `. See - :doc:`/reference/command/collMod` and - :collflag:`usePowerOf2Sizes`. + :doc:`/reference/command/collMod`. prefix compression Reduces memory and disk consumption by storing any identical index diff --git a/source/reference/limits.txt b/source/reference/limits.txt index 5a104b636d1..29778e9572f 100644 --- a/source/reference/limits.txt +++ b/source/reference/limits.txt @@ -105,7 +105,9 @@ Namespaces .. include:: /includes/fact-collection-namespace-limit.rst - .. seealso:: :ref:`faq-restrictions-on-collection-names` + .. seealso:: + + :ref:`faq-restrictions-on-collection-names` @@ -118,8 +120,8 @@ Indexes .. limit:: Index Key Limit - .. admonition:: Changed in version 4.2 - :class: note + .. note:: Changed in version 4.2 + Starting in version 4.2, MongoDB removes the :limit:`Index Key Limit` for :ref:`featureCompatibilityVersion ` (fCV) @@ -142,11 +144,11 @@ Indexes .. _limit-index-name-length: .. limit:: Index Name Length - .. admonition:: Changed in version 4.2 - :class: note + .. note:: Changed in version 4.2 + - Starting in version 4.2, MongoDB removes the :limit:`Index Name Length - Limit` for MongoDB versions with + Starting in version 4.2, MongoDB removes the + :limit:`Index Name Length` limit for MongoDB versions with :ref:`featureCompatibilityVersion ` (fCV) set to ``"4.2"`` or greater. @@ -177,7 +179,10 @@ Indexes .. include:: /includes/geo-data-limit-for-2dsphere.rst -.. seealso:: The unique indexes limit in :ref:`limits-sharding-operations`. +.. seealso:: + + The unique indexes limit in :ref:`limits-sharding-operations`. + .. limit:: NaN values returned from Covered Queries by the WiredTiger Storage Engine are always of type double @@ -317,8 +322,8 @@ Shard Key Limitations .. limit:: Shard Key Selection is Immutable in MongoDB 4.2 and Earlier - .. admonition:: Changed in Version 4.4 - :class: note + .. note:: Changed in Version 4.4 + Starting in MongoDB 4.4, you can refine a collection's shard key by adding a suffix field or fields to the existing key. See @@ -489,7 +494,7 @@ Sessions For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit - session using :method:`Session.startSession()` and periodically + session using :method:`Mongo.startSession()` and periodically refresh the session using the :dbcommand:`refreshSessions` command. For example: @@ -522,8 +527,8 @@ Sessions minutes. Since the session will never exceed the 30 minute idle timeout, the cursor can remain open indefinitely. - For MongoDB drivers, defer to the :ecosystem:`driver documentation - ` for instructions and syntax for creating sessions. + For MongoDB drivers, defer to the :driver:`driver documentation + ` for instructions and syntax for creating sessions. Shell ----- diff --git a/source/reference/local-database.txt b/source/reference/local-database.txt index 1331a6de762..fd2f81764ac 100644 --- a/source/reference/local-database.txt +++ b/source/reference/local-database.txt @@ -12,10 +12,10 @@ The ``local`` Database :depth: 1 :class: singlecol -.. index:: replica set; local database -.. index:: local database -.. index:: database; local -.. index:: namespace; local + + + + Overview -------- diff --git a/source/reference/map-reduce-to-aggregation-pipeline.txt b/source/reference/map-reduce-to-aggregation-pipeline.txt index c5f72e37cfd..a168711d764 100644 --- a/source/reference/map-reduce-to-aggregation-pipeline.txt +++ b/source/reference/map-reduce-to-aggregation-pipeline.txt @@ -49,18 +49,6 @@ shows an approximate translation of ``mapFunction`` using the - The ``emits`` field in :pipeline:`$project` may be named something else. For visual comparison, the field name ``emits`` was chosen. -.. role:: red(strong) - :class: text-danger - -.. role:: orange(strong) - :class: text-warning - -.. role:: green(strong) - :class: text-success - -.. role:: blue(strong) - :class: text-info - .. list-table:: :class: border-table :widths: 45 55 @@ -70,14 +58,14 @@ shows an approximate translation of ``mapFunction`` using the - Aggregation Pipeline * - | db.collection.mapReduce( - | :red:``, - | :orange:``, + | :highlight-red:``, + | :highlight-yellow:``, | { | query: , | sort: , | limit: , - | finalize: :green:``, - | out: :blue:`` + | finalize: :highlight-green:``, + | out: :highlight-blue:`` | } | ) @@ -85,30 +73,30 @@ shows an approximate translation of ``mapFunction`` using the | { $match: }, | { $sort: }, | { $limit: }, - | { :red:`$project: { emits: { k: , v: } }` }, - | { :red:`$unwind: "$emits"` }, - | { :orange:`$group`: { + | { :highlight-red:`$project: { emits: { k: , v: } }` }, + | { :highlight-red:`$unwind: "$emits"` }, + | { :highlight-yellow:`$group`: { | _id: "$emits.k"}, - | value: { :orange:`$accumulator`: { + | value: { :highlight-yellow:`$accumulator`: { | init: , - | accumulate: :orange:``, + | accumulate: :highlight-yellow:``, | accumulateArgs: [ "$emit.v"], - | merge: :orange:``, - | finalize: :green:``, + | merge: :highlight-yellow:``, + | finalize: :highlight-green:``, | lang: "js" }} | } }, - | { $out: :blue:`` } + | { $out: :highlight-blue:`` } | ] ) * - | db.collection.mapReduce( - | :red:``, - | :orange:``, + | :highlight-red:``, + | :highlight-yellow:``, | { | query: , | sort: , | limit: , - | finalize: :green:``, - | out: { :blue:`replace: , db:` } + | finalize: :highlight-green:``, + | out: { :highlight-blue:`replace: , db:` } | } | ) @@ -116,30 +104,30 @@ shows an approximate translation of ``mapFunction`` using the | { $match: }, | { $sort: }, | { $limit: }, - | { :red:`$project: { emits: { k: , v: } }` }, - | { :red:`$unwind: "$emits"` }, - | { :orange:`$group`: { + | { :highlight-red:`$project: { emits: { k: , v: } }` }, + | { :highlight-red:`$unwind: "$emits"` }, + | { :highlight-yellow:`$group`: { | _id: "$emits.k"}, - | value: { :orange:`$accumulator`: { + | value: { :highlight-yellow:`$accumulator`: { | init: , - | accumulate: :orange:``, + | accumulate: :highlight-yellow:``, | accumulateArgs: [ "$emit.v"], - | merge: :orange:``, - | finalize: :green:``, + | merge: :highlight-yellow:``, + | finalize: :highlight-green:``, | lang: "js" }} | } }, - | { $out: { :blue:`db: , coll: ` } } + | { $out: { :highlight-blue:`db: , coll: ` } } | ] ) * - | db.collection.mapReduce( - | :red:``, - | :orange:``, + | :highlight-red:``, + | :highlight-yellow:``, | { | query: , | sort: , | limit: , - | finalize: :green:``, - | out: { :blue:`merge: , db: ` } + | finalize: :highlight-green:``, + | out: { :highlight-blue:`merge: , db: ` } | } | ) @@ -147,20 +135,20 @@ shows an approximate translation of ``mapFunction`` using the | { $match: }, | { $sort: }, | { $limit: }, - | { :red:`$project: { emits: { k: , v: } }` }, - | { :red:`$unwind: "$emits"` }, - | { :orange:`$group`: { + | { :highlight-red:`$project: { emits: { k: , v: } }` }, + | { :highlight-red:`$unwind: "$emits"` }, + | { :highlight-yellow:`$group`: { | _id: "$emits.k"}, - | value: { :orange:`$accumulator`: { + | value: { :highlight-yellow:`$accumulator`: { | init: , - | accumulate: :orange:``, + | accumulate: :highlight-yellow:``, | accumulateArgs: [ "$emit.v"], - | merge: :orange:``, - | finalize: :green:``, + | merge: :highlight-yellow:``, + | finalize: :highlight-green:``, | lang: "js" }} | } }, - | { :blue:`$merge`: { - | into: { :blue:`db: , coll: `}, + | { :highlight-blue:`$merge`: { + | into: { :highlight-blue:`db: , coll: `}, | on: "_id" | whenMatched: "replace", | whenNotMatched: "insert" @@ -168,14 +156,14 @@ shows an approximate translation of ``mapFunction`` using the | ] ) * - | db.collection.mapReduce( - | :red:``, - | :orange:``, + | :highlight-red:``, + | :highlight-yellow:``, | { | query: , | sort: , | limit: , - | finalize: :green:``, - | out: { :blue:`reduce: , db: ` } + | finalize: :highlight-green:``, + | out: { :highlight-blue:`reduce: , db: ` } | } | ) @@ -183,25 +171,25 @@ shows an approximate translation of ``mapFunction`` using the | { $match: }, | { $sort: }, | { $limit: }, - | { :red:`$project: { emits: { k: , v: } }` }, - | { :red:`$unwind: "$emits"` }, - | { :orange:`$group`: { + | { :highlight-red:`$project: { emits: { k: , v: } }` }, + | { :highlight-red:`$unwind: "$emits"` }, + | { :highlight-yellow:`$group`: { | _id: "$emits.k"}, - | value: { :orange:`$accumulator`: { + | value: { :highlight-yellow:`$accumulator`: { | init: , - | accumulate: :orange:``, + | accumulate: :highlight-yellow:``, | accumulateArgs: [ "$emit.v"], - | merge: :orange:``, - | finalize: :green:``, + | merge: :highlight-yellow:``, + | finalize: :highlight-green:``, | lang: "js" }} | } }, - | { :blue:`$merge`: { - | into: { :blue:`db: , coll: ` }, + | { :highlight-blue:`$merge`: { + | into: { :highlight-blue:`db: , coll: ` }, | on: "_id" | whenMatched: [ | { $project: { | value: { $function: { - | body: :orange:``, + | body: :highlight-yellow:``, | args: [ | "$_id", | [ "$value", "$$new.value" ] @@ -215,13 +203,13 @@ shows an approximate translation of ``mapFunction`` using the | ] ) * - | db.collection.mapReduce( - | :red:``, - | :orange:``, + | :highlight-red:``, + | :highlight-yellow:``, | { | query: , | sort: , | limit: , - | finalize: :green:``, + | finalize: :highlight-green:``, | out: { inline: 1 } | } | ) @@ -230,16 +218,16 @@ shows an approximate translation of ``mapFunction`` using the | { $match: }, | { $sort: }, | { $limit: }, - | { :red:`$project: { emits: { k: , v: } }` }, - | { :red:`$unwind: "$emits"` }, - | { :orange:`$group`: { + | { :highlight-red:`$project: { emits: { k: , v: } }` }, + | { :highlight-red:`$unwind: "$emits"` }, + | { :highlight-yellow:`$group`: { | _id: "$emits.k"}, - | value: { :orange:`$accumulator`: { + | value: { :highlight-yellow:`$accumulator`: { | init: , - | accumulate: :orange:``, + | accumulate: :highlight-yellow:``, | accumulateArgs: [ "$emit.v"], - | merge: :orange:``, - | finalize: :green:``, + | merge: :highlight-yellow:``, + | finalize: :highlight-green:``, | lang: "js" }} | } } | ] ) @@ -260,260 +248,257 @@ examples provide both alternatives. Example 1 ~~~~~~~~~ -.. container:: +The following map-reduce operation on the ``orders`` collection groups +by the ``cust_id``, and calculates the sum of the ``price`` for each +``cust_id``: - The following map-reduce operation on the ``orders`` collection groups - by the ``cust_id``, and calculates the sum of the ``price`` for each - ``cust_id``: - - .. code-block:: javascript +.. code-block:: javascript - var mapFunction1 = function() { - emit(this.cust_id, this.price); - }; - - var reduceFunction1 = function(keyCustId, valuesPrices) { - return Array.sum(valuesPrices); - }; - - db.orders.mapReduce( - mapFunction1, - reduceFunction1, - { out: "map_reduce_example" } - ) + var mapFunction1 = function() { + emit(this.cust_id, this.price); + }; - **Alternative 1: (Recommended)** You can rewrite the operation into - an aggregation pipeline without translating the map-reduce function - to equivalent pipeline stages: + var reduceFunction1 = function(keyCustId, valuesPrices) { + return Array.sum(valuesPrices); + }; - .. code-block:: javascript + db.orders.mapReduce( + mapFunction1, + reduceFunction1, + { out: "map_reduce_example" } + ) + +**Alternative 1: (Recommended)** You can rewrite the operation into +an aggregation pipeline without translating the map-reduce function +to equivalent pipeline stages: + +.. code-block:: javascript - db.orders.aggregate([ - { $group: { _id: "$cust_id", value: { $sum: "$price" } } }, - { $out: "agg_alternative_1" } - ]) + db.orders.aggregate([ + { $group: { _id: "$cust_id", value: { $sum: "$price" } } }, + { $out: "agg_alternative_1" } + ]) - **Alternative 2: (For illustrative purposes only)** The - following aggregation pipeline provides a translation of the various - map-reduce functions, using :group:`$accumulator` to define custom - functions: +**Alternative 2: (For illustrative purposes only)** The +following aggregation pipeline provides a translation of the various +map-reduce functions, using :group:`$accumulator` to define custom +functions: + +.. code-block:: javascript + + db.orders.aggregate( [ + { $project: { emit: { key: "$cust_id", value: "$price" } } }, // equivalent to the map function + { $group: { // equivalent to the reduce function + _id: "$emit.key", + valuesPrices: { $accumulator: { + init: function() { return 0; }, + initArgs: [], + accumulate: function(state, value) { return state + value; }, + accumulateArgs: [ "$emit.value" ], + merge: function(state1, state2) { return state1 + state2; }, + lang: "js" + } } + } }, + { $out: "agg_alternative_2" } + ] ) + + +#. First, the :pipeline:`$project` stage outputs documents with an + ``emit`` field. The ``emit`` field is a document with the fields: + + - ``key`` that contains the ``cust_id`` value for the document + - ``value`` that contains the ``price`` value for the document .. code-block:: javascript + :copyable: false + + { "_id" : 1, "emit" : { "key" : "Ant O. Knee", "value" : 25 } } + { "_id" : 2, "emit" : { "key" : "Ant O. Knee", "value" : 70 } } + { "_id" : 3, "emit" : { "key" : "Busby Bee", "value" : 50 } } + { "_id" : 4, "emit" : { "key" : "Busby Bee", "value" : 25 } } + { "_id" : 5, "emit" : { "key" : "Busby Bee", "value" : 50 } } + { "_id" : 6, "emit" : { "key" : "Cam Elot", "value" : 35 } } + { "_id" : 7, "emit" : { "key" : "Cam Elot", "value" : 25 } } + { "_id" : 8, "emit" : { "key" : "Don Quis", "value" : 75 } } + { "_id" : 9, "emit" : { "key" : "Don Quis", "value" : 55 } } + { "_id" : 10, "emit" : { "key" : "Don Quis", "value" : 25 } } + +#. Then, the :pipeline:`$group` uses the :group:`$accumulator` + operator to add the emitted values: - db.orders.aggregate( [ - { $project: { emit: { key: "$cust_id", value: "$price" } } }, // equivalent to the map function - { $group: { // equivalent to the reduce function - _id: "$emit.key", - valuesPrices: { $accumulator: { - init: function() { return 0; }, - initArgs: [], - accumulate: function(state, value) { return state + value; }, - accumulateArgs: [ "$emit.value" ], - merge: function(state1, state2) { return state1 + state2; }, - lang: "js" - } } - } }, - { $out: "agg_alternative_2" } - ] ) + .. code-block:: javascript + :copyable: false + { "_id" : "Don Quis", "valuesPrices" : 155 } + { "_id" : "Cam Elot", "valuesPrices" : 60 } + { "_id" : "Ant O. Knee", "valuesPrices" : 95 } + { "_id" : "Busby Bee", "valuesPrices" : 125 } - #. First, the :pipeline:`$project` stage outputs documents with an - ``emit`` field. The ``emit`` field is a document with the fields: - - - ``key`` that contains the ``cust_id`` value for the document - - ``value`` that contains the ``price`` value for the document - - .. code-block:: javascript - :copyable: false - - { "_id" : 1, "emit" : { "key" : "Ant O. Knee", "value" : 25 } } - { "_id" : 2, "emit" : { "key" : "Ant O. Knee", "value" : 70 } } - { "_id" : 3, "emit" : { "key" : "Busby Bee", "value" : 50 } } - { "_id" : 4, "emit" : { "key" : "Busby Bee", "value" : 25 } } - { "_id" : 5, "emit" : { "key" : "Busby Bee", "value" : 50 } } - { "_id" : 6, "emit" : { "key" : "Cam Elot", "value" : 35 } } - { "_id" : 7, "emit" : { "key" : "Cam Elot", "value" : 25 } } - { "_id" : 8, "emit" : { "key" : "Don Quis", "value" : 75 } } - { "_id" : 9, "emit" : { "key" : "Don Quis", "value" : 55 } } - { "_id" : 10, "emit" : { "key" : "Don Quis", "value" : 25 } } - - #. Then, the :pipeline:`$group` uses the :expression:`$accumulator` - operator to add the emitted values: - - .. code-block:: javascript - :copyable: false - - { "_id" : "Don Quis", "valuesPrices" : 155 } - { "_id" : "Cam Elot", "valuesPrices" : 60 } - { "_id" : "Ant O. Knee", "valuesPrices" : 95 } - { "_id" : "Busby Bee", "valuesPrices" : 125 } - - #. Finally, the :pipeline:`$out` writes the output to the collection - ``agg_alternative_2``. Alternatively, you could use - :pipeline:`$merge` instead of :pipeline:`$out`. +#. Finally, the :pipeline:`$out` writes the output to the collection + ``agg_alternative_2``. Alternatively, you could use + :pipeline:`$merge` instead of :pipeline:`$out`. .. _mr-to-agg-examples2: Example 2 ~~~~~~~~~ -.. container:: +The following map-reduce operation on the ``orders`` collection +groups by the ``item.sku`` field and calculates the number of +orders and the total quantity ordered for each sku. The operation +then calculates the average quantity per order for each sku value +and merges the results into the output collection. - The following map-reduce operation on the ``orders`` collection - groups by the ``item.sku`` field and calculates the number of - orders and the total quantity ordered for each sku. The operation - then calculates the average quantity per order for each sku value - and merges the results into the output collection. - - .. code-block:: javascript - - var mapFunction2 = function() { - for (var idx = 0; idx < this.items.length; idx++) { - var key = this.items[idx].sku; - var value = { count: 1, qty: this.items[idx].qty }; - - emit(key, value); - } - }; - - var reduceFunction2 = function(keySKU, countObjVals) { - reducedVal = { count: 0, qty: 0 }; +.. code-block:: javascript - for (var idx = 0; idx < countObjVals.length; idx++) { - reducedVal.count += countObjVals[idx].count; - reducedVal.qty += countObjVals[idx].qty; - } + var mapFunction2 = function() { + for (var idx = 0; idx < this.items.length; idx++) { + var key = this.items[idx].sku; + var value = { count: 1, qty: this.items[idx].qty }; - return reducedVal; - }; - - var finalizeFunction2 = function (key, reducedVal) { - reducedVal.avg = reducedVal.qty/reducedVal.count; - return reducedVal; - }; - - db.orders.mapReduce( - mapFunction2, - reduceFunction2, - { - out: { merge: "map_reduce_example2" }, - query: { ord_date: { $gte: new Date("2020-03-01") } }, - finalize: finalizeFunction2 + emit(key, value); } - ); + }; + + var reduceFunction2 = function(keySKU, countObjVals) { + reducedVal = { count: 0, qty: 0 }; - **Alternative 1: (Recommended)** You can rewrite the operation into - an aggregation pipeline without translating the map-reduce function - to equivalent pipeline stages: + for (var idx = 0; idx < countObjVals.length; idx++) { + reducedVal.count += countObjVals[idx].count; + reducedVal.qty += countObjVals[idx].qty; + } - .. code-block:: javascript + return reducedVal; + }; + + var finalizeFunction2 = function (key, reducedVal) { + reducedVal.avg = reducedVal.qty/reducedVal.count; + return reducedVal; + }; - db.orders.aggregate( [ - { $match: { ord_date: { $gte: new Date("2020-03-01") } } }, + db.orders.mapReduce( + mapFunction2, + reduceFunction2, + { + out: { merge: "map_reduce_example2" }, + query: { ord_date: { $gte: new Date("2020-03-01") } }, + finalize: finalizeFunction2 + } + ); + +**Alternative 1: (Recommended)** You can rewrite the operation into +an aggregation pipeline without translating the map-reduce function +to equivalent pipeline stages: + +.. code-block:: javascript + + db.orders.aggregate( [ + { $match: { ord_date: { $gte: new Date("2020-03-01") } } }, + { $unwind: "$items" }, + { $group: { _id: "$items.sku", qty: { $sum: "$items.qty" }, orders_ids: { $addToSet: "$_id" } } }, + { $project: { value: { count: { $size: "$orders_ids" }, qty: "$qty", avg: { $divide: [ "$qty", { $size: "$orders_ids" } ] } } } }, + { $merge: { into: "agg_alternative_3", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } + ] ) + +**Alternative 2: (For illustrative purposes only)** The following +aggregation pipeline provides a translation of the various +map-reduce functions, using :group:`$accumulator` to define custom +functions: + +.. code-block:: javascript + + db.orders.aggregate( [ + { $match: { ord_date: {$gte: new Date("2020-03-01") } } }, { $unwind: "$items" }, - { $group: { _id: "$items.sku", qty: { $sum: "$items.qty" }, orders_ids: { $addToSet: "$_id" } } }, - { $project: { value: { count: { $size: "$orders_ids" }, qty: "$qty", avg: { $divide: [ "$qty", { $size: "$orders_ids" } ] } } } }, - { $merge: { into: "agg_alternative_3", on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } - ] ) + { $project: { emit: { key: "$items.sku", value: { count: { $literal: 1 }, qty: "$items.qty" } } } }, + { $group: { + _id: "$emit.key", + value: { $accumulator: { + init: function() { return { count: 0, qty: 0 }; }, + initArgs: [], + accumulate: function(state, value) { + state.count += value.count; + state.qty += value.qty; + return state; + }, + accumulateArgs: [ "$emit.value" ], + merge: function(state1, state2) { + return { count: state1.count + state2.count, qty: state1.qty + state2.qty }; + }, + finalize: function(state) { + state.avg = state.qty / state.count; + return state; + }, + lang: "js"} + } + } }, + { $merge: { + into: "agg_alternative_4", + on: "_id", + whenMatched: "replace", + whenNotMatched: "insert" + } } + ] ) + +#. The :pipeline:`$match` stage selects only those + documents with ``ord_date`` greater than or equal to ``new + Date("2020-03-01")``. + +#. The :pipeline:`$unwind` stage breaks down the document by + the ``items`` array field to output a document for each array + element. For example: + + .. code-block:: javascript + :copyable: false - **Alternative 2: (For illustrative purposes only)** The following - aggregation pipeline provides a translation of the various - map-reduce functions, using :group:`$accumulator` to define custom - functions: + { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 5, "price" : 2.5 }, "status" : "A" } + { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "apples", "qty" : 5, "price" : 2.5 }, "status" : "A" } + { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "oranges", "qty" : 8, "price" : 2.5 }, "status" : "A" } + { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } + { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "pears", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 4, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-18T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } + { "_id" : 5, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-19T00:00:00Z"), "price" : 50, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } + ... + +#. The :pipeline:`$project` stage outputs documents with an ``emit`` + field. The ``emit`` field is a document with the fields: + + - ``key`` that contains the ``items.sku`` value + - ``value`` that contains a document with the ``qty`` value and a ``count`` value .. code-block:: javascript + :copyable: false + + { "_id" : 1, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 5 } } } + { "_id" : 1, "emit" : { "key" : "apples", "value" : { "count" : 1, "qty" : 5 } } } + { "_id" : 2, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 8 } } } + { "_id" : 2, "emit" : { "key" : "chocolates", "value" : { "count" : 1, "qty" : 5 } } } + { "_id" : 3, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 10 } } } + { "_id" : 3, "emit" : { "key" : "pears", "value" : { "count" : 1, "qty" : 10 } } } + { "_id" : 4, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 10 } } } + { "_id" : 5, "emit" : { "key" : "chocolates", "value" : { "count" : 1, "qty" : 5 } } } + ... + +#. The :pipeline:`$group` uses the :group:`$accumulator` + operator to add the emitted ``count`` and ``qty`` and calculate the + ``avg`` field: - db.orders.aggregate( [ - { $match: { ord_date: {$gte: new Date("2020-03-01") } } }, - { $unwind: "$items" }, - { $project: { emit: { key: "$items.sku", value: { count: { $literal: 1 }, qty: "$items.qty" } } } }, - { $group: { - _id: "$emit.key", - value: { $accumulator: { - init: function() { return { count: 0, qty: 0 }; }, - initArgs: [], - accumulate: function(state, value) { - state.count += value.count; - state.qty += value.qty; - return state; - }, - accumulateArgs: [ "$emit.value" ], - merge: function(state1, state2) { - return { count: state1.count + state2.count, qty: state1.qty + state2.qty }; - }, - finalize: function(state) { - state.avg = state.qty / state.count; - return state; - }, - lang: "js"} - } - } }, - { $merge: { - into: "agg_alternative_4", - on: "_id", - whenMatched: "replace", - whenNotMatched: "insert" - } } - ] ) - - #. The :pipeline:`$match` stage selects only those - documents with ``ord_date`` greater than or equal to ``new - Date("2020-03-01")``. - - #. The :pipeline:`$unwinds` stage breaks down the document by - the ``items`` array field to output a document for each array - element. For example: - - .. code-block:: javascript - :copyable: false - - { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 5, "price" : 2.5 }, "status" : "A" } - { "_id" : 1, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-01T00:00:00Z"), "price" : 25, "items" : { "sku" : "apples", "qty" : 5, "price" : 2.5 }, "status" : "A" } - { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "oranges", "qty" : 8, "price" : 2.5 }, "status" : "A" } - { "_id" : 2, "cust_id" : "Ant O. Knee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 70, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } - { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } - { "_id" : 3, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-08T00:00:00Z"), "price" : 50, "items" : { "sku" : "pears", "qty" : 10, "price" : 2.5 }, "status" : "A" } - { "_id" : 4, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-18T00:00:00Z"), "price" : 25, "items" : { "sku" : "oranges", "qty" : 10, "price" : 2.5 }, "status" : "A" } - { "_id" : 5, "cust_id" : "Busby Bee", "ord_date" : ISODate("2020-03-19T00:00:00Z"), "price" : 50, "items" : { "sku" : "chocolates", "qty" : 5, "price" : 10 }, "status" : "A" } - ... - - #. The :pipeline:`$project` stage outputs documents with an ``emit`` - field. The ``emit`` field is a document with the fields: - - - ``key`` that contains the ``items.sku`` value - - ``value`` that contains a document with the ``qty`` value and a ``count`` value - - .. code-block:: javascript - :copyable: false - - { "_id" : 1, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 5 } } } - { "_id" : 1, "emit" : { "key" : "apples", "value" : { "count" : 1, "qty" : 5 } } } - { "_id" : 2, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 8 } } } - { "_id" : 2, "emit" : { "key" : "chocolates", "value" : { "count" : 1, "qty" : 5 } } } - { "_id" : 3, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 10 } } } - { "_id" : 3, "emit" : { "key" : "pears", "value" : { "count" : 1, "qty" : 10 } } } - { "_id" : 4, "emit" : { "key" : "oranges", "value" : { "count" : 1, "qty" : 10 } } } - { "_id" : 5, "emit" : { "key" : "chocolates", "value" : { "count" : 1, "qty" : 5 } } } - ... - - #. The :pipeline:`$group` uses the :expression:`$accumulator` - operator to add the emitted ``count`` and ``qty`` and calculate the - ``avg`` field: - - .. code-block:: javascript - :copyable: false - - { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } } - { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } } - { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } } - { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } } - { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } } - - #. Finally, the :pipeline:`$merge` writes the output to the - collection ``agg_alternative_4``. If an existing document has the same - key ``_id`` as the new result, the operation overwrites the existing - document. If there is no existing document with the same key, the - operation inserts the document. - + .. code-block:: javascript + :copyable: false + + { "_id" : "chocolates", "value" : { "count" : 3, "qty" : 15, "avg" : 5 } } + { "_id" : "oranges", "value" : { "count" : 7, "qty" : 63, "avg" : 9 } } + { "_id" : "carrots", "value" : { "count" : 2, "qty" : 15, "avg" : 7.5 } } + { "_id" : "apples", "value" : { "count" : 4, "qty" : 35, "avg" : 8.75 } } + { "_id" : "pears", "value" : { "count" : 1, "qty" : 10, "avg" : 10 } } + +#. Finally, the :pipeline:`$merge` writes the output to the + collection ``agg_alternative_4``. If an existing document has the same + key ``_id`` as the new result, the operation overwrites the existing + document. If there is no existing document with the same key, the + operation inserts the document. + +.. seealso:: -.. seealso:: :doc:`/reference/aggregation-commands-comparison` + :doc:`/reference/aggregation-commands-comparison` diff --git a/source/reference/method.txt b/source/reference/method.txt index 5861062fa67..c56bdc84bba 100644 --- a/source/reference/method.txt +++ b/source/reference/method.txt @@ -19,8 +19,6 @@ Collection ---------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -235,8 +233,6 @@ Collection Cursor ------ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -389,8 +385,6 @@ Cursor Database -------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -550,7 +544,7 @@ Database * - :method:`db.serverBuildInfo()` - - Returns a document that displays the compilation parameters for the :binary:`~bin.mongod` instance. Wraps :dbcommand:`buildinfo`. + - Returns a document that displays the compilation parameters for the :binary:`~bin.mongod` instance. Wraps :dbcommand:`buildInfo`. * - :method:`db.serverCmdLineOpts()` @@ -597,8 +591,6 @@ Database Query Plan Cache ---------------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -653,8 +645,6 @@ Query Plan Cache Bulk Write Operation -------------------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -747,8 +737,6 @@ Bulk Write Operation User Management --------------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -828,8 +816,6 @@ User Management Role Management --------------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -900,8 +886,6 @@ Role Management Replication ----------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -982,8 +966,6 @@ Replication Sharding -------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -1129,26 +1111,24 @@ Sharding Free Monitoring --------------- -.. only:: website - - .. list-table:: +.. list-table:: - * - Name + * - Name - - Description + - Description - * - :method:`db.enableFreeMonitoring()` + * - :method:`db.enableFreeMonitoring()` - - Enables free monitoring during runtime. + - Enables free monitoring during runtime. - * - :method:`db.disableFreeMonitoring()` + * - :method:`db.disableFreeMonitoring()` - - Disables free monitoring during runtime. + - Disables free monitoring during runtime. - * - :method:`db.getFreeMonitoringStatus()` + * - :method:`db.getFreeMonitoringStatus()` - - Returns the free monitoring status. + - Returns the free monitoring status. .. toctree:: :titlesonly: @@ -1159,8 +1139,6 @@ Free Monitoring Constructors ------------ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -1219,8 +1197,6 @@ Constructors Connection ---------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -1298,8 +1274,6 @@ Connection Native ------ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -1406,8 +1380,6 @@ Client-Side Field Level Encryption .. include:: /includes/extracts/csfle-requires-enabling-encryption.rst -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -1465,4 +1437,4 @@ Client-Side Field Level Encryption :titlesonly: :hidden: - /reference/method/js-client-side-field-level-encryption \ No newline at end of file + /reference/method/js-client-side-field-level-encryption diff --git a/source/reference/method/Bulk.execute.txt b/source/reference/method/Bulk.execute.txt index 3f9047976cc..2e8230339e5 100644 --- a/source/reference/method/Bulk.execute.txt +++ b/source/reference/method/Bulk.execute.txt @@ -86,7 +86,7 @@ Transactions .. include:: /includes/extracts/transactions-supported-operation.rst -For :method:`Bulk.find.insert()` operations, the collection must already exist. +For :method:`Bulk.insert()` operations, the collection must already exist. For :method:`Bulk.find.upsert()`, if the operation results in an upsert, the collection must already exist. @@ -165,5 +165,7 @@ The operation returns the following :method:`BulkWriteResult()` object: "upserted" : [ ] }) -.. see:: :method:`Bulk()` for a listing of methods available for bulk +.. see:: + + :method:`Bulk()` for a listing of methods available for bulk operations. diff --git a/source/reference/method/Bulk.getOperations.txt b/source/reference/method/Bulk.getOperations.txt index 309b38e41fd..a6ea9f4bcbb 100644 --- a/source/reference/method/Bulk.getOperations.txt +++ b/source/reference/method/Bulk.getOperations.txt @@ -115,4 +115,7 @@ The array contains documents with the following fields: Array of documents that contain the details of the operation. -.. seealso:: :method:`Bulk()` and :method:`Bulk.execute()`. +.. seealso:: + + :method:`Bulk()` and :method:`Bulk.execute()`. + diff --git a/source/reference/method/Bulk.toString.txt b/source/reference/method/Bulk.toString.txt index 97d1a3cb57b..59ec60f4794 100644 --- a/source/reference/method/Bulk.toString.txt +++ b/source/reference/method/Bulk.toString.txt @@ -22,16 +22,20 @@ The following initializes a :method:`Bulk()` operations builder on the ``items`` collection, adds a series of write operations, and calls :method:`Bulk.toString()` on the ``bulk`` builder object. - .. code-block:: javascript +.. code-block:: javascript - var bulk = db.items.initializeOrderedBulkOp(); - bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } ); - bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } ); - bulk.find( { status: "D" } ).removeOne(); - bulk.toString(); + var bulk = db.items.initializeOrderedBulkOp(); + bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } ); + bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } ); + bulk.find( { status: "D" } ).removeOne(); + bulk.toString(); The :method:`Bulk.toString()` returns the following JSON document +.. code-block:: javascript + { "nInsertOps" : 2, "nUpdateOps" : 0, "nRemoveOps" : 1, "nBatches" : 2 } -.. seealso:: :method:`Bulk()` +.. seealso:: + + :method:`Bulk()` diff --git a/source/reference/method/Bulk.tojson.txt b/source/reference/method/Bulk.tojson.txt index 930ec0ce841..800a9be08a7 100644 --- a/source/reference/method/Bulk.tojson.txt +++ b/source/reference/method/Bulk.tojson.txt @@ -22,16 +22,20 @@ The following initializes a :method:`Bulk()` operations builder on the ``items`` collection, adds a series of write operations, and calls :method:`Bulk.tojson()` on the ``bulk`` builder object. - .. code-block:: javascript +.. code-block:: javascript - var bulk = db.items.initializeOrderedBulkOp(); - bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } ); - bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } ); - bulk.find( { status: "D" } ).removeOne(); - bulk.tojson(); + var bulk = db.items.initializeOrderedBulkOp(); + bulk.insert( { item: "abc123", status: "A", defaultQty: 500, points: 5 } ); + bulk.insert( { item: "ijk123", status: "A", defaultQty: 100, points: 10 } ); + bulk.find( { status: "D" } ).removeOne(); + bulk.tojson(); The :method:`Bulk.tojson()` returns the following JSON document +.. code-block:: javascript + { "nInsertOps" : 2, "nUpdateOps" : 0, "nRemoveOps" : 1, "nBatches" : 2 } -.. seealso:: :method:`Bulk()` +.. seealso:: + + :method:`Bulk()` diff --git a/source/reference/method/Bulk.txt b/source/reference/method/Bulk.txt index 90bcfb6ab7e..f8dbf7b629d 100644 --- a/source/reference/method/Bulk.txt +++ b/source/reference/method/Bulk.txt @@ -67,7 +67,7 @@ Transactions .. include:: /includes/extracts/transactions-supported-operation.rst -For :method:`Bulk.find.insert()` operations, the collection must already exist. +For :method:`Bulk.insert()` operations, the collection must already exist. For :method:`Bulk.find.upsert()`, if the operation results in an upsert, the collection must already exist. diff --git a/source/reference/method/ClientEncryption.decrypt.txt b/source/reference/method/ClientEncryption.decrypt.txt index e34f7861ebc..a4a979c31dd 100644 --- a/source/reference/method/ClientEncryption.decrypt.txt +++ b/source/reference/method/ClientEncryption.decrypt.txt @@ -31,7 +31,7 @@ ClientEncryption.decrypt() `_ created using client-side field level encryption. -:returns: The decrypted value. + :returns: The decrypted value. Behavior -------- diff --git a/source/reference/method/ClientEncryption.encrypt.txt b/source/reference/method/ClientEncryption.encrypt.txt index 2c03f714cc3..57595b7d422 100644 --- a/source/reference/method/ClientEncryption.encrypt.txt +++ b/source/reference/method/ClientEncryption.encrypt.txt @@ -48,8 +48,8 @@ ClientEncryption.encrypt() - The data encryption key to use for encrypting the ``value``. The :abbr:`UUID (Universally unique identifier)` is a BSON - :bsontype:`binary data` object with subtype ``4`` that - identifies a specific data encryption key. If the data + :bsontype:`binary data ` object with subtype ``4`` + that identifies a specific data encryption key. If the data encryption key does not exist in the key vault configured for the database connection, :method:`~ClientEncryption.encrypt()` returns an error. See :ref:`field-level-encryption-keyvault` @@ -74,10 +74,10 @@ ClientEncryption.encrypt() For complete documentation on the supported encryption algorithms, see :ref:`field-level-encryption-algorithms`. -:returns: + :returns: - A :bsontype:`binary data ` object with - `subtype 6 `_. + A :bsontype:`binary data ` object with + `subtype 6 `_. Behavior -------- diff --git a/source/reference/method/Date.txt b/source/reference/method/Date.txt index 65ee8cebf97..df0d528aada 100644 --- a/source/reference/method/Date.txt +++ b/source/reference/method/Date.txt @@ -41,8 +41,8 @@ Date() datetime in UTC. - ``new Date()`` specifies the datetime as milliseconds - since the :term:`Unix epoch` (Jan 1, 1970), and returns the - resulting ``ISODate`` instance. + since the :term:`UNIX epoch ` (Jan 1, 1970), and + returns the resulting ``ISODate`` instance. Behavior -------- @@ -70,7 +70,9 @@ collection, the following operation inserts a document with the field { upsert: true } ) -.. seealso:: +.. seealso:: + + - :update:`$currentDate` diff --git a/source/reference/method/KeyVault.addKeyAlternateName.txt b/source/reference/method/KeyVault.addKeyAlternateName.txt index 1d46afde27f..6a3c17c962e 100644 --- a/source/reference/method/KeyVault.addKeyAlternateName.txt +++ b/source/reference/method/KeyVault.addKeyAlternateName.txt @@ -34,12 +34,12 @@ KeyVault.addKeyAlternateName() "keyAlternateName" ) -:returns: + :returns: - Returns the previous version of the data encryption key document. + Returns the previous version of the data encryption key document. - Returns ``null`` if no data encryption key has the specified - ``UUID()``. + Returns ``null`` if no data encryption key has the specified + ``UUID()``. Behavior -------- diff --git a/source/reference/method/KeyVault.createKey.txt b/source/reference/method/KeyVault.createKey.txt index 73aea02a48c..7971e9ab255 100644 --- a/source/reference/method/KeyVault.createKey.txt +++ b/source/reference/method/KeyVault.createKey.txt @@ -146,10 +146,10 @@ KeyVault.createKey() ` filter for only documents where ``keyAltNames`` exists. -:returns: + :returns: - The ``UUID`` unique identifier of the created data encryption - key. + The ``UUID`` unique identifier of the created data encryption + key. Behavior -------- @@ -170,7 +170,7 @@ client-side field level encryption. For specific examples of using .. include:: /includes/extracts/csfle-connection-boilerplate.rst -Retrieve the :method:`keyVault ` object and +Retrieve the :method:`keyVault ` object and use the :method:`KeyVault.createKey()` method to create a new data encryption key using the locally managed key: diff --git a/source/reference/method/KeyVault.deleteKey.txt b/source/reference/method/KeyVault.deleteKey.txt index f92673a9bbc..8ef0ce5f2a2 100644 --- a/source/reference/method/KeyVault.deleteKey.txt +++ b/source/reference/method/KeyVault.deleteKey.txt @@ -28,7 +28,7 @@ KeyVault.deleteKey() The :abbr:`UUID (Universally unique identifier)` is a BSON :bsontype:`binary data ` object with subtype ``4``. -:returns: A document indicating the number of deleted keys. + :returns: A document indicating the number of deleted keys. Behavior -------- diff --git a/source/reference/method/KeyVault.getKey.txt b/source/reference/method/KeyVault.getKey.txt index 990e40cf72a..1c6e62e39a0 100644 --- a/source/reference/method/KeyVault.getKey.txt +++ b/source/reference/method/KeyVault.getKey.txt @@ -29,12 +29,12 @@ KeyVault.getKey() The :abbr:`UUID (Universally unique identifier)` is a BSON :bsontype:`binary data ` object with subtype ``4``. -:returns: + :returns: - Document representing a matching data encryption key. + Document representing a matching data encryption key. - Returns nothing if no key in the key vault has the specified - ``UUID``. + Returns nothing if no key in the key vault has the specified + ``UUID``. Behavior -------- diff --git a/source/reference/method/KeyVault.getKeyByAltName.txt b/source/reference/method/KeyVault.getKeyByAltName.txt index c643ecd2394..3488d1c91d1 100644 --- a/source/reference/method/KeyVault.getKeyByAltName.txt +++ b/source/reference/method/KeyVault.getKeyByAltName.txt @@ -24,12 +24,12 @@ KeyVault.getKeyByAltName() keyVault.getKeyByAltName("keyAltName") -:returns: + :returns: - Document representing a matching data encryption key. + Document representing a matching data encryption key. - Returns nothing if no data encryption key has the specified - ``keyAltName``. + Returns nothing if no data encryption key has the specified + ``keyAltName``. Behavior -------- diff --git a/source/reference/method/KeyVault.getKeys.txt b/source/reference/method/KeyVault.getKeys.txt index c9080ce632d..b808f8a6ea3 100644 --- a/source/reference/method/KeyVault.getKeys.txt +++ b/source/reference/method/KeyVault.getKeys.txt @@ -25,11 +25,11 @@ KeyVault.getKeys() keyVault.getKeys() -:returns: + :returns: - Returns all data encryption keys associated to the key vault. + Returns all data encryption keys associated to the key vault. - Returns nothing if the key vault is empty. + Returns nothing if the key vault is empty. Behavior -------- diff --git a/source/reference/method/KeyVault.removeKeyAlternateName.txt b/source/reference/method/KeyVault.removeKeyAlternateName.txt index e71035e0ae2..c88e111f103 100644 --- a/source/reference/method/KeyVault.removeKeyAlternateName.txt +++ b/source/reference/method/KeyVault.removeKeyAlternateName.txt @@ -27,11 +27,11 @@ KeyVault.removeKeyAlternateName() "keyAltName" ) -:returns: - The data encryption key *prior* to updating the ``keyAltName``. + :returns: + The data encryption key *prior* to updating the ``keyAltName``. - Returns ``null`` if no data encryption key has the specified - ``UUID()``. + Returns ``null`` if no data encryption key has the specified + ``UUID()``. Behavior -------- diff --git a/source/reference/method/Mongo.getDB.txt b/source/reference/method/Mongo.getDB.txt index 8b9c2d711c9..d480e95b273 100644 --- a/source/reference/method/Mongo.getDB.txt +++ b/source/reference/method/Mongo.getDB.txt @@ -52,4 +52,6 @@ to ``"myDatabase"``: db = new Mongo().getDB("myDatabase"); -.. seealso:: :method:`Mongo()` and :doc:`/reference/method/connect` +.. seealso:: + + :method:`Mongo()` and :doc:`/reference/method/connect` diff --git a/source/reference/method/Mongo.getReadPrefMode.txt b/source/reference/method/Mongo.getReadPrefMode.txt index 9a68951b92c..2ef1bb4fb81 100644 --- a/source/reference/method/Mongo.getReadPrefMode.txt +++ b/source/reference/method/Mongo.getReadPrefMode.txt @@ -40,6 +40,8 @@ Mongo.getReadPrefMode() - :readmode:`secondaryPreferred` - :readmode:`nearest` - .. seealso:: :doc:`/core/read-preference`, + .. seealso:: + + :doc:`/core/read-preference`, :method:`~cursor.readPref()`, :method:`~Mongo.setReadPref()`, and :method:`~Mongo.getReadPrefTagSet()`. diff --git a/source/reference/method/Mongo.getReadPrefTagSet.txt b/source/reference/method/Mongo.getReadPrefTagSet.txt index f62dfa47c52..2ccd1f0e07f 100644 --- a/source/reference/method/Mongo.getReadPrefTagSet.txt +++ b/source/reference/method/Mongo.getReadPrefTagSet.txt @@ -31,6 +31,8 @@ Mongo.getReadPrefTagSet() printjson(db.getMongo().getReadPrefTagSet()); - .. seealso:: :doc:`/core/read-preference`, + .. seealso:: + + :doc:`/core/read-preference`, :method:`~cursor.readPref()`, :method:`~Mongo.setReadPref()`, and :method:`~Mongo.getReadPrefTagSet()`. diff --git a/source/reference/method/Mongo.setReadPref.txt b/source/reference/method/Mongo.setReadPref.txt index c98b2bbb33b..76318e07e37 100644 --- a/source/reference/method/Mongo.setReadPref.txt +++ b/source/reference/method/Mongo.setReadPref.txt @@ -149,7 +149,9 @@ members with the ``datacenter: "B"`` tag first. See :ref:`read-pref-order-matching` for details. -.. seealso:: :doc:`/tutorial/configure-replica-set-tag-sets` +.. seealso:: + + :doc:`/tutorial/configure-replica-set-tag-sets` Specify Hedged Read ~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/method/Mongo.startSession.txt b/source/reference/method/Mongo.startSession.txt index 4fdc9eb5d54..d4d06c2fc10 100644 --- a/source/reference/method/Mongo.startSession.txt +++ b/source/reference/method/Mongo.startSession.txt @@ -54,8 +54,8 @@ Definition - Document. Specifies the :ref:`read concern `. To modify the setting after starting a session, see - :method:`Sessions.getOptions().setReadConcern() - `. + :method:`Session.getOptions().setReadConcern() + `. * - readPreference @@ -69,8 +69,8 @@ Definition { mode: , tags: } To modify the setting after starting a session, see - :method:`Sessions.getOptions().setReadPreference() - `. + :method:`Session.getOptions().setReadPreference() + `. * - retryWrites @@ -89,8 +89,8 @@ Definition - Document. Specifies the :ref:`write concern `. To modify the setting after starting a session, see - :method:`Sessions.getOptions().setWriteConcern() - `. + :method:`Session.getOptions().setWriteConcern() + `. Examples -------- diff --git a/source/reference/method/Mongo.txt b/source/reference/method/Mongo.txt index b0b7e14c10f..0ed33790c0e 100644 --- a/source/reference/method/Mongo.txt +++ b/source/reference/method/Mongo.txt @@ -62,7 +62,10 @@ Description For documentation of usage and syntax, see :ref:`ClientSideFieldLevelEncryptionOptions`. -.. seealso:: :method:`Mongo.getDB()` and :method:`db.getMongo()`. +.. seealso:: + + :method:`Mongo.getDB()` and :method:`db.getMongo()`. + .. _ClientSideFieldLevelEncryptionOptions: diff --git a/source/reference/method/Mongo.watch.txt b/source/reference/method/Mongo.watch.txt index 34d46410ddb..8e547912320 100644 --- a/source/reference/method/Mongo.watch.txt +++ b/source/reference/method/Mongo.watch.txt @@ -190,7 +190,9 @@ Definition See :doc:`/reference/change-events` for examples of change event documents. - .. seealso:: :method:`db.collection.watch()` and :method:`db.watch()` + .. seealso:: + + :method:`db.collection.watch()` and :method:`db.watch()` Availability ------------ diff --git a/source/reference/method/ObjectId.getTimestamp.txt b/source/reference/method/ObjectId.getTimestamp.txt index 8f2df6810d8..c3c3ef1ca30 100644 --- a/source/reference/method/ObjectId.getTimestamp.txt +++ b/source/reference/method/ObjectId.getTimestamp.txt @@ -30,4 +30,6 @@ This will return the following output: ISODate("2012-10-15T21:26:17Z") -.. seealso:: :ref:`ObjectId BSON Type ` +.. seealso:: + + :ref:`ObjectId BSON Type ` diff --git a/source/reference/method/ObjectId.txt b/source/reference/method/ObjectId.txt index 7278bc3fc98..efee79c1b67 100644 --- a/source/reference/method/ObjectId.txt +++ b/source/reference/method/ObjectId.txt @@ -124,5 +124,7 @@ This operation will return the following hexadecimal string: 507f191e810c19729de860ea -.. seealso:: :ref:`ObjectId BSON Type ` +.. seealso:: + + :ref:`ObjectId BSON Type ` diff --git a/source/reference/method/PlanCache.clearPlansByQuery.txt b/source/reference/method/PlanCache.clearPlansByQuery.txt index 49c7beedd14..dfbaa9d62c7 100644 --- a/source/reference/method/PlanCache.clearPlansByQuery.txt +++ b/source/reference/method/PlanCache.clearPlansByQuery.txt @@ -103,5 +103,5 @@ The following operation removes the query plan cached for the shape: .. seealso:: - :method:`db.collection.getPlanCache()` - - :method:`PlanCache.listQueryShapes()` + - ``PlanCache.listQueryShapes()`` - :method:`PlanCache.clear()` diff --git a/source/reference/method/PlanCache.help.txt b/source/reference/method/PlanCache.help.txt index 87d706e0595..418d77a4192 100644 --- a/source/reference/method/PlanCache.help.txt +++ b/source/reference/method/PlanCache.help.txt @@ -25,4 +25,7 @@ Definition db.collection.getPlanCache().help() -.. seealso:: :method:`db.collection.getPlanCache()` +.. seealso:: + + :method:`db.collection.getPlanCache()` + diff --git a/source/reference/method/PlanCache.list.txt b/source/reference/method/PlanCache.list.txt index df5a8a470f0..dc29a26d057 100644 --- a/source/reference/method/PlanCache.list.txt +++ b/source/reference/method/PlanCache.list.txt @@ -68,7 +68,9 @@ Definition For details on the output, see :ref:`$planCacheStats output `. - .. seealso:: + .. seealso:: + + - :pipeline:`$planCacheStats` - :method:`db.collection.aggregate()` - :method:`~cursor.toArray()` diff --git a/source/reference/method/Session.abortTransaction.txt b/source/reference/method/Session.abortTransaction.txt index fd4d9bff0aa..a9d17bc2ca1 100644 --- a/source/reference/method/Session.abortTransaction.txt +++ b/source/reference/method/Session.abortTransaction.txt @@ -23,8 +23,8 @@ Definition without saving any of the changes made by the operations in the transaction. - .. admonition:: Availability - :class: note + .. note:: Availability + - **In version 4.0**, MongoDB supports multi-document transactions on replica sets. diff --git a/source/reference/method/Session.commitTransaction.txt b/source/reference/method/Session.commitTransaction.txt index 3b8f1189f33..2594ba3db0c 100644 --- a/source/reference/method/Session.commitTransaction.txt +++ b/source/reference/method/Session.commitTransaction.txt @@ -20,8 +20,8 @@ Definition Saves the changes made by the operations in the :doc:`multi-document transaction ` and ends the transaction. - .. admonition:: Availability - :class: note + .. note:: Availability + - **In version 4.0**, MongoDB supports multi-document transactions on replica sets. diff --git a/source/reference/method/Session.startTransaction.txt b/source/reference/method/Session.startTransaction.txt index 13b8ace3354..7d983491527 100644 --- a/source/reference/method/Session.startTransaction.txt +++ b/source/reference/method/Session.startTransaction.txt @@ -21,8 +21,8 @@ Definition associated with the session. At any given time, you can have at most one open transaction for a session. - .. admonition:: Availability - :class: note + .. note:: Availability + - **In version 4.0**, MongoDB supports multi-document transactions on replica sets. diff --git a/source/reference/method/UUID.txt b/source/reference/method/UUID.txt index 2a85e2924ad..13febd71c03 100644 --- a/source/reference/method/UUID.txt +++ b/source/reference/method/UUID.txt @@ -17,40 +17,33 @@ Generates a BSON :abbr:`UUID (Universally unique identifier)` object. :method:`~UUID()` has the following syntax: -.. code-block:: javascript - - UUID() - +.. method:: UUID() -.. list-table:: - :header-rows: 1 - :widths: 20 20 80 + .. list-table:: + :header-rows: 1 + :widths: 20 20 80 - * - Parameter + * - Parameter - - Type + - Type - - Description + - Description - * - ``hex`` + * - ``hex`` - - string + - string - - Optional. Specify a 36 character string to convert to a UUID BSON object. If - not provided, MongoDB generates a random UUID in - `RFC 4122 v4 `_ format. - - .. versionchanged:: 3.6 - - In earlier versions of the :binary:`~bin.mongo` shell, - :method:`UUID` required a hexadecimal string argument. See the - :v3.4:`3.4 manual `. - - + - Optional. Specify a 36 character string to convert to a UUID BSON object. If + not provided, MongoDB generates a random UUID in + `RFC 4122 v4 `_ format. + .. versionchanged:: 3.6 + In earlier versions of the :binary:`~bin.mongo` shell, + :method:`UUID` required a hexadecimal string argument. See the + :v3.4:`3.4 manual `. -:returns: A BSON UUID object. + :returns: A BSON UUID object. Example ------- @@ -60,14 +53,12 @@ Convert Character String to UUID Create a 36 character string you wish to convert to a UUID: -.. cssclass:: copyable-code .. code-block:: javascript var myuuid = '3b241101-e2bb-4255-8caf-4136c566a962' The following command outputs the ``myuuid`` variable as a BSON UUID object: -.. cssclass:: copyable-code .. code-block:: javascript UUID(myuuid) @@ -84,7 +75,6 @@ Generate Random UUID You can run the :method:`~UUID()` method without specifying an argument to generate a random UUID: -.. cssclass:: copyable-code .. code-block:: javascript UUID() diff --git a/source/reference/method/WriteResult.hasWriteConcernError.txt b/source/reference/method/WriteResult.hasWriteConcernError.txt index 249bcfa1d71..f7f53fcb99a 100644 --- a/source/reference/method/WriteResult.hasWriteConcernError.txt +++ b/source/reference/method/WriteResult.hasWriteConcernError.txt @@ -19,4 +19,6 @@ Definition method has :data:`WriteResult.writeConcernError`. Otherwise, the method returns ``false``. -.. seealso:: :method:`WriteResult()` +.. seealso:: + + :method:`WriteResult()` diff --git a/source/reference/method/WriteResult.hasWriteError.txt b/source/reference/method/WriteResult.hasWriteError.txt index b5734d067ac..60187106ad0 100644 --- a/source/reference/method/WriteResult.hasWriteError.txt +++ b/source/reference/method/WriteResult.hasWriteError.txt @@ -19,4 +19,6 @@ Definition method has :data:`WriteResult.writeError`. Otherwise, the method returns ``false``. -.. seealso:: :method:`WriteResult()` +.. seealso:: + + :method:`WriteResult()` diff --git a/source/reference/method/WriteResult.txt b/source/reference/method/WriteResult.txt index defa2b53735..53c1f3f9970 100644 --- a/source/reference/method/WriteResult.txt +++ b/source/reference/method/WriteResult.txt @@ -100,5 +100,8 @@ The :method:`WriteResult` has the following properties: .. include:: /includes/fact-errInfo-wc-provenance.rst -.. seealso:: :method:`WriteResult.hasWriteError()`, +.. seealso:: + + :method:`WriteResult.hasWriteError()`, + :method:`WriteResult.hasWriteConcernError()` diff --git a/source/reference/method/connect.txt b/source/reference/method/connect.txt index cd4df141ee8..29a0902ed42 100644 --- a/source/reference/method/connect.txt +++ b/source/reference/method/connect.txt @@ -74,4 +74,7 @@ to ``myDatabase``: db = connect("localhost:27017/myDatabase") -.. seealso:: :method:`Mongo()`, :method:`Mongo.getDB()`, :method:`db.auth()` +.. seealso:: + + :method:`Mongo()`, :method:`Mongo.getDB()`, :method:`db.auth()` + diff --git a/source/reference/method/cursor.addOption.txt b/source/reference/method/cursor.addOption.txt index 42a609b54d7..fc1f4f67e4c 100644 --- a/source/reference/method/cursor.addOption.txt +++ b/source/reference/method/cursor.addOption.txt @@ -43,7 +43,7 @@ Definition - ``OP_QUERY`` wire protocol flag. For the :binary:`~bin.mongo` shell, you can use the cursor flags listed below. For the driver-specific - list, see your :ecosystem:`driver documentation `. + list, see your :driver:`driver documentation `. diff --git a/source/reference/method/cursor.batchSize.txt b/source/reference/method/cursor.batchSize.txt index eaa1681f7a4..2cb0892d81a 100644 --- a/source/reference/method/cursor.batchSize.txt +++ b/source/reference/method/cursor.batchSize.txt @@ -23,8 +23,8 @@ Definition number of documents to return in each batch of the response from the MongoDB instance. In most cases, modifying the batch size will not affect the user or the application, as the - :binary:`~bin.mongo` shell and most :ecosystem:`drivers - ` return results as if MongoDB returned a + :binary:`~bin.mongo` shell and most :driver:`drivers + ` return results as if MongoDB returned a single batch. The :method:`~cursor.batchSize()` method takes the diff --git a/source/reference/method/cursor.count.txt b/source/reference/method/cursor.count.txt index 8ee07e93a57..ab69f1f6035 100644 --- a/source/reference/method/cursor.count.txt +++ b/source/reference/method/cursor.count.txt @@ -97,7 +97,10 @@ Definition :method:`~cursor.count()`. See :ref:`count-method-hint` for an example. - .. seealso:: :method:`cursor.size()` + .. seealso:: + + :method:`cursor.size()` + Behavior -------- diff --git a/source/reference/method/cursor.forEach.txt b/source/reference/method/cursor.forEach.txt index 83daa2cea22..dc512e30c6a 100644 --- a/source/reference/method/cursor.forEach.txt +++ b/source/reference/method/cursor.forEach.txt @@ -65,4 +65,7 @@ the name of each user in the collection: db.users.find().forEach( function(myDoc) { print( "user: " + myDoc.name ); } ); -.. seealso:: :method:`cursor.map()` for similar functionality. +.. seealso:: + + :method:`cursor.map()` for similar functionality. + diff --git a/source/reference/method/cursor.itcount.txt b/source/reference/method/cursor.itcount.txt index 8c78fe78571..31af95af578 100644 --- a/source/reference/method/cursor.itcount.txt +++ b/source/reference/method/cursor.itcount.txt @@ -32,4 +32,7 @@ Definition db.collection.find().itcount() - .. seealso:: :method:`cursor.count()` + .. seealso:: + + :method:`cursor.count()` + diff --git a/source/reference/method/cursor.map.txt b/source/reference/method/cursor.map.txt index cd5508960b3..6b587ee3947 100644 --- a/source/reference/method/cursor.map.txt +++ b/source/reference/method/cursor.map.txt @@ -50,4 +50,7 @@ Example db.users.find().map( function(u) { return u.name; } ); -.. seealso:: :method:`cursor.forEach()` for similar functionality. +.. seealso:: + + :method:`cursor.forEach()` for similar functionality. + diff --git a/source/reference/method/cursor.max.txt b/source/reference/method/cursor.max.txt index 169a5cf88b3..a4773811d2f 100644 --- a/source/reference/method/cursor.max.txt +++ b/source/reference/method/cursor.max.txt @@ -74,7 +74,10 @@ order*. if multiple indexes exist on same fields with different sort orders, the selection of the index may be ambiguous. -.. seealso:: :method:`~cursor.min()`. +.. seealso:: + + :method:`~cursor.min()`. + :method:`~cursor.max()` exists primarily to support the :binary:`~bin.mongos` (sharding) process, and is a shell wrapper around diff --git a/source/reference/method/cursor.maxTimeMS.txt b/source/reference/method/cursor.maxTimeMS.txt index 1a255952710..44e12954d72 100644 --- a/source/reference/method/cursor.maxTimeMS.txt +++ b/source/reference/method/cursor.maxTimeMS.txt @@ -92,7 +92,7 @@ error. For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit session -using :method:`Session.startSession()` and periodically refresh the +using :method:`Mongo.startSession()` and periodically refresh the session using the :dbcommand:`refreshSessions` command. For example: .. code-block:: javascript @@ -125,10 +125,12 @@ Since the session will never exceed the 30 minute idle timeout, the cursor can remain open up to the configured :method:`~cursor.maxTimeMS()`. -For MongoDB drivers, defer to the :ecosystem:`driver documentation -` for instructions and syntax for creating sessions. +For MongoDB drivers, defer to the :driver:`driver documentation +` for instructions and syntax for creating sessions. -.. seealso:: :limit:`Session Idle Timeout` +.. seealso:: + + :limit:`Session Idle Timeout` Examples -------- diff --git a/source/reference/method/cursor.min.txt b/source/reference/method/cursor.min.txt index 19fb0bdebdf..cd3a50189f9 100644 --- a/source/reference/method/cursor.min.txt +++ b/source/reference/method/cursor.min.txt @@ -68,7 +68,10 @@ Definition with different sort orders, the selection of the index may be ambiguous. -.. seealso:: :method:`~cursor.max()`. +.. seealso:: + + :method:`~cursor.max()`. + :method:`~cursor.min()` exists primarily to support the :binary:`~bin.mongos` process, and is a shell wrapper around the diff --git a/source/reference/method/cursor.noCursorTimeout.txt b/source/reference/method/cursor.noCursorTimeout.txt index 800b8d6ae8d..600a552251f 100644 --- a/source/reference/method/cursor.noCursorTimeout.txt +++ b/source/reference/method/cursor.noCursorTimeout.txt @@ -45,7 +45,7 @@ error. For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit session -using :method:`Session.startSession()` and periodically refresh the +using :method:`Mongo.startSession()` and periodically refresh the session using the :dbcommand:`refreshSessions` command. For example: .. code-block:: shell @@ -77,5 +77,5 @@ the cursor if idle. The ``while`` loop includes a block that uses Since the session will never exceed the 30 minute idle timeout, the cursor can remain open indefinitely. -For MongoDB drivers, defer to the :ecosystem:`driver documentation -` for instructions and syntax for creating sessions. +For MongoDB drivers, defer to the :driver:`driver documentation +` for instructions and syntax for creating sessions. diff --git a/source/reference/method/cursor.readConcern.txt b/source/reference/method/cursor.readConcern.txt index a846629a4e0..b1a3080e8b7 100644 --- a/source/reference/method/cursor.readConcern.txt +++ b/source/reference/method/cursor.readConcern.txt @@ -49,7 +49,7 @@ Definition - string - - :term:`Read concern` level. + - :term:`Read concern ` level. .. include:: /includes/fact-readConcern-option-description.rst @@ -80,4 +80,6 @@ Linearizable Read Concern Performance db.restaurants.find( { _id: 5 } ).readConcern("linearizable").maxTimeMS(10000) -.. seealso:: :doc:`/reference/read-concern` +.. seealso:: + + :doc:`/reference/read-concern` diff --git a/source/reference/method/cursor.readPref.txt b/source/reference/method/cursor.readPref.txt index 0c3018a96b6..52f9b448abd 100644 --- a/source/reference/method/cursor.readPref.txt +++ b/source/reference/method/cursor.readPref.txt @@ -92,7 +92,7 @@ Parameters .. versionadded:: 4.4 -:method:`cursor.setReadPref()` does not support the +:method:`~cursor.readPref()` does not support the :ref:`replica-set-read-preference-max-staleness` option for read preference. @@ -144,7 +144,9 @@ members with the ``datacenter: "B"`` tag first. See :ref:`read-pref-order-matching` for details. -.. seealso:: :doc:`/tutorial/configure-replica-set-tag-sets` +.. seealso:: + + :doc:`/tutorial/configure-replica-set-tag-sets` Specify Hedged Read ~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/method/cursor.returnKey.txt b/source/reference/method/cursor.returnKey.txt index 16a53bbc603..c87d0c26b27 100644 --- a/source/reference/method/cursor.returnKey.txt +++ b/source/reference/method/cursor.returnKey.txt @@ -20,9 +20,9 @@ Definition .. tip:: - Starting in MongoDB 4.4, :projection:`$meta` supports the keyword + Starting in MongoDB 4.4, :expression:`$meta` supports the keyword ``"indexKey"`` to return index key metadata if an index is used. - The use of :projection:`{ $meta: "indexKey" } <$meta>` is + The use of :expression:`{ $meta: "indexKey" } <$meta>` is preferred over :method:`cursor.returnKey()`. Modifies the cursor to return index keys rather than the documents. diff --git a/source/reference/method/cursor.sort.txt b/source/reference/method/cursor.sort.txt index 5c4eb2c0c3c..1326a56144e 100644 --- a/source/reference/method/cursor.sort.txt +++ b/source/reference/method/cursor.sort.txt @@ -168,7 +168,7 @@ The following sample document specifies a descending sort by the The ``"textScore"`` metadata sorts in descending order. -For more information, see :projection:`$meta` for details. +For more information, see :expression:`$meta` for details. .. _sort-index-use: @@ -213,7 +213,9 @@ To prevent blocking sorts from consuming too much memory: with :method:`cursor.sort()`. See :ref:`sort-limit-results` for more information and examples. -.. seealso:: +.. seealso:: + + - :limit:`Memory Limits on Sort Operations ` @@ -234,15 +236,18 @@ footprint of these ``k`` results exceeds 100 megabytes, the query will fail *unless* the query specifies :method:`cursor.allowDiskUse()` (*New in MongoDB 4.4*). -.. seealso:: :limit:`Memory Limits on Sort Operations ` +.. seealso:: + + :limit:`Memory Limits on Sort Operations ` .. _sort-with-projection: -Interaction with :term:`Projection` -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Interaction with Projection +~~~~~~~~~~~~~~~~~~~~~~~~~~~ -When a set of results are both sorted and projected, the MongoDB query engine -will always apply the sorting **first**. +When a set of results are both sorted *and* +:term:`projected `, the MongoDB query engine will always +apply the sorting **first**. Examples -------- @@ -332,4 +337,6 @@ Index Use .. include:: /includes/fact-natural-parameter.rst -.. seealso:: :operator:`$natural` +.. seealso:: + + :operator:`$natural` diff --git a/source/reference/method/db.auth.txt b/source/reference/method/db.auth.txt index 9d57821a0be..c7047fa9497 100644 --- a/source/reference/method/db.auth.txt +++ b/source/reference/method/db.auth.txt @@ -36,151 +36,147 @@ The :method:`db.auth()` has the following syntax forms: ``db.auth(, )`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +.. tabs:: - .. tabs:: + .. tab:: MongoDB 4.4 + :tabid: mdb-4-4 - .. tab:: MongoDB 4.4 - :tabid: mdb-4-4 + Starting in MongoDB 4.4, you can either: + + - Omit the password to prompt the user to enter a password: - Starting in MongoDB 4.4, you can either: - - - Omit the password to prompt the user to enter a password: + .. code-block:: javascript - .. code-block:: javascript + db.auth( ) - db.auth( ) + - Use :method:`passwordPrompt()` to prompt the user to enter + a password: + + .. code-block:: javascript - - Use :method:`passwordPrompt()` to prompt the user to enter - a password: - - .. code-block:: javascript + db.auth( , passwordPrompt() ) - db.auth( , passwordPrompt() ) + - Specify a cleartext password. - - Specify a cleartext password. + .. code-block:: javascript - .. code-block:: javascript + db.auth( , ) - db.auth( , ) + .. tab:: MongoDB 4.2 + :tabid: mdb-4-2 - .. tab:: MongoDB 4.2 - :tabid: mdb-4-2 + Starting in MongoDB 4.2, you can either: + + - Use :method:`passwordPrompt()` to prompt the user to enter + a password: - Starting in MongoDB 4.2, you can either: - - - Use :method:`passwordPrompt()` to prompt the user to enter - a password: + .. code-block:: javascript - .. code-block:: javascript + db.auth( , passwordPrompt() ) - db.auth( , passwordPrompt() ) + - Specify a cleartext password: + + .. code-block:: javascript - - Specify a cleartext password: - - .. code-block:: javascript + db.auth( , ) - db.auth( , ) + .. tab:: MongoDB 4.0 and Earlier + :tabid: mdb-4-0-earlier: - .. tab:: MongoDB 4.0 and Earlier - :tabid: mdb-4-0-earlier: + In MongoDB 4.0 and earlier, you must specify a cleartext + password: - In MongoDB 4.0 and earlier, you must specify a cleartext - password: + .. code-block:: javascript - .. code-block:: javascript - - db.auth( , ) + db.auth( , ) .. _db-auth-syntax-user-document: ``db.auth()`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. code-block:: javascript +.. code-block:: javascript - db.auth( { - user: , - pwd: passwordPrompt(), // Or "" - mechanism: , - digestPassword: - } ) + db.auth( { + user: , + pwd: passwordPrompt(), // Or "" + mechanism: , + digestPassword: + } ) - .. list-table:: - :header-rows: 1 - :widths: 20 20 80 +.. list-table:: + :header-rows: 1 + :widths: 20 20 80 - * - Parameter + * - Parameter - - Type + - Type - - Description + - Description - * - ``user`` + * - ``user`` - - string + - string - - The name of the user with access privileges for this database. - - + - The name of the user with access privileges for this database. + + - * - ``pwd`` + * - ``pwd`` - - string + - string - - The user's password. The value can be either: - - - the user's password in cleartext string, or - - - :method:`passwordPrompt()` to prompt for the user's password. - - .. tip:: - - .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst + - The user's password. The value can be either: + + - the user's password in cleartext string, or + + - :method:`passwordPrompt()` to prompt for the user's password. + + .. tip:: + + .. include:: /includes/extracts/4.2-changes-passwordPrompt.rst - When using the user document syntax, you cannot omit the - ``pwd``. - - + When using the user document syntax, you cannot omit the + ``pwd``. + + - * - ``mechanism`` + * - ``mechanism`` - - string + - string - - Optional. The :ref:`authentication mechanism - ` to use. - - For available mechanisms, see :ref:`authentication mechanisms - `. - - If unspecified, uses the :dbcommand:`isMaster` to determine the SASL - mechanism or mechanisms for the specified user. See - :data:`~isMaster.saslSupportedMechs`. - - + - Optional. The :ref:`authentication mechanism + ` to use. + + For available mechanisms, see :ref:`authentication mechanisms + `. + + If unspecified, uses the :dbcommand:`isMaster` to determine the SASL + mechanism or mechanisms for the specified user. See + :data:`~isMaster.saslSupportedMechs`. + + - * - ``digestPassword`` + * - ``digestPassword`` - - boolean + - boolean - - Optional. Determines whether or not the supplied password should be pre-hashed - before being used with the specified authentication mechanism. - - - For :ref:`SCRAM-SHA-1 `, although you may - specify ``true``, setting this value to ``true`` does not improve - security and may interfere with credentials using other mechanisms. - - - For all other methods, this value must be set to ``false`` - (default value). Any other value will result in authentication - failure since those methods do not understand MongoDB pre-hashing. - - The default value is ``false``. + - Optional. Determines whether or not the supplied password should be pre-hashed + before being used with the specified authentication mechanism. + + - For :ref:`SCRAM-SHA-1 `, although you may + specify ``true``, setting this value to ``true`` does not improve + security and may interfere with credentials using other mechanisms. + + - For all other methods, this value must be set to ``false`` + (default value). Any other value will result in authentication + failure since those methods do not understand MongoDB pre-hashing. + + The default value is ``false``. - .. |operation-name| replace:: :method:`db.auth()` - .. include:: /includes/note-auth-methods-excluded-from-shell-history.rst +.. |operation-name| replace:: :method:`db.auth()` +.. include:: /includes/note-auth-methods-excluded-from-shell-history.rst Returns :method:`db.auth()` returns ``0`` when authentication is diff --git a/source/reference/method/db.changeUserPassword.txt b/source/reference/method/db.changeUserPassword.txt index a33c59ccee5..9ed533ea5d3 100644 --- a/source/reference/method/db.changeUserPassword.txt +++ b/source/reference/method/db.changeUserPassword.txt @@ -17,7 +17,7 @@ Definition Updates a user's password. Run the method in the database where the user is defined, i.e. the database you :method:`created - ` the user. + ` the user. .. list-table:: diff --git a/source/reference/method/db.collection.aggregate.txt b/source/reference/method/db.collection.aggregate.txt index 2f287f76d9f..4b605758c53 100644 --- a/source/reference/method/db.collection.aggregate.txt +++ b/source/reference/method/db.collection.aggregate.txt @@ -270,7 +270,9 @@ retrieved), such as the following methods: * :method:`cursor.itcount()` * :method:`cursor.pretty()` -.. seealso:: For more information, see +.. seealso:: + + For more information, see :doc:`/core/aggregation-pipeline`, :doc:`/reference/aggregation`, :doc:`/core/aggregation-pipeline-limits`, and :dbcommand:`aggregate`. @@ -292,7 +294,7 @@ Session Idle Timeout For operations that return a cursor, if the cursor may be idle for longer than 30 minutes, issue the operation within an explicit session -using :method:`Session.startSession()` and periodically refresh the +using :method:`Mongo.startSession()` and periodically refresh the session using the :dbcommand:`refreshSessions` command. See :limit:`Session Idle Timeout` for more information. diff --git a/source/reference/method/db.collection.count.txt b/source/reference/method/db.collection.count.txt index 09ce6aacab5..a11f4047663 100644 --- a/source/reference/method/db.collection.count.txt +++ b/source/reference/method/db.collection.count.txt @@ -157,7 +157,9 @@ Definition :method:`~db.collection.count()` is equivalent to the ``db.collection.find(query).count()`` construct. -.. seealso:: +.. seealso:: + + - :method:`cursor.count()` - :method:`db.collection.estimatedDocumentCount()` diff --git a/source/reference/method/db.collection.createIndex.txt b/source/reference/method/db.collection.createIndex.txt index 6ec2433bc91..ff93188f093 100644 --- a/source/reference/method/db.collection.createIndex.txt +++ b/source/reference/method/db.collection.createIndex.txt @@ -234,8 +234,8 @@ otherwise specified: - Optional. The name of the index. If unspecified, MongoDB generates an index name by concatenating the names of the indexed fields and the sort order. - .. admonition:: Changed in MongoDB 4.2 - :class: note + .. note:: Changed in MongoDB 4.2 + .. include:: /includes/extracts/4.2-changes-index-names.rst @@ -710,7 +710,9 @@ For example, db.restaurants.unhideIndex( { borough: 1, city: 1 } ); -.. seealso:: :doc:`/core/index-hidden` +.. seealso:: + + :doc:`/core/index-hidden` Index Key Length Limit ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/method/db.collection.createIndexes.txt b/source/reference/method/db.collection.createIndexes.txt index 00ae3bbf45b..f36641fbc95 100644 --- a/source/reference/method/db.collection.createIndexes.txt +++ b/source/reference/method/db.collection.createIndexes.txt @@ -252,8 +252,8 @@ otherwise specified: - Optional. The name of the index. If unspecified, MongoDB generates an index name by concatenating the names of the indexed fields and the sort order. - .. admonition:: Changed in MongoDB 4.2 - :class: note + .. note:: Changed in MongoDB 4.2 + .. include:: /includes/extracts/4.2-changes-index-names.rst @@ -717,7 +717,9 @@ For example, db.restaurants.unhideIndex( { borough: 1, city: 1 } ); -.. seealso:: :doc:`/core/index-hidden` +.. seealso:: + + :doc:`/core/index-hidden` Index Key Length Limit ~~~~~~~~~~~~~~~~~~~~~~ @@ -762,7 +764,10 @@ Transactions Example ------- -.. seealso:: :method:`db.collection.createIndex()` for examples of +.. seealso:: + + :method:`db.collection.createIndex()` for examples of + various index specifications. Create Indexes Without Options diff --git a/source/reference/method/db.collection.deleteMany.txt b/source/reference/method/db.collection.deleteMany.txt index 8088c3498ec..c5223e70a14 100644 --- a/source/reference/method/db.collection.deleteMany.txt +++ b/source/reference/method/db.collection.deleteMany.txt @@ -102,7 +102,7 @@ Definition A document containing: - - A boolean ``acknowledged`` as ``true`` if the operation ran with + - A boolean ``acknowledged`` as ``true`` if the operation ran with :term:`write concern` or ``false`` if write concern was disabled - ``deletedCount`` containing the number of deleted documents diff --git a/source/reference/method/db.collection.deleteOne.txt b/source/reference/method/db.collection.deleteOne.txt index ff0b02ea378..8eb12e039eb 100644 --- a/source/reference/method/db.collection.deleteOne.txt +++ b/source/reference/method/db.collection.deleteOne.txt @@ -329,5 +329,7 @@ To view the indexes used, you can use the :pipeline:`$indexStats` pipeline: The ``accesses.ops`` field in the :pipeline:`$indexStats` output indicates the number of operations that used the index. -.. seealso:: To delete multiple documents, see +.. seealso:: + + To delete multiple documents, see :method:`db.collection.deleteMany()` diff --git a/source/reference/method/db.collection.distinct.txt b/source/reference/method/db.collection.distinct.txt index 8483f604d61..e2274899eab 100644 --- a/source/reference/method/db.collection.distinct.txt +++ b/source/reference/method/db.collection.distinct.txt @@ -184,7 +184,9 @@ The method returns the following array of distinct ``sku`` values: [ "111", "222", "333" ] -.. seealso:: :ref:`document-dot-notation` for information on accessing fields +.. seealso:: + + :ref:`document-dot-notation` for information on accessing fields within embedded documents .. _distinct-method-array: diff --git a/source/reference/method/db.collection.estimatedDocumentCount.txt b/source/reference/method/db.collection.estimatedDocumentCount.txt index 656a3f7011f..2cedf4bab77 100644 --- a/source/reference/method/db.collection.estimatedDocumentCount.txt +++ b/source/reference/method/db.collection.estimatedDocumentCount.txt @@ -99,7 +99,9 @@ all documents in the ``orders`` collection: db.orders.estimatedDocumentCount({}) -.. seealso:: +.. seealso:: + + - :method:`db.collection.countDocuments()` - :dbcommand:`count` diff --git a/source/reference/method/db.collection.explain.txt b/source/reference/method/db.collection.explain.txt index 83dba912abb..843d482b984 100644 --- a/source/reference/method/db.collection.explain.txt +++ b/source/reference/method/db.collection.explain.txt @@ -120,28 +120,22 @@ information returned depend on the ``verbosity`` mode. name: "queryPlanner Mode (Default)" content: | - .. container:: + By default, :method:`db.collection.explain()` runs in + ``queryPlanner`` verbosity mode. - By default, :method:`db.collection.explain()` runs in - ``queryPlanner`` verbosity mode. - - .. include:: /includes/fact-explain-verbosity-queryPlanner.rst + .. include:: /includes/fact-explain-verbosity-queryPlanner.rst - id: executionstats name: "executionStats Mode" content: | - .. container:: - - .. include:: /includes/fact-explain-verbosity-executionStats.rst + .. include:: /includes/fact-explain-verbosity-executionStats.rst - id: allplans name: "allPlansExecution Mode" content: | - .. container:: - - .. include:: /includes/fact-explain-verbosity-allPlansExecution.rst + .. include:: /includes/fact-explain-verbosity-allPlansExecution.rst Explain and Write Operations ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -166,7 +160,7 @@ The :method:`db.collection.explain()` method wraps the .. include:: /includes/fact-explain-methods-differences.rst -:method:`db.collection.explain().aggregate()` is equivalent to passing +:method:`db.collection.explain().aggregate() ` is equivalent to passing the :ref:`explain ` option to the :method:`db.collection.aggregate()` method. @@ -182,7 +176,7 @@ To see the list of operations supported by db.collection.explain().help() -:method:`db.collection.explain().find()` returns a cursor, which allows +:method:`db.collection.explain().find() ` returns a cursor, which allows for the chaining of query modifiers. To see the list of query modifiers supported by :method:`db.collection.explain().find() ` as well as cursor-related methods, run: @@ -256,7 +250,7 @@ all considered plans for the specified Explain ``find()`` with Modifiers ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:method:`db.collection.explain().find()` construct allows for the +:method:`db.collection.explain().find() ` construct allows for the chaining of query modifiers. For example, the following operation provides information on the :method:`~db.collection.find()` method with :method:`~cursor.sort()` and :method:`~cursor.hint()` query modifiers. @@ -277,7 +271,7 @@ shell: Iterate the ``explain().find()`` Return Cursor ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:method:`db.collection.explain().find()` returns a cursor to the +:method:`db.collection.explain().find() ` returns a cursor to the explain results. If run interactively in the :binary:`~bin.mongo` shell, the :binary:`~bin.mongo` shell automatically iterates the cursor using the ``.next()`` method. For scripts, however, you must explicitly call diff --git a/source/reference/method/db.collection.find.txt b/source/reference/method/db.collection.find.txt index 14473be0f90..5efe9042c5b 100644 --- a/source/reference/method/db.collection.find.txt +++ b/source/reference/method/db.collection.find.txt @@ -109,8 +109,8 @@ automatically iterates the cursor to display up to the first 20 documents. Type ``it`` to continue iteration. To access the returned documents with a driver, use the appropriate -cursor handling mechanism for the :ecosystem:`driver language -`. +cursor handling mechanism for the :driver:`driver language +`. .. seealso:: @@ -191,7 +191,7 @@ Session Idle Timeout For operations that may be idle for longer than 30 minutes, associate the operation with an explicit session using -:method:`Session.startSession()` and periodically refresh the session +:method:`Mongo.startSession()` and periodically refresh the session using the :dbcommand:`refreshSessions` command. See :limit:`Session Idle Timeout` for more information. @@ -662,7 +662,9 @@ The operation returns the following documents: { "birth" : ISODate("1955-05-19T04:00:00Z"), "contribs" : [ "Java" ], "name" : "James Gosling", "awards" : 2, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 } { "contribs" : [ "Scala" ], "name" : "Martin Odersky", "awards" : 0, "reportDate" : "2020-06-05", "reportBy" : "hellouser123", "reportNumber" : 1 } -.. seealso:: :doc:`/tutorial/project-fields-from-query-results` +.. seealso:: + + :doc:`/tutorial/project-fields-from-query-results` .. _crud-read-cursor: @@ -737,8 +739,8 @@ to iterate the cursor and access the documents: Modify the Cursor Behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :binary:`~bin.mongo` shell and the :ecosystem:`drivers -` provide several cursor methods that call on the +The :binary:`~bin.mongo` shell and the :driver:`drivers +` provide several cursor methods that call on the *cursor* returned by the :method:`~db.collection.find()` method to modify its behavior. diff --git a/source/reference/method/db.collection.findAndModify.txt b/source/reference/method/db.collection.findAndModify.txt index e664848ed4c..1825d9122f5 100644 --- a/source/reference/method/db.collection.findAndModify.txt +++ b/source/reference/method/db.collection.findAndModify.txt @@ -4,8 +4,7 @@ db.collection.findAndModify() .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -364,23 +363,21 @@ When using :dbcommand:`findAndModify` against a sharded collection, the Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +.. include:: /includes/shard-key-modification-warning.rst - .. include:: /includes/shard-key-modification-warning.rst +To modify the **existing** shard key value with +:method:`db.collection.findAndModify()`: - To modify the **existing** shard key value with - :method:`db.collection.findAndModify()`: - - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. - - - You :red:`must` include an equality filter on the full shard key. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. + +- You :red:`must` include an equality filter on the full shard key. .. _method-findAndModify-missing-shard-key: @@ -388,31 +385,28 @@ Shard Key Modification Missing Shard Key ````````````````` -.. container:: - - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :method:`db.collection.findAndModify()` to set the document's - **missing** shard key: +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:method:`db.collection.findAndModify()` to set the document's +**missing** shard key: - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - ` if the new shard key value is not - ``null``. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + ` if the new shard key value is not + ``null``. - - You :red:`must` include an equality filter on the full shard key. +- You :red:`must` include an equality filter on the full shard key. - .. tip:: +.. tip:: - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - See also: - - - :ref:`shard-key-missing` +See also: +- :ref:`shard-key-missing` Document Validation ~~~~~~~~~~~~~~~~~~~ @@ -656,8 +650,6 @@ Update Elements Match ``arrayFilters`` Criteria Create a collection ``students`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.insert([ @@ -671,8 +663,6 @@ To modify all elements that are greater than or equal to ``100`` in the :update:`$[\]` with the ``arrayFilters`` option in the :method:`db.collection.findAndModify` method: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.findAndModify({ @@ -842,4 +832,6 @@ For the syntax, see :ref:`let `. } ) -.. seealso:: :ref:`perform-findAndModify-linearizable-reads` +.. seealso:: + + :ref:`perform-findAndModify-linearizable-reads` diff --git a/source/reference/method/db.collection.findOne.txt b/source/reference/method/db.collection.findOne.txt index 4ffb4dc1d90..c2bb452c7b8 100644 --- a/source/reference/method/db.collection.findOne.txt +++ b/source/reference/method/db.collection.findOne.txt @@ -81,8 +81,8 @@ Client Disconnection Projection ~~~~~~~~~~ -.. admonition:: Language Consistency - :class: important +.. important:: Language Consistency + Starting in MongoDB 4.4, as part of making :method:`~db.collection.find` and diff --git a/source/reference/method/db.collection.findOneAndReplace.txt b/source/reference/method/db.collection.findOneAndReplace.txt index 36aed787472..37cc9eb1c3e 100644 --- a/source/reference/method/db.collection.findOneAndReplace.txt +++ b/source/reference/method/db.collection.findOneAndReplace.txt @@ -10,8 +10,7 @@ db.collection.findOneAndReplace() :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + Definition ---------- @@ -238,23 +237,21 @@ include an equality condition on the shard key. Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +.. include:: /includes/shard-key-modification-warning.rst - .. include:: /includes/shard-key-modification-warning.rst +To modify the **existing** shard key value with +:method:`db.collection.findOneAndReplace()`: - To modify the **existing** shard key value with - :method:`db.collection.findOneAndReplace()`: - - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. - - - You :red:`must` include an equality filter on the full shard key. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. + +- You :red:`must` include an equality filter on the full shard key. .. _findOneAndReplace-missing-shard-key: @@ -262,30 +259,28 @@ Shard Key Modification Missing Shard Key ````````````````` -.. container:: - - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :method:`db.collection.findOneAndReplace()` to set the document's - **missing** shard key, +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:method:`db.collection.findOneAndReplace()` to set the document's +**missing** shard key, - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - ` if the new shard key value is not - ``null``. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + ` if the new shard key value is not + ``null``. - - You :red:`must` include an equality filter on the full shard key. +- You :red:`must` include an equality filter on the full shard key. - .. tip:: +.. tip:: - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - See also: +See also: - - :ref:`shard-key-missing` +- :ref:`shard-key-missing` Transactions diff --git a/source/reference/method/db.collection.findOneAndUpdate.txt b/source/reference/method/db.collection.findOneAndUpdate.txt index 9d5c9cbc0e7..9dbfc359897 100644 --- a/source/reference/method/db.collection.findOneAndUpdate.txt +++ b/source/reference/method/db.collection.findOneAndUpdate.txt @@ -4,8 +4,7 @@ db.collection.findOneAndUpdate() .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -253,23 +252,21 @@ include an equality condition on the shard key. Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +.. include:: /includes/shard-key-modification-warning.rst - .. include:: /includes/shard-key-modification-warning.rst +To modify the **existing** shard key value with +:method:`db.collection.findOneAndUpdate()`: - To modify the **existing** shard key value with - :method:`db.collection.findOneAndUpdate()`: - - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. - - - You :red:`must` include an equality filter on the full shard key. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. + +- You :red:`must` include an equality filter on the full shard key. .. _findOneAndUpdate-missing-shard-key: @@ -277,30 +274,28 @@ Shard Key Modification Missing Shard Key ````````````````` -.. container:: - - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :method:`db.collection.findOneAndUpdate()` to set the document's - **missing** shard key, +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:method:`db.collection.findOneAndUpdate()` to set the document's +**missing** shard key, - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - ` if the new shard key value is not - ``null``. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + ` if the new shard key value is not + ``null``. - - You :red:`must` include an equality filter on the full shard key. +- You :red:`must` include an equality filter on the full shard key. - .. tip:: +.. tip:: - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - See also: +See also: - - :ref:`shard-key-missing` +- :ref:`shard-key-missing` Transactions ~~~~~~~~~~~~ diff --git a/source/reference/method/db.collection.getShardDistribution.txt b/source/reference/method/db.collection.getShardDistribution.txt index a4946440891..2bc6df6d1db 100644 --- a/source/reference/method/db.collection.getShardDistribution.txt +++ b/source/reference/method/db.collection.getShardDistribution.txt @@ -37,7 +37,9 @@ Definition db.adminCommand( { flushRouterConfig: "test.myShardedCollection" } ); db.getSiblingDB("test").myShardedCollection.getShardDistribution(); -.. seealso:: :doc:`/sharding` +.. seealso:: + + :doc:`/sharding` .. TODO - Improve the output sections. diff --git a/source/reference/method/db.collection.isCapped.txt b/source/reference/method/db.collection.isCapped.txt index 75e740b95b4..231efffa9f9 100644 --- a/source/reference/method/db.collection.isCapped.txt +++ b/source/reference/method/db.collection.isCapped.txt @@ -19,4 +19,6 @@ db.collection.isCapped() :returns: Returns ``true`` if the collection is a :term:`capped collection`, otherwise returns ``false``. - .. seealso:: :doc:`/core/capped-collections` + .. seealso:: + + :doc:`/core/capped-collections` diff --git a/source/reference/method/db.collection.latencyStats.txt b/source/reference/method/db.collection.latencyStats.txt index 82f58ceec8b..3d0c57e275d 100644 --- a/source/reference/method/db.collection.latencyStats.txt +++ b/source/reference/method/db.collection.latencyStats.txt @@ -33,7 +33,9 @@ Definition ``histograms: true`` then :method:`~db.collection.latencyStats()` adds latency histograms to the return document. -.. seealso:: :pipeline:`$collStats` +.. seealso:: + + :pipeline:`$collStats` Output ------ diff --git a/source/reference/method/db.collection.mapReduce.txt b/source/reference/method/db.collection.mapReduce.txt index a2e1f38a34b..f9eb7119662 100644 --- a/source/reference/method/db.collection.mapReduce.txt +++ b/source/reference/method/db.collection.mapReduce.txt @@ -79,7 +79,7 @@ Syntax type 13 `) or String (i.e. :doc:`BSON type 2 `). - See :ref:`mapReduce-map-mtd` for more information. + See :ref:`mapreduce-map-mtd` for more information. @@ -93,7 +93,7 @@ Syntax `) or String (i.e. :doc:`BSON type 2 `). - See :ref:`mapReduce-reduce-mtd` for more information. + See :ref:`mapreduce-reduce-mtd` for more information. @@ -133,7 +133,7 @@ The following table describes additional arguments that performing map-reduce operations on the primary members of the set; on :term:`secondary` members you may only use the ``inline`` output. - See :ref:`mapReduce-out-mtd` for more information. + See :ref:`mapreduce-out-mtd` for more information. @@ -176,7 +176,7 @@ The following table describes additional arguments that JavaScript (i.e. :doc:`BSON type 13 `) or String (i.e. :doc:`BSON type 2 `). - See :ref:`mapReduce-finalize-mtd` for more information. + See :ref:`mapreduce-finalize-mtd` for more information. diff --git a/source/reference/method/db.collection.reIndex.txt b/source/reference/method/db.collection.reIndex.txt index 844153582a5..cbeab60dceb 100644 --- a/source/reference/method/db.collection.reIndex.txt +++ b/source/reference/method/db.collection.reIndex.txt @@ -63,4 +63,6 @@ database and blocks other operations on the database until finished. For more information on locking in MongoDB, see :doc:`/faq/concurrency`. -.. seealso:: :doc:`/indexes` +.. seealso:: + + :doc:`/indexes` diff --git a/source/reference/method/db.collection.remove.txt b/source/reference/method/db.collection.remove.txt index 74a219e41e7..7ec49baddc5 100644 --- a/source/reference/method/db.collection.remove.txt +++ b/source/reference/method/db.collection.remove.txt @@ -295,7 +295,10 @@ documents removed: WriteResult({ "nRemoved" : 4 }) -.. seealso:: :data:`WriteResult.nRemoved` +.. seealso:: + + :data:`WriteResult.nRemoved` + Write Concern Errors ~~~~~~~~~~~~~~~~~~~~ @@ -323,7 +326,9 @@ concern errors, the results include the } }) -.. seealso:: +.. seealso:: + + - :method:`WriteResult.hasWriteConcernError()` @@ -345,4 +350,7 @@ concern error, the results include :data:`WriteResult.writeError` field: } }) -.. seealso:: :method:`WriteResult.hasWriteError()` +.. seealso:: + + :method:`WriteResult.hasWriteError()` + diff --git a/source/reference/method/db.collection.renameCollection.txt b/source/reference/method/db.collection.renameCollection.txt index ab179fd90f2..8428c6476e2 100644 --- a/source/reference/method/db.collection.renameCollection.txt +++ b/source/reference/method/db.collection.renameCollection.txt @@ -44,7 +44,7 @@ Definition - boolean - - Optional. If ``true``, :binary:`~bin.mongod` drops the `target` of :dbcommand:`renameCollection` prior to + - Optional. If ``true``, :binary:`~bin.mongod` drops the ``target`` of :dbcommand:`renameCollection` prior to renaming the collection. The default value is ``false``. diff --git a/source/reference/method/db.collection.replaceOne.txt b/source/reference/method/db.collection.replaceOne.txt index 350c90a9ef6..ac90f8d5a5c 100644 --- a/source/reference/method/db.collection.replaceOne.txt +++ b/source/reference/method/db.collection.replaceOne.txt @@ -4,8 +4,7 @@ db.collection.replaceOne() .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -190,102 +189,93 @@ replacement document. Shard Key Requirements In Replacement Document `````````````````````````````````````````````` -.. container:: - - Starting in MongoDB 4.4, the replacement document does not need to - include the shard key. In MongoDB 4.2 and earlier, the replacement - document must include the shard key. +Starting in MongoDB 4.4, the replacement document does not need to +include the shard key. In MongoDB 4.2 and earlier, the replacement +document must include the shard key. - .. include:: /includes/shard-key-modification-warning.rst +.. include:: /includes/shard-key-modification-warning.rst .. _replaceOne-sharded-upsert: ``upsert`` on a Sharded Collection `````````````````````````````````` -.. container:: - - Starting in MongoDB 4.2, a :method:`db.collection.replaceOne()` - operation that includes ``upsert: true`` on a sharded collection must - include the full shard key in the ``filter``. +Starting in MongoDB 4.2, a :method:`db.collection.replaceOne()` +operation that includes ``upsert: true`` on a sharded collection must +include the full shard key in the ``filter``. - .. include:: /includes/extracts/missing-shard-key-equality-condition-update.rst +.. include:: /includes/extracts/missing-shard-key-equality-condition-update.rst .. _replaceOne-shard-key-modification: Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +.. include:: /includes/shard-key-modification-warning.rst - .. include:: /includes/shard-key-modification-warning.rst - - To modify the **existing** shard key value with - :method:`db.collection.replaceOne()`: - - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +To modify the **existing** shard key value with +:method:`db.collection.replaceOne()`: - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` include an equality :ref:`filter - ` on the full shard key. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. +- You :red:`must` include an equality :ref:`filter + ` on the full shard key. .. _replaceOne-missing-shard-key: Missing Shard Key ````````````````` -.. container:: +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:method:`db.collection.replaceOne()` to set the document's +**missing** shard key, you :red:`must` run on a +:binary:`~bin.mongos`. Do :red:`not` issue the operation directly on +the shard. - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :method:`db.collection.replaceOne()` to set the document's - **missing** shard key, you :red:`must` run on a - :binary:`~bin.mongos`. Do :red:`not` issue the operation directly on - the shard. +In addition, the following requirements also apply: - In addition, the following requirements also apply: +.. list-table:: + :header-rows: 1 + :widths: 30 70 - .. list-table:: - :header-rows: 1 - :widths: 30 70 + * - - * - + - Requirements - - Requirements + * - To set to ``null`` - * - To set to ``null`` + - - Requires equality filter on the full shard key if ``upsert: + true`` is specified. - - - Requires equality filter on the full shard key if ``upsert: - true`` is specified. + * - To set to a non-``null`` value - * - To set to a non-``null`` value + - - :red:`Must` be performed either inside a :doc:`transaction + ` or as a :doc:`retryable write + `. - - - :red:`Must` be performed either inside a :doc:`transaction - ` or as a :doc:`retryable write - `. + - Requires equality filter on the full shard key if either: - - Requires equality filter on the full shard key if either: + - ``upsert: true``, or - - ``upsert: true``, or + - the new shard key value belongs to a different shard. - - the new shard key value belongs to a different shard. +.. tip:: - .. tip:: + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst +See also: - See also: - - - :ref:`replaceOne-sharded-upsert` - - - :ref:`shard-key-missing` +- :ref:`replaceOne-sharded-upsert` + +- :ref:`shard-key-missing` Transactions ~~~~~~~~~~~~ diff --git a/source/reference/method/db.collection.stats.txt b/source/reference/method/db.collection.stats.txt index 6d97ae35e93..38030294363 100644 --- a/source/reference/method/db.collection.stats.txt +++ b/source/reference/method/db.collection.stats.txt @@ -72,7 +72,7 @@ Definition :data:`index details ` in addition to the collection stats. - Only works for :ref:`WiredTiger` storage engine. + Only works for :ref:`WiredTiger` storage engine. Defaults to ``false``. @@ -666,4 +666,6 @@ Both operations will return the same output: For explanation of the output, see :ref:`output details`. -.. seealso:: :pipeline:`$collStats` +.. seealso:: + + :pipeline:`$collStats` diff --git a/source/reference/method/db.collection.update.txt b/source/reference/method/db.collection.update.txt index c50e6293668..174e399fb08 100644 --- a/source/reference/method/db.collection.update.txt +++ b/source/reference/method/db.collection.update.txt @@ -4,8 +4,7 @@ db.collection.update() .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -266,7 +265,10 @@ When the :method:`db.collection.update()` performs update operations (and not document replacement operations), :method:`db.collection.update()` can target multiple shards. -.. seealso:: :method:`~db.collection.findAndModify()` +.. seealso:: + + :method:`~db.collection.findAndModify()` + Replace Document Operations on a Sharded Collection ``````````````````````````````````````````````````` @@ -299,86 +301,82 @@ must include the full shard key in the ``filter``: Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +To modify the **existing** shard key value with +:method:`db.collection.update()`: - To modify the **existing** shard key value with - :method:`db.collection.update()`: +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. +- You :red:`must` specify ``multi: false``. - - You :red:`must` specify ``multi: false``. +- You :red:`must` include an equality :ref:`query filter + ` on the full shard key. - - You :red:`must` include an equality :ref:`query filter - ` on the full shard key. +.. tip:: - .. tip:: + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - - See also :ref:`method-update-sharded-upsert`. +See also :ref:`method-update-sharded-upsert`. .. _method-update-missing-shard-key: Missing Shard Key ````````````````` -.. container:: - - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :method:`db.collection.update()` to set the document's - **missing** shard key, you :red:`must` run on a - :binary:`~bin.mongos`. Do :red:`not` issue the operation directly on - the shard. +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:method:`db.collection.update()` to set the document's +**missing** shard key, you :red:`must` run on a +:binary:`~bin.mongos`. Do :red:`not` issue the operation directly on +the shard. - In addition, the following requirements also apply: +In addition, the following requirements also apply: - .. list-table:: - :header-rows: 1 - :widths: 30 70 +.. list-table:: + :header-rows: 1 + :widths: 30 70 - * - + * - - - Requirements + - Requirements - * - To set to ``null`` + * - To set to ``null`` - - - Can specify ``multi: true``. + - - Can specify ``multi: true``. - - Requires equality filter on the full shard key if ``upsert: - true``. + - Requires equality filter on the full shard key if ``upsert: + true``. - * - To set to a non-``null`` value + * - To set to a non-``null`` value - - - :red:`Must` be performed either inside a :doc:`transaction - ` or as a :doc:`retryable write - `. + - - :red:`Must` be performed either inside a :doc:`transaction + ` or as a :doc:`retryable write + `. - - :red:`Must` specify ``multi: false``. + - :red:`Must` specify ``multi: false``. - - Requires equality filter on the full shard key if either: + - Requires equality filter on the full shard key if either: - - ``upsert: true``, or + - ``upsert: true``, or - - if using a replacement document and the new shard key - value belongs to a different shard. + - if using a replacement document and the new shard key + value belongs to a different shard. - .. tip:: +.. tip:: - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - See also: +See also: - - :ref:`method-update-sharded-upsert` +- :ref:`method-update-sharded-upsert` - - :ref:`shard-key-missing` +- :ref:`shard-key-missing` Transactions ~~~~~~~~~~~~ @@ -411,365 +409,357 @@ Write Concerns and Transactions Examples -------- -.. container:: - - .. tabs:: - - .. tab:: Use Update Operator Expressions ($inc, $set) - :tabid: op-expr +.. tabs:: - .. include:: /includes/fact-update-example-docs-intro.rst + .. tab:: Use Update Operator Expressions ($inc, $set) + :tabid: op-expr - .. include:: /includes/fact-update-example-docs.rst + .. include:: /includes/fact-update-example-docs-intro.rst - If the ```` document contains :ref:`update operator - ` modifiers, such as those using the - :update:`$set` modifier, then: + .. include:: /includes/fact-update-example-docs.rst - - The ```` document must contain *only* - :ref:`update operator ` expressions. + If the ```` document contains :ref:`update operator + ` modifiers, such as those using the + :update:`$set` modifier, then: - - The :method:`db.collection.update()` method updates only the - corresponding fields in the document. + - The ```` document must contain *only* + :ref:`update operator ` expressions. - - To update an embedded document or an array as a whole, - specify the replacement value for the field. + - The :method:`db.collection.update()` method updates only the + corresponding fields in the document. - - To update particular fields in an embedded document or in - an array, use :ref:`dot notation ` - to specify the field. + - To update an embedded document or an array as a whole, + specify the replacement value for the field. - .. only:: website + - To update particular fields in an embedded document or in + an array, use :ref:`dot notation ` + to specify the field. - You can use the web shell below to insert the sample - documents and execute the example update operation: + You can use the web shell below to insert the sample + documents and execute the example update operation: - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-mws.rst - .. code-block:: javascript - - db.books.update( - { _id: 1 }, - { - $inc: { stock: 5 }, - $set: { - item: "ABC123", - "info.publisher": "2222", - tags: [ "software" ], - "ratings.1": { by: "xyz", rating: 3 } - } - } - ) - - In this operation: - - - The ```` parameter of ``{ _id: 1 }`` specifies which - document to update, - - - the :update:`$inc` operator increments the ``stock`` field, - and - - - the :update:`$set` operator replaces the value of the - - - ``item`` field, - - ``publisher`` field in the ``info`` embedded document, - - ``tags`` field, and - - second element in the ``ratings`` array. - - The updated document is the following: - - .. code-block:: javascript - :emphasize-lines: 2,4-6 + .. code-block:: javascript + db.books.update( + { _id: 1 }, { - "_id" : 1, - "item" : "ABC123", - "stock" : 5, - "info" : { "publisher" : "2222", "pages" : 430 }, - "tags" : [ "software" ], - "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "xyz", "rating" : 3 } ], - "reorder" : false + $inc: { stock: 5 }, + $set: { + item: "ABC123", + "info.publisher": "2222", + tags: [ "software" ], + "ratings.1": { by: "xyz", rating: 3 } + } } + ) - This operation corresponds to the following SQL statement: + In this operation: - .. code-block:: sql + - The ```` parameter of ``{ _id: 1 }`` specifies which + document to update, - UPDATE books - SET stock = stock + 5 - item = "ABC123" - publisher = 2222 - pages = 430 - tags = "software" - rating_authors = "ijk,xyz" - rating_values = "4,3" - WHERE _id = 1 + - the :update:`$inc` operator increments the ``stock`` field, + and - .. note:: + - the :update:`$set` operator replaces the value of the - If the ``query`` parameter had matched multiple documents, - this operation would only update one matching document. To - update multiple documents, you must set the ``multi`` option - to ``true``. + - ``item`` field, + - ``publisher`` field in the ``info`` embedded document, + - ``tags`` field, and + - second element in the ``ratings`` array. - .. seealso:: :update:`$set`, :update:`$inc`, - :doc:`/reference/operator/update`, - :ref:`dot notation ` + The updated document is the following: - .. tab:: Push Elements to Existing Array - :tabid: push-elements-existing-array + .. code-block:: javascript + :emphasize-lines: 2,4-6 - .. include:: /includes/fact-update-example-docs-intro.rst + { + "_id" : 1, + "item" : "ABC123", + "stock" : 5, + "info" : { "publisher" : "2222", "pages" : 430 }, + "tags" : [ "software" ], + "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "xyz", "rating" : 3 } ], + "reorder" : false + } - .. include:: /includes/fact-update-example-docs.rst + This operation corresponds to the following SQL statement: - The following operation uses the :update:`$push` update - operator to append a new object to the ``ratings`` array. + .. code-block:: sql - .. only:: website + UPDATE books + SET stock = stock + 5 + item = "ABC123" + publisher = 2222 + pages = 430 + tags = "software" + rating_authors = "ijk,xyz" + rating_values = "4,3" + WHERE _id = 1 - You can use the web shell below to insert the sample - documents and execute the example update operation: + .. note:: - .. include:: /includes/fact-mws.rst + If the ``query`` parameter had matched multiple documents, + this operation would only update one matching document. To + update multiple documents, you must set the ``multi`` option + to ``true``. - .. code-block:: javascript + .. seealso:: - db.books.update( - { _id: 2 }, - { - $push: { ratings: { "by" : "jkl", "rating" : 2 } } - } - ) + :update:`$set`, :update:`$inc`, + :doc:`/reference/operator/update`, + :ref:`dot notation ` - The updated document is the following: + .. tab:: Push Elements to Existing Array + :tabid: push-elements-existing-array - .. code-block:: javascript - :emphasize-lines: 12 + .. include:: /includes/fact-update-example-docs-intro.rst - { - "_id" : 2, - "item" : "XYZ123", - "stock" : 15, - "info" : { - "publisher" : "5555", - "pages" : 150 - }, - "tags" : [ ], - "ratings" : [ - { "by" : "xyz", "rating" : 5 }, - { "by" : "jkl", "rating" : 2 } - ], - "reorder" : false - } + .. include:: /includes/fact-update-example-docs.rst - .. seealso:: + The following operation uses the :update:`$push` update + operator to append a new object to the ``ratings`` array. - :update:`$push` + You can use the web shell below to insert the sample + documents and execute the example update operation: - .. tab:: Remove Fields ($unset) - :tabid: remove-fields + .. include:: /includes/fact-mws.rst - .. include:: /includes/fact-update-example-docs-intro.rst + .. code-block:: javascript - .. include:: /includes/fact-update-example-docs.rst + db.books.update( + { _id: 2 }, + { + $push: { ratings: { "by" : "jkl", "rating" : 2 } } + } + ) + + The updated document is the following: + + .. code-block:: javascript + :emphasize-lines: 12 + + { + "_id" : 2, + "item" : "XYZ123", + "stock" : 15, + "info" : { + "publisher" : "5555", + "pages" : 150 + }, + "tags" : [ ], + "ratings" : [ + { "by" : "xyz", "rating" : 5 }, + { "by" : "jkl", "rating" : 2 } + ], + "reorder" : false + } - The following operation uses the :update:`$unset` operator to remove - the ``tags`` field from the document with ``{ _id: 1 }``. + .. seealso:: - .. only:: website + :update:`$push` - You can use the web shell below to insert the sample - documents and execute the example update operation: + .. tab:: Remove Fields ($unset) + :tabid: remove-fields - .. include:: /includes/fact-mws.rst + .. include:: /includes/fact-update-example-docs-intro.rst - .. code-block:: javascript + .. include:: /includes/fact-update-example-docs.rst - db.books.update( { _id: 1 }, { $unset: { tags: 1 } } ) + The following operation uses the :update:`$unset` operator to remove + the ``tags`` field from the document with ``{ _id: 1 }``. - The updated document is the following: + You can use the web shell below to insert the sample + documents and execute the example update operation: - .. code-block:: javascript + .. include:: /includes/fact-mws.rst - { - "_id" : 1, - "item" : "TBD", - "stock" : 0, - "info" : { - "publisher" : "1111", - "pages" : 430 - }, - "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "lmn", "rating" : 5 } ], - "reorder" : false - } + .. code-block:: javascript - There is not a direct SQL equivalent to :update:`$unset`, - however :update:`$unset` is similar to the following SQL - command which removes the ``tags`` field from the ``books`` - table: + db.books.update( { _id: 1 }, { $unset: { tags: 1 } } ) - .. code-block:: sql + The updated document is the following: - ALTER TABLE books - DROP COLUMN tags + .. code-block:: javascript + + { + "_id" : 1, + "item" : "TBD", + "stock" : 0, + "info" : { + "publisher" : "1111", + "pages" : 430 + }, + "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "lmn", "rating" : 5 } ], + "reorder" : false + } - .. seealso:: :update:`$unset`, :update:`$rename`, :doc:`/reference/operator/update` + There is not a direct SQL equivalent to :update:`$unset`, + however :update:`$unset` is similar to the following SQL + command which removes the ``tags`` field from the ``books`` + table: - .. tab:: Replace Entire Document - :tabid: replace-doc + .. code-block:: sql - .. include:: /includes/fact-update-example-docs-intro.rst + ALTER TABLE books + DROP COLUMN tags - .. include:: /includes/fact-update-example-docs.rst + .. seealso:: - If the ```` document contains *only* ``field:value`` - expressions, then: + :update:`$unset`, :update:`$rename`, :doc:`/reference/operator/update` - - The :method:`db.collection.update()` method *replaces* the matching - document with the ```` document. The - :method:`db.collection.update()` method *does not* replace the - ``_id`` value. + .. tab:: Replace Entire Document + :tabid: replace-doc - - :method:`db.collection.update()` *cannot* update multiple - documents. + .. include:: /includes/fact-update-example-docs-intro.rst - The following operation passes an ```` document that contains - only field and value pairs. The ```` document completely - replaces the original document except for the ``_id`` field. + .. include:: /includes/fact-update-example-docs.rst - .. only:: website + If the ```` document contains *only* ``field:value`` + expressions, then: - You can use the web shell below to insert the sample - documents and execute the example update operation: + - The :method:`db.collection.update()` method *replaces* the matching + document with the ```` document. The + :method:`db.collection.update()` method *does not* replace the + ``_id`` value. - .. include:: /includes/fact-mws.rst + - :method:`db.collection.update()` *cannot* update multiple + documents. - .. code-block:: javascript + The following operation passes an ```` document that contains + only field and value pairs. The ```` document completely + replaces the original document except for the ``_id`` field. - db.books.update( - { _id: 2 }, - { - item: "XYZ123", - stock: 10, - info: { publisher: "2255", pages: 150 }, - tags: [ "baking", "cooking" ] - } - ) + You can use the web shell below to insert the sample + documents and execute the example update operation: - The updated document contains *only* the fields from the - replacement document and the ``_id`` field. As such, the fields - ``ratings`` and ``reorder`` no longer exist in the updated - document since the fields were not in the replacement document. + .. include:: /includes/fact-mws.rst - .. code-block:: javascript + .. code-block:: javascript + db.books.update( + { _id: 2 }, { - "_id" : 2, - "item" : "XYZ123", - "stock" : 10, - "info" : { "publisher" : "2255", "pages" : 150 }, - "tags" : [ "baking", "cooking" ] + item: "XYZ123", + stock: 10, + info: { publisher: "2255", pages: 150 }, + tags: [ "baking", "cooking" ] } + ) - This operation corresponds to the following SQL statements: + The updated document contains *only* the fields from the + replacement document and the ``_id`` field. As such, the fields + ``ratings`` and ``reorder`` no longer exist in the updated + document since the fields were not in the replacement document. - .. code-block:: sql + .. code-block:: javascript - DELETE from books WHERE _id = 2 + { + "_id" : 2, + "item" : "XYZ123", + "stock" : 10, + "info" : { "publisher" : "2255", "pages" : 150 }, + "tags" : [ "baking", "cooking" ] + } - INSERT INTO books - (_id, - item, - stock, - publisher, - pages, - tags) - VALUES (2, - "xyz123", - 10, - "2255", - 150, - "baking,cooking") + This operation corresponds to the following SQL statements: - .. tab:: Update Multiple Documents - :tabid: update-multiple + .. code-block:: sql - .. include:: /includes/fact-update-example-docs-intro.rst + DELETE from books WHERE _id = 2 - .. include:: /includes/fact-update-example-docs.rst + INSERT INTO books + (_id, + item, + stock, + publisher, + pages, + tags) + VALUES (2, + "xyz123", + 10, + "2255", + 150, + "baking,cooking") - If ``multi`` is set to ``true``, the - :method:`db.collection.update()` method updates *all* documents - that meet the ```` criteria. The ``multi`` update - operation may interleave with other read/write operations. + .. tab:: Update Multiple Documents + :tabid: update-multiple - The following operation sets the ``reorder`` field to ``true`` - for all documents where ``stock`` is less than or equal to - ``10``. If the ``reorder`` field does not exist in the matching - document(s), the :update:`$set` operator adds the field - with the specified value. + .. include:: /includes/fact-update-example-docs-intro.rst - .. only:: website + .. include:: /includes/fact-update-example-docs.rst - You can use the web shell below to insert the sample - documents and execute the example update operation: + If ``multi`` is set to ``true``, the + :method:`db.collection.update()` method updates *all* documents + that meet the ```` criteria. The ``multi`` update + operation may interleave with other read/write operations. - .. include:: /includes/fact-mws.rst + The following operation sets the ``reorder`` field to ``true`` + for all documents where ``stock`` is less than or equal to + ``10``. If the ``reorder`` field does not exist in the matching + document(s), the :update:`$set` operator adds the field + with the specified value. - .. code-block:: javascript + You can use the web shell below to insert the sample + documents and execute the example update operation: - db.books.update( - { stock: { $lte: 10 } }, - { $set: { reorder: true } }, - { multi: true } - ) + .. include:: /includes/fact-mws.rst - The resulting documents in the collection are the following: + .. code-block:: javascript - .. code-block:: javascript - :emphasize-lines: 11,19 + db.books.update( + { stock: { $lte: 10 } }, + { $set: { reorder: true } }, + { multi: true } + ) - [ - { - "_id" : 1, - "item" : "ABC123", - "stock" : 5, - "info" : { - "publisher" : "2222", - "pages" : 430 - }, - "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "xyz", "rating" : 3 } ], - "reorder" : true - } - { - "_id" : 2, - "item" : "XYZ123", - "stock" : 10, - "info" : { "publisher" : "2255", "pages" : 150 }, - "tags" : [ "baking", "cooking" ], - "reorder" : true - } - ] + The resulting documents in the collection are the following: + + .. code-block:: javascript + :emphasize-lines: 11,19 + + [ + { + "_id" : 1, + "item" : "ABC123", + "stock" : 5, + "info" : { + "publisher" : "2222", + "pages" : 430 + }, + "ratings" : [ { "by" : "ijk", "rating" : 4 }, { "by" : "xyz", "rating" : 3 } ], + "reorder" : true + } + { + "_id" : 2, + "item" : "XYZ123", + "stock" : 10, + "info" : { "publisher" : "2255", "pages" : 150 }, + "tags" : [ "baking", "cooking" ], + "reorder" : true + } + ] - This operation corresponds to the following SQL statement: + This operation corresponds to the following SQL statement: - .. code-block:: sql + .. code-block:: sql - UPDATE books - SET reorder=true - WHERE stock <= 10 + UPDATE books + SET reorder=true + WHERE stock <= 10 - .. note:: + .. note:: - You cannot specify ``multi: true`` when performing a - replacement, i.e., when the :ref:`\ - ` document contains *only* - ``field:value`` expressions. + You cannot specify ``multi: true`` when performing a + replacement, i.e., when the :ref:`\ + ` document contains *only* + ``field:value`` expressions. - .. seealso:: + .. seealso:: - :update:`$set` + :update:`$set` .. _example-update-upsert: .. _upsert-parameter: @@ -791,295 +781,299 @@ include the full shard key in the ``filter``. For additional :method:`db.collection.update()` behavior on a sharded collection, see :ref:`update-sharded-collection`. -.. container:: - - .. tabs:: - - .. tab:: Upsert with Replacement Document - :tabid: upsert-example - - If no document matches the query criteria and the ```` - parameter is a replacement document (i.e., contains only field - and value pairs), the update inserts a new document with the - fields and values of the replacement document. - - - If you specify an ``_id`` field in either the query parameter - or replacement document, MongoDB uses that ``_id`` field in the - inserted document. - - - If you do not specify an ``_id`` field in either the query - parameter or replacement document, MongoDB generates adds the - ``_id`` field with a randomly generated :ref:`objectid` - value. - - .. note:: - - You cannot specify different ``_id`` field values in the - query parameter and replacement document. If you do, the - operation errors. - - For example, the following update sets the :ref:`upsert - ` option to ``true``: - - .. code-block:: javascript - :emphasize-lines: 8 - - db.books.update( - { item: "ZZZ135" }, // Query parameter - { // Replacement document - item: "ZZZ135", - stock: 5, - tags: [ "database" ] - }, - { upsert: true } // Options - ) - - If no document matches the ```` parameter, the update - operation inserts a document with *only* the replacement - document. Because no ``_id`` field was specified in the - replacement document or query document, the operation creates a - new unique ``ObjectId`` for the new document's ``_id`` field. - You can see the ``upsert`` reflected in the :ref:`WriteResult - ` of the operation: - - .. code-block:: javascript - :copyable: false - - WriteResult({ - "nMatched" : 0, - "nUpserted" : 1, - "nModified" : 0, - "_id" : ObjectId("5da78973835b2f1c75347a83") - }) - - The operation inserts the following document into the ``books`` - collection (your :ref:`objectid` value will differ): - - .. code-block:: javascript - - { - "_id" : ObjectId("5da78973835b2f1c75347a83"), - "item" : "ZZZ135", - "stock" : 5, - "tags" : [ "database" ] - } - - .. tab:: Upsert with Operator Expressions - :tabid: upsert-op-expr - - If no document matches the query criteria and the ```` - parameter is a document with :ref:`update operator expressions - `, then the operation creates a base document - from the equality clauses in the ```` parameter and - applies the expressions from the ```` parameter. - - :doc:`Comparison ` operations from - the ```` will not be included in the new document. If - the new document does not include the ``_id`` field, MongoDB - adds the ``_id`` field with an :ref:`objectid` value. - - For example, the following update sets the :ref:`upsert - ` option to ``true``: - - .. code-block:: javascript - - db.books.update( - { item: "BLP921" }, // Query parameter - { // Update document - $set: { reorder: false }, - $setOnInsert: { stock: 10 } - }, - { upsert: true } // Options - ) - - If no documents match the query condition, the operation - inserts the following document (your :ref:`objectid` value - will differ): - - .. code-block:: javascript - - { - "_id" : ObjectId("5da79019835b2f1c75348a0a"), - "item" : "BLP921", - "reorder" : false, - "stock" : 10 - } - - .. seealso:: :update:`$setOnInsert` - - .. tab:: Aggregation Pipeline using Upsert - :tabid: agg-pipeline-upsert - - If the ```` parameter is an :ref:`aggregation pipeline - `, the update creates a base - document from the equality clauses in the ```` - parameter, and then applies the pipeline to the document to - create the document to insert. If the new document does not - include the ``_id`` field, MongoDB adds the ``_id`` field with - an :ref:`objectid` value. - - For example, the following :ref:`upsert: true - ` operation specifies an aggregation pipeline that uses - - - the :pipeline:`$replaceRoot` stage which can provide - somewhat similar behavior to a :update:`$setOnInsert` - update operator expression, - - - the :pipeline:`$set` stage which can provide similar - behavior to the :update:`$set` update operator expression, - - - the aggregation variable :variable:`NOW`, which resolves to - the current datetime and can provide similar behavior to the - :update:`$currentDate` update operator expression. - - .. code-block:: javascript - - db.books.update( - { item: "MRQ014", ratings: [2, 5, 3] }, // Query parameter - [ // Aggregation pipeline - { $replaceRoot: { newRoot: { $mergeObjects: [ { stock: 0 }, "$$ROOT" ] } } }, - { $set: { avgRating: { $avg: "$ratings" }, tags: [ "fiction", "murder" ], lastModified: "$$NOW" } } - ], - { upsert: true } // Options - ) - - If no document matches the ```` parameter, the - operation inserts the following document into the ``books`` - collection (your :ref:`objectid` value will differ): - - .. code-block:: javascript - - { - "_id" : ObjectId("5e2921e0b4c550aad59d1ba9"), - "stock" : 0, - "item" : "MRQ014", - "ratings" : [ 2, 5, 3 ], - "avgRating" : 3.3333333333333335, - "tags" : [ "fiction", "murder" ], - "lastModified" : ISODate("2020-01-23T04:32:32.951Z") - } - - .. seealso:: For additional examples of updates using - aggregation pipelines, see :ref:`update-behavior-agg-pipeline`. - - .. tab:: Combine Upsert and Multi Options - :tabid: combine-upsert-multi - - Combine Upsert and Multi Options (Match) - ```````````````````````````````````````` - - From the :binary:`~bin.mongo` shell, insert the following - documents into a ``books`` collection: - - .. code-block:: javascript - - db.books.insertMany([ - { - _id: 5, - item: "RQM909", - stock: 18, - info: { publisher: "0000", pages: 170 }, - reorder: true - }, - { - _id: 6, - item: "EFG222", - stock: 15, - info: { publisher: "1111", pages: 72 }, - reorder: true - } - ]) - - The following operation specifies both the ``multi`` option and - the ``upsert`` option. If matching documents exist, the - operation updates all matching documents. If no matching - documents exist, the operation inserts a new document. - - .. code-block:: javascript - - db.books.update( - { stock: { $gte: 10 } }, // Query parameter - { // Update document - $set: { reorder: false, tags: [ "literature", "translated" ] } - }, - { upsert: true, multi: true } // Options - ) - - The operation updates all matching documents and results in the - following: - - .. code-block:: javascript - - { - "_id" : 5, - "item" : "RQM909", - "stock" : 18, - "info" : { "publisher" : "0000", "pages" : 170 }, - "reorder" : false, - "tags" : [ "literature", "translated" ] - } - { - "_id" : 6, - "item" : "EFG222", - "stock" : 15, - "info" : { "publisher" : "1111", "pages" : 72 }, - "reorder" : false, - "tags" : [ "literature", "translated" ] - } - - Combine Upsert and Multi Options (No Match) - ``````````````````````````````````````````` - - If the collection had *no* matching document, the operation - would result in the insertion of a single document using the - fields from both the ```` and the ```` - specifications. For example, consider the following operation: - - .. code-block:: javascript - - db.books.update( - { "info.publisher": "Self-Published" }, // Query parameter - { // Update document - $set: { reorder: false, tags: [ "literature", "hardcover" ], stock: 25 } - }, - { upsert: true, multi: true } // Options - ) - - The operation inserts the following document into the ``books`` - collection (your :ref:`objectid` value will differ): - - .. code-block:: javascript - - { - "_id" : ObjectId("5db337934f670d584b6ca8e0"), - "info" : { "publisher" : "Self-Published" }, - "reorder" : false, - "stock" : 25, - "tags" : [ "literature", "hardcover" ] - } - - .. tab:: Upsert with Dotted _id Query - :tabid: upsert-dotted-id - - .. include:: /includes/fact-upsert-id.rst - - The ``WriteResult`` of the operation returns the following - error: - - .. code-block:: javascript - :copyable: false - - WriteResult({ - "nMatched" : 0, - "nUpserted" : 0, - "nModified" : 0, - "writeError" : { - "code" : 111, - "errmsg" : "field at '_id' must be exactly specified, field at sub-path '_id.name'found" - } - }) - - .. seealso:: :method:`WriteResult()` +.. tabs:: + + .. tab:: Upsert with Replacement Document + :tabid: upsert-example + + If no document matches the query criteria and the ```` + parameter is a replacement document (i.e., contains only field + and value pairs), the update inserts a new document with the + fields and values of the replacement document. + + - If you specify an ``_id`` field in either the query parameter + or replacement document, MongoDB uses that ``_id`` field in the + inserted document. + + - If you do not specify an ``_id`` field in either the query + parameter or replacement document, MongoDB generates adds the + ``_id`` field with a randomly generated :ref:`objectid` + value. + + .. note:: + + You cannot specify different ``_id`` field values in the + query parameter and replacement document. If you do, the + operation errors. + + For example, the following update sets the :ref:`upsert + ` option to ``true``: + + .. code-block:: javascript + :emphasize-lines: 8 + + db.books.update( + { item: "ZZZ135" }, // Query parameter + { // Replacement document + item: "ZZZ135", + stock: 5, + tags: [ "database" ] + }, + { upsert: true } // Options + ) + + If no document matches the ```` parameter, the update + operation inserts a document with *only* the replacement + document. Because no ``_id`` field was specified in the + replacement document or query document, the operation creates a + new unique ``ObjectId`` for the new document's ``_id`` field. + You can see the ``upsert`` reflected in the :ref:`WriteResult + ` of the operation: + + .. code-block:: javascript + :copyable: false + + WriteResult({ + "nMatched" : 0, + "nUpserted" : 1, + "nModified" : 0, + "_id" : ObjectId("5da78973835b2f1c75347a83") + }) + + The operation inserts the following document into the ``books`` + collection (your :ref:`objectid` value will differ): + + .. code-block:: javascript + + { + "_id" : ObjectId("5da78973835b2f1c75347a83"), + "item" : "ZZZ135", + "stock" : 5, + "tags" : [ "database" ] + } + + .. tab:: Upsert with Operator Expressions + :tabid: upsert-op-expr + + If no document matches the query criteria and the ```` + parameter is a document with :ref:`update operator expressions + `, then the operation creates a base document + from the equality clauses in the ```` parameter and + applies the expressions from the ```` parameter. + + :doc:`Comparison ` operations from + the ```` will not be included in the new document. If + the new document does not include the ``_id`` field, MongoDB + adds the ``_id`` field with an :ref:`objectid` value. + + For example, the following update sets the :ref:`upsert + ` option to ``true``: + + .. code-block:: javascript + + db.books.update( + { item: "BLP921" }, // Query parameter + { // Update document + $set: { reorder: false }, + $setOnInsert: { stock: 10 } + }, + { upsert: true } // Options + ) + + If no documents match the query condition, the operation + inserts the following document (your :ref:`objectid` value + will differ): + + .. code-block:: javascript + + { + "_id" : ObjectId("5da79019835b2f1c75348a0a"), + "item" : "BLP921", + "reorder" : false, + "stock" : 10 + } + + .. seealso:: + + :update:`$setOnInsert` + + .. tab:: Aggregation Pipeline using Upsert + :tabid: agg-pipeline-upsert + + If the ```` parameter is an :ref:`aggregation pipeline + `, the update creates a base + document from the equality clauses in the ```` + parameter, and then applies the pipeline to the document to + create the document to insert. If the new document does not + include the ``_id`` field, MongoDB adds the ``_id`` field with + an :ref:`objectid` value. + + For example, the following :ref:`upsert: true + ` operation specifies an aggregation pipeline that uses + + - the :pipeline:`$replaceRoot` stage which can provide + somewhat similar behavior to a :update:`$setOnInsert` + update operator expression, + + - the :pipeline:`$set` stage which can provide similar + behavior to the :update:`$set` update operator expression, + + - the aggregation variable :variable:`NOW`, which resolves to + the current datetime and can provide similar behavior to the + :update:`$currentDate` update operator expression. + + .. code-block:: javascript + + db.books.update( + { item: "MRQ014", ratings: [2, 5, 3] }, // Query parameter + [ // Aggregation pipeline + { $replaceRoot: { newRoot: { $mergeObjects: [ { stock: 0 }, "$$ROOT" ] } } }, + { $set: { avgRating: { $avg: "$ratings" }, tags: [ "fiction", "murder" ], lastModified: "$$NOW" } } + ], + { upsert: true } // Options + ) + + If no document matches the ```` parameter, the + operation inserts the following document into the ``books`` + collection (your :ref:`objectid` value will differ): + + .. code-block:: javascript + + { + "_id" : ObjectId("5e2921e0b4c550aad59d1ba9"), + "stock" : 0, + "item" : "MRQ014", + "ratings" : [ 2, 5, 3 ], + "avgRating" : 3.3333333333333335, + "tags" : [ "fiction", "murder" ], + "lastModified" : ISODate("2020-01-23T04:32:32.951Z") + } + + .. seealso:: + + For additional examples of updates using + aggregation pipelines, see :ref:`update-behavior-agg-pipeline`. + + .. tab:: Combine Upsert and Multi Options + :tabid: combine-upsert-multi + + Combine Upsert and Multi Options (Match) + ```````````````````````````````````````` + + From the :binary:`~bin.mongo` shell, insert the following + documents into a ``books`` collection: + + .. code-block:: javascript + + db.books.insertMany([ + { + _id: 5, + item: "RQM909", + stock: 18, + info: { publisher: "0000", pages: 170 }, + reorder: true + }, + { + _id: 6, + item: "EFG222", + stock: 15, + info: { publisher: "1111", pages: 72 }, + reorder: true + } + ]) + + The following operation specifies both the ``multi`` option and + the ``upsert`` option. If matching documents exist, the + operation updates all matching documents. If no matching + documents exist, the operation inserts a new document. + + .. code-block:: javascript + + db.books.update( + { stock: { $gte: 10 } }, // Query parameter + { // Update document + $set: { reorder: false, tags: [ "literature", "translated" ] } + }, + { upsert: true, multi: true } // Options + ) + + The operation updates all matching documents and results in the + following: + + .. code-block:: javascript + + { + "_id" : 5, + "item" : "RQM909", + "stock" : 18, + "info" : { "publisher" : "0000", "pages" : 170 }, + "reorder" : false, + "tags" : [ "literature", "translated" ] + } + { + "_id" : 6, + "item" : "EFG222", + "stock" : 15, + "info" : { "publisher" : "1111", "pages" : 72 }, + "reorder" : false, + "tags" : [ "literature", "translated" ] + } + + Combine Upsert and Multi Options (No Match) + ``````````````````````````````````````````` + + If the collection had *no* matching document, the operation + would result in the insertion of a single document using the + fields from both the ```` and the ```` + specifications. For example, consider the following operation: + + .. code-block:: javascript + + db.books.update( + { "info.publisher": "Self-Published" }, // Query parameter + { // Update document + $set: { reorder: false, tags: [ "literature", "hardcover" ], stock: 25 } + }, + { upsert: true, multi: true } // Options + ) + + The operation inserts the following document into the ``books`` + collection (your :ref:`objectid` value will differ): + + .. code-block:: javascript + + { + "_id" : ObjectId("5db337934f670d584b6ca8e0"), + "info" : { "publisher" : "Self-Published" }, + "reorder" : false, + "stock" : 25, + "tags" : [ "literature", "hardcover" ] + } + + .. tab:: Upsert with Dotted _id Query + :tabid: upsert-dotted-id + + .. include:: /includes/fact-upsert-id.rst + + The ``WriteResult`` of the operation returns the following + error: + + .. code-block:: javascript + :copyable: false + + WriteResult({ + "nMatched" : 0, + "nUpserted" : 0, + "nModified" : 0, + "writeError" : { + "code" : 111, + "errmsg" : "field at '_id' must be exactly specified, field at sub-path '_id.name'found" + } + }) + + .. seealso:: + + :method:`WriteResult()` .. _update-with-unique-indexes: @@ -1129,7 +1123,9 @@ The remaining operations would either: applications may retry the operation which will succeed as an update operation. -.. seealso:: :update:`$setOnInsert` +.. seealso:: + + :update:`$setOnInsert` .. _update-behavior-agg-pipeline: .. _update-example-agg: @@ -1152,141 +1148,141 @@ field values or updating one field using the value of another field(s). Modify a Field Using the Values of the Other Fields in the Document ``````````````````````````````````````````````````````````````````` -.. container:: +Create a ``members`` collection with the following documents: - Create a ``members`` collection with the following documents: +.. code-block:: javascript - .. code-block:: javascript + db.members.insertMany([ + { "_id" : 1, "member" : "abc123", "status" : "A", "points" : 2, "misc1" : "note to self: confirm status", "misc2" : "Need to activate", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }, + { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") } + ]) - db.members.insertMany([ - { "_id" : 1, "member" : "abc123", "status" : "A", "points" : 2, "misc1" : "note to self: confirm status", "misc2" : "Need to activate", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }, - { "_id" : 2, "member" : "xyz123", "status" : "A", "points" : 60, "misc1" : "reminder: ping me at 100pts", "misc2" : "Some random comment", "lastUpdate" : ISODate("2019-01-01T00:00:00Z") } - ]) +Assume that instead of separate ``misc1`` and ``misc2`` fields, you +want to gather these into a new ``comments`` field. The following +update operation uses an aggregation pipeline to: - Assume that instead of separate ``misc1`` and ``misc2`` fields, you - want to gather these into a new ``comments`` field. The following - update operation uses an aggregation pipeline to: +- add the new ``comments`` field and set the ``lastUpdate`` field. - - add the new ``comments`` field and set the ``lastUpdate`` field. +- remove the ``misc1`` and ``misc2`` fields for all documents in the + collection. - - remove the ``misc1`` and ``misc2`` fields for all documents in the - collection. +.. code-block:: javascript - .. code-block:: javascript + db.members.update( + { }, + [ + { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ], lastUpdate: "$$NOW" } }, + { $unset: [ "misc1", "misc2" ] } + ], + { multi: true } + ) - db.members.update( - { }, - [ - { $set: { status: "Modified", comments: [ "$misc1", "$misc2" ], lastUpdate: "$$NOW" } }, - { $unset: [ "misc1", "misc2" ] } - ], - { multi: true } - ) +.. note:: - .. note:: + The ``$set`` and ``$unset`` used in the pipeline refers to the + aggregation stages :pipeline:`$set` and :pipeline:`$unset` + respectively, and not the update operators :update:`$set` and + :update:`$unset`. - The ``$set`` and ``$unset`` used in the pipeline refers to the - aggregation stages :pipeline:`$set` and :pipeline:`$unset` - respectively, and not the update operators :update:`$set` and - :update:`$unset`. +First Stage + The :pipeline:`$set` stage: - First Stage - The :pipeline:`$set` stage: + - creates a new array field ``comments`` whose elements are the current + content of the ``misc1`` and ``misc2`` fields and - - creates a new array field ``comments`` whose elements are the current - content of the ``misc1`` and ``misc2`` fields and + - sets the field ``lastUpdate`` to the value of the aggregation + variable :variable:`NOW`. The aggregation variable + :variable:`NOW` resolves to the current datetime value and remains + the same throughout the pipeline. To access aggregation + variables, prefix the variable with double dollar signs ``$$`` + and enclose in quotes. - - sets the field ``lastUpdate`` to the value of the aggregation - variable :variable:`NOW`. The aggregation variable - :variable:`NOW` resolves to the current datetime value and remains - the same throughout the pipeline. To access aggregation - variables, prefix the variable with double dollar signs ``$$`` - and enclose in quotes. +Second Stage + The :pipeline:`$unset` stage removes the ``misc1`` and ``misc2`` fields. - Second Stage - The :pipeline:`$unset` stage removes the ``misc1`` and ``misc2`` fields. +After the command, the collection contains the following documents: - After the command, the collection contains the following documents: +.. code-block:: javascript - .. code-block:: javascript + { "_id" : 1, "member" : "abc123", "status" : "Modified", "points" : 2, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "note to self: confirm status", "Need to activate" ] } + { "_id" : 2, "member" : "xyz123", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "reminder: ping me at 100pts", "Some random comment" ] } - { "_id" : 1, "member" : "abc123", "status" : "Modified", "points" : 2, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "note to self: confirm status", "Need to activate" ] } - { "_id" : 2, "member" : "xyz123", "status" : "Modified", "points" : 60, "lastUpdate" : ISODate("2020-01-23T05:11:45.784Z"), "comments" : [ "reminder: ping me at 100pts", "Some random comment" ] } +.. seealso:: - .. seealso:: :doc:`/tutorial/update-documents-with-aggregation-pipeline` + :doc:`/tutorial/update-documents-with-aggregation-pipeline` Perform Conditional Updates Based on Current Field Values ````````````````````````````````````````````````````````` -.. container:: +Create a ``students3`` collection with the following documents: - Create a ``students3`` collection with the following documents: +.. code-block:: javascript - .. code-block:: javascript + db.students3.insert([ + { "_id" : 1, "tests" : [ 95, 92, 90 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }, + { "_id" : 2, "tests" : [ 94, 88, 90 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }, + { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") } + ]); - db.students3.insert([ - { "_id" : 1, "tests" : [ 95, 92, 90 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }, - { "_id" : 2, "tests" : [ 94, 88, 90 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") }, - { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2019-01-01T00:00:00Z") } - ]); +Using an aggregation pipeline, you can update the documents with the +calculated grade average and letter grade. - Using an aggregation pipeline, you can update the documents with the - calculated grade average and letter grade. +.. code-block:: javascript - .. code-block:: javascript + db.students3.update( + { }, + [ + { $set: { average : { $trunc: [ { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } }, + { $set: { grade: { $switch: { + branches: [ + { case: { $gte: [ "$average", 90 ] }, then: "A" }, + { case: { $gte: [ "$average", 80 ] }, then: "B" }, + { case: { $gte: [ "$average", 70 ] }, then: "C" }, + { case: { $gte: [ "$average", 60 ] }, then: "D" } + ], + default: "F" + } } } } + ], + { multi: true } + ) - db.students3.update( - { }, - [ - { $set: { average : { $trunc: [ { $avg: "$tests" }, 0 ] }, lastUpdate: "$$NOW" } }, - { $set: { grade: { $switch: { - branches: [ - { case: { $gte: [ "$average", 90 ] }, then: "A" }, - { case: { $gte: [ "$average", 80 ] }, then: "B" }, - { case: { $gte: [ "$average", 70 ] }, then: "C" }, - { case: { $gte: [ "$average", 60 ] }, then: "D" } - ], - default: "F" - } } } } - ], - { multi: true } - ) - - .. note:: - - The ``$set`` used in the pipeline refers to the aggregation stage - :pipeline:`$set`, and not the update operators :update:`$set`. - - First Stage - The :pipeline:`$set` stage: - - - calculates a new field ``average`` based on the average of the - ``tests`` field. See :group:`$avg` for more information on the - ``$avg`` aggregation operator and :expression:`$trunc` for more - information on the ``$trunc`` truncate aggregation operator. - - - sets the field ``lastUpdate`` to the value of the aggregation - variable :variable:`NOW`. The aggregation variable - :variable:`NOW` resolves to the current datetime value and remains - the same throughout the pipeline. To access aggregation - variables, prefix the variable with double dollar signs ``$$`` - and enclose in quotes. - - Second Stage - The :pipeline:`$set` stage calculates a new field ``grade`` based on - the ``average`` field calculated in the previous stage. See - :expression:`$switch` for more information on the ``$switch`` - aggregation operator. - - After the command, the collection contains the following documents: - - .. code-block:: javascript - - { "_id" : 1, "tests" : [ 95, 92, 90 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 92, "grade" : "A" } - { "_id" : 2, "tests" : [ 94, 88, 90 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 90, "grade" : "A" } - { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 75, "grade" : "C" } - - .. seealso:: :doc:`/tutorial/update-documents-with-aggregation-pipeline` +.. note:: + + The ``$set`` used in the pipeline refers to the aggregation stage + :pipeline:`$set`, and not the update operators :update:`$set`. + +First Stage + The :pipeline:`$set` stage: + + - calculates a new field ``average`` based on the average of the + ``tests`` field. See :group:`$avg` for more information on the + ``$avg`` aggregation operator and :expression:`$trunc` for more + information on the ``$trunc`` truncate aggregation operator. + + - sets the field ``lastUpdate`` to the value of the aggregation + variable :variable:`NOW`. The aggregation variable + :variable:`NOW` resolves to the current datetime value and remains + the same throughout the pipeline. To access aggregation + variables, prefix the variable with double dollar signs ``$$`` + and enclose in quotes. + +Second Stage + The :pipeline:`$set` stage calculates a new field ``grade`` based on + the ``average`` field calculated in the previous stage. See + :expression:`$switch` for more information on the ``$switch`` + aggregation operator. + +After the command, the collection contains the following documents: + +.. code-block:: javascript + + { "_id" : 1, "tests" : [ 95, 92, 90 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 92, "grade" : "A" } + { "_id" : 2, "tests" : [ 94, 88, 90 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 90, "grade" : "A" } + { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:29:35.340Z"), "average" : 75, "grade" : "C" } + +.. seealso:: + + :doc:`/tutorial/update-documents-with-aggregation-pipeline` .. _update-arrayFilters: @@ -1572,7 +1568,9 @@ inserted by the update, and the number of documents modified: WriteResult({ "nMatched" : 1, "nUpserted" : 0, "nModified" : 1 }) -.. see:: :data:`WriteResult.nMatched`, :data:`WriteResult.nUpserted`, +.. see:: + + :data:`WriteResult.nMatched`, :data:`WriteResult.nUpserted`, :data:`WriteResult.nModified` Write Concern Errors @@ -1608,7 +1606,10 @@ The following table explains the possible values of .. include:: /includes/fact-wc-provenance-table.rst -.. seealso:: :method:`WriteResult.hasWriteConcernError()` +.. seealso:: + + :method:`WriteResult.hasWriteConcernError()` + Errors Unrelated to Write Concern ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1629,4 +1630,7 @@ field: } }) -.. seealso:: :method:`WriteResult.hasWriteError()` +.. seealso:: + + :method:`WriteResult.hasWriteError()` + diff --git a/source/reference/method/db.collection.updateMany.txt b/source/reference/method/db.collection.updateMany.txt index 6d99de2dfda..8d8684c5fcd 100644 --- a/source/reference/method/db.collection.updateMany.txt +++ b/source/reference/method/db.collection.updateMany.txt @@ -531,7 +531,9 @@ After the command, the collection contains the following documents: { "_id" : 2, "tests" : [ 94, 88, 90 ], "lastUpdate" : ISODate("2020-01-24T17:31:01.670Z"), "average" : 90, "grade" : "A" } { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:31:01.670Z"), "average" : 75, "grade" : "C" } -.. seealso:: :doc:`/tutorial/update-documents-with-aggregation-pipeline` +.. seealso:: + + :doc:`/tutorial/update-documents-with-aggregation-pipeline` .. _updateMany-example-update-multiple-documents-with-upsert: @@ -670,8 +672,6 @@ Update Elements Match ``arrayFilters`` Criteria Create a collection ``students`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.insert([ @@ -684,8 +684,6 @@ To update all elements that are greater than or equal to ``100`` in the ``grades`` array, use the filtered positional operator :update:`$[\]` with the ``arrayFilters`` option: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.updateMany( @@ -708,8 +706,6 @@ Update Specific Elements of an Array of Documents Create a collection ``students2`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.students2.insert([ @@ -737,8 +733,6 @@ To modify the value of the ``mean`` field for all elements in the use the filtered positional operator :update:`$[\]` with the ``arrayFilters``: -.. cssclass:: copyable-code - .. code-block:: javascript db.students2.updateMany( diff --git a/source/reference/method/db.collection.updateOne.txt b/source/reference/method/db.collection.updateOne.txt index 1c2e099c50d..360391ce59e 100644 --- a/source/reference/method/db.collection.updateOne.txt +++ b/source/reference/method/db.collection.updateOne.txt @@ -4,8 +4,7 @@ db.collection.updateOne() .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -317,74 +316,70 @@ To use :method:`db.collection.updateOne()` on a sharded collection: Shard Key Modification `````````````````````` -.. container:: +.. include:: /includes/limits-sharding-shardkey-document-immutable.rst - .. include:: /includes/limits-sharding-shardkey-document-immutable.rst +.. include:: /includes/shard-key-modification-warning.rst - .. include:: /includes/shard-key-modification-warning.rst +To modify the **existing** shard key value with +:method:`db.collection.updateOne()`: - To modify the **existing** shard key value with - :method:`db.collection.updateOne()`: - - - You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` - issue the operation directly on the shard. +- You :red:`must` run on a :binary:`~bin.mongos`. Do :red:`not` + issue the operation directly on the shard. - - You :red:`must` run either in a :doc:`transaction - ` or as a :doc:`retryable write - `. +- You :red:`must` run either in a :doc:`transaction + ` or as a :doc:`retryable write + `. - - You :red:`must` include an equality :ref:`filter - ` on the full shard key. - - See also :ref:`updateOne-sharded-upsert`. +- You :red:`must` include an equality :ref:`filter + ` on the full shard key. + +See also :ref:`updateOne-sharded-upsert`. .. _updateOne-missing-shard-key: Missing Shard Key ````````````````` -.. container:: +Starting in version 4.4, documents in a sharded collection can be +:ref:`missing the shard key fields `. To use +:method:`db.collection.updateOne()` to set the document's +**missing** shard key, you :red:`must` run on a +:binary:`~bin.mongos`. Do :red:`not` issue the operation directly on +the shard. - Starting in version 4.4, documents in a sharded collection can be - :ref:`missing the shard key fields `. To use - :method:`db.collection.updateOne()` to set the document's - **missing** shard key, you :red:`must` run on a - :binary:`~bin.mongos`. Do :red:`not` issue the operation directly on - the shard. - - In addition, the following requirements also apply: +In addition, the following requirements also apply: - .. list-table:: - :header-rows: 1 - :widths: 30 70 +.. list-table:: + :header-rows: 1 + :widths: 30 70 - * - + * - - - Requirements + - Requirements - * - To set to ``null`` + * - To set to ``null`` - - - Requires equality filter on the full shard key if - ``upsert: true``. + - - Requires equality filter on the full shard key if + ``upsert: true``. - * - To set to a non-``null`` value + * - To set to a non-``null`` value - - - :red:`Must` be performed either inside a - :doc:`transaction ` or as a - :doc:`retryable write `. + - - :red:`Must` be performed either inside a + :doc:`transaction ` or as a + :doc:`retryable write `. - - Requires equality filter on the full shard key if ``upsert: - true``. + - Requires equality filter on the full shard key if ``upsert: + true``. - .. tip:: +.. tip:: - .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst + .. include:: /includes/extracts/missing-shard-key-equality-condition-abridged.rst - See also: - - - :ref:`updateOne-sharded-upsert` - - - :ref:`shard-key-missing` +See also: + +- :ref:`updateOne-sharded-upsert` + +- :ref:`shard-key-missing` Explainability ~~~~~~~~~~~~~~ @@ -614,7 +609,9 @@ After the command, the collection contains the following documents: { "_id" : 2, "tests" : [ 94, 88, 90 ], "average" : 91, "grade" : "A", "lastUpdate" : ISODate("2020-01-23T05:18:40.013Z") } { "_id" : 3, "tests" : [ 70, 75, 82 ], "lastUpdate" : ISODate("2020-01-24T17:33:30.674Z"), "average" : 75, "grade" : "C" } -.. seealso:: :doc:`/tutorial/update-documents-with-aggregation-pipeline` +.. seealso:: + + :doc:`/tutorial/update-documents-with-aggregation-pipeline` .. _updateOne-example-update-with-upsert: @@ -943,5 +940,7 @@ To view the indexes used, you can use the :pipeline:`$indexStats` pipeline: db.members.aggregate( [ { $indexStats: { } }, { $sort: { name: 1 } } ] ) -.. seealso:: To update multiple documents, see +.. seealso:: + + To update multiple documents, see :method:`db.collection.updateMany()`. diff --git a/source/reference/method/db.collection.validate.txt b/source/reference/method/db.collection.validate.txt index 9582668bcb8..9e5d2838893 100644 --- a/source/reference/method/db.collection.validate.txt +++ b/source/reference/method/db.collection.validate.txt @@ -30,8 +30,8 @@ Description Syntax ------ -.. admonition:: Changed in version 4.4 - :class: note +.. note:: Changed in version 4.4 + :method:`db.collection.validate()` no longer accepts just a boolean parameter. See :ref:`4.4-validate-method-signature`. diff --git a/source/reference/method/db.collection.watch.txt b/source/reference/method/db.collection.watch.txt index ef69e4df2ea..23946f66b35 100644 --- a/source/reference/method/db.collection.watch.txt +++ b/source/reference/method/db.collection.watch.txt @@ -194,7 +194,9 @@ Definition See :doc:`/reference/change-events` for examples of change event documents. - .. seealso:: :method:`db.watch()` and :method:`Mongo.watch()` + .. seealso:: + + :method:`db.watch()` and :method:`Mongo.watch()` Availability diff --git a/source/reference/method/db.copyDatabase.txt b/source/reference/method/db.copyDatabase.txt index 49a9e160664..9d61021122b 100644 --- a/source/reference/method/db.copyDatabase.txt +++ b/source/reference/method/db.copyDatabase.txt @@ -105,7 +105,7 @@ Definition .. versionchanged:: 4.0 - :method:`copyDatabase()` no longer supports ``MONGODB-CR`` to + :method:`db.copyDatabase()` no longer supports ``MONGODB-CR`` to authenticate to the ``fromhost``. diff --git a/source/reference/method/db.createCollection.txt b/source/reference/method/db.createCollection.txt index 31cbac46302..0ff1f1a28dd 100644 --- a/source/reference/method/db.createCollection.txt +++ b/source/reference/method/db.createCollection.txt @@ -30,8 +30,8 @@ Definition The :method:`db.createCollection()` method has the following prototype form: - .. admonition:: Starting in MongoDB 4.2 - :class: note + .. note:: Starting in MongoDB 4.2 + MongoDB removes the MMAPv1 storage engine and the MMAPv1 specific options ``paddingFactor``, ``paddingBytes``, ``preservePadding`` @@ -399,8 +399,6 @@ Schema validator: MongoDB 3.6 adds the :query:`$jsonSchema` operator to support JSON Schema validation. -.. cssclass:: copyable-code - .. code-block:: json db.createCollection( "contacts", { @@ -433,8 +431,6 @@ With the validator in place, the following insert operation fails validation: The method returns the error in the ``WriteResult``: -.. cssclass:: copyable-code - .. code-block:: javascript WriteResult({ @@ -499,7 +495,9 @@ The same operation on a collection that uses simple binary collation { "_id" : 2, "category" : "cafe" } { "_id" : 1, "category" : "café" } -.. seealso:: :ref:`create-view-w-collation` +.. seealso:: + + :ref:`create-view-w-collation` .. _create-collection-storage-engine-options: diff --git a/source/reference/method/db.createRole.txt b/source/reference/method/db.createRole.txt index e94f6dee855..cb8343140b3 100644 --- a/source/reference/method/db.createRole.txt +++ b/source/reference/method/db.createRole.txt @@ -13,7 +13,7 @@ db.createRole() Definition ---------- -.. method:: db.createRole ( role, writeConcern ) +.. method:: db.createRole(role, writeConcern) Creates a role in a database. You can specify privileges for the role by explicitly listing the privileges or by having the role diff --git a/source/reference/method/db.createUser.txt b/source/reference/method/db.createUser.txt index d9099eabaa8..8abc71e8b09 100644 --- a/source/reference/method/db.createUser.txt +++ b/source/reference/method/db.createUser.txt @@ -13,7 +13,7 @@ db.createUser() Definition ---------- -.. method:: db.createUser ( user, writeConcern ) +.. method:: db.createUser(user, writeConcern) Creates a new user for the database on which the method is run. :method:`db.createUser()` returns a *duplicate user* error if the diff --git a/source/reference/method/db.createView.txt b/source/reference/method/db.createView.txt index 4c0df0e9d03..e6d45cb8c93 100644 --- a/source/reference/method/db.createView.txt +++ b/source/reference/method/db.createView.txt @@ -211,7 +211,7 @@ Perform Aggregation Pipeline on a View `````````````````````````````````````` The following operation performs an aggregation on the -``managementFeedback`` view, using the :expression:`$sortByCount` to +``managementFeedback`` view, using the :pipeline:`$sortByCount` to group by the ``department`` field and sort in descending order by the count of each distinct department: @@ -320,7 +320,7 @@ Perform Aggregation Pipeline on a View `````````````````````````````````````` The following operation performs an aggregation on the ``orderDetails`` -view, using the :expression:`$sortByCount` to group by the ``item`` +view, using the :pipeline:`$sortByCount` to group by the ``item`` field and sort in descending order by the count of each distinct item: .. code-block:: javascript @@ -372,4 +372,6 @@ The operation returns ``3``. An operation that attempts to change or override a view's default collation will fail with an error. -.. seealso:: :ref:`ref-collation-and-views` +.. seealso:: + + :ref:`ref-collation-and-views` diff --git a/source/reference/method/db.currentOp.txt b/source/reference/method/db.currentOp.txt index 8c4cab63559..36665a0224a 100644 --- a/source/reference/method/db.currentOp.txt +++ b/source/reference/method/db.currentOp.txt @@ -144,7 +144,9 @@ Starting in 3.2.9, users can run ``db.currentOp( { "$ownOps": true } )`` on :binary:`~bin.mongod` instances to view their own operations even without the :authaction:`inprog` privilege action. -.. seealso:: :ref:`create-role-to-manage-ops` +.. seealso:: + + :ref:`create-role-to-manage-ops` .. _currentOp-method-examples: diff --git a/source/reference/method/db.disableFreeMonitoring.txt b/source/reference/method/db.disableFreeMonitoring.txt index a0ac23154a5..0349dae8400 100644 --- a/source/reference/method/db.disableFreeMonitoring.txt +++ b/source/reference/method/db.disableFreeMonitoring.txt @@ -81,4 +81,7 @@ Even when disabled, your unique URL is returned so that if you re-enable monitoring at a later time, you can access your previous metrics that has not expired within the past 24 hours. -.. seealso:: :method:`db.enableFreeMonitoring()` +.. seealso:: + + :method:`db.enableFreeMonitoring()` + diff --git a/source/reference/method/db.dropAllRoles.txt b/source/reference/method/db.dropAllRoles.txt index bbf76ae97bc..034327f8c7e 100644 --- a/source/reference/method/db.dropAllRoles.txt +++ b/source/reference/method/db.dropAllRoles.txt @@ -20,10 +20,10 @@ Definition .. warning:: - The :method:`dropAllRoles` method removes *all* :ref:`user-defined - ` roles from the database. + The :method:`db.dropAllRoles()` method removes *all* + :ref:`user-defined ` roles from the database. - The :method:`dropAllRoles` method takes the following argument: + The :method:`db.dropAllRoles()` method takes the following argument: .. list-table:: diff --git a/source/reference/method/db.dropAllUsers.txt b/source/reference/method/db.dropAllUsers.txt index 4c4ecd687ee..a58ffe8f3b2 100644 --- a/source/reference/method/db.dropAllUsers.txt +++ b/source/reference/method/db.dropAllUsers.txt @@ -13,16 +13,16 @@ db.dropAllUsers() Definition ---------- -.. method:: db.dropAllUsers ( writeConcern ) +.. method:: db.dropAllUsers(writeConcern) Removes all users from the current database. .. warning:: - The :method:`dropAllUsers` method removes all users from the + The :method:`db.dropAllUsers` method removes all users from the database. - The :method:`dropAllUsers` method takes the following arguments: + The :method:`db.dropAllUsers` method takes the following arguments: .. |local-cmd-name| replace:: :method:`db.dropAllUsers()` diff --git a/source/reference/method/db.dropDatabase.txt b/source/reference/method/db.dropDatabase.txt index 1928a8e5601..9a104212890 100644 --- a/source/reference/method/db.dropDatabase.txt +++ b/source/reference/method/db.dropDatabase.txt @@ -124,4 +124,6 @@ the ``temp`` database: use temp db.dropDatabase() -.. seealso:: :dbcommand:`dropDatabase` +.. seealso:: + + :dbcommand:`dropDatabase` diff --git a/source/reference/method/db.dropUser.txt b/source/reference/method/db.dropUser.txt index 22c3110f387..59d64530748 100644 --- a/source/reference/method/db.dropUser.txt +++ b/source/reference/method/db.dropUser.txt @@ -13,7 +13,7 @@ db.dropUser() Definition ---------- -.. method:: db.dropUser ( username, writeConcern ) +.. method:: db.dropUser(username, writeConcern) Removes the user from the current database. diff --git a/source/reference/method/db.enableFreeMonitoring.txt b/source/reference/method/db.enableFreeMonitoring.txt index 6c5d4a35528..eae41c4bd03 100644 --- a/source/reference/method/db.enableFreeMonitoring.txt +++ b/source/reference/method/db.enableFreeMonitoring.txt @@ -98,5 +98,8 @@ returns your free monitoring status: You can also use :method:`db.getFreeMonitoringStatus()` any time to check your free monitoring status. -.. seealso:: :method:`db.disableFreeMonitoring()` +.. seealso:: + + :method:`db.disableFreeMonitoring()` + diff --git a/source/reference/method/db.getCollection.txt b/source/reference/method/db.getCollection.txt index c4a1c6ed8f2..1a384706b0b 100644 --- a/source/reference/method/db.getCollection.txt +++ b/source/reference/method/db.getCollection.txt @@ -109,4 +109,6 @@ The following example attempts the same operation, but without using the The operation errors as ``db.auth()`` method has no ``insertOne`` method. -.. seealso:: :doc:`/reference/method/js-collection` +.. seealso:: + + :doc:`/reference/method/js-collection` diff --git a/source/reference/method/db.getCollectionInfos.txt b/source/reference/method/db.getCollectionInfos.txt index d7808639117..ca8cb11b17e 100644 --- a/source/reference/method/db.getCollectionInfos.txt +++ b/source/reference/method/db.getCollectionInfos.txt @@ -296,7 +296,7 @@ collection information for the ``employees`` collection in the ] You can specify a filter on any of the fields returned by -:dbcommand:`getCollectionInfos`. +:method:`db.getCollectionInfos()`. For example, the following command returns information for all collections in the ``example`` database where ``info.readOnly`` is diff --git a/source/reference/method/db.getFreeMonitoringStatus.txt b/source/reference/method/db.getFreeMonitoringStatus.txt index 3b4d0e8b5b1..f10fd3276c3 100644 --- a/source/reference/method/db.getFreeMonitoringStatus.txt +++ b/source/reference/method/db.getFreeMonitoringStatus.txt @@ -18,7 +18,10 @@ db.getFreeMonitoringStatus :method:`db.getFreeMonitoringStatus()` is a wrapper around the :dbcommand:`getFreeMonitoringStatus` command. - .. seealso:: :method:`db.enableFreeMonitoring()` + .. seealso:: + + :method:`db.enableFreeMonitoring()` + Access Control @@ -104,5 +107,8 @@ The method returns information on your free monitoring status. "ok" : 1 } -.. seealso:: :serverstatus:`freeMonitoring` field returned from :method:`db.serverStatus()` +.. seealso:: + + :serverstatus:`freeMonitoring` field returned from :method:`db.serverStatus()` + diff --git a/source/reference/method/db.getLastError.txt b/source/reference/method/db.getLastError.txt index b9815307087..34f54e130fa 100644 --- a/source/reference/method/db.getLastError.txt +++ b/source/reference/method/db.getLastError.txt @@ -66,7 +66,9 @@ connection, has propagated to at least two members of the replica set. db.getLastError(2) -.. seealso:: +.. seealso:: + + :dbcommand:`getLastError` and :doc:`/reference/write-concern` for all options, :ref:`Write Concern ` for a conceptual diff --git a/source/reference/method/db.getLastErrorObj.txt b/source/reference/method/db.getLastErrorObj.txt index 62f5260d837..76f8b1bcdcc 100644 --- a/source/reference/method/db.getLastErrorObj.txt +++ b/source/reference/method/db.getLastErrorObj.txt @@ -101,4 +101,7 @@ a document similar to the following: } } -.. seealso:: :doc:`/reference/write-concern`. +.. seealso:: + + :doc:`/reference/write-concern`. + diff --git a/source/reference/method/db.grantPrivilegesToRole.txt b/source/reference/method/db.grantPrivilegesToRole.txt index b0cd0ebd788..53794ccd3fc 100644 --- a/source/reference/method/db.grantPrivilegesToRole.txt +++ b/source/reference/method/db.grantPrivilegesToRole.txt @@ -13,12 +13,12 @@ db.grantPrivilegesToRole() Definition ---------- -.. method:: db.grantPrivilegesToRole ( rolename, privileges, writeConcern ) +.. method:: db.grantPrivilegesToRole(rolename, privileges, writeConcern) Grants additional :ref:`privileges ` to a :ref:`user-defined ` role. - The :method:`grantPrivilegesToRole()` method uses the following syntax: + The :method:`db.grantPrivilegesToRole()` method uses the following syntax: .. code-block:: javascript @@ -31,7 +31,7 @@ Definition { < writeConcern > } ) - The :method:`grantPrivilegesToRole()` method takes the following arguments: + The :method:`db.grantPrivilegesToRole()` method takes the following arguments: .. list-table:: @@ -73,7 +73,7 @@ Definition - The :method:`grantPrivilegesToRole()` method can grant one or more + The :method:`db.grantPrivilegesToRole()` method can grant one or more privileges. Each ```` has the following syntax: .. code-block:: javascript diff --git a/source/reference/method/db.grantRolesToRole.txt b/source/reference/method/db.grantRolesToRole.txt index 4fbfbf2ff5e..1b3382319ef 100644 --- a/source/reference/method/db.grantRolesToRole.txt +++ b/source/reference/method/db.grantRolesToRole.txt @@ -13,17 +13,18 @@ db.grantRolesToRole() Definition ---------- -.. method:: db.grantRolesToRole ( rolename, roles, writeConcern ) +.. method:: db.grantRolesToRole(rolename, roles, writeConcern) Grants roles to a :ref:`user-defined role `. - The :method:`grantRolesToRole` method uses the following syntax: + The :method:`db.grantRolesToRole()` method uses the following syntax: .. code-block:: javascript db.grantRolesToRole( "", [ ], { } ) - The :method:`grantRolesToRole` method takes the following arguments: + The :method:`db.grantRolesToRole()` method takes the following + arguments: .. list-table:: @@ -97,7 +98,7 @@ Example .. TODO Update this example -The following :method:`grantRolesToRole()` operation updates the +The following :method:`db.grantRolesToRole()` operation updates the ``productsReaderWriter`` role in the ``products`` database to :ref:`inherit ` the :ref:`privileges ` of ``productsReader`` role: diff --git a/source/reference/method/db.grantRolesToUser.txt b/source/reference/method/db.grantRolesToUser.txt index 09603ce1251..666ffc88c7d 100644 --- a/source/reference/method/db.grantRolesToUser.txt +++ b/source/reference/method/db.grantRolesToUser.txt @@ -13,17 +13,17 @@ db.grantRolesToUser() Definition ---------- -.. method:: db.grantRolesToUser ( username, roles, writeConcern ) +.. method:: db.grantRolesToUser(username, roles, writeConcern) Grants additional roles to a user. - The :method:`grantRolesToUser` method uses the following syntax: + The :method:`db.grantRolesToUser()` method uses the following syntax: .. code-block:: javascript db.grantRolesToUser( "", [ ], { } ) - The :method:`grantRolesToUser` method takes the following arguments: + The :method:`db.grantRolesToUser()` method takes the following arguments: .. list-table:: @@ -99,7 +99,7 @@ roles: } ] -The following :method:`grantRolesToUser()` operation gives ``accountUser01`` +The following :method:`db.grantRolesToUser()` operation gives ``accountUser01`` the :authrole:`readWrite` role on the ``products`` database and the :authrole:`read` role on the ``stock`` database. diff --git a/source/reference/method/db.isMaster.txt b/source/reference/method/db.isMaster.txt index 0558d720e30..e1ce9178135 100644 --- a/source/reference/method/db.isMaster.txt +++ b/source/reference/method/db.isMaster.txt @@ -20,5 +20,7 @@ db.isMaster() fields report if the instance is the :term:`primary` or if it is a :term:`secondary` member of the replica set. - .. see:: :dbcommand:`isMaster` for the complete documentation of + .. see:: + + :dbcommand:`isMaster` for the complete documentation of the output of :method:`db.isMaster()`. diff --git a/source/reference/method/db.killOp.txt b/source/reference/method/db.killOp.txt index f09f5bebb0d..fcb35ec295d 100644 --- a/source/reference/method/db.killOp.txt +++ b/source/reference/method/db.killOp.txt @@ -97,7 +97,10 @@ Starting in MongoDB 4.0 db.killOp() - .. seealso:: The ``localOps`` parameter in :pipeline:`$currentOp`. + .. seealso:: + + The ``localOps`` parameter in :pipeline:`$currentOp`. + - id: mongod name: From a shard member @@ -306,4 +309,6 @@ includes the :authaction:`killop` privilege action. On :binary:`~bin.mongod` instances, users can kill their own operations even without the :authaction:`killop` privilege action. -.. seealso:: :pipeline:`$currentOp` +.. seealso:: + + :pipeline:`$currentOp` diff --git a/source/reference/method/db.printCollectionStats.txt b/source/reference/method/db.printCollectionStats.txt index e950c039db9..9ec238d640d 100644 --- a/source/reference/method/db.printCollectionStats.txt +++ b/source/reference/method/db.printCollectionStats.txt @@ -22,4 +22,6 @@ db.printCollectionStats() .. include:: /includes/note-method-does-not-return-json.rst - .. seealso:: :doc:`/reference/command/collStats` + .. seealso:: + + :doc:`/reference/command/collStats` diff --git a/source/reference/method/db.printShardingStatus.txt b/source/reference/method/db.printShardingStatus.txt index 8e56da49671..2af83fce694 100644 --- a/source/reference/method/db.printShardingStatus.txt +++ b/source/reference/method/db.printShardingStatus.txt @@ -68,4 +68,7 @@ Definition .. include:: /includes/note-method-does-not-return-json.rst - .. seealso:: :method:`sh.status()` + .. seealso:: + + :method:`sh.status()` + diff --git a/source/reference/method/db.revokePrivilegesFromRole.txt b/source/reference/method/db.revokePrivilegesFromRole.txt index 29e2c03f851..a3fb6f017e0 100644 --- a/source/reference/method/db.revokePrivilegesFromRole.txt +++ b/source/reference/method/db.revokePrivilegesFromRole.txt @@ -13,11 +13,11 @@ db.revokePrivilegesFromRole() Definition ---------- -.. method:: db.revokePrivilegesFromRole ( rolename, privileges, writeConcern ) +.. method:: db.revokePrivilegesFromRole(rolename, privileges, writeConcern) Removes the specified privileges from the :ref:`user-defined ` role on the database where the method runs. The - :method:`revokePrivilegesFromRole` method has the following syntax: + :method:`db.revokePrivilegesFromRole` method has the following syntax: .. code-block:: javascript @@ -30,7 +30,7 @@ Definition { } ) - The :method:`revokePrivilegesFromRole` method takes the following arguments: + The :method:`db.revokePrivilegesFromRole` method takes the following arguments: .. list-table:: diff --git a/source/reference/method/db.revokeRolesFromRole.txt b/source/reference/method/db.revokeRolesFromRole.txt index 1b74d3166ef..7d5aad0feeb 100644 --- a/source/reference/method/db.revokeRolesFromRole.txt +++ b/source/reference/method/db.revokeRolesFromRole.txt @@ -13,17 +13,17 @@ db.revokeRolesFromRole() Definition ---------- -.. method:: db.revokeRolesFromRole ( rolename, roles, writeConcern ) +.. method:: db.revokeRolesFromRole(rolename, roles, writeConcern) Removes the specified inherited roles from a role. - The :method:`revokeRolesFromRole` method uses the following syntax: + The :method:`db.revokeRolesFromRole()` method uses the following syntax: .. code-block:: javascript db.revokeRolesFromRole( "", [ ], { } ) - The :method:`revokeRolesFromRole` method takes the following arguments: + The :method:`db.revokeRolesFromRole()` method takes the following arguments: .. list-table:: diff --git a/source/reference/method/db.revokeRolesFromUser.txt b/source/reference/method/db.revokeRolesFromUser.txt index aa15b3891d4..b87f4af3bfe 100644 --- a/source/reference/method/db.revokeRolesFromUser.txt +++ b/source/reference/method/db.revokeRolesFromUser.txt @@ -13,7 +13,7 @@ db.revokeRolesFromUser() Definition ---------- -.. method:: db.revokeRolesFromUser ( ) +.. method:: db.revokeRolesFromUser() Removes a one or more roles from a user on the current database. The :method:`db.revokeRolesFromUser()` method uses the @@ -23,7 +23,7 @@ Definition db.revokeRolesFromUser( "", [ ], { } ) - The :method:`revokeRolesFromUser` method takes the following arguments: + The :method:`db.revokeRolesFromUser()` method takes the following arguments: .. list-table:: diff --git a/source/reference/method/db.updateRole.txt b/source/reference/method/db.updateRole.txt index f5ff2bbb31a..01f959c7313 100644 --- a/source/reference/method/db.updateRole.txt +++ b/source/reference/method/db.updateRole.txt @@ -32,7 +32,7 @@ Definition An update to the ``privileges`` or ``roles`` array completely replaces the previous array's values. - The :method:`updateRole()` method uses the following syntax: + The :method:`db.updateRole()` method uses the following syntax: .. code-block:: javascript diff --git a/source/reference/method/db.watch.txt b/source/reference/method/db.watch.txt index 29e4d9b9c7b..bb1bc368d01 100644 --- a/source/reference/method/db.watch.txt +++ b/source/reference/method/db.watch.txt @@ -188,7 +188,9 @@ Definition See :doc:`/reference/change-events` for examples of change event documents. - .. seealso:: :method:`db.collection.watch()` and :method:`Mongo.watch()` + .. seealso:: + + :method:`db.collection.watch()` and :method:`Mongo.watch()` Availability ------------ diff --git a/source/reference/method/getClientEncryption.txt b/source/reference/method/getClientEncryption.txt index 15375051ad6..5df94fe8d24 100644 --- a/source/reference/method/getClientEncryption.txt +++ b/source/reference/method/getClientEncryption.txt @@ -26,9 +26,9 @@ getClientEncryption() db.getMongo().getClientEncryption(); -:returns: + :returns: - The ``ClientEncryption`` object for current database connection. + The ``ClientEncryption`` object for current database connection. Use the ``ClientEncryption`` object to access the following explicit encryption methods: diff --git a/source/reference/method/getKeyVault.txt b/source/reference/method/getKeyVault.txt index 3a09c5b311a..2aa9fc020bc 100644 --- a/source/reference/method/getKeyVault.txt +++ b/source/reference/method/getKeyVault.txt @@ -25,9 +25,9 @@ getKeyVault() keyVault = db.getMongo().getKeyVault(); -:returns: + :returns: - The ``KeyVault`` object for current database connection. + The ``KeyVault`` object for current database connection. Use the ``KeyVault`` object to access the following data encryption key management methods: diff --git a/source/reference/method/isInteractive.txt b/source/reference/method/isInteractive.txt index 671fe52bad7..b53fbb7372c 100644 --- a/source/reference/method/isInteractive.txt +++ b/source/reference/method/isInteractive.txt @@ -31,70 +31,64 @@ Interactive Mode Issuing Operations inside the Shell ``````````````````````````````````` -.. container:: +Connect a :binary:`~bin.mongo` shell to a deployment. Inside the +:binary:`~bin.mongo` shell, type: - Connect a :binary:`~bin.mongo` shell to a deployment. Inside the - :binary:`~bin.mongo` shell, type: +.. code-block:: javascript - .. code-block:: javascript + isInteractive() - isInteractive() - - The method returns ``true``. +The method returns ``true``. Running a Javascript File inside the ``mongo`` Shell ````````````````````````````````````````````````````` -.. container:: +Create a JavaScript ``testExample.js`` file with the content: - Create a JavaScript ``testExample.js`` file with the content: +.. code-block:: javascript - .. code-block:: javascript - - print("Is the shell in interactive mode? " + isInteractive() ); + print("Is the shell in interactive mode? " + isInteractive() ); - Connect a :binary:`~bin.mongo` shell to a deployment. Inside the - :binary:`~bin.mongo` shell, load the javascript file (see - :method:`load()`): +Connect a :binary:`~bin.mongo` shell to a deployment. Inside the +:binary:`~bin.mongo` shell, load the javascript file (see +:method:`load()`): - .. code-block:: javascript +.. code-block:: javascript - let loadStatus = load("testExample.js"); //You may need to specify the path to the file + let loadStatus = load("testExample.js"); //You may need to specify the path to the file - The method returns in the :binary:`~bin.mongo` shell: +The method returns in the :binary:`~bin.mongo` shell: - .. code-block:: none +.. code-block:: none - Is the shell in interactive mode? true + Is the shell in interactive mode? true Script Mode ~~~~~~~~~~~ -.. container:: +Create a JavaScript ``testExample.js`` file with the content: - Create a JavaScript ``testExample.js`` file with the content: +.. code-block:: javascript - .. code-block:: javascript + print("\n\nIs the shell in interactive mode? " + isInteractive() ); - print("\n\nIs the shell in interactive mode? " + isInteractive() ); +From a terminal/command-line prompt (i.e. not inside the +:binary:`~bin.mongo` shell), specify the javascript file to the +:binary:`~bin.mongo` shell to execute the file: - From a terminal/command-line prompt (i.e. not inside the - :binary:`~bin.mongo` shell), specify the javascript file to the - :binary:`~bin.mongo` shell to execute the file: +.. code-block:: sh - .. code-block:: sh + mongo localhost:27017/test testExample.js - mongo localhost:27017/test testExample.js +The operation prints to the terminal information about the MongoDB +shell version and various information followed by: - The operation prints to the terminal information about the MongoDB - shell version and various information followed by: +.. code-block:: none - .. code-block:: none - - MongoDB shell version v4.2.0 - ... + MongoDB shell version v4.2.0 + ... - Is the shell in interactive mode? false + Is the shell in interactive mode? false diff --git a/source/reference/method/js-database.txt b/source/reference/method/js-database.txt index e0a11c12751..e22189144dc 100644 --- a/source/reference/method/js-database.txt +++ b/source/reference/method/js-database.txt @@ -172,7 +172,7 @@ Database Methods * - :method:`db.serverBuildInfo()` - - Returns a document that displays the compilation parameters for the :binary:`~bin.mongod` instance. Wraps :dbcommand:`buildinfo`. + - Returns a document that displays the compilation parameters for the :binary:`~bin.mongod` instance. Wraps :dbcommand:`buildInfo`. * - :method:`db.serverCmdLineOpts()` diff --git a/source/reference/method/js-free-monitoring.txt b/source/reference/method/js-free-monitoring.txt index 768961550a9..95ca3870baa 100644 --- a/source/reference/method/js-free-monitoring.txt +++ b/source/reference/method/js-free-monitoring.txt @@ -12,27 +12,25 @@ Free Monitoring Methods .. include:: /includes/extracts/methods-toc-explanation.rst -.. only:: website +.. list-table:: - .. list-table:: + * - Name - * - Name + - Description - - Description + * - :method:`db.disableFreeMonitoring()` - * - :method:`db.disableFreeMonitoring()` + - Disables free monitoring during runtime. - - Disables free monitoring during runtime. + * - :method:`db.enableFreeMonitoring()` - * - :method:`db.enableFreeMonitoring()` + - Enables free monitoring during runtime. - - Enables free monitoring during runtime. + * - :method:`db.getFreeMonitoringStatus()` - * - :method:`db.getFreeMonitoringStatus()` - - - Returns the free monitoring status. + - Returns the free monitoring status. .. toctree:: :titlesonly: diff --git a/source/reference/method/rs.add.txt b/source/reference/method/rs.add.txt index 566dd1bca6f..f45eb3e80bf 100644 --- a/source/reference/method/rs.add.txt +++ b/source/reference/method/rs.add.txt @@ -114,16 +114,12 @@ to a new replica set, you can call the :method:`rs.add()` method with: - Member Configuration Document - .. cssclass:: copyable-code - .. code-block:: javascript rs.add( { host: "mongodbd4.example.net:27017" } ) - Host name - .. cssclass:: copyable-code - .. code-block:: javascript rs.add( "mongodbd4.example.net:27017" ) @@ -144,8 +140,6 @@ to an existing replica set: `, :doc:`priority 0 ` member: - .. cssclass:: copyable-code - .. code-block:: javascript rs.add( { host: "mongodbd4.example.net:27017", priority: 0, votes: 0 } ) @@ -154,7 +148,6 @@ to an existing replica set: To check the state of the replica set members, run :method:`rs.status()`: - .. cssclass:: copyable-code .. code-block:: javascript rs.status() @@ -186,8 +179,6 @@ the host ``mongodb4.example.net`` and accessible on the default port ``27017``, as a :doc:`priority 0 ` secondary member: -.. cssclass:: copyable-code - .. code-block:: javascript rs.add( { host: "mongodbd4.example.net:27017", priority: 0 } ) @@ -209,16 +200,12 @@ the host ``mongodb3.example.net`` and accessible on the default port - Member Configuration Document - .. cssclass:: copyable-code - .. code-block:: javascript rs.add( { host: "mongodb3.example.net:27017", arbiterOnly: true } ) - Host name - .. cssclass:: copyable-code - .. code-block:: javascript rs.add("mongodb3.example.net:27017", true) diff --git a/source/reference/method/rs.initiate.txt b/source/reference/method/rs.initiate.txt index 4ab38071644..7ed77103ef3 100644 --- a/source/reference/method/rs.initiate.txt +++ b/source/reference/method/rs.initiate.txt @@ -106,5 +106,7 @@ For details on replica set configuration, see For details on deploying a replica set, see :doc:`/tutorial/deploy-replica-set`. -.. seealso:: :doc:`/administration/replica-set-member-configuration` +.. seealso:: + + :doc:`/administration/replica-set-member-configuration` diff --git a/source/reference/method/rs.reconfig.txt b/source/reference/method/rs.reconfig.txt index 6b15e94aab6..e0f9c7ab125 100644 --- a/source/reference/method/rs.reconfig.txt +++ b/source/reference/method/rs.reconfig.txt @@ -393,7 +393,9 @@ the primary. } } -.. seealso:: +.. seealso:: + + - :method:`rs.conf()` diff --git a/source/reference/method/rs.syncFrom.txt b/source/reference/method/rs.syncFrom.txt index 6b6c362729f..98d12edec93 100644 --- a/source/reference/method/rs.syncFrom.txt +++ b/source/reference/method/rs.syncFrom.txt @@ -35,4 +35,7 @@ To use the :method:`rs.syncFrom()` helper in the :binary:`~bin.mongo` shell: rs.syncFrom("myHost:27017"); -.. seealso:: :dbcommand:`replSetSyncFrom`. +.. seealso:: + + :dbcommand:`replSetSyncFrom`. + diff --git a/source/reference/method/sh.addShardTag.txt b/source/reference/method/sh.addShardTag.txt index d27e066b39e..27af09cea3a 100644 --- a/source/reference/method/sh.addShardTag.txt +++ b/source/reference/method/sh.addShardTag.txt @@ -74,4 +74,7 @@ three shards: sh.addShardTag("shard0001", "LAX") sh.addShardTag("shard0002", "NRT") -.. seealso:: :method:`sh.addTagRange()` and :method:`sh.removeShardTag()`. +.. seealso:: + + :method:`sh.addTagRange()` and :method:`sh.removeShardTag()`. + diff --git a/source/reference/method/sh.addShardToZone.txt b/source/reference/method/sh.addShardToZone.txt index bc1a4a9bd49..4340964cdfb 100644 --- a/source/reference/method/sh.addShardToZone.txt +++ b/source/reference/method/sh.addShardToZone.txt @@ -123,4 +123,7 @@ A shard can associate with multiple zones. The following example associates balanced cluster, MongoDB routes reads and writes covered by either zone to ``shard0000``. -.. seealso:: :method:`sh.updateZoneKeyRange()` and :method:`sh.removeShardFromZone()`. +.. seealso:: + + :method:`sh.updateZoneKeyRange()` and :method:`sh.removeShardFromZone()`. + diff --git a/source/reference/method/sh.balancerCollectionStatus.txt b/source/reference/method/sh.balancerCollectionStatus.txt index a2ad014390a..c765d44d540 100644 --- a/source/reference/method/sh.balancerCollectionStatus.txt +++ b/source/reference/method/sh.balancerCollectionStatus.txt @@ -49,7 +49,7 @@ The :method:`sh.balancerCollectionStatus()` method takes the following parameter - Type - Description - * - :ref:`namespace ` + * - :ref:`namespace ` - String diff --git a/source/reference/method/sh.enableSharding.txt b/source/reference/method/sh.enableSharding.txt index 884230806fc..0f918dcb302 100644 --- a/source/reference/method/sh.enableSharding.txt +++ b/source/reference/method/sh.enableSharding.txt @@ -66,8 +66,8 @@ The :method:`sh.enableSharding()` method takes the following parameter: the primary shard, it is recommended to let the balancer select the primary shard instead. - .. admonition:: Tip - :class: warning + .. warning:: Tip + In general, you should not need to specify the primary shard. Allow the balancer to select the primary shard instead. diff --git a/source/reference/method/sh.moveChunk.txt b/source/reference/method/sh.moveChunk.txt index 135b73549b7..8909eb6a5f5 100644 --- a/source/reference/method/sh.moveChunk.txt +++ b/source/reference/method/sh.moveChunk.txt @@ -71,7 +71,10 @@ Definition label. See :ref:`moveChunk ` command for details. -.. seealso:: :dbcommand:`moveChunk`, :method:`sh.splitAt()`, +.. seealso:: + + :dbcommand:`moveChunk`, :method:`sh.splitAt()`, + :method:`sh.splitFind()`, :doc:`/sharding`, and :ref:`chunk migration `. diff --git a/source/reference/method/sh.shardCollection.txt b/source/reference/method/sh.shardCollection.txt index 2bc641745e0..a35e0e53405 100644 --- a/source/reference/method/sh.shardCollection.txt +++ b/source/reference/method/sh.shardCollection.txt @@ -212,7 +212,9 @@ Use the form ``field: "hashed"`` to specify a hashed shard key field. .. include:: /includes/note-hashed-shard-key-during-chunk-migration.rst -.. seealso:: :doc:`/core/hashed-sharding` +.. seealso:: + + :doc:`/core/hashed-sharding` .. _sh.shardCollection-zones: @@ -244,7 +246,9 @@ is ``false``. See :ref:`pre-define-zone-range-hashed-example` for an example. -.. seealso:: :ref:`initial-chunks` +.. seealso:: + + :ref:`initial-chunks` Uniqueness ~~~~~~~~~~ diff --git a/source/reference/method/sh.splitAt.txt b/source/reference/method/sh.splitAt.txt index 142607ee3d4..a6aec277b72 100644 --- a/source/reference/method/sh.splitAt.txt +++ b/source/reference/method/sh.splitAt.txt @@ -82,8 +82,6 @@ Example For the sharded collection ``test.foo``, the following example splits a chunk at the shard key value ``x: 70``. -.. cssclass:: copyable-code - .. code-block:: javascript sh.splitAt( "test.foo", { x: 70 } ) diff --git a/source/reference/method/sh.splitFind.txt b/source/reference/method/sh.splitFind.txt index 9deeba7d295..c3578276b25 100644 --- a/source/reference/method/sh.splitFind.txt +++ b/source/reference/method/sh.splitFind.txt @@ -72,8 +72,6 @@ For the sharded collection ``test.foo``, the following example splits, at the median point, a chunk that contains the shard key value ``x: 70``. -.. cssclass:: copyable-code - .. code-block:: javascript sh.splitFind( "test.foo", { x: 70 } ) diff --git a/source/reference/method/sh.status.txt b/source/reference/method/sh.status.txt index 309313c0c1a..d3327904055 100644 --- a/source/reference/method/sh.status.txt +++ b/source/reference/method/sh.status.txt @@ -62,7 +62,10 @@ Definition The default verbose value is ``false``. - .. seealso:: :method:`db.printShardingStatus()` + .. seealso:: + + :method:`db.printShardingStatus()` + .. end-include-here @@ -241,9 +244,9 @@ Active ``mongos`` Instances Autosplit ~~~~~~~~~ -.. data:: sh.status.active-mongoses +.. data:: sh.status.autosplit - :data:`sh.status.active-mongoses` indicates whether autosplit is + :data:`sh.status.autosplit` indicates whether autosplit is currently enabled. .. note:: @@ -384,7 +387,7 @@ Sharded Collection .. data:: sh.status.databases..shard-key - The :data:`~sh.status.databases.collection.shard-key` displays the shard + The :data:`~sh.status.databases..shard-key` displays the shard key specification document. .. data:: sh.status.databases..unique @@ -395,7 +398,7 @@ Sharded Collection .. versionadded:: 3.2 -.. data:: sh.status.databases.balancing +.. data:: sh.status.databases..balancing The :data:`~sh.status.databases..balancing` displays whether balancing is enabled (``true``) or disabled (``false``) for @@ -424,7 +427,10 @@ Sharded Collection The :data:`~sh.status.databases..tag` lists the details of the tags associated with a range of shard key values. -.. seealso:: :method:`sh.balancerCollectionStatus()` +.. seealso:: + + :method:`sh.balancerCollectionStatus()` + .. [#chunk-details] The sharded collection section, by default, displays the chunk information if the total number of chunks is less diff --git a/source/reference/method/sh.updateZoneKeyRange.txt b/source/reference/method/sh.updateZoneKeyRange.txt index 4ebb05d3bad..f904e33a64f 100644 --- a/source/reference/method/sh.updateZoneKeyRange.txt +++ b/source/reference/method/sh.updateZoneKeyRange.txt @@ -141,7 +141,10 @@ For a more complete example of defining zones and zone ranges for initial chunk distribution on a compound hashed shard key, see :ref:`pre-define-zone-range-hashed-example`. -.. seealso:: :method:`sh.balancerCollectionStatus()` +.. seealso:: + + :method:`sh.balancerCollectionStatus()` + Balancer ~~~~~~~~ @@ -353,4 +356,7 @@ described shard key type: .. include:: /includes/steps/zones-initial-chunk-distribution-compound-hashed-non-prefix.rst -.. seealso:: :method:`sh.addShardToZone()`, :method:`sh.removeRangeFromZone()` +.. seealso:: + + :method:`sh.addShardToZone()`, :method:`sh.removeRangeFromZone()` + diff --git a/source/reference/mongo-shell.txt b/source/reference/mongo-shell.txt index eb269e68311..657c5b6fb7a 100644 --- a/source/reference/mongo-shell.txt +++ b/source/reference/mongo-shell.txt @@ -77,7 +77,7 @@ displays some common help methods and commands: - Show help for database methods. - * - :method:`db.\.help() ` + * - :method:`db.\.help() ` - Show help on collection methods. The ```` can be the name of an existing collection or a non-existing collection. @@ -100,7 +100,10 @@ displays some common help methods and commands: - Print a list of all collections for current database. - .. seealso:: :ref:`4.0-compat-show-collections` + .. seealso:: + + :ref:`4.0-compat-show-collections` + * - ``show users`` diff --git a/source/reference/mongodb-defaults.txt b/source/reference/mongodb-defaults.txt index a3718571b55..316f49ea27a 100644 --- a/source/reference/mongodb-defaults.txt +++ b/source/reference/mongodb-defaults.txt @@ -9,8 +9,7 @@ Default MongoDB Read Concerns/Write Concerns .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -101,59 +100,57 @@ Specify Read Concern: MongoDB Drivers inside transactions, click on the ``Operations in Transactions`` tab. - .. container:: - - Using the `MongoDB drivers `__, - you can override the default :doc:`read concern - ` and set read concern for operations at - the following levels: + Using the `MongoDB drivers `__, + you can override the default :doc:`read concern + ` and set read concern for operations at + the following levels: - .. list-table:: - :header-rows: 1 - :widths: 25 75 + .. list-table:: + :header-rows: 1 + :widths: 25 75 - * - Level + * - Level - - Description + - Description - * - Client level + * - Client level - - Applies to operations unless a finer-grained read concern for an - operation is set at the database/collection/operation level. + - Applies to operations unless a finer-grained read concern for an + operation is set at the database/collection/operation level. - * - Database level + * - Database level - - Applies to operations on the database's collections - (i.e. overrides the client read concern) unless a read - concern has been set at the collection level or the operation - level. + - Applies to operations on the database's collections + (i.e. overrides the client read concern) unless a read + concern has been set at the collection level or the operation + level. - .. note:: + .. note:: - Does not apply to operations inside transactions. + Does not apply to operations inside transactions. - * - Collection level + * - Collection level - - Applies for read operations on the collection (i.e. overrides - the database/client read concern) unless a read concern has - been set at the operation level. + - Applies for read operations on the collection (i.e. overrides + the database/client read concern) unless a read concern has + been set at the operation level. - .. note:: + .. note:: - Does not apply to operations inside transactions. + Does not apply to operations inside transactions. - * - Operation level + * - Operation level - - Applies for the specific read operation (i.e. overrides the - database/client/collection read concern). + - Applies for the specific read operation (i.e. overrides the + database/client/collection read concern). - The ability to set read concern at the operation depends on the - driver. Refer to your `driver's documentation - `__. + The ability to set read concern at the operation depends on the + driver. Refer to your `driver's documentation + `__. - .. note:: + .. note:: - Does not apply to operations inside transactions. + Does not apply to operations inside transactions. .. tab:: Operations in Transactions :tabid: override-concern-txn @@ -167,62 +164,60 @@ Specify Read Concern: MongoDB Drivers :red:`outside` transactions, click on the ``Operations outside Transactions`` tab. - .. container:: + Using the `MongoDB drivers `__, + you can override the default :doc:`read concern + ` and set read concern **for transactions** + at the following levels: - Using the `MongoDB drivers `__, - you can override the default :doc:`read concern - ` and set read concern **for transactions** - at the following levels: + .. list-table:: + :header-rows: 1 + :widths: 25 75 - .. list-table:: - :header-rows: 1 - :widths: 25 75 + * - Level - * - Level + - Description - - Description + * - Client level - * - Client level + - Applies to transactions unless a finer-grained read concern + is set at the session/transaction level. - - Applies to transactions unless a finer-grained read concern - is set at the session/transaction level. + .. note:: + + All operations in a transaction use the transaction read + concern; i.e., any read concern set at the + operation/collection/database level is :red:`ignored` + inside the transaction. - .. note:: - - All operations in a transaction use the transaction read - concern; i.e., any read concern set at the - operation/collection/database level is :red:`ignored` - inside the transaction. + * - Session level - * - Session level + - Applies to :doc:`transactions ` started + in the session (i.e. overrides the client read concern) + unless a finer-grained read concern level is set at a + specific transaction level. - - Applies to :doc:`transactions ` started - in the session (i.e. overrides the client read concern) - unless a finer-grained read concern level is set at a - specific transaction level. + .. note:: + + All operations in a transaction use the transaction read + concern; i.e., any read concern set at the + operation/collection/database level is :red:`ignored` + inside the transaction. - .. note:: - - All operations in a transaction use the transaction read - concern; i.e., any read concern set at the - operation/collection/database level is :red:`ignored` - inside the transaction. + See :ref:`transactions-read-concern` for more information. - See :ref:`transactions-read-concern` for more information. + * - Transaction level - * - Transaction level + - Applies to the specific transaction (i.e. overrides the + client/session read concern). - - Applies to the specific transaction (i.e. overrides the - client/session read concern). + .. note:: - .. note:: + All operations in a transaction use the transaction read + concern; i.e., any read concern set at the + operation/collection/database level is :red:`ignored` + inside the transaction. - All operations in a transaction use the transaction read - concern; i.e., any read concern set at the - operation/collection/database level is :red:`ignored` - inside the transaction. - - See :ref:`transactions-read-concern` for more information. + See :ref:`transactions-read-concern` for more information. Additional Information ~~~~~~~~~~~~~~~~~~~~~~ @@ -241,7 +236,7 @@ Default Write Concern ~~~~~~~~~~~~~~~~~~~~~ The :red:`default` :doc:`write concern ` is -:writeconcern:`w: 1 >`. +:writeconcern:`w: 1 <\>`. .. note:: @@ -271,64 +266,60 @@ Specify Write Concern: MongoDB Drivers inside transactions, click on the ``Operations in Transactions`` tab. - .. container:: - - Using the `MongoDB drivers `__, - you can override the default :doc:`write concern - ` and set write concern for operations at - the following levels: + Using the `MongoDB drivers `__, + you can override the default :doc:`write concern + ` and set write concern for operations at + the following levels: - .. list-table:: - :header-rows: 1 - :widths: 25 75 + .. list-table:: + :header-rows: 1 + :widths: 25 75 - * - Level + * - Level - - Description + - Description - * - Client level + * - Client level - - Applies to operations unless a finer-grained write concern - for an operation is set at the operation/database/collection. + - Applies to operations unless a finer-grained write concern + for an operation is set at the operation/database/collection. - * - Database level + * - Database level - - Applies to write operations on the database's collections - (i.e. overrides the client write concern) unless a write - concern has been set at the collection level or the operation - level. + - Applies to write operations on the database's collections + (i.e. overrides the client write concern) unless a write + concern has been set at the collection level or the operation + level. - .. note:: + .. note:: - Does not apply to operations inside transactions. + Does not apply to operations inside transactions. - * - Collection level + * - Collection level - - Applies to write operations on the collection (i.e. - overrides the database and client write concern) unless a - write concern has been set at the operation level. + - Applies to write operations on the collection (i.e. + overrides the database and client write concern) unless a + write concern has been set at the operation level. - .. note:: + .. note:: - Does not apply to operations inside transactions. + Does not apply to operations inside transactions. - * - Operation level + * - Operation level - - Applies to the specific write operation. + - Applies to the specific write operation. - The ability to set write concern at the operation depends on the - driver. Refer to your `driver's documentation - `__. + The ability to set write concern at the operation depends on the + driver. Refer to your `driver's documentation + `__. - .. note:: - - Does not apply to operations inside transactions. + .. note:: + Does not apply to operations inside transactions. .. tab:: Operations in Transactions :tabid: override-concern-txn - .. note:: The following applies to operations issued inside :doc:`transactions @@ -338,67 +329,65 @@ Specify Write Concern: MongoDB Drivers :red:`outside` transactions, click on the ``Operations outside Transactions`` tab. - .. container:: - - Using the `MongoDB drivers `__, - you can override the default :doc:`write concern - ` and set write concern for **for - transactions** at the following levels: + Using the `MongoDB drivers `__, + you can override the default :doc:`write concern + ` and set write concern for **for + transactions** at the following levels: - .. list-table:: - :header-rows: 1 - :widths: 25 75 + .. list-table:: + :header-rows: 1 + :widths: 25 75 - * - Level + * - Level - - Description + - Description - * - Client level + * - Client level - - Applies to transactions unless a finer-grained write concern for - transactions are set at the session/transaction level. - - Transaction write concern applies to the commit operation and - the operations inside the transaction. + - Applies to transactions unless a finer-grained write concern for + transactions are set at the session/transaction level. + + Transaction write concern applies to the commit operation and + the operations inside the transaction. - .. note:: + .. note:: - All operations within a transaction use the transaction write - concern; i.e., any write concern set at the - operation/collection/database level is :red:`ignored` inside - the transaction. + All operations within a transaction use the transaction write + concern; i.e., any write concern set at the + operation/collection/database level is :red:`ignored` inside + the transaction. - * - Session level + * - Session level - - Applies for :doc:`transactions ` started in - the session unless the write concern level is set at a specific - transaction level. + - Applies for :doc:`transactions ` started in + the session unless the write concern level is set at a specific + transaction level. - Transaction write concern applies to the commit operation and - the operations inside the transaction. + Transaction write concern applies to the commit operation and + the operations inside the transaction. - .. note:: + .. note:: - All operations within a transaction use the transaction write - concern; i.e., any write concern set at the - operation/collection/database level is :red:`ignored` inside - the transaction. + All operations within a transaction use the transaction write + concern; i.e., any write concern set at the + operation/collection/database level is :red:`ignored` inside + the transaction. - * - Transaction level + * - Transaction level - - Applies to the specific transaction. + - Applies to the specific transaction. - Transaction write concern applies to the commit operation and - the operations inside the transaction. + Transaction write concern applies to the commit operation and + the operations inside the transaction. - .. note:: + .. note:: - All operations within a transaction use the transaction write - concern; i.e., any write concern set at the - operation/collection/database level is :red:`ignored` inside - the transaction. + All operations within a transaction use the transaction write + concern; i.e., any write concern set at the + operation/collection/database level is :red:`ignored` inside + the transaction. - See :ref:`transactions-write-concern` for more information. + See :ref:`transactions-write-concern` for more information. Additional Information ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/mongodb-extended-json-v1.txt b/source/reference/mongodb-extended-json-v1.txt index 0406b8ab3dc..49bf62208fb 100644 --- a/source/reference/mongodb-extended-json-v1.txt +++ b/source/reference/mongodb-extended-json-v1.txt @@ -11,8 +11,8 @@ MongoDB Extended JSON (v1) :class: singlecol -.. admonition:: Disambiguation - :class: important +.. important:: Disambiguation + The following page discusses MongoDB Extended JSON v1 (Legacy extended JSON). For discussion on MongoDB Extended JSON v2, see diff --git a/source/reference/mongodb-extended-json.txt b/source/reference/mongodb-extended-json.txt index f64642d44f2..4b2a6c861d6 100644 --- a/source/reference/mongodb-extended-json.txt +++ b/source/reference/mongodb-extended-json.txt @@ -10,8 +10,8 @@ MongoDB Extended JSON (v2) :depth: 1 :class: singlecol -.. admonition:: Disambiguation - :class: important +.. important:: Disambiguation + The following page discusses MongoDB Extended JSON v2. For discussion on the Legacy MongoDB Extended JSON v1, see @@ -126,15 +126,13 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: +.. list-table:: - .. list-table:: - - * - Where the array elements are as follows: + * - Where the array elements are as follows: - * - - ```` - Array elements use Extended JSON. - To specify an empty array, omit the content ``[ ]``. + * - - ```` + Array elements use Extended JSON. + To specify an empty array, omit the content ``[ ]``. .. _extended-json-binary: @@ -165,19 +163,17 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: +.. list-table:: - .. list-table:: - - * - Where the values are as follows: + * - Where the values are as follows: - * - - ``""`` - Base64 encoded (with padding as "=") payload string. + * - - ``""`` + Base64 encoded (with padding as "=") payload string. - - ``""`` - A one- or two-character hex string that corresponds to a - BSON binary subtype. See the extended bson documentation - http://bsonspec.org/spec.html for subtypes available. + - ``""`` + A one- or two-character hex string that corresponds to a + BSON binary subtype. See the extended bson documentation + http://bsonspec.org/spec.html for subtypes available. .. _extended-json-date: @@ -223,25 +219,23 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: +.. list-table:: - .. list-table:: - - * - Where the values are as follows: - * - - ``""`` - A 64-bit signed integer as string. The value - represents milliseconds relative to the epoch. + * - Where the values are as follows: + * - - ``""`` + A 64-bit signed integer as string. The value + represents milliseconds relative to the epoch. - - ``""`` - A date in `ISO-8601 Internet - Date/Time Format - `__ as string. - The date/time has a maximum time precision of milliseconds: + - ``""`` + A date in `ISO-8601 Internet + Date/Time Format + `__ as string. + The date/time has a maximum time precision of milliseconds: - - Fractional seconds have exactly 3 decimal - places if the fractional part is non-zero. + - Fractional seconds have exactly 3 decimal + places if the fractional part is non-zero. - - Otherwise, fractional seconds SHOULD be omitted if zero. + - Otherwise, fractional seconds SHOULD be omitted if zero. .. bsontype:: Decimal128 @@ -267,16 +261,14 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: +.. list-table:: - .. list-table:: - - * - Where the values are as follows: + * - Where the values are as follows: - * - - ``""`` - A `high-precision decimal - `_ - as string. + * - - ``""`` + A `high-precision decimal + `_ + as string. .. bsontype:: Document @@ -300,15 +292,13 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: +.. list-table:: - .. list-table:: - - * - Where the document contents are as follows: + * - Where the document contents are as follows: - * - - ```` - Name:value pairs that use Extended JSON. - To specify an empty document, omit the content ``{ }``. + * - - ```` + Name:value pairs that use Extended JSON. + To specify an empty document, omit the content ``{ }``. .. bsontype:: Double @@ -352,17 +342,15 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: +.. list-table:: - .. list-table:: - - * - Where the values are as follows: - * - - ``""`` - A 64-bit signed floating point as a string. + * - Where the values are as follows: + * - - ``""`` + A 64-bit signed floating point as a string. - - ```` - A non-integer number. Integer numbers are parsed as - integer instead of double. + - ```` + A non-integer number. Integer numbers are parsed as + integer instead of double. .. bsontype:: Int64 @@ -386,17 +374,15 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: - - .. list-table:: - - * - Where the values are as follows: + .. list-table:: + + * - Where the values are as follows: - * - - ``""`` - A 64-bit signed integer as string. + * - - ``""`` + A 64-bit signed integer as string. - - ```` - A 64-bit signed integer. + - ```` + A 64-bit signed integer. .. bsontype:: Int32 @@ -420,17 +406,15 @@ https://github.com/mongodb/specifications/blob/master/source/extended-json.rst#c -.. container:: - - .. list-table:: - - * - Where the values are as follows: + .. list-table:: + + * - Where the values are as follows: - * - - ``""`` - A 32-bit signed integer as string. + * - - ``""`` + A 32-bit signed integer as string. - - ```` - A 32-bit signed integer. + - ```` + A 32-bit signed integer. .. bsontype:: MaxKey @@ -507,15 +491,13 @@ comparison order for BSON types. -.. container:: +.. list-table:: - .. list-table:: - - * - Where the values are as follows: + * - Where the values are as follows: - * - - ``""`` - A 24-character, big-endian hexadecimal string that - represents the ObjectId bytes. + * - - ``""`` + A 24-character, big-endian hexadecimal string that + represents the ObjectId bytes. .. bsontype:: Regular Expression @@ -544,28 +526,26 @@ comparison order for BSON types. -.. container:: +.. list-table:: - .. list-table:: - - * - Where the values are as follows: + * - Where the values are as follows: - * - - ``""`` - A string that corresponds to the regular expression - pattern. The string can contain valid JSON characters and - unescaped double quote (``"``) characters, but may not - contain unescaped forward slash (``/``) characters. + * - - ``""`` + A string that corresponds to the regular expression + pattern. The string can contain valid JSON characters and + unescaped double quote (``"``) characters, but may not + contain unescaped forward slash (``/``) characters. - - ``""`` - A string that specifies BSON regular expression options - ('g', 'i', 'm' and 's') or an empty string ``""``. - - Options other than ('g', 'i', 'm' and 's') will be dropped - when converting to this representation. + - ``""`` + A string that specifies BSON regular expression options + ('g', 'i', 'm' and 's') or an empty string ``""``. + + Options other than ('g', 'i', 'm' and 's') will be dropped + when converting to this representation. - .. important:: + .. important:: - The options MUST be in alphabetical order. + The options MUST be in alphabetical order. .. bsontype:: Timestamp @@ -589,17 +569,15 @@ comparison order for BSON types. -.. container:: +.. list-table:: - .. list-table:: - - * - Where the values are as follows: + * - Where the values are as follows: - * - - ```` - A positive integer for the seconds since epoch. + * - - ```` + A positive integer for the seconds since epoch. - - ```` - A positive integer for the increment. + - ```` + A positive integer for the increment. Example diff --git a/source/reference/operator.txt b/source/reference/operator.txt index 2856ee9934f..4d552e944a8 100644 --- a/source/reference/operator.txt +++ b/source/reference/operator.txt @@ -10,26 +10,24 @@ Operators :depth: 1 :class: singlecol -.. class:: toc +:doc:`/reference/operator/query` + Query operators provide ways to locate data within the database + and projection operators modify how data is presented. - :doc:`/reference/operator/query` - Query operators provide ways to locate data within the database - and projection operators modify how data is presented. +:doc:`/reference/operator/update` + Update operators are operators that enable you to modify the data + in your database or add additional data. - :doc:`/reference/operator/update` - Update operators are operators that enable you to modify the data - in your database or add additional data. +:doc:`/reference/operator/aggregation-pipeline` + Available aggregation stages for + :doc:`/core/aggregation-pipeline`. - :doc:`/reference/operator/aggregation-pipeline` - Available aggregation stages for - :doc:`/core/aggregation-pipeline`. +:doc:`/reference/operator/aggregation` + Aggregation pipeline operations have a collection of operators + available to define and manipulate documents in pipeline stages. - :doc:`/reference/operator/aggregation` - Aggregation pipeline operations have a collection of operators - available to define and manipulate documents in pipeline stages. - - :doc:`/reference/operator/query-modifier` - Query modifiers determine the way that queries will be executed. +:doc:`/reference/operator/query-modifier` + Query modifiers determine the way that queries will be executed. .. toctree:: diff --git a/source/reference/operator/aggregation-pipeline.txt b/source/reference/operator/aggregation-pipeline.txt index ae4e927595a..178d32612db 100644 --- a/source/reference/operator/aggregation-pipeline.txt +++ b/source/reference/operator/aggregation-pipeline.txt @@ -304,10 +304,6 @@ Alphabetical Listing of Stages with an element value. For each input document, outputs *n* documents where *n* is the number of array elements and can be zero for an empty array. - - - -.. class:: hidden .. toctree:: :titlesonly: diff --git a/source/reference/operator/aggregation/accumulator.txt b/source/reference/operator/aggregation/accumulator.txt index d784ff3858a..e7fc488301a 100644 --- a/source/reference/operator/aggregation/accumulator.txt +++ b/source/reference/operator/aggregation/accumulator.txt @@ -46,167 +46,165 @@ Definition Syntax ------ -.. container:: +The :group:`$accumulator` operator has the following syntax: - The :group:`$accumulator` operator has the following syntax: +.. code-block:: javascript - .. code-block:: javascript + { + $accumulator: { + init: , + initArgs: , // Optional + accumulate: , + accumulateArgs: , + merge: , + finalize: , // Optional + lang: + } + } - { - $accumulator: { - init: , - initArgs: , // Optional - accumulate: , - accumulateArgs: , - merge: , - finalize: , // Optional - lang: - } - } +.. list-table:: + :header-rows: 1 + :widths: 20 40 10 - .. list-table:: - :header-rows: 1 - :widths: 20 40 10 + * - Field + - Type + - Description - * - Field - - Type - - Description + * - :ref:`init ` - * - :ref:`init ` + - String or Code - - String or Code + - .. _accumulator-init: + + Function used to initialize the state. The ``init`` function + receives its arguments from the :ref:`initArgs + ` array expression. You can specify the + function definition as either BSON type Code or String. - - .. _accumulator-init: - - Function used to initialize the state. The ``init`` function - receives its arguments from the :ref:`initArgs - ` array expression. You can specify the - function definition as either BSON type Code or String. + The ``init`` function has the following form: - The ``init`` function has the following form: + .. code-block:: javascript + :copyable: false - .. code-block:: javascript - :copyable: false + function (, , ...) { + ... + return + } - function (, , ...) { - ... - return - } + * - :ref:`initArgs ` - * - :ref:`initArgs ` + - Array - - Array + - .. _accumulator-initArgs: + + Optional. Arguments passed to the ``init`` function. - - .. _accumulator-initArgs: - - Optional. Arguments passed to the ``init`` function. + ``initArgs`` has the following form: - ``initArgs`` has the following form: + .. code-block:: javascript + :copyable: false - .. code-block:: javascript - :copyable: false + [ , , ... ] - [ , , ... ] + .. important:: - .. important:: + When used in a :pipeline:`$bucketAuto` stage, ``initArgs`` + cannot refer to the group key (i.e., you cannot use the + ``$`` syntax). Instead, in a + :pipeline:`$bucketAuto` stage, you can only specify + constant values in ``initArgs``. - When used in a :pipeline:`$bucketAuto` stage, ``initArgs`` - cannot refer to the group key (i.e., you cannot use the - ``$`` syntax). Instead, in a - :pipeline:`$bucketAuto` stage, you can only specify - constant values in ``initArgs``. + * - :ref:`accumulate ` - * - :ref:`accumulate ` + - String or Code - - String or Code + - .. _accumulator-accumulate: + + Function used to accumulate documents. The ``accumulate`` + function receives its arguments from the current state and + :ref:`accumulateArgs ` array + expression. The result of the ``accumulate`` function becomes + the new state. You can specify the function definition as + either BSON type Code or String. - - .. _accumulator-accumulate: - - Function used to accumulate documents. The ``accumulate`` - function receives its arguments from the current state and - :ref:`accumulateArgs ` array - expression. The result of the ``accumulate`` function becomes - the new state. You can specify the function definition as - either BSON type Code or String. + The ``accumulate`` function has the following form: - The ``accumulate`` function has the following form: + .. code-block:: javascript + :copyable: false - .. code-block:: javascript - :copyable: false + function(state, , , ...) { + ... + return + } - function(state, , , ...) { - ... - return - } - - * - :ref:`accumulateArgs ` + * - :ref:`accumulateArgs ` - - Array + - Array - - .. _accumulator-accumulateArgs: - - Arguments passed to the ``accumulate`` function. You can use - ``accumulateArgs`` to specify what field value(s) to pass to - the ``accumulate`` function. + - .. _accumulator-accumulateArgs: + + Arguments passed to the ``accumulate`` function. You can use + ``accumulateArgs`` to specify what field value(s) to pass to + the ``accumulate`` function. - ``accumulateArgs`` has the following form: + ``accumulateArgs`` has the following form: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - [ , , ... ] + [ , , ... ] - * - :ref:`merge ` + * - :ref:`merge ` - - String or Code + - String or Code - - .. _accumulator-merge: - - Function used to merge two internal states. ``merge`` must be - either a String or Code BSON type. ``merge`` returns the - combined result of the two merged states. For information on - when the merge function is called, see - :ref:`merge-multiple-states`. + - .. _accumulator-merge: + + Function used to merge two internal states. ``merge`` must be + either a String or Code BSON type. ``merge`` returns the + combined result of the two merged states. For information on + when the merge function is called, see + :ref:`merge-multiple-states`. - The ``merge`` function has the following form: + The ``merge`` function has the following form: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - function (, ) { - - return - } + function (, ) { + + return + } - * - :ref:`finalize ` + * - :ref:`finalize ` - - String or Code + - String or Code - - .. _accumulator-finalize: - - Optional. Function used to update the result of the accumulation. + - .. _accumulator-finalize: + + Optional. Function used to update the result of the accumulation. - The ``finalize`` function has the following form: + The ``finalize`` function has the following form: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - function (state) { - ... - return - } + function (state) { + ... + return + } - * - :ref:`lang ` + * - :ref:`lang ` - - String + - String - - .. _accumulator-lang: + - .. _accumulator-lang: - The language used in the :group:`$accumulator` code. + The language used in the :group:`$accumulator` code. - .. important:: + .. important:: - Currently, the only supported value for ``lang`` is ``js``. + Currently, the only supported value for ``lang`` is ``js``. Behavior -------- @@ -271,7 +269,7 @@ For example, :group:`$accumulator` may need to combine two states when: Javascript Enabled ~~~~~~~~~~~~~~~~~~ -To use :expression:`$accumulator`, you must have server-side scripting +To use :group:`$accumulator`, you must have server-side scripting enabled. If you do not use :group:`$accumulator` (or :expression:`$function`, diff --git a/source/reference/operator/aggregation/addToSet.txt b/source/reference/operator/aggregation/addToSet.txt index 51d733336b3..7226c1e9a76 100644 --- a/source/reference/operator/aggregation/addToSet.txt +++ b/source/reference/operator/aggregation/addToSet.txt @@ -22,7 +22,7 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-addToSet.rst - :expression:`$addToSet` has the following syntax: + :group:`$addToSet` has the following syntax: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/arrayToObject.txt b/source/reference/operator/aggregation/arrayToObject.txt index 90724d745f4..0ea962c60c3 100644 --- a/source/reference/operator/aggregation/arrayToObject.txt +++ b/source/reference/operator/aggregation/arrayToObject.txt @@ -139,7 +139,6 @@ The following aggregation pipeline operation use the :expression:`$arrayToObject` to return the ``dimensions`` field as a document: -.. cssclass:: copyable-code .. code-block:: javascript db.inventory.aggregate( @@ -170,4 +169,6 @@ value for that field. .. include:: /includes/example-objectToArray-arrayToObject.rst -.. seealso:: :expression:`$objectToArray` +.. seealso:: + + :expression:`$objectToArray` diff --git a/source/reference/operator/aggregation/avg.txt b/source/reference/operator/aggregation/avg.txt index 4d174581eb4..5451373c425 100644 --- a/source/reference/operator/aggregation/avg.txt +++ b/source/reference/operator/aggregation/avg.txt @@ -20,7 +20,7 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-avg.rst - When used in the :pipeline:`$group` stage, :expression:`$avg` has the + When used in the :pipeline:`$group` stage, :group:`$avg` has the following syntax and returns the collective average of all the numeric values that result from applying a specified expression to each document in a group of documents that share the same group by key: @@ -29,17 +29,17 @@ Definition { $avg: } - When used in the other supported stages, :expression:`$avg` returns + When used in the other supported stages, :group:`$avg` returns the average of the specified expression or list of expressions for each document and has one of two syntaxes: - - :expression:`$avg` has one specified expression as its operand: + - :group:`$avg` has one specified expression as its operand: .. code-block:: javascript { $avg: } - - :expression:`$avg` has a list of specified expressions as its + - :group:`$avg` has a list of specified expressions as its operand: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/binarySize.txt b/source/reference/operator/aggregation/binarySize.txt index b0bce63353c..773aacb8848 100644 --- a/source/reference/operator/aggregation/binarySize.txt +++ b/source/reference/operator/aggregation/binarySize.txt @@ -187,7 +187,7 @@ First Stage - The ``name`` field - - The ``imageSize`` field, which uses :expression:`binarySize` to + - The ``imageSize`` field, which uses :expression:`$binarySize` to return the size of the document's ``binary`` field in bytes. This stage outputs the following documents to the next stage: @@ -225,7 +225,9 @@ Third Stage { "_id" : 4, "name" : "concert.jpg", "imageSize" : 269 } -.. seealso:: +.. seealso:: + + - :pipeline:`$project` - :pipeline:`$sort` diff --git a/source/reference/operator/aggregation/bsonSize.txt b/source/reference/operator/aggregation/bsonSize.txt index 223971139f2..b9ef2ea88c6 100644 --- a/source/reference/operator/aggregation/bsonSize.txt +++ b/source/reference/operator/aggregation/bsonSize.txt @@ -221,7 +221,9 @@ Third Stage { "_id" : 2, "name" : "Bob", "task_object_size" : 152 } -.. seealso:: +.. seealso:: + + - :pipeline:`$project` - :pipeline:`$sort` diff --git a/source/reference/operator/aggregation/bucket.txt b/source/reference/operator/aggregation/bucket.txt index 95fe0c8ef28..06b8dbe0a6d 100644 --- a/source/reference/operator/aggregation/bucket.txt +++ b/source/reference/operator/aggregation/bucket.txt @@ -30,129 +30,127 @@ Definition Syntax ------ -.. container:: - - .. code-block:: javascript - - { - $bucket: { - groupBy: , - boundaries: [ , , ... ], - default: , - output: { - : { <$accumulator expression> }, - ... - : { <$accumulator expression> } - } +.. code-block:: javascript + + { + $bucket: { + groupBy: , + boundaries: [ , , ... ], + default: , + output: { + : { <$accumulator expression> }, + ... + : { <$accumulator expression> } } } + } - The :pipeline:`$bucket` document contains the following fields: +The :pipeline:`$bucket` document contains the following fields: - .. list-table:: - :header-rows: 1 - :widths: 20 20 80 - - * - Field - - - Type - - - Description - - * - :ref:`groupBy ` - - - expression - - - .. _bucket-group-by: - - An :ref:`expression ` to group - documents by. To specify a :ref:`field path - `, prefix the field name with a - dollar sign ``$`` and enclose it in quotes. - - Unless :pipeline:`$bucket` includes a :ref:`default - ` specification, each input document must - resolve the ``groupBy`` field path or expression to a value - that falls within one of the ranges specified by the - :ref:`boundaries `. - - * - :ref:`boundaries ` - - - array - - - .. _bucket-boundaries: - - An array of values based on the :ref:`groupBy - ` expression that specify the boundaries for - each bucket. Each adjacent pair of values acts as the - inclusive lower boundary and the exclusive upper boundary for - the bucket. You must specify at least two boundaries. - - The specified values must be in ascending order and all of the - same :doc:`type `. The exception is if - the values are of mixed numeric types, such as: - - ``[ 10, NumberLong(20), NumberInt(30) ]`` - - .. example:: - - An array of ``[ 0, 5, 10 ]`` creates two buckets: - - - [0, 5) with inclusive lower bound ``0`` and exclusive - upper bound ``5``. - - - [5, 10) with inclusive lower bound ``5`` and exclusive - upper bound ``10``. - - * - :ref:`default ` - - - literal - - - .. _bucket-default: - - Optional. A literal that specifies the ``_id`` of an - additional bucket that contains all documents whose - :ref:`groupBy ` expression result does not fall into a bucket - specified by :ref:`boundaries `. - - If unspecified, each input document must resolve the - ``groupBy`` expression to a value within one of the bucket - ranges specified by ``boundaries`` or the operation throws an - error. - - The ``default`` value must be less than the lowest - ``boundaries`` value, or greater than or equal to the highest - ``boundaries`` value. - - The ``default`` value can be of a different - :doc:`type ` than the entries in - ``boundaries``. - - * - :ref:`output ` - - - document - - - .. _bucket-output: - - Optional. A document that specifies the fields to include in - the output documents in addition to the ``_id`` field. To - specify the field to include, you must use :ref:`accumulator - expressions `. - - .. code-block:: javascript - - : { : }, - ... - : { : } - - If you do not specify an ``output`` document, the operation - returns a ``count`` field containing the number of documents - in each bucket. - - If you specify an ``output`` document, only the fields - specified in the document are returned; i.e. the ``count`` - field is not returned unless it is explicitly included in the - ``output`` document. +.. list-table:: + :header-rows: 1 + :widths: 20 20 80 + + * - Field + + - Type + + - Description + + * - :ref:`groupBy ` + + - expression + + - .. _bucket-group-by: + + An :ref:`expression ` to group + documents by. To specify a :ref:`field path + `, prefix the field name with a + dollar sign ``$`` and enclose it in quotes. + + Unless :pipeline:`$bucket` includes a :ref:`default + ` specification, each input document must + resolve the ``groupBy`` field path or expression to a value + that falls within one of the ranges specified by the + :ref:`boundaries `. + + * - :ref:`boundaries ` + + - array + + - .. _bucket-boundaries: + + An array of values based on the :ref:`groupBy + ` expression that specify the boundaries for + each bucket. Each adjacent pair of values acts as the + inclusive lower boundary and the exclusive upper boundary for + the bucket. You must specify at least two boundaries. + + The specified values must be in ascending order and all of the + same :doc:`type `. The exception is if + the values are of mixed numeric types, such as: + + ``[ 10, NumberLong(20), NumberInt(30) ]`` + + .. example:: + + An array of ``[ 0, 5, 10 ]`` creates two buckets: + + - [0, 5) with inclusive lower bound ``0`` and exclusive + upper bound ``5``. + + - [5, 10) with inclusive lower bound ``5`` and exclusive + upper bound ``10``. + + * - :ref:`default ` + + - literal + + - .. _bucket-default: + + Optional. A literal that specifies the ``_id`` of an + additional bucket that contains all documents whose + :ref:`groupBy ` expression result does not fall into a bucket + specified by :ref:`boundaries `. + + If unspecified, each input document must resolve the + ``groupBy`` expression to a value within one of the bucket + ranges specified by ``boundaries`` or the operation throws an + error. + + The ``default`` value must be less than the lowest + ``boundaries`` value, or greater than or equal to the highest + ``boundaries`` value. + + The ``default`` value can be of a different + :doc:`type ` than the entries in + ``boundaries``. + + * - :ref:`output ` + + - document + + - .. _bucket-output: + + Optional. A document that specifies the fields to include in + the output documents in addition to the ``_id`` field. To + specify the field to include, you must use :ref:`accumulator + expressions `. + + .. code-block:: javascript + + : { : }, + ... + : { : } + + If you do not specify an ``output`` document, the operation + returns a ``count`` field containing the number of documents + in each bucket. + + If you specify an ``output`` document, only the fields + specified in the document are returned; i.e. the ``count`` + field is not returned unless it is explicitly included in the + ``output`` document. Behavior -------- diff --git a/source/reference/operator/aggregation/collStats.txt b/source/reference/operator/aggregation/collStats.txt index 61c4703fc4b..568f07e80b9 100644 --- a/source/reference/operator/aggregation/collStats.txt +++ b/source/reference/operator/aggregation/collStats.txt @@ -124,14 +124,14 @@ Definition .. versionadded:: 3.6 * - ``host`` - - The hostname and port of the `mongod` process which produced + - The hostname and port of the ``mongod`` process which produced the output document. .. versionadded:: 3.6 * - ``localTime`` - The current time on the MongoDB server, expressed as UTC - milliseconds since the :term:`Unix epoch`. + milliseconds since the :term:`UNIX epoch `. * - ``latencyStats`` - Statistics related to request latency for a collection or diff --git a/source/reference/operator/aggregation/concatArrays.txt b/source/reference/operator/aggregation/concatArrays.txt index 6623e57af04..930d2826c20 100644 --- a/source/reference/operator/aggregation/concatArrays.txt +++ b/source/reference/operator/aggregation/concatArrays.txt @@ -96,4 +96,6 @@ arrays: { "_id" : 3, "items" : [ "pears", "pecans", "cherries" ] } { "_id" : 4, "items" : [ "ice cream" ] } -.. seealso:: :group:`$push` +.. seealso:: + + :group:`$push` diff --git a/source/reference/operator/aggregation/cond.txt b/source/reference/operator/aggregation/cond.txt index ee60909b732..e8a55e193b9 100644 --- a/source/reference/operator/aggregation/cond.txt +++ b/source/reference/operator/aggregation/cond.txt @@ -42,7 +42,9 @@ Definition `. For more information on expressions, see :ref:`aggregation-expressions`. -.. seealso:: :expression:`$switch` +.. seealso:: + + :expression:`$switch` Example ------- diff --git a/source/reference/operator/aggregation/convert.txt b/source/reference/operator/aggregation/convert.txt index 5fc0f5f34b1..b09e1d47670 100644 --- a/source/reference/operator/aggregation/convert.txt +++ b/source/reference/operator/aggregation/convert.txt @@ -279,7 +279,9 @@ The following table lists some conversion to boolean examples: - null -.. seealso:: :expression:`$toBool` +.. seealso:: + + :expression:`$toBool` .. _convert-to-int: @@ -434,7 +436,10 @@ The following table lists some conversion to integer examples: - null -.. seealso:: :expression:`$toInt` operator. +.. seealso:: + + :expression:`$toInt` operator. + .. _convert-to-decimal: @@ -543,7 +548,9 @@ The following table lists some conversion to decimal examples: - NumberDecimal("1522127087890") -.. seealso:: :expression:`$toDecimal` +.. seealso:: + + :expression:`$toDecimal` .. _convert-to-double: @@ -679,7 +686,9 @@ The following table lists some conversion to double examples: - 1522127087890 -.. seealso:: :expression:`$toDouble` +.. seealso:: + + :expression:`$toDouble` .. _convert-to-long: @@ -838,7 +847,9 @@ The following table lists some conversion to long examples: - null -.. seealso:: :expression:`$toLong` +.. seealso:: + + :expression:`$toLong` .. _convert-to-date: @@ -974,7 +985,9 @@ The following table lists some conversion to date examples: - "Could not convert to type date." -.. seealso:: :expression:`$toDate` operator, :expression:`$dateFromString` +.. seealso:: + + :expression:`$toDate` operator, :expression:`$dateFromString` .. _convert-to-objectId: @@ -1030,7 +1043,10 @@ The following table lists some conversion to date examples: } - "Could not convert to type ObjectId." -.. seealso:: :expression:`$toObjectId` operator. +.. seealso:: + + :expression:`$toObjectId` operator. + .. _convert-to-string: @@ -1127,7 +1143,10 @@ The following table lists some conversion to string examples: { input: ISODate("2018-03-27T16:58:51.538Z"), to: "string" } - "2018-03-27T16:58:51.538Z" -.. seealso:: :expression:`$toString` operator. :expression:`$dateToString` +.. seealso:: + + :expression:`$toString` operator. :expression:`$dateToString` + Example ------- diff --git a/source/reference/operator/aggregation/count.txt b/source/reference/operator/aggregation/count.txt index 7e58f5e1b05..2ea2f3e66a6 100644 --- a/source/reference/operator/aggregation/count.txt +++ b/source/reference/operator/aggregation/count.txt @@ -54,7 +54,10 @@ The :pipeline:`$count` stage is equivalent to the following where ``myCount`` would be the output field that contains the count. You can specify another name for the output field. -.. seealso:: :method:`db.collection.countDocuments()` which wraps the +.. seealso:: + + :method:`db.collection.countDocuments()` which wraps the + :pipeline:`$group` aggregation stage with a :group:`$sum` expression. Example @@ -73,7 +76,7 @@ A collection named ``scores`` has the following documents: The following aggregation operation has two stages: -#. The :expression:`$match` stage excludes documents that have a +#. The :pipeline:`$match` stage excludes documents that have a ``score`` value of less than or equal to ``80`` to pass along the documents with ``score`` greater than ``80`` to the next stage. diff --git a/source/reference/operator/aggregation/currentOp.txt b/source/reference/operator/aggregation/currentOp.txt index 287d8379802..ebfc8224572 100644 --- a/source/reference/operator/aggregation/currentOp.txt +++ b/source/reference/operator/aggregation/currentOp.txt @@ -899,7 +899,10 @@ relevant for the operation: operation. Each user document contains the ``user`` name and the authentication ``db``. - .. seealso:: :data:`$currentOp.runBy` + .. seealso:: + + :data:`$currentOp.runBy` + .. versionadded:: 4.2 @@ -1024,7 +1027,7 @@ relevant for the operation: sharded cluster transaction that uses :ref:`"snapshot" read concern `. For transactions on sharded clusters, the read concern - :readconcern:`snapshot` of the data is synchronized across + :readconcern:`"snapshot"` of the data is synchronized across shards; i.e. other read concerns cannot guarantee that the data is from the same snapshot view across the shards. @@ -1067,9 +1070,9 @@ relevant for the operation: The duration, in microseconds, for the transaction. The - :data:`timeActiveMicros <$currentOp.transaction.parameters.timeActiveMicros>` + :data:`timeActiveMicros <$currentOp.transaction.timeActiveMicros>` value added to the - :data:`timeInactiveMicros <$currentOp.transaction.parameters.timeInactiveMicros>` + :data:`timeInactiveMicros <$currentOp.transaction.timeInactiveMicros>` should equal the :data:`timeOpenMicros <$currentOp.transaction.timeOpenMicros>`. Only present if the operation is part of a multi-document @@ -1083,11 +1086,11 @@ relevant for the operation: i.e. when the transaction had operations running. The - :data:`timeActiveMicros <$currentOp.transaction.parameters.timeActiveMicros>` + :data:`timeActiveMicros <$currentOp.transaction.timeActiveMicros>` value added to the - :data:`timeInactiveMicros <$currentOp.transaction.parameters.timeInactiveMicros>` + :data:`timeInactiveMicros <$currentOp.transaction.timeInactiveMicros>` should equal the - :data:`timeOpenMicros <$currentOp.transaction.parameters.timeOpenMicros>`. + :data:`timeOpenMicros <$currentOp.transaction.timeOpenMicros>`. Only present if the operation is part of a multi-document transaction. @@ -1100,11 +1103,11 @@ relevant for the operation: inactive; i.e. when the transaction had no operations running. The - :data:`timeInactiveMicros <$currentOp.transaction.parameters.timeInactiveMicros>` + :data:`timeInactiveMicros <$currentOp.transaction.timeInactiveMicros>` value added to the - :data:`timeActiveMicros <$currentOp.transaction.parameters.timeActiveMicros>` + :data:`timeActiveMicros <$currentOp.transaction.timeActiveMicros>` should equal the - :data:`timeOpenMicros <$currentOp.transaction.parameters.timeOpenMicros>`. + :data:`timeOpenMicros <$currentOp.transaction.timeOpenMicros>`. Only present if the operation is part of a multi-document transaction. @@ -1200,7 +1203,7 @@ relevant for the operation: ``"command"`` operations include most :doc:`commands ` such as the - :dbcommand:`createIndexes`, :dbcommand:`aggregate`, and :dbcommand:`findandmodify`. + :dbcommand:`createIndexes`, :dbcommand:`aggregate`, and :dbcommand:`findAndModify`. ``"query"`` operations include :dbcommand:`find` operations and OP_QUERY operations. @@ -1275,7 +1278,10 @@ relevant for the operation: - If false, the cursor will time out when idle. - .. seealso:: :method:`cursor.addOption()` + .. seealso:: + + :method:`cursor.addOption()` + .. data:: $currentOp.cursor.tailable diff --git a/source/reference/operator/aggregation/dateFromParts.txt b/source/reference/operator/aggregation/dateFromParts.txt index 92ae762efa6..192cec16979 100644 --- a/source/reference/operator/aggregation/dateFromParts.txt +++ b/source/reference/operator/aggregation/dateFromParts.txt @@ -46,7 +46,7 @@ Definition } } - The :pipeline:`$dateFromParts` takes a document with the following fields: + The :expression:`$dateFromParts` takes a document with the following fields: .. important:: You cannot combine the use of calendar dates and ISO week date @@ -265,7 +265,6 @@ Example The following aggregation uses :expression:`$dateFromParts` to construct three date objects from the provided input fields: -.. cssclass:: copyable-code .. code-block:: javascript db.sales.aggregate([ diff --git a/source/reference/operator/aggregation/dateFromString.txt b/source/reference/operator/aggregation/dateFromString.txt index 4a8d1a27aa3..79672b8a4c1 100644 --- a/source/reference/operator/aggregation/dateFromString.txt +++ b/source/reference/operator/aggregation/dateFromString.txt @@ -31,7 +31,7 @@ Definition onNull: } } - The :pipeline:`$dateFromString` takes a document with the following fields: + The :expression:`$dateFromString` takes a document with the following fields: .. list-table:: :header-rows: 1 @@ -78,7 +78,7 @@ Definition ```` allows for the following options and expressions that evaluate to them: - - an `Olson Timezone Identifier + - an `Olson Timezone Identifier `_, such as ``"Europe/London"`` or ``"America/New_York"``, or @@ -90,7 +90,7 @@ Definition - ``+/-[hh]``, e.g. ``"+03"``, or - - The strings `"Z"`, `"UTC"`, or `"GMT"` + - The strings ``"Z"``, ``"UTC"``, or ``"GMT"`` For more information on expressions, see :ref:`aggregation-expressions`. @@ -116,7 +116,9 @@ Definition If you do not specify ``onNull`` and ``dateString`` is ``null`` or missing, then :expression:`$dateFromString` outputs ``null``. -.. seealso:: :expression:`$toDate` and :expression:`$convert` +.. seealso:: + + :expression:`$toDate` and :expression:`$convert` Behavior -------- diff --git a/source/reference/operator/aggregation/dateToParts.txt b/source/reference/operator/aggregation/dateToParts.txt index 27816262681..edbcc44f9e4 100644 --- a/source/reference/operator/aggregation/dateToParts.txt +++ b/source/reference/operator/aggregation/dateToParts.txt @@ -41,7 +41,7 @@ Definition } } - The :pipeline:`$dateToParts` takes a document with the following fields: + The :expression:`$dateToParts` takes a document with the following fields: .. list-table:: :header-rows: 1 @@ -67,7 +67,7 @@ Definition * - ``timezone`` - Optional - The timezone to use to format the date. By default, - :pipeline:`$dateToParts` uses UTC. + :expression:`$dateToParts` uses UTC. ```` can be any :ref:`expression ` that evaluates to a string whose @@ -117,7 +117,6 @@ Consider a ``sales`` collection with the following document: The following aggregation uses :expression:`$dateToParts` to return a document that contains the constituent parts of the ``date`` field. -.. cssclass:: copyable-code .. code-block:: javascript db.sales.aggregate([ diff --git a/source/reference/operator/aggregation/dateToString.txt b/source/reference/operator/aggregation/dateToString.txt index 81e60d42270..00660d49186 100644 --- a/source/reference/operator/aggregation/dateToString.txt +++ b/source/reference/operator/aggregation/dateToString.txt @@ -30,7 +30,7 @@ Definition onNull: } } - The :pipeline:`$dateToString` takes a document with the following fields: + The :expression:`$dateToString` takes a document with the following fields: .. list-table:: :header-rows: 1 @@ -86,7 +86,9 @@ Definition ``"4.0"`` or greater. For more information on fCV, see :dbcommand:`setFeatureCompatibilityVersion`. -.. seealso:: :expression:`$toString` and :expression:`$convert` +.. seealso:: + + :expression:`$toString` and :expression:`$convert` .. _format-specifiers: @@ -100,7 +102,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -114,7 +116,6 @@ Consider a ``sales`` collection with the following document: The following aggregation uses :expression:`$dateToString` to return the ``date`` field as formatted strings: -.. cssclass:: copyable-code .. code-block:: javascript db.sales.aggregate( diff --git a/source/reference/operator/aggregation/dayOfMonth.txt b/source/reference/operator/aggregation/dayOfMonth.txt index 33309a40ff4..acc71c61c04 100644 --- a/source/reference/operator/aggregation/dayOfMonth.txt +++ b/source/reference/operator/aggregation/dayOfMonth.txt @@ -106,7 +106,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -120,7 +120,7 @@ Consider a ``sales`` collection with the following document: The following aggregation uses the :expression:`$dayOfMonth` and other date operators to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 8 diff --git a/source/reference/operator/aggregation/dayOfWeek.txt b/source/reference/operator/aggregation/dayOfWeek.txt index 64e00eedf6f..c2602d6e2a3 100644 --- a/source/reference/operator/aggregation/dayOfWeek.txt +++ b/source/reference/operator/aggregation/dayOfWeek.txt @@ -107,7 +107,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -121,7 +121,7 @@ Consider a ``sales`` collection with the following document: The following aggregation uses the :expression:`$dayOfWeek` and other date operators to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 14 diff --git a/source/reference/operator/aggregation/dayOfYear.txt b/source/reference/operator/aggregation/dayOfYear.txt index 85399ea3d6a..c4766c93c3f 100644 --- a/source/reference/operator/aggregation/dayOfYear.txt +++ b/source/reference/operator/aggregation/dayOfYear.txt @@ -106,7 +106,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -120,7 +120,7 @@ Consider a ``sales`` collection with the following document: The following aggregation uses the :expression:`$dayOfYear` and other date expressions to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 13 diff --git a/source/reference/operator/aggregation/first-array-element.txt b/source/reference/operator/aggregation/first-array-element.txt index 742e511417e..9fad15c8757 100644 --- a/source/reference/operator/aggregation/first-array-element.txt +++ b/source/reference/operator/aggregation/first-array-element.txt @@ -19,15 +19,17 @@ Definition Returns the first element in an array. - .. admonition:: Disambiguation - :class: note + .. note:: Disambiguation + The following page describes the array element operator :expression:`$first`. For the accumulator :group:`$first`, available only with the :pipeline:`$group` stage, see :group:`$first (accumulator) <$first>` instead. -.. seealso:: :expression:`$last` +.. seealso:: + + :expression:`$last` Syntax ------ @@ -202,7 +204,7 @@ The operation returns the following documents: { "_id" : 2, "team" : "Bears", "progress" : -2 } { "_id" : 3, "team" : "Cobras", "progress" : "Not enough data." } -By default, the :binary:`~bin.shell` uses the 64-bit floating-point +By default, the :binary:`~bin.mongo` shell uses the 64-bit floating-point double for numbers. To improve precision, you can use :ref:`shell-type-decimal` instead. diff --git a/source/reference/operator/aggregation/first.txt b/source/reference/operator/aggregation/first.txt index c578f4e5421..eba3af53309 100644 --- a/source/reference/operator/aggregation/first.txt +++ b/source/reference/operator/aggregation/first.txt @@ -21,8 +21,8 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-first.rst - .. admonition:: Disambiguation - :class: note + .. note:: Disambiguation + The following page describes the accumulator :group:`$first`, available only within the :pipeline:`$group` stage. For the array diff --git a/source/reference/operator/aggregation/function.txt b/source/reference/operator/aggregation/function.txt index 3efdd201207..2f1d5f634c1 100644 --- a/source/reference/operator/aggregation/function.txt +++ b/source/reference/operator/aggregation/function.txt @@ -34,67 +34,65 @@ Definition Syntax ------ -.. container:: +The :expression:`$function` operator has the following syntax: - The :expression:`$function` operator has the following syntax: +.. code-block:: javascript - .. code-block:: javascript + { + $function: { + body: , + args: , + lang: "js" + } + } - { - $function: { - body: , - args: , - lang: "js" - } - } +.. list-table:: + :header-rows: 1 + :widths: 20 20 80 - .. list-table:: - :header-rows: 1 - :widths: 20 20 80 + * - Field + - Type + - Description + - * - Field - - Type - - Description - + * - :ref:`body ` - * - :ref:`body ` + - String or Code - - String or Code - - - .. _function-body: + - .. _function-body: - The function definition. You can specify the function - definition as either BSON type Code or String. See also - :ref:`lang `. + The function definition. You can specify the function + definition as either BSON type Code or String. See also + :ref:`lang `. - ``function(arg1, arg2, ...) { ... }`` + ``function(arg1, arg2, ...) { ... }`` - or + or - ``"function(arg1, arg2, ...) { ... }"`` + ``"function(arg1, arg2, ...) { ... }"`` - * - :ref:`args ` + * - :ref:`args ` - - Array + - Array - - .. _function-args: + - .. _function-args: - Arguments passed to the function :ref:`body `. - If the :ref:`body ` function does not take an - argument, you can specify an empty array ``[ ]``. + Arguments passed to the function :ref:`body `. + If the :ref:`body ` function does not take an + argument, you can specify an empty array ``[ ]``. - The array elements can be any BSON type, including Code. See - :ref:`function-example-where-alternative`. + The array elements can be any BSON type, including Code. See + :ref:`function-example-where-alternative`. - * - :ref:`lang ` + * - :ref:`lang ` - - String + - String - - .. _function-lang: + - .. _function-lang: - The language used in the :ref:`body `. You - must specify ``lang: "js"``. + The language used in the :ref:`body `. You + must specify ``lang: "js"``. Considerations @@ -164,76 +162,74 @@ Examples Example 1: Usage Example ~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Create a sample collection named ``players`` with the following +documents: - Create a sample collection named ``players`` with the following - documents: +.. code-block:: javascript - .. code-block:: javascript + db.players.insertMany([ + { _id: 1, name: "Miss Cheevous", scores: [ 10, 5, 10 ] }, + { _id: 2, name: "Miss Ann Thrope", scores: [ 10, 10, 10 ] }, + { _id: 3, name: "Mrs. Eppie Delta ", scores: [ 9, 8, 8 ] } + ]) - db.players.insertMany([ - { _id: 1, name: "Miss Cheevous", scores: [ 10, 5, 10 ] }, - { _id: 2, name: "Miss Ann Thrope", scores: [ 10, 10, 10 ] }, - { _id: 3, name: "Mrs. Eppie Delta ", scores: [ 9, 8, 8 ] } - ]) +The following aggregation operation uses :pipeline:`$addFields` to +add new fields to each document: - The following aggregation operation uses :pipeline:`$addFields` to - add new fields to each document: - - - ``isFound`` whose value is determined by the custom - :expression:`$function` expression that checks whether the MD5 - hash of the name is equal to a specified hash. - - - ``message`` whose value is determined by the custom - :expression:`$function` expression that format a string message - using a template. - - .. code-block:: javascript - - db.players.aggregate( [ - { $addFields: - { - isFound: - { $function: - { - body: function(name) { - return hex_md5(name) == "15b0a220baa16331e8d80e15367677ad" - }, - args: [ "$name" ], - lang: "js" - } - }, - message: - { $function: - { - body: function(name, scores) { - let total = Array.sum(scores); - return `Hello ${name}. Your total score is ${total}.` - }, - args: [ "$name", "$scores"], - lang: "js" - } +- ``isFound`` whose value is determined by the custom + :expression:`$function` expression that checks whether the MD5 + hash of the name is equal to a specified hash. + +- ``message`` whose value is determined by the custom + :expression:`$function` expression that format a string message + using a template. + +.. code-block:: javascript + + db.players.aggregate( [ + { $addFields: + { + isFound: + { $function: + { + body: function(name) { + return hex_md5(name) == "15b0a220baa16331e8d80e15367677ad" + }, + args: [ "$name" ], + lang: "js" + } + }, + message: + { $function: + { + body: function(name, scores) { + let total = Array.sum(scores); + return `Hello ${name}. Your total score is ${total}.` + }, + args: [ "$name", "$scores"], + lang: "js" } - } + } } - ] ) + } + ] ) - The operation returns the following documents: +The operation returns the following documents: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "name" : "Miss Cheevous", "scores" : [ 10, 5, 10 ], "isFound" : false, "message" : "Hello Miss Cheevous. Your total score is 25." } - { "_id" : 2, "name" : "Miss Ann Thrope", "scores" : [ 10, 10, 10 ], "isFound" : true, "message" : "Hello Miss Ann Thrope. Your total score is 30." } - { "_id" : 3, "name" : "Mrs. Eppie Delta ", "scores" : [ 9, 8, 8 ], "isFound" : false, "message" : "Hello Mrs. Eppie Delta . Your total score is 25." } + { "_id" : 1, "name" : "Miss Cheevous", "scores" : [ 10, 5, 10 ], "isFound" : false, "message" : "Hello Miss Cheevous. Your total score is 25." } + { "_id" : 2, "name" : "Miss Ann Thrope", "scores" : [ 10, 10, 10 ], "isFound" : true, "message" : "Hello Miss Ann Thrope. Your total score is 30." } + { "_id" : 3, "name" : "Mrs. Eppie Delta ", "scores" : [ 9, 8, 8 ], "isFound" : false, "message" : "Hello Mrs. Eppie Delta . Your total score is 25." } .. _function-example-where-alternative: Example 2: Alternative to ``$where`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. admonition:: Aggregation Alternatives Preferred over ``$where`` - :class: note +.. note:: Aggregation Alternatives Preferred over ``$where`` + Starting in MongoDB 3.6, the :query:`$expr` operator allows the use of :ref:`aggregation expressions ` within the diff --git a/source/reference/operator/aggregation/geoNear.txt b/source/reference/operator/aggregation/geoNear.txt index e5ff8a25a08..bbc9835c348 100644 --- a/source/reference/operator/aggregation/geoNear.txt +++ b/source/reference/operator/aggregation/geoNear.txt @@ -199,6 +199,7 @@ When using :pipeline:`$geoNear`, consider that: the calculated distance. - .. include:: /includes/extracts/geoNear-stage-index-requirement.rst + If you have more than one geospatial index on the collection, use the ``keys`` parameter to specify which field to use in the calculation. If you have only one geospatial index, :pipeline:`$geoNear` implicitly diff --git a/source/reference/operator/aggregation/hour.txt b/source/reference/operator/aggregation/hour.txt index fc27afea8ec..66907a97ef7 100644 --- a/source/reference/operator/aggregation/hour.txt +++ b/source/reference/operator/aggregation/hour.txt @@ -106,7 +106,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -120,7 +120,7 @@ Consider a ``sales`` collection with the following document: The following aggregation uses the :expression:`$hour` and other date expressions to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 9 diff --git a/source/reference/operator/aggregation/indexOfArray.txt b/source/reference/operator/aggregation/indexOfArray.txt index 4275b6f2172..8357db0bdcf 100644 --- a/source/reference/operator/aggregation/indexOfArray.txt +++ b/source/reference/operator/aggregation/indexOfArray.txt @@ -209,4 +209,6 @@ The operation returns the following results: { "_id" : 5, "index" : null } -.. seealso:: :expression:`$indexOfBytes`, :expression:`$indexOfCP`, and :expression:`$in` +.. seealso:: + + :expression:`$indexOfBytes`, :expression:`$indexOfCP`, and :expression:`$in` diff --git a/source/reference/operator/aggregation/indexOfBytes.txt b/source/reference/operator/aggregation/indexOfBytes.txt index 219fe3c2fe0..c4e22e86e91 100644 --- a/source/reference/operator/aggregation/indexOfBytes.txt +++ b/source/reference/operator/aggregation/indexOfBytes.txt @@ -151,7 +151,7 @@ Consider an ``inventory`` collection with the following documents: { "_id" : 6, "amount" : 3 } The following operation uses the :expression:`$indexOfBytes` operator to -retrieve the indexes at which the string `foo` is located in each item: +retrieve the indexes at which the string ``foo`` is located in each item: .. code-block:: javascript @@ -178,4 +178,6 @@ The operation returns the following results: { "_id" : 6, "byteLocation" : null } -.. seealso:: :expression:`$indexOfCP` and :expression:`$indexOfArray` +.. seealso:: + + :expression:`$indexOfCP` and :expression:`$indexOfArray` diff --git a/source/reference/operator/aggregation/indexOfCP.txt b/source/reference/operator/aggregation/indexOfCP.txt index 41ace8fa13e..1dea93a20f4 100644 --- a/source/reference/operator/aggregation/indexOfCP.txt +++ b/source/reference/operator/aggregation/indexOfCP.txt @@ -217,4 +217,6 @@ The operation returns the following results: { "_id" : 6, "cpLocation" : null } -.. seealso:: :expression:`$indexOfBytes` and :expression:`$indexOfArray` +.. seealso:: + + :expression:`$indexOfBytes` and :expression:`$indexOfArray` diff --git a/source/reference/operator/aggregation/isArray.txt b/source/reference/operator/aggregation/isArray.txt index b0acb6e7212..bde6cbd912c 100644 --- a/source/reference/operator/aggregation/isArray.txt +++ b/source/reference/operator/aggregation/isArray.txt @@ -83,4 +83,6 @@ fields are arrays before concatenating the two: { "_id" : 3, "items" : [ "pears", "pecans", "cherries" ] } { "_id" : 4, "items" : [ "ice cream" ] } -.. seealso:: :expression:`$cond`, :expression:`$concatArrays` \ No newline at end of file +.. seealso:: + + :expression:`$cond`, :expression:`$concatArrays` diff --git a/source/reference/operator/aggregation/isNumber.txt b/source/reference/operator/aggregation/isNumber.txt index 01973e167ee..e110d7bde82 100644 --- a/source/reference/operator/aggregation/isNumber.txt +++ b/source/reference/operator/aggregation/isNumber.txt @@ -45,7 +45,9 @@ Definition The argument can be any valid :ref:`expression `. -.. seealso:: +.. seealso:: + + - :expression:`$type (Aggregation) <$type>` - returns the BSON type of the argument. - :query:`$type (Query) <$type>` - filters fields based on BSON type. diff --git a/source/reference/operator/aggregation/isoDayOfWeek.txt b/source/reference/operator/aggregation/isoDayOfWeek.txt index d5569cd110c..259a6ae3250 100644 --- a/source/reference/operator/aggregation/isoDayOfWeek.txt +++ b/source/reference/operator/aggregation/isoDayOfWeek.txt @@ -109,7 +109,7 @@ Example A collection called ``birthdays`` contains the following documents: -.. class:: copyable-code + .. code-block:: javascript { "_id" : 1, "name" : "Betty", "birthday" : ISODate("1993-09-21T00:00:00Z") } @@ -118,7 +118,7 @@ A collection called ``birthdays`` contains the following documents: The following operation returns the weekday number for each ``birthday`` field. -.. class:: copyable-code + .. code-block:: javascript db.dates.aggregate( [ diff --git a/source/reference/operator/aggregation/isoWeek.txt b/source/reference/operator/aggregation/isoWeek.txt index e7a7d348b15..7552c4522ec 100644 --- a/source/reference/operator/aggregation/isoWeek.txt +++ b/source/reference/operator/aggregation/isoWeek.txt @@ -110,7 +110,7 @@ Example A collection called ``deliveries`` contains the following documents: -.. class:: copyable-code + .. code-block:: javascript { "_id" : 1, "date" : ISODate("2006-10-24T00:00:00Z"), "city" : "Boston" } @@ -118,7 +118,7 @@ A collection called ``deliveries`` contains the following documents: The following operation returns the week number for each ``date`` field. -.. class:: copyable-code + .. code-block:: javascript db.deliveries.aggregate( [ diff --git a/source/reference/operator/aggregation/isoWeekYear.txt b/source/reference/operator/aggregation/isoWeekYear.txt index 969c62f66e1..3812b2c12f5 100644 --- a/source/reference/operator/aggregation/isoWeekYear.txt +++ b/source/reference/operator/aggregation/isoWeekYear.txt @@ -110,7 +110,7 @@ Example A collection called ``anniversaries`` contains the following documents: -.. class:: copyable-code + .. code-block:: javascript { "_id" : 1, "date" : ISODate("2016-01-01T00:00:00Z") } @@ -121,7 +121,7 @@ A collection called ``anniversaries`` contains the following documents: The following operation returns the year number in ISO 8601 format for each ``date`` field. -.. class:: copyable-code + .. code-block:: javascript db.anniversaries.aggregate( [ diff --git a/source/reference/operator/aggregation/last-array-element.txt b/source/reference/operator/aggregation/last-array-element.txt index 6000079bbd6..5dd5aaafced 100644 --- a/source/reference/operator/aggregation/last-array-element.txt +++ b/source/reference/operator/aggregation/last-array-element.txt @@ -19,8 +19,8 @@ Definition Returns the last element in an array. - .. admonition:: Disambiguation - :class: note + .. note:: Disambiguation + The following page describes the array element operator :expression:`$last`. For the accumulator :group:`$last`, @@ -202,7 +202,7 @@ The operation returns the following documents: { "_id" : 2, "team" : "Bears", "progress" : -2 } { "_id" : 3, "team" : "Cobras", "progress" : "Not enough data." } -By default, the :binary:`~bin.shell` uses the 64-bit floating-point +By default, the :binary:`~bin.mongo` shell uses the 64-bit floating-point double for numbers. To improve precision, you can use :ref:`shell-type-decimal` instead. diff --git a/source/reference/operator/aggregation/last.txt b/source/reference/operator/aggregation/last.txt index dd96e5147e0..bbe2c2f78c7 100644 --- a/source/reference/operator/aggregation/last.txt +++ b/source/reference/operator/aggregation/last.txt @@ -21,8 +21,8 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-last.rst - .. admonition:: Disambiguation - :class: note + .. note:: Disambiguation + The following page describes the accumulator :group:`$last`, available only within the :pipeline:`$group` stage. For the array diff --git a/source/reference/operator/aggregation/let.txt b/source/reference/operator/aggregation/let.txt index 5a330e08fda..327f4bec36c 100644 --- a/source/reference/operator/aggregation/let.txt +++ b/source/reference/operator/aggregation/let.txt @@ -133,4 +133,6 @@ The aggregation returns the following results: { "_id" : 1, "finalTotal" : 9.450000000000001 } { "_id" : 2, "finalTotal" : 10.25 } -.. seealso:: :expression:`$map` +.. seealso:: + + :expression:`$map` diff --git a/source/reference/operator/aggregation/limit.txt b/source/reference/operator/aggregation/limit.txt index 117a6dd659c..f99e0a9d39d 100644 --- a/source/reference/operator/aggregation/limit.txt +++ b/source/reference/operator/aggregation/limit.txt @@ -80,6 +80,8 @@ of the documents it passes. .. include:: /includes/fact-agg-sort-limit.rst -.. seealso:: +.. seealso:: + + :doc:`/tutorial/aggregation-zip-code-data-set`, :doc:`/tutorial/aggregation-with-user-preference-data` diff --git a/source/reference/operator/aggregation/listLocalSessions.txt b/source/reference/operator/aggregation/listLocalSessions.txt index 6b021b6ec88..9f7920f336f 100644 --- a/source/reference/operator/aggregation/listLocalSessions.txt +++ b/source/reference/operator/aggregation/listLocalSessions.txt @@ -62,14 +62,14 @@ Definition - Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges - with :authaction:`listSession` action on the cluster to list + with :authaction:`listSessions` action on the cluster to list sessions for other users. * - ``{ allUsers: true }`` - Returns all sessions for all users. If running with access control, the authenticated user must have privileges with - :authaction:`listSession` action on the cluster. + :authaction:`listSessions` action on the cluster. Restrictions ------------ @@ -89,7 +89,7 @@ all sessions: .. note:: If running with access control, the current user must have - privileges with :authaction:`listSession` action on the cluster. + privileges with :authaction:`listSessions` action on the cluster. .. code-block:: javascript @@ -106,7 +106,7 @@ sessions for the specified user ``myAppReader@test``: If running with access control and the current user is not the specified user, the current user must - have privileges with :authaction:`listSession` action on the cluster. + have privileges with :authaction:`listSessions` action on the cluster. .. code-block:: javascript diff --git a/source/reference/operator/aggregation/listSessions.txt b/source/reference/operator/aggregation/listSessions.txt index e3dd35f8b6e..a6ec5fada3a 100644 --- a/source/reference/operator/aggregation/listSessions.txt +++ b/source/reference/operator/aggregation/listSessions.txt @@ -60,14 +60,14 @@ Definition - Returns all sessions for the specified users. If running with access control, the authenticated user must have privileges - with :authaction:`listSession` action on the cluster to list + with :authaction:`listSessions` action on the cluster to list sessions for other users. * - ``{ allUsers: true }`` - Returns all sessions for all users. If running with access control, the authenticated user must have privileges with - :authaction:`listSession` action on the cluster. + :authaction:`listSessions` action on the cluster. Restrictions ------------ @@ -86,7 +86,7 @@ the following aggregation operation lists all sessions: .. note:: If running with access control, the current user must have - privileges with :authaction:`listSession` action on the cluster. + privileges with :authaction:`listSessions` action on the cluster. .. code-block:: javascript @@ -105,7 +105,7 @@ specified user ``myAppReader@test``: If running with access control and the current user is not the specified user, the current user must - have privileges with :authaction:`listSession` action on the cluster. + have privileges with :authaction:`listSessions` action on the cluster. .. code-block:: javascript diff --git a/source/reference/operator/aggregation/literal.txt b/source/reference/operator/aggregation/literal.txt index 67d9d3584e9..24c7693d775 100644 --- a/source/reference/operator/aggregation/literal.txt +++ b/source/reference/operator/aggregation/literal.txt @@ -61,7 +61,7 @@ Treat ``$`` as a Literal In :ref:`expression `, the dollar sign ``$`` evaluates to a field path; i.e. provides access -to the field. For example, the :operator:`$eq` expression ``$eq: [ +to the field. For example, the :expression:`$eq` expression ``$eq: [ "$price", "$1" ]`` performs an equality check between the value in the field named ``price`` and the value in the field named ``1`` in the document. diff --git a/source/reference/operator/aggregation/ln.txt b/source/reference/operator/aggregation/ln.txt index 0eb82113ef2..4453a89a304 100644 --- a/source/reference/operator/aggregation/ln.txt +++ b/source/reference/operator/aggregation/ln.txt @@ -83,4 +83,6 @@ The operation returns the following results: { "_id" : 2, "x" : "2005", "y" : 15.424948470398375 } { "_id" : 3, "x" : "2010", "y" : 15.648092021712584 } -.. seealso:: :expression:`$log` +.. seealso:: + + :expression:`$log` diff --git a/source/reference/operator/aggregation/log.txt b/source/reference/operator/aggregation/log.txt index e3fef8b512d..f4a6db7aac9 100644 --- a/source/reference/operator/aggregation/log.txt +++ b/source/reference/operator/aggregation/log.txt @@ -89,4 +89,6 @@ The operation returns the following results: { "_id" : 3, "bitsNeeded" : 5 } { "_id" : 4, "bitsNeeded" : 4 } -.. seealso:: :expression:`$log10` and :expression:`$ln` +.. seealso:: + + :expression:`$log10` and :expression:`$ln` diff --git a/source/reference/operator/aggregation/log10.txt b/source/reference/operator/aggregation/log10.txt index 16264cd1414..bee3c1bf6d5 100644 --- a/source/reference/operator/aggregation/log10.txt +++ b/source/reference/operator/aggregation/log10.txt @@ -85,4 +85,6 @@ The operation returns the following results: { "_id" : 2, "pH" : 3 } { "_id" : 3, "pH" : 1.6989700043360187 } -.. seealso:: :expression:`$log` +.. seealso:: + + :expression:`$log` diff --git a/source/reference/operator/aggregation/lookup.txt b/source/reference/operator/aggregation/lookup.txt index c9a9348307f..bfbd52fe4c4 100644 --- a/source/reference/operator/aggregation/lookup.txt +++ b/source/reference/operator/aggregation/lookup.txt @@ -438,8 +438,6 @@ Perform a Single Equality Join with ``$lookup`` Create a collection ``orders`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.insert([ @@ -450,8 +448,6 @@ Create a collection ``orders`` with these documents: Create another collection ``inventory`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.inventory.insert([ @@ -469,8 +465,6 @@ joins the documents from ``orders`` with the documents from the ``orders`` collection and the ``sku`` field from the ``inventory`` collection: -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.aggregate([ @@ -615,8 +609,6 @@ Use ``$lookup`` with ``$mergeObjects`` Create a collection ``orders`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.insert([ @@ -626,8 +618,6 @@ Create a collection ``orders`` with these documents: Create another collection ``items`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.items.insert([ @@ -641,8 +631,6 @@ join the two collections by the ``item`` fields and then uses :expression:`$mergeObjects` in the :pipeline:`$replaceRoot` to merge the joined documents from ``items`` and ``orders``: -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.aggregate([ @@ -687,8 +675,6 @@ MongoDB 5.0 also supports :ref:`concise correlated subqueries Create a collection ``orders`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.insert([ @@ -699,8 +685,6 @@ Create a collection ``orders`` with these documents: Create another collection ``warehouses`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.warehouses.insert([ @@ -719,8 +703,6 @@ The following example: - Ensures the quantity of the item in stock can fulfill the ordered quantity. -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.aggregate([ @@ -779,11 +761,12 @@ the ``warehouses`` collection: - The equality match on the ``warehouses.stock_item`` field uses the index. - - The range part of the query on the ``warehouses.instock`` field also uses the indexed field in the compound index. -.. seealso:: +.. seealso:: + + - :query:`$expr` - :doc:`/reference/aggregation-variables/` @@ -801,8 +784,6 @@ Perform an Uncorrelated Subquery with ``$lookup`` Create a collection ``absences`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.absences.insert([ @@ -812,8 +793,6 @@ Create a collection ``absences`` with these documents: Create another collection ``holidays`` with these documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.holidays.insert([ @@ -827,8 +806,6 @@ Create another collection ``holidays`` with these documents: The following operation joins the ``absences`` collection with 2018 holiday information from the ``holidays`` collection: -.. cssclass:: copyable-code - .. code-block:: javascript db.absences.aggregate([ diff --git a/source/reference/operator/aggregation/ltrim.txt b/source/reference/operator/aggregation/ltrim.txt index d4010426c43..407d5e13dd9 100644 --- a/source/reference/operator/aggregation/ltrim.txt +++ b/source/reference/operator/aggregation/ltrim.txt @@ -59,7 +59,9 @@ Definition characters, including the null character. For the list of whitespace characters, see :ref:`ltrim-white-space`. - .. seealso:: :expression:`$trim` and :expression:`$rtrim` + .. seealso:: + + :expression:`$trim` and :expression:`$rtrim` Behavior -------- diff --git a/source/reference/operator/aggregation/map.txt b/source/reference/operator/aggregation/map.txt index c7cb506aa7a..78855ab4862 100644 --- a/source/reference/operator/aggregation/map.txt +++ b/source/reference/operator/aggregation/map.txt @@ -195,7 +195,9 @@ This operation returns the following results: { "_id" : 2, "date" : ISODate("2019-07-07T00:00:00Z"), "tempsC" : [ 14, 24, 11 ], "tempsF" : [ 57.2, 75.2, 51.8 ] } { "_id" : 3, "date" : ISODate("2019-10-30T00:00:00Z"), "tempsC" : [ 18, 6, 8 ], "tempsF" : [ 64.4, 42.8, 46.4 ] } -.. seealso:: +.. seealso:: + + - :expression:`$let` - :expression:`$add` diff --git a/source/reference/operator/aggregation/max.txt b/source/reference/operator/aggregation/max.txt index 85f6155ae85..e5030b1475d 100644 --- a/source/reference/operator/aggregation/max.txt +++ b/source/reference/operator/aggregation/max.txt @@ -21,7 +21,7 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-max.rst - When used in the :pipeline:`$group` stage, :expression:`$max` has the + When used in the :pipeline:`$group` stage, :group:`$max` has the following syntax and returns the maximum value that results from applying an expression to each document in a group of documents that share the same group by key: @@ -31,16 +31,16 @@ Definition { $max: } When used in the other supported stages, - :expression:`$max` returns the maximum of the specified expression + :group:`$max` returns the maximum of the specified expression or list of expressions for each document and has one of two syntaxes: - - :expression:`$max` has one specified expression as its operand: + - :group:`$max` has one specified expression as its operand: .. code-block:: javascript { $max: } - - :expression:`$max` has a list of specified expressions as its + - :group:`$max` has a list of specified expressions as its operand: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/merge.txt b/source/reference/operator/aggregation/merge.txt index 9793443ee42..595657ca513 100644 --- a/source/reference/operator/aggregation/merge.txt +++ b/source/reference/operator/aggregation/merge.txt @@ -58,7 +58,7 @@ Definition the aggregation results to a collection, see :ref:`merge-out-comparison`. -.. topic:: On-Demand Materialized Views +.. note:: On-Demand Materialized Views :pipeline:`$merge` can incorporate the pipeline results into an existing output collection rather than perform a full replacement of @@ -418,183 +418,173 @@ Considerations ``_id`` Field Generation ~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +If the ``_id`` field is not present in a document from the +aggregation pipeline results, the :pipeline:`$merge` stage generates +it automatically. - If the ``_id`` field is not present in a document from the - aggregation pipeline results, the :pipeline:`$merge` stage generates - it automatically. - - For example, in the following aggregation pipeline, - :pipeline:`$project` excludes the ``_id`` field from the documents - passed into :pipeline:`$merge`. When :pipeline:`$merge` writes these - documents to the ``"newCollection"``, :pipeline:`$merge` generates a - new ``_id`` field and value. - - .. code-block:: javascript - - db.sales.aggregate( [ - { $project: { _id: 0 } }, - { $merge : { into : "newCollection" } } - ] ) +For example, in the following aggregation pipeline, +:pipeline:`$project` excludes the ``_id`` field from the documents +passed into :pipeline:`$merge`. When :pipeline:`$merge` writes these +documents to the ``"newCollection"``, :pipeline:`$merge` generates a +new ``_id`` field and value. + +.. code-block:: javascript + + db.sales.aggregate( [ + { $project: { _id: 0 } }, + { $merge : { into : "newCollection" } } + ] ) .. _merge-behavior-create-collection: Create a New Collection if Output Collection is Non-Existent ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +The :pipeline:`$merge` operation creates a new collection if the +specified output collection does not exist. - The :pipeline:`$merge` operation creates a new collection if the - specified output collection does not exist. +- The output collection is created when :pipeline:`$merge` writes + the first document into the collection and is immediately visible. - - The output collection is created when :pipeline:`$merge` writes - the first document into the collection and is immediately visible. +- If the aggregation fails, any writes completed by the + :pipeline:`$merge` before the error will not be rolled back. - - If the aggregation fails, any writes completed by the - :pipeline:`$merge` before the error will not be rolled back. +.. note:: - .. note:: - - For a :ref:`replica set ` or a standalone, if the - output database does not exist, :pipeline:`$merge` also creates - the database. + For a :ref:`replica set ` or a standalone, if the + output database does not exist, :pipeline:`$merge` also creates + the database. - For a :ref:`sharded cluster `, the specified - output database must already exist. + For a :ref:`sharded cluster `, the specified + output database must already exist. - .. _merge-use-different-on: +.. _merge-use-different-on: - If the output collection does not exist, :pipeline:`$merge` requires - the :ref:`on ` identifier to be the ``_id`` field. To use a - different ``on`` field value for a collection that does not exist, you - can create the collection first by creating a unique index on the - desired field(s) first. For example, if the output collection - ``newDailySales201905`` does not exist and you want to specify the - ``salesDate`` field as the :ref:`on ` identifier: +If the output collection does not exist, :pipeline:`$merge` requires +the :ref:`on ` identifier to be the ``_id`` field. To use a +different ``on`` field value for a collection that does not exist, you +can create the collection first by creating a unique index on the +desired field(s) first. For example, if the output collection +``newDailySales201905`` does not exist and you want to specify the +``salesDate`` field as the :ref:`on ` identifier: - .. code-block:: javascript +.. code-block:: javascript - db.newDailySales201905.createIndex( { salesDate: 1 }, { unique: true } ) + db.newDailySales201905.createIndex( { salesDate: 1 }, { unique: true } ) - db.sales.aggregate( [ - { $match: { date: { $gte: new Date("2019-05-01"), $lt: new Date("2019-06-01") } } }, - { $group: { _id: { $dateToString: { format: "%Y-%m-%d", date: "$date" } }, totalqty: { $sum: "$quantity" } } }, - { $project: { _id: 0, salesDate: { $toDate: "$_id" }, totalqty: 1 } }, - { $merge : { into : "newDailySales201905", on: "salesDate" } } - ] ) + db.sales.aggregate( [ + { $match: { date: { $gte: new Date("2019-05-01"), $lt: new Date("2019-06-01") } } }, + { $group: { _id: { $dateToString: { format: "%Y-%m-%d", date: "$date" } }, totalqty: { $sum: "$quantity" } } }, + { $project: { _id: 0, salesDate: { $toDate: "$_id" }, totalqty: 1 } }, + { $merge : { into : "newDailySales201905", on: "salesDate" } } + ] ) Output to a Sharded Collection ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +The :pipeline:`$merge` stage can output to a sharded collection. +When the output collection is sharded, :pipeline:`$merge` uses +the ``_id`` field and all the :ref:`shard key +` fields as the default :ref:`on +` identifier. If you override the default, the :ref:`on +` identifier must include all the :ref:`shard key +` fields: - The :pipeline:`$merge` stage can output to a sharded collection. - When the output collection is sharded, :pipeline:`$merge` uses - the ``_id`` field and all the :ref:`shard key - ` fields as the default :ref:`on - ` identifier. If you override the default, the :ref:`on - ` identifier must include all the :ref:`shard key - ` fields: - - .. code-block:: javascript +.. code-block:: javascript - { $merge: { - into: "" or { db:"", coll: "" }, - on: [ "", "",... ], // Shard key fields and any additional fields - let: , // Optional - whenMatched: , // Optional - whenNotMatched: // Optional - } } + { $merge: { + into: "" or { db:"", coll: "" }, + on: [ "", "",... ], // Shard key fields and any additional fields + let: , // Optional + whenMatched: , // Optional + whenNotMatched: // Optional + } } - For example, in a database that has :method:`sharding enabled - `, use the :method:`sh.shardCollection()` method - to create a new sharded collection ``newrestaurants`` with the - ``postcode`` field as the shard key. +For example, in a database that has :method:`sharding enabled +`, use the :method:`sh.shardCollection()` method +to create a new sharded collection ``newrestaurants`` with the +``postcode`` field as the shard key. - .. code-block:: javascript +.. code-block:: javascript - sh.enableSharding("exampledb"); // Sharding must be enabled in the database - sh.shardCollection( - "exampledb.newrestaurants", // Namespace of the collection to shard - { postcode: 1 }, // Shard key - ); - - The ``newrestaurants`` collection will contain documents with - information on new restaurant openings by month (``date`` field) and - postcode (shard key); specifically, the :ref:`on ` - identifier is ``["date", "postcode"]`` (the ordering of the fields - does not matter). Because :pipeline:`$merge` requires a unique, - index with keys that correspond to the :ref:`on - ` identifier fields, create the unique index - (the ordering of the fields do not matter): [#uniqueoption]_ + sh.enableSharding("exampledb"); // Sharding must be enabled in the database + sh.shardCollection( + "exampledb.newrestaurants", // Namespace of the collection to shard + { postcode: 1 }, // Shard key + ); + +The ``newrestaurants`` collection will contain documents with +information on new restaurant openings by month (``date`` field) and +postcode (shard key); specifically, the :ref:`on ` +identifier is ``["date", "postcode"]`` (the ordering of the fields +does not matter). Because :pipeline:`$merge` requires a unique, +index with keys that correspond to the :ref:`on +` identifier fields, create the unique index +(the ordering of the fields do not matter): [#uniqueoption]_ - .. code-block:: javascript +.. code-block:: javascript - use exampledb - db.newrestaurants.createIndex( { postcode: 1, date: 1 }, { unique: true } ) + use exampledb + db.newrestaurants.createIndex( { postcode: 1, date: 1 }, { unique: true } ) - With the sharded collection ``restaurants`` and the unique index - created, you can use :pipeline:`$merge` to output the aggregation - results to this collection, matching on ``[ "date", "postcode" ]`` - as in this example: +With the sharded collection ``restaurants`` and the unique index +created, you can use :pipeline:`$merge` to output the aggregation +results to this collection, matching on ``[ "date", "postcode" ]`` +as in this example: - .. code-block:: javascript +.. code-block:: javascript - use exampledb + use exampledb - db.openings.aggregate([ - { $group: { - _id: { date: { $dateToString: { format: "%Y-%m", date: "$date" } }, postcode: "$postcode" }, - restaurants: { $push: "$restaurantName" } } }, - { $project: { _id: 0, postcode: "$_id.postcode", date: "$_id.date", restaurants: 1 } }, - { $merge: { into: "newrestaurants", "on": [ "date", "postcode" ], whenMatched: "replace", whenNotMatched: "insert" } } - ]) + db.openings.aggregate([ + { $group: { + _id: { date: { $dateToString: { format: "%Y-%m", date: "$date" } }, postcode: "$postcode" }, + restaurants: { $push: "$restaurantName" } } }, + { $project: { _id: 0, postcode: "$_id.postcode", date: "$_id.date", restaurants: 1 } }, + { $merge: { into: "newrestaurants", "on": [ "date", "postcode" ], whenMatched: "replace", whenNotMatched: "insert" } } + ]) - .. [#uniqueoption] +.. [#uniqueoption] - The :method:`sh.shardCollection()` method can also create a - unique index on the shard key when passed the ``{ unique: true - }`` option if: the shard key is :doc:`range-based - `, the collection is empty, and a unique - index on the shard key doesn't already exist. + The :method:`sh.shardCollection()` method can also create a + unique index on the shard key when passed the ``{ unique: true + }`` option if: the shard key is :doc:`range-based + `, the collection is empty, and a unique + index on the shard key doesn't already exist. - In the previous example, because the ``on`` identifier is the - shard key and another field, a separate operation to create the - corresponding index is required. + In the previous example, because the ``on`` identifier is the + shard key and another field, a separate operation to create the + corresponding index is required. .. _merge-behavior-replaceCollection: Replace Documents (``$merge``) vs Replace Collection (``$out``) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - :pipeline:`$merge` can replace an existing document in the output - collection if the aggregation results contain a document or - documents that match based on the :ref:`on ` - specification. As such, :pipeline:`$merge` can replace all documents - in the existing collection if the aggregation results include - matching documents for all existing documents in the collection and - you specify :ref:`"replace" ` for - :ref:`whenMatched `. +:pipeline:`$merge` can replace an existing document in the output +collection if the aggregation results contain a document or +documents that match based on the :ref:`on ` +specification. As such, :pipeline:`$merge` can replace all documents +in the existing collection if the aggregation results include +matching documents for all existing documents in the collection and +you specify :ref:`"replace" ` for +:ref:`whenMatched `. - However, **to replace an existing collection** regardless of the - aggregation results, use :pipeline:`$out` instead. +However, **to replace an existing collection** regardless of the +aggregation results, use :pipeline:`$out` instead. Existing Documents and ``_id`` and Shard Key Values ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - The :pipeline:`$merge` errors if the :pipeline:`$merge` results in a - change to an existing document's ``_id`` value. +The :pipeline:`$merge` errors if the :pipeline:`$merge` results in a +change to an existing document's ``_id`` value. - .. tip:: +.. tip:: - To avoid this error, if the :ref:`on ` field does not - include the ``_id`` field, remove the ``_id`` field in the - aggregation results to avoid the error, such as with a preceding - :pipeline:`$unset` stage, and so on. + To avoid this error, if the :ref:`on ` field does not + include the ``_id`` field, remove the ``_id`` field in the + aggregation results to avoid the error, such as with a preceding + :pipeline:`$unset` stage, and so on. Additionally, for a sharded collection, :pipeline:`$merge` also generates an error if it results in a change to the shard key value @@ -608,137 +598,129 @@ Existing Documents and ``_id`` and Shard Key Values Unique Index Constraints ~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +If the unique index used by :pipeline:`$merge` for :ref:`on +` field(s) is dropped mid-aggregation, there is no +guarantee that the aggregation will be killed. If the aggregation +continues, there is no guarantee that documents do not have +duplicate ``on`` field values. - If the unique index used by :pipeline:`$merge` for :ref:`on - ` field(s) is dropped mid-aggregation, there is no - guarantee that the aggregation will be killed. If the aggregation - continues, there is no guarantee that documents do not have - duplicate ``on`` field values. +If the :pipeline:`$merge` attempts to write a document that violates +any unique index on the output collection, the operation generates an +error. For example: - If the :pipeline:`$merge` attempts to write a document that violates - any unique index on the output collection, the operation generates an - error. For example: +- :ref:`Insert a non-matching document + ` that violates a unique index other + than the index on the :ref:`on ` field(s). - - :ref:`Insert a non-matching document - ` that violates a unique index other - than the index on the :ref:`on ` field(s). +- :ref:`Fail ` if there is a matching + document in the collection. Specifically, the operation attempts + to insert the matching document which violates the unique index on + the :ref:`on ` field(s). - - :ref:`Fail ` if there is a matching - document in the collection. Specifically, the operation attempts - to insert the matching document which violates the unique index on - the :ref:`on ` field(s). +- :ref:`Replace an existing document + ` with a new document that + violates a unique index other than the index on the :ref:`on + ` field(s). - - :ref:`Replace an existing document - ` with a new document that - violates a unique index other than the index on the :ref:`on - ` field(s). - - - :ref:`Merge the matching documents ` that - results in a document that violates a unique index other than the - index on the :ref:`on ` field(s). +- :ref:`Merge the matching documents ` that + results in a document that violates a unique index other than the + index on the :ref:`on ` field(s). ``whenMatched`` Pipeline Behavior ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - Starting in MongoDB 4.2.2, if all of the following are true for a - :pipeline:`$merge` stage: +Starting in MongoDB 4.2.2, if all of the following are true for a +:pipeline:`$merge` stage: - - The value of :ref:`whenMatched ` is an - aggregation pipeline, - - - The value of :ref:`whenNotMatched ` is - ``insert``, and +- The value of :ref:`whenMatched ` is an + aggregation pipeline, + +- The value of :ref:`whenNotMatched ` is + ``insert``, and - - There is no match for a document in the output collection, +- There is no match for a document in the output collection, - :pipeline:`$merge` inserts the document directly into the output - collection. +:pipeline:`$merge` inserts the document directly into the output +collection. - Prior to MongoDB 4.2.2, when these conditions for a - :pipeline:`$merge` stage are met, the pipeline specified in the - :ref:`whenMatched ` field is executed with an - empty input document. The resulting document from the pipeline is - inserted into the output collection. +Prior to MongoDB 4.2.2, when these conditions for a +:pipeline:`$merge` stage are met, the pipeline specified in the +:ref:`whenMatched ` field is executed with an +empty input document. The resulting document from the pipeline is +inserted into the output collection. - .. seealso:: +.. seealso:: - :ref:`4.2.2 Release Notes <4.2.2-release-notes>` + :ref:`4.2.2 Release Notes <4.2.2-release-notes>` .. _merge-out-comparison: -Comparison with ``$out`` -~~~~~~~~~~~~~~~~~~~~~~~~ +``$merge`` and ``$out`` Comparison +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. topic:: ``$merge`` and ``$out`` Comparison +With the introduction of :pipeline:`$merge`, MongoDB provides two +stages, :pipeline:`$merge` and :pipeline:`$out`, for writing the +results of the aggregation pipeline to a collection: - With the introduction of :pipeline:`$merge`, MongoDB provides two - stages, :pipeline:`$merge` and :pipeline:`$out`, for writing the - results of the aggregation pipeline to a collection: - - .. list-table:: - :header-rows: 1 - :class: border-table +.. list-table:: + :header-rows: 1 + :class: border-table - * - :pipeline:`$merge` - - :pipeline:`$out` + * - :pipeline:`$merge` + - :pipeline:`$out` - * - - Available starting in MongoDB 4.2 - - - Available starting in MongoDB 2.6 + * - - Available starting in MongoDB 4.2 + - - Available starting in MongoDB 2.6 - * - - Can output to a collection in the same or different database. - - - Can output to a collection in the same or, starting in - MongoDB 4.4, different database. + * - - Can output to a collection in the same or different database. + - - Can output to a collection in the same or, starting in + MongoDB 4.4, different database. - * - - Creates a new collection if the output collection does not - already exist. + * - - Creates a new collection if the output collection does not + already exist. - - - Creates a new collection if the output collection does not - already exist. + - - Creates a new collection if the output collection does not + already exist. - * - - Can incorporate results (insert new documents, merge - documents, replace documents, keep existing documents, fail - the operation, process documents with a custom update pipeline) into - an existing collection. + * - - Can incorporate results (insert new documents, merge + documents, replace documents, keep existing documents, fail + the operation, process documents with a custom update pipeline) into + an existing collection. - | See also :ref:`merge-behavior-replaceCollection`. + | See also :ref:`merge-behavior-replaceCollection`. - - - Replaces the output collection completely if it already exists. + - - Replaces the output collection completely if it already exists. - * - - Can output to a sharded collection. Input collection can - also be sharded. + * - - Can output to a sharded collection. Input collection can + also be sharded. - - - Cannot output to a sharded collection. Input collection, - however, can be sharded. + - - Cannot output to a sharded collection. Input collection, + however, can be sharded. - * - - Corresponds to SQL statements: + * - - Corresponds to SQL statements: - - ``MERGE``. + - ``MERGE``. - - ``INSERT INTO T2 SELECT FROM T1``. + - ``INSERT INTO T2 SELECT FROM T1``. - - ``SELECT INTO T2 FROM T1``. - - - Create/Refresh Materialized Views. + - ``SELECT INTO T2 FROM T1``. + + - Create/Refresh Materialized Views. - - - Corresponds to SQL statement: + - - Corresponds to SQL statement: - - ``INSERT INTO T2 SELECT FROM T1``. + - ``INSERT INTO T2 SELECT FROM T1``. - - ``SELECT INTO T2 FROM T1``. + - ``SELECT INTO T2 FROM T1``. .. _merge-behavior-same-collection: Output to the Same Collection that is Being Aggregated ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +.. include:: /includes/fact-merge-same-collection-warning.rst - .. include:: /includes/fact-merge-same-collection-warning.rst - - .. include:: /includes/fact-merge-same-collection-behavior.rst +.. include:: /includes/fact-merge-same-collection-behavior.rst Restrictions ------------ @@ -796,725 +778,721 @@ Examples On-Demand Materialized View: Initial Creation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +If the output collection does not exist, the :pipeline:`$merge` creates +the collection. - If the output collection does not exist, the :pipeline:`$merge` creates - the collection. +For example, a collection named ``salaries`` in the ``zoo`` database +is populated with the employee salary and department history: - For example, a collection named ``salaries`` in the ``zoo`` database - is populated with the employee salary and department history: +.. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("zoo").salaries.insertMany([ + { "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 }, + { "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 }, + { "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 }, + { "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 }, + { "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 }, + { "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 }, + { "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 }, + { "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 }, + { "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 }, + { "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 } + ]) - db.getSiblingDB("zoo").salaries.insertMany([ - { "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 }, - { "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 }, - { "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 }, - { "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 }, - { "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 }, - { "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 }, - { "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 }, - { "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 }, - { "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 }, - { "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 } - ]) +You can use the :pipeline:`$group` and :pipeline:`$merge` stages to +initially create a collection named ``budgets`` (in the ``reporting`` +database) from the data currently in the ``salaries`` collection: - You can use the :pipeline:`$group` and :pipeline:`$merge` stages to - initially create a collection named ``budgets`` (in the ``reporting`` - database) from the data currently in the ``salaries`` collection: +.. note:: - .. note:: + For a replica set or a standalone deployment, if the output + database does not exist, :pipeline:`$merge` also creates the + database. - For a replica set or a standalone deployment, if the output - database does not exist, :pipeline:`$merge` also creates the - database. + For a sharded cluster deployment, the specified output database + must already exist. - For a sharded cluster deployment, the specified output database - must already exist. +.. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("zoo").salaries.aggregate( [ + { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, salaries: { $sum: "$salary" } } }, + { $merge : { into: { db: "reporting", coll: "budgets" }, on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } + ] ) - db.getSiblingDB("zoo").salaries.aggregate( [ - { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, salaries: { $sum: "$salary" } } }, - { $merge : { into: { db: "reporting", coll: "budgets" }, on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } - ] ) +- :pipeline:`$group` stage to group the salaries by the ``fiscal_year`` + and ``dept``. - - :pipeline:`$group` stage to group the salaries by the ``fiscal_year`` - and ``dept``. +- :pipeline:`$merge` stage writes the output of the preceding + :pipeline:`$group` stage to the ``budgets`` collection in the + ``reporting`` database. - - :pipeline:`$merge` stage writes the output of the preceding - :pipeline:`$group` stage to the ``budgets`` collection in the - ``reporting`` database. +To view the documents in the new ``budgets`` collection: - To view the documents in the new ``budgets`` collection: +.. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("reporting").budgets.find().sort( { _id: 1 } ) - db.getSiblingDB("reporting").budgets.find().sort( { _id: 1 } ) +The ``budgets`` collection contains the following documents: - The ``budgets`` collection contains the following documents: +.. code-block:: javascript - .. code-block:: javascript + { "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 } + { "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 } + { "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 } + { "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 } + { "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 125000 } + { "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 310000 } - { "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 } - { "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 } - { "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 } - { "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 } - { "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 125000 } - { "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 310000 } +.. seealso:: - .. seealso:: :doc:`/core/materialized-views` + :doc:`/core/materialized-views` .. _merge-mat-view-refresh: On-Demand Materialized View: Update/Replace Data ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +The following example uses the collections in the previous example. - The following example uses the collections in the previous example. +The example ``salaries`` collection contains the +employee salary and department history: - The example ``salaries`` collection contains the - employee salary and department history: +.. code-block:: javascript - .. code-block:: javascript + { "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 }, + { "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 }, + { "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 }, + { "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 }, + { "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 }, + { "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 }, + { "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 }, + { "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 }, + { "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 }, + { "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 } - { "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 }, - { "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 }, - { "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 }, - { "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 }, - { "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 }, - { "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 }, - { "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 }, - { "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 }, - { "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 }, - { "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 } +The example ``budgets`` collection contains the cumulative yearly +budgets: - The example ``budgets`` collection contains the cumulative yearly - budgets: +.. code-block:: javascript - .. code-block:: javascript + { "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 } + { "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 } + { "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 } + { "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 } + { "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 125000 } + { "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 310000 } - { "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 } - { "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 } - { "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 } - { "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 } - { "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 125000 } - { "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 310000 } +During the current fiscal year (``2019`` in this example), new employees +are added to the ``salaries`` collection and new head counts are +pre-allocated for the next year: - During the current fiscal year (``2019`` in this example), new employees - are added to the ``salaries`` collection and new head counts are - pre-allocated for the next year: +.. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("zoo").salaries.insertMany([ + { "_id" : 11, employee: "Wren", dept: "Z", salary: 100000, fiscal_year: 2019 }, + { "_id" : 12, employee: "Zebra", dept: "A", salary: 150000, fiscal_year: 2019 }, + { "_id" : 13, employee: "headcount1", dept: "Z", salary: 120000, fiscal_year: 2020 }, + { "_id" : 14, employee: "headcount2", dept: "Z", salary: 120000, fiscal_year: 2020 } + ]) - db.getSiblingDB("zoo").salaries.insertMany([ - { "_id" : 11, employee: "Wren", dept: "Z", salary: 100000, fiscal_year: 2019 }, - { "_id" : 12, employee: "Zebra", dept: "A", salary: 150000, fiscal_year: 2019 }, - { "_id" : 13, employee: "headcount1", dept: "Z", salary: 120000, fiscal_year: 2020 }, - { "_id" : 14, employee: "headcount2", dept: "Z", salary: 120000, fiscal_year: 2020 } - ]) +To update the ``budgets`` collection to reflect the new +salary information, the following aggregation pipeline uses: - To update the ``budgets`` collection to reflect the new - salary information, the following aggregation pipeline uses: +- :pipeline:`$match` stage to find all documents with ``fiscal_year`` + greater than or equal to ``2019``. - - :pipeline:`$match` stage to find all documents with ``fiscal_year`` - greater than or equal to ``2019``. +- :pipeline:`$group` stage to group the salaries by the ``fiscal_year`` + and ``dept``. - - :pipeline:`$group` stage to group the salaries by the ``fiscal_year`` - and ``dept``. +- :pipeline:`$merge` to write the result set to the ``budgets`` + collection, :ref:`replacing documents + ` with the same ``_id`` value (in + this example, a document with the fiscal year and dept). For + documents that do not have matches in the collection, + :pipeline:`$merge` inserts the new documents. - - :pipeline:`$merge` to write the result set to the ``budgets`` - collection, :ref:`replacing documents - ` with the same ``_id`` value (in - this example, a document with the fiscal year and dept). For - documents that do not have matches in the collection, - :pipeline:`$merge` inserts the new documents. +.. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("zoo").salaries.aggregate( [ + { $match : { fiscal_year: { $gte : 2019 } } }, + { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, salaries: { $sum: "$salary" } } }, + { $merge : { into: { db: "reporting", coll: "budgets" }, on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } + ] ) - db.getSiblingDB("zoo").salaries.aggregate( [ - { $match : { fiscal_year: { $gte : 2019 } } }, - { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, salaries: { $sum: "$salary" } } }, - { $merge : { into: { db: "reporting", coll: "budgets" }, on: "_id", whenMatched: "replace", whenNotMatched: "insert" } } - ] ) +After the aggregation is run, view the documents in the ``budgets`` +collection: - After the aggregation is run, view the documents in the ``budgets`` - collection: +.. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB("reporting").budgets.find().sort( { _id: 1 } ) - db.getSiblingDB("reporting").budgets.find().sort( { _id: 1 } ) +The ``budgets`` collection incorporates the new salary data for fiscal +year 2019 and adds new documents for fiscal year 2020: - The ``budgets`` collection incorporates the new salary data for fiscal - year 2019 and adds new documents for fiscal year 2020: +.. code-block:: javascript + :emphasize-lines: 5-7 - .. code-block:: javascript - :emphasize-lines: 5-7 + { "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 } + { "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 } + { "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 } + { "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 } + { "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 275000 } + { "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 410000 } + { "_id" : { "fiscal_year" : 2020, "dept" : "Z" }, "salaries" : 240000 } - { "_id" : { "fiscal_year" : 2017, "dept" : "A" }, "salaries" : 220000 } - { "_id" : { "fiscal_year" : 2017, "dept" : "Z" }, "salaries" : 115000 } - { "_id" : { "fiscal_year" : 2018, "dept" : "A" }, "salaries" : 215000 } - { "_id" : { "fiscal_year" : 2018, "dept" : "Z" }, "salaries" : 280000 } - { "_id" : { "fiscal_year" : 2019, "dept" : "A" }, "salaries" : 275000 } - { "_id" : { "fiscal_year" : 2019, "dept" : "Z" }, "salaries" : 410000 } - { "_id" : { "fiscal_year" : 2020, "dept" : "Z" }, "salaries" : 240000 } +.. seealso:: - .. seealso:: :doc:`/core/materialized-views` + + + :doc:`/core/materialized-views` .. _merge-mat-view-insert-only: Only Insert New Data ~~~~~~~~~~~~~~~~~~~~ -.. container:: - - To ensure that the :pipeline:`$merge` does not overwrite existing data - in the collection, set :ref:`whenMatched ` to - :ref:`keepExisting ` or :ref:`fail - `. +To ensure that the :pipeline:`$merge` does not overwrite existing data +in the collection, set :ref:`whenMatched ` to +:ref:`keepExisting ` or :ref:`fail +`. - The example ``salaries`` collection in the ``zoo`` database contains - the employee salary and department history: +The example ``salaries`` collection in the ``zoo`` database contains +the employee salary and department history: - .. code-block:: javascript - - { "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 }, - { "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 }, - { "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 }, - { "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 }, - { "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 }, - { "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 }, - { "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 }, - { "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 }, - { "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 }, - { "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 } +.. code-block:: javascript - A collection ``orgArchive`` in the ``reporting`` database - contains historical departmental organization records for the past - fiscal years. Archived records should not be modified. + { "_id" : 1, employee: "Ant", dept: "A", salary: 100000, fiscal_year: 2017 }, + { "_id" : 2, employee: "Bee", dept: "A", salary: 120000, fiscal_year: 2017 }, + { "_id" : 3, employee: "Cat", dept: "Z", salary: 115000, fiscal_year: 2017 }, + { "_id" : 4, employee: "Ant", dept: "A", salary: 115000, fiscal_year: 2018 }, + { "_id" : 5, employee: "Bee", dept: "Z", salary: 145000, fiscal_year: 2018 }, + { "_id" : 6, employee: "Cat", dept: "Z", salary: 135000, fiscal_year: 2018 }, + { "_id" : 7, employee: "Gecko", dept: "A", salary: 100000, fiscal_year: 2018 }, + { "_id" : 8, employee: "Ant", dept: "A", salary: 125000, fiscal_year: 2019 }, + { "_id" : 9, employee: "Bee", dept: "Z", salary: 160000, fiscal_year: 2019 }, + { "_id" : 10, employee: "Cat", dept: "Z", salary: 150000, fiscal_year: 2019 } + +A collection ``orgArchive`` in the ``reporting`` database +contains historical departmental organization records for the past +fiscal years. Archived records should not be modified. - .. code-block:: javascript +.. code-block:: javascript - { "_id" : ObjectId("5cd8c68261baa09e9f3622be"), "employees" : [ "Ant", "Gecko" ], "dept" : "A", "fiscal_year" : 2018 } - { "_id" : ObjectId("5cd8c68261baa09e9f3622bf"), "employees" : [ "Ant", "Bee" ], "dept" : "A", "fiscal_year" : 2017 } - { "_id" : ObjectId("5cd8c68261baa09e9f3622c0"), "employees" : [ "Bee", "Cat" ], "dept" : "Z", "fiscal_year" : 2018 } - { "_id" : ObjectId("5cd8c68261baa09e9f3622c1"), "employees" : [ "Cat" ], "dept" : "Z", "fiscal_year" : 2017 } + { "_id" : ObjectId("5cd8c68261baa09e9f3622be"), "employees" : [ "Ant", "Gecko" ], "dept" : "A", "fiscal_year" : 2018 } + { "_id" : ObjectId("5cd8c68261baa09e9f3622bf"), "employees" : [ "Ant", "Bee" ], "dept" : "A", "fiscal_year" : 2017 } + { "_id" : ObjectId("5cd8c68261baa09e9f3622c0"), "employees" : [ "Bee", "Cat" ], "dept" : "Z", "fiscal_year" : 2018 } + { "_id" : ObjectId("5cd8c68261baa09e9f3622c1"), "employees" : [ "Cat" ], "dept" : "Z", "fiscal_year" : 2017 } - The ``orgArchive`` collection has a unique compound index on the - ``fiscal_year`` and ``dept`` fields. Specifically, there should be at - most one record for the same fiscal year and department combination: +The ``orgArchive`` collection has a unique compound index on the +``fiscal_year`` and ``dept`` fields. Specifically, there should be at +most one record for the same fiscal year and department combination: - .. code-block:: javascript +.. code-block:: javascript - db.getSiblingDB("reporting").orgArchive.createIndex ( { fiscal_year: 1, dept: 1 }, { unique: true } ) + db.getSiblingDB("reporting").orgArchive.createIndex ( { fiscal_year: 1, dept: 1 }, { unique: true } ) - At the end of current fiscal year (``2019`` in this example), the - ``salaries`` collection contain the following documents: +At the end of current fiscal year (``2019`` in this example), the +``salaries`` collection contain the following documents: - .. code-block:: javascript +.. code-block:: javascript - { "_id" : 1, "employee" : "Ant", "dept" : "A", "salary" : 100000, "fiscal_year" : 2017 } - { "_id" : 2, "employee" : "Bee", "dept" : "A", "salary" : 120000, "fiscal_year" : 2017 } - { "_id" : 3, "employee" : "Cat", "dept" : "Z", "salary" : 115000, "fiscal_year" : 2017 } - { "_id" : 4, "employee" : "Ant", "dept" : "A", "salary" : 115000, "fiscal_year" : 2018 } - { "_id" : 5, "employee" : "Bee", "dept" : "Z", "salary" : 145000, "fiscal_year" : 2018 } - { "_id" : 6, "employee" : "Cat", "dept" : "Z", "salary" : 135000, "fiscal_year" : 2018 } - { "_id" : 7, "employee" : "Gecko", "dept" : "A", "salary" : 100000, "fiscal_year" : 2018 } - { "_id" : 8, "employee" : "Ant", "dept" : "A", "salary" : 125000, "fiscal_year" : 2019 } - { "_id" : 9, "employee" : "Bee", "dept" : "Z", "salary" : 160000, "fiscal_year" : 2019 } - { "_id" : 10, "employee" : "Cat", "dept" : "Z", "salary" : 150000, "fiscal_year" : 2019 } - { "_id" : 11, "employee" : "Wren", "dept" : "Z", "salary" : 100000, "fiscal_year" : 2019 } - { "_id" : 12, "employee" : "Zebra", "dept" : "A", "salary" : 150000, "fiscal_year" : 2019 } - { "_id" : 13, "employee" : "headcount1", "dept" : "Z", "salary" : 120000, "fiscal_year" : 2020 } - { "_id" : 14, "employee" : "headcount2", "dept" : "Z", "salary" : 120000, "fiscal_year" : 2020 } - - To update the ``orgArchive`` collection to include the fiscal - year ``2019`` that has just ended, the following aggregation pipeline - uses: - - - :pipeline:`$match` stage to find all documents with ``fiscal_year`` - equal to ``2019``. - - - :pipeline:`$group` stage to group the employees by the ``fiscal_year`` - and ``dept``. - - - :pipeline:`$project` stage to suppress the ``_id`` field and add - separate ``dept`` and ``fiscal_year`` field. When the documents - are passed to :pipeline:`$merge`, :pipeline:`$merge` automatically - generates a new ``_id`` field for the documents. - - - :pipeline:`$merge` to write the result set to ``orgArchive``. - - The :pipeline:`$merge` stage matches documents :ref:`on - ` the ``dept`` and ``fiscal_year`` fields and ``fails`` - when matched. That is, if a document already exists for the same - department and fiscal year, the :pipeline:`$merge` errors. + { "_id" : 1, "employee" : "Ant", "dept" : "A", "salary" : 100000, "fiscal_year" : 2017 } + { "_id" : 2, "employee" : "Bee", "dept" : "A", "salary" : 120000, "fiscal_year" : 2017 } + { "_id" : 3, "employee" : "Cat", "dept" : "Z", "salary" : 115000, "fiscal_year" : 2017 } + { "_id" : 4, "employee" : "Ant", "dept" : "A", "salary" : 115000, "fiscal_year" : 2018 } + { "_id" : 5, "employee" : "Bee", "dept" : "Z", "salary" : 145000, "fiscal_year" : 2018 } + { "_id" : 6, "employee" : "Cat", "dept" : "Z", "salary" : 135000, "fiscal_year" : 2018 } + { "_id" : 7, "employee" : "Gecko", "dept" : "A", "salary" : 100000, "fiscal_year" : 2018 } + { "_id" : 8, "employee" : "Ant", "dept" : "A", "salary" : 125000, "fiscal_year" : 2019 } + { "_id" : 9, "employee" : "Bee", "dept" : "Z", "salary" : 160000, "fiscal_year" : 2019 } + { "_id" : 10, "employee" : "Cat", "dept" : "Z", "salary" : 150000, "fiscal_year" : 2019 } + { "_id" : 11, "employee" : "Wren", "dept" : "Z", "salary" : 100000, "fiscal_year" : 2019 } + { "_id" : 12, "employee" : "Zebra", "dept" : "A", "salary" : 150000, "fiscal_year" : 2019 } + { "_id" : 13, "employee" : "headcount1", "dept" : "Z", "salary" : 120000, "fiscal_year" : 2020 } + { "_id" : 14, "employee" : "headcount2", "dept" : "Z", "salary" : 120000, "fiscal_year" : 2020 } + +To update the ``orgArchive`` collection to include the fiscal +year ``2019`` that has just ended, the following aggregation pipeline +uses: + +- :pipeline:`$match` stage to find all documents with ``fiscal_year`` + equal to ``2019``. + +- :pipeline:`$group` stage to group the employees by the ``fiscal_year`` + and ``dept``. + +- :pipeline:`$project` stage to suppress the ``_id`` field and add + separate ``dept`` and ``fiscal_year`` field. When the documents + are passed to :pipeline:`$merge`, :pipeline:`$merge` automatically + generates a new ``_id`` field for the documents. + +- :pipeline:`$merge` to write the result set to ``orgArchive``. + + The :pipeline:`$merge` stage matches documents :ref:`on + ` the ``dept`` and ``fiscal_year`` fields and ``fails`` + when matched. That is, if a document already exists for the same + department and fiscal year, the :pipeline:`$merge` errors. - .. code-block:: javascript +.. code-block:: javascript - db.getSiblingDB("zoo").salaries.aggregate( [ - { $match: { fiscal_year: 2019 }}, - { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, employees: { $push: "$employee" } } }, - { $project: { _id: 0, dept: "$_id.dept", fiscal_year: "$_id.fiscal_year", employees: 1 } }, - { $merge : { into : { db: "reporting", coll: "orgArchive" }, on: [ "dept", "fiscal_year" ], whenMatched: "fail" } } - ] ) + db.getSiblingDB("zoo").salaries.aggregate( [ + { $match: { fiscal_year: 2019 }}, + { $group: { _id: { fiscal_year: "$fiscal_year", dept: "$dept" }, employees: { $push: "$employee" } } }, + { $project: { _id: 0, dept: "$_id.dept", fiscal_year: "$_id.fiscal_year", employees: 1 } }, + { $merge : { into : { db: "reporting", coll: "orgArchive" }, on: [ "dept", "fiscal_year" ], whenMatched: "fail" } } + ] ) - After the operation, the ``orgArchive`` collection contains the following - documents: +After the operation, the ``orgArchive`` collection contains the following +documents: - .. code-block:: javascript - :emphasize-lines: 3,6 - - { "_id" : ObjectId("5caccc6a66b22dd8a8cc419f"), "employees" : [ "Ahn", "Bess" ], "dept" : "A", "fiscal_year" : 2017 } - { "_id" : ObjectId("5caccc6a66b22dd8a8cc419e"), "employees" : [ "Ahn", "Gee" ], "dept" : "A", "fiscal_year" : 2018 } - { "_id" : ObjectId("5caccd0b66b22dd8a8cc438e"), "employees" : [ "Ahn", "Zeb" ], "dept" : "A", "fiscal_year" : 2019 } - { "_id" : ObjectId("5caccc6a66b22dd8a8cc41a0"), "employees" : [ "Carl" ], "dept" : "Z", "fiscal_year" : 2017 } - { "_id" : ObjectId("5caccc6a66b22dd8a8cc41a1"), "employees" : [ "Bess", "Carl" ], "dept" : "Z", "fiscal_year" : 2018 } - { "_id" : ObjectId("5caccd0b66b22dd8a8cc438d"), "employees" : [ "Bess", "Carl", "Wen" ], "dept" : "Z", "fiscal_year" : 2019 } - - If the ``orgArchive`` collection already contained a document for - 2019 for department ``"A"`` and/or ``"B"``, the aggregation - :ref:`fails because of the duplicate key error - `. However, any document inserted - before the error will not be rolled back. - - If you specify :ref:`keepExisting - ` for the matching document, the - aggregation does not affect the matching document and does not error - with duplicate key error. Similarly, if you specify - :ref:`replace `, the - operation would not fail; however, the operation would replace the - existing document. +.. code-block:: javascript + :emphasize-lines: 3,6 + + { "_id" : ObjectId("5caccc6a66b22dd8a8cc419f"), "employees" : [ "Ahn", "Bess" ], "dept" : "A", "fiscal_year" : 2017 } + { "_id" : ObjectId("5caccc6a66b22dd8a8cc419e"), "employees" : [ "Ahn", "Gee" ], "dept" : "A", "fiscal_year" : 2018 } + { "_id" : ObjectId("5caccd0b66b22dd8a8cc438e"), "employees" : [ "Ahn", "Zeb" ], "dept" : "A", "fiscal_year" : 2019 } + { "_id" : ObjectId("5caccc6a66b22dd8a8cc41a0"), "employees" : [ "Carl" ], "dept" : "Z", "fiscal_year" : 2017 } + { "_id" : ObjectId("5caccc6a66b22dd8a8cc41a1"), "employees" : [ "Bess", "Carl" ], "dept" : "Z", "fiscal_year" : 2018 } + { "_id" : ObjectId("5caccd0b66b22dd8a8cc438d"), "employees" : [ "Bess", "Carl", "Wen" ], "dept" : "Z", "fiscal_year" : 2019 } + +If the ``orgArchive`` collection already contained a document for +2019 for department ``"A"`` and/or ``"B"``, the aggregation +:ref:`fails because of the duplicate key error +`. However, any document inserted +before the error will not be rolled back. + +If you specify :ref:`keepExisting +` for the matching document, the +aggregation does not affect the matching document and does not error +with duplicate key error. Similarly, if you specify +:ref:`replace `, the +operation would not fail; however, the operation would replace the +existing document. .. _merge-mat-view-merge: Merge Results from Multiple Collections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +By default, if a document in the aggregation results matches a +document in the collection, the :pipeline:`$merge` stage +:ref:`merges ` the documents. - By default, if a document in the aggregation results matches a - document in the collection, the :pipeline:`$merge` stage - :ref:`merges ` the documents. +An example collection ``purchaseorders`` is populated with the +purchase order information by quarter and regions: - An example collection ``purchaseorders`` is populated with the - purchase order information by quarter and regions: +.. code-block:: javascript - .. code-block:: javascript + db.purchaseorders.insertMany( [ + { _id: 1, quarter: "2019Q1", region: "A", qty: 200, reportDate: new Date("2019-04-01") }, + { _id: 2, quarter: "2019Q1", region: "B", qty: 300, reportDate: new Date("2019-04-01") }, + { _id: 3, quarter: "2019Q1", region: "C", qty: 700, reportDate: new Date("2019-04-01") }, + { _id: 4, quarter: "2019Q2", region: "B", qty: 300, reportDate: new Date("2019-07-01") }, + { _id: 5, quarter: "2019Q2", region: "C", qty: 1000, reportDate: new Date("2019-07-01") }, + { _id: 6, quarter: "2019Q2", region: "A", qty: 400, reportDate: new Date("2019-07-01") }, + ] ) - db.purchaseorders.insertMany( [ - { _id: 1, quarter: "2019Q1", region: "A", qty: 200, reportDate: new Date("2019-04-01") }, - { _id: 2, quarter: "2019Q1", region: "B", qty: 300, reportDate: new Date("2019-04-01") }, - { _id: 3, quarter: "2019Q1", region: "C", qty: 700, reportDate: new Date("2019-04-01") }, - { _id: 4, quarter: "2019Q2", region: "B", qty: 300, reportDate: new Date("2019-07-01") }, - { _id: 5, quarter: "2019Q2", region: "C", qty: 1000, reportDate: new Date("2019-07-01") }, - { _id: 6, quarter: "2019Q2", region: "A", qty: 400, reportDate: new Date("2019-07-01") }, - ] ) +Another example collection ``reportedsales`` is populated with the +reported sales information by quarter and regions: - Another example collection ``reportedsales`` is populated with the - reported sales information by quarter and regions: +.. code-block:: javascript + + db.reportedsales.insertMany( [ + { _id: 1, quarter: "2019Q1", region: "A", qty: 400, reportDate: new Date("2019-04-02") }, + { _id: 2, quarter: "2019Q1", region: "B", qty: 550, reportDate: new Date("2019-04-02") }, + { _id: 3, quarter: "2019Q1", region: "C", qty: 1000, reportDate: new Date("2019-04-05") }, + { _id: 4, quarter: "2019Q2", region: "B", qty: 500, reportDate: new Date("2019-07-02") }, + ] ) - .. code-block:: javascript - db.reportedsales.insertMany( [ - { _id: 1, quarter: "2019Q1", region: "A", qty: 400, reportDate: new Date("2019-04-02") }, - { _id: 2, quarter: "2019Q1", region: "B", qty: 550, reportDate: new Date("2019-04-02") }, - { _id: 3, quarter: "2019Q1", region: "C", qty: 1000, reportDate: new Date("2019-04-05") }, - { _id: 4, quarter: "2019Q2", region: "B", qty: 500, reportDate: new Date("2019-07-02") }, - ] ) +Assume that, for reporting purposes, you want to view the data by +quarter in the following format: +.. code-block:: javascript - Assume that, for reporting purposes, you want to view the data by - quarter in the following format: + { "_id" : "2019Q1", "sales" : 1950, "purchased" : 1200 } + { "_id" : "2019Q2", "sales" : 500, "purchased" : 1700 } - .. code-block:: javascript +You can use the :pipeline:`$merge` to merge in results from the +``purchaseorders`` collection and the ``reportedsales`` collection +to create a new collection ``quarterlyreport``. + +To create the ``quarterlyreport`` collection, you can use the +following pipeline: - { "_id" : "2019Q1", "sales" : 1950, "purchased" : 1200 } - { "_id" : "2019Q2", "sales" : 500, "purchased" : 1700 } +.. code-block:: javascript + + db.purchaseorders.aggregate( [ + { $group: { _id: "$quarter", purchased: { $sum: "$qty" } } }, // group purchase orders by quarter + { $merge : { into: "quarterlyreport", on: "_id", whenMatched: "merge", whenNotMatched: "insert" } } + ]) - You can use the :pipeline:`$merge` to merge in results from the - ``purchaseorders`` collection and the ``reportedsales`` collection - to create a new collection ``quarterlyreport``. +First stage: + The :pipeline:`$group` stage groups by the quarter and uses + :group:`$sum` to add the ``qty`` fields into a new + ``purchased`` field. For example: To create the ``quarterlyreport`` collection, you can use this pipeline: - + .. code-block:: javascript + :copyable: false - db.purchaseorders.aggregate( [ - { $group: { _id: "$quarter", purchased: { $sum: "$qty" } } }, // group purchase orders by quarter - { $merge : { into: "quarterlyreport", on: "_id", whenMatched: "merge", whenNotMatched: "insert" } } - ]) - - First stage: - The :pipeline:`$group` stage groups by the quarter and uses - :expression:`$sum` to add the ``qty`` fields into a new - ``purchased`` field. For example: + { "_id" : "2019Q2", "purchased" : 1700 } + { "_id" : "2019Q1", "purchased" : 1200 } - .. code-block:: javascript - :copyable: false +Second stage: + The :pipeline:`$merge` stage writes the documents to the + ``quarterlyreport`` collection in the same database. If the stage + finds an existing document in the collection that :ref:`matches + on ` the ``_id`` field, the stage merges the matching + documents. Otherwise, the stage inserts the document. For the + initial creation, no documents should match. + +To view the documents in the collection, run the following operation: - { "_id" : "2019Q2", "purchased" : 1700 } - { "_id" : "2019Q1", "purchased" : 1200 } +.. code-block:: javascript - Second stage: - The :pipeline:`merge` stage writes the documents to the - ``quarterlyreport`` collection in the same database. If the stage - finds an existing document in the collection that :ref:`matches - on ` the ``_id`` field, the stage merges the matching - documents. Otherwise, the stage inserts the document. For the - initial creation, no documents should match. + db.quarterlyreport.find().sort( { _id: 1 } ) - To view the documents in the collection: +The collection contains the following documents: - .. code-block:: javascript +.. code-block:: javascript + :copyable: false + + { "_id" : "2019Q1", "sales" : 1200, "purchased" : 1200 } + { "_id" : "2019Q2", "sales" : 1700, "purchased" : 1700 } + +Similarly, run the following aggregation pipeline against the +``reportedsales`` collection to merge the sales results into the +``quarterlyreport`` collection. + +.. code-block:: javascript - db.quarterlyreport.find().sort( { _id: 1 } ) + db.reportedsales.aggregate( [ + { $group: { _id: "$quarter", sales: { $sum: "$qty" } } }, // group sales by quarter + { $merge : { into: "quarterlyreport", on: "_id", whenMatched: "merge", whenNotMatched: "insert" } } + ]) - The collection contains the following documents: +First stage: + The :pipeline:`$group` stage groups by the quarter and uses + :group:`$sum` to add the ``qty`` fields into a new + ``sales`` field. For example: .. code-block:: javascript :copyable: false - { "_id" : "2019Q1", "sales" : 1200, "purchased" : 1200 } - { "_id" : "2019Q2", "sales" : 1700, "purchased" : 1700 } + { "_id" : "2019Q2", "sales" : 500 } + { "_id" : "2019Q1", "sales" : 1950 } - Similarly, run the following aggregation pipeline against the - ``reportedsales`` collection to merge the sales results into the - ``quarterlyreport`` collection. +Second stage: + The :pipeline:`$merge` stage writes the documents to the + ``quarterlyreport`` collection in the same database. If the stage + finds an existing document in the collection that :ref:`matches + on ` the ``_id`` field (the quarter), the stage merges + the matching documents. Otherwise, the stage inserts the document. - .. code-block:: javascript +To view the documents in the ``quarterlyreport`` collection after +the data has been merged, run the following operation: - db.reportedsales.aggregate( [ - { $group: { _id: "$quarter", sales: { $sum: "$qty" } } }, // group sales by quarter - { $merge : { into: "quarterlyreport", on: "_id", whenMatched: "merge", whenNotMatched: "insert" } } - ]) - - First stage: - The :pipeline:`$group` stage groups by the quarter and uses - :expression:`$sum` to add the ``qty`` fields into a new - ``sales`` field. For example: +.. code-block:: javascript - .. code-block:: javascript - :copyable: false + db.quarterlyreport.find().sort( { _id: 1 } ) - { "_id" : "2019Q2", "sales" : 500 } - { "_id" : "2019Q1", "sales" : 1950 } +The collection contains the following documents: - Second stage: - The :pipeline:`merge` stage writes the documents to the - ``quarterlyreport`` collection in the same database. If the stage - finds an existing document in the collection that :ref:`matches - on ` the ``_id`` field (the quarter), the stage merges - the matching documents. Otherwise, the stage inserts the document. +.. code-block:: javascript + :copyable: false - To view the documents in the ``quarterlyreport`` collection after - the data has been merged: + { "_id" : "2019Q1", "sales" : 1950, "purchased" : 1200 } + { "_id" : "2019Q2", "sales" : 500, "purchased" : 1700 } - .. code-block:: javascript +Use the Pipeline to Customize the Merge +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - db.quarterlyreport.find().sort( { _id: 1 } ) +The :pipeline:`$merge` can use a :ref:`custom update pipeline +` when documents match. The +:ref:`whenMatched pipeline ` can have +the following stages: - The collection contains the following documents: +- :pipeline:`$addFields` and its alias :pipeline:`$set` +- :pipeline:`$project` and its alias :pipeline:`$unset` +- :pipeline:`$replaceRoot` and its alias :pipeline:`$replaceWith` - .. code-block:: javascript - :copyable: false +An example collection ``votes`` is populated with the daily vote +tally. Create the collection with the following documents:s + +.. code-block:: javascript - { "_id" : "2019Q1", "sales" : 1950, "purchased" : 1200 } - { "_id" : "2019Q2", "sales" : 500, "purchased" : 1700 } + db.votes.insertMany([ + { date: new Date("2019-05-01"), "thumbsup" : 1, "thumbsdown" : 1 }, + { date: new Date("2019-05-02"), "thumbsup" : 3, "thumbsdown" : 1 }, + { date: new Date("2019-05-03"), "thumbsup" : 1, "thumbsdown" : 1 }, + { date: new Date("2019-05-04"), "thumbsup" : 2, "thumbsdown" : 2 }, + { date: new Date("2019-05-05"), "thumbsup" : 6, "thumbsdown" : 10 }, + { date: new Date("2019-05-06"), "thumbsup" : 13, "thumbsdown" : 16 } + ]) -Use a Pipeline to Customize the Merge -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Another example collection ``monthlytotals`` has the up-to-date +monthly vote totals. Create the collection with the following +document: -.. container:: +.. code-block:: javascript - The :pipeline:`$merge` can use a :ref:`custom update pipeline - ` when documents match. The - :ref:`whenMatched pipeline ` can have - these stages: + db.monthlytotals.insertOne({ "_id" : "2019-05", "thumbsup" : 26, "thumbsdown" : 31 } ) - - :pipeline:`$addFields` and its alias :pipeline:`$set` - - :pipeline:`$project` and its alias :pipeline:`$unset` - - :pipeline:`$replaceRoot` and its alias :pipeline:`$replaceWith` - - An example collection ``votes`` is populated with the daily vote - tally. Create the collection with these documents: +At the end of each day, that day's votes is inserted into the +``votes`` collection: - .. code-block:: javascript +.. code-block:: javascript - db.votes.insertMany([ - { date: new Date("2019-05-01"), "thumbsup" : 1, "thumbsdown" : 1 }, - { date: new Date("2019-05-02"), "thumbsup" : 3, "thumbsdown" : 1 }, - { date: new Date("2019-05-03"), "thumbsup" : 1, "thumbsdown" : 1 }, - { date: new Date("2019-05-04"), "thumbsup" : 2, "thumbsdown" : 2 }, - { date: new Date("2019-05-05"), "thumbsup" : 6, "thumbsdown" : 10 }, - { date: new Date("2019-05-06"), "thumbsup" : 13, "thumbsdown" : 16 } - ]) + db.votes.insertOne( + { date: new Date("2019-05-07"), "thumbsup" : 14, "thumbsdown" : 10 } + ) - Another example collection ``monthlytotals`` has the up-to-date - monthly vote totals. Create the collection with this document: +You can use :pipeline:`$merge` with an custom pipeline to update the +existing document in the collection ``monthlytotals``: - .. code-block:: javascript +.. code-block:: javascript - db.monthlytotals.insertOne({ "_id" : "2019-05", "thumbsup" : 26, "thumbsdown" : 31 } ) + db.votes.aggregate([ + { $match: { date: { $gte: new Date("2019-05-07"), $lt: new Date("2019-05-08") } } }, + { $project: { _id: { $dateToString: { format: "%Y-%m", date: "$date" } }, thumbsup: 1, thumbsdown: 1 } }, + { $merge: { + into: "monthlytotals", + on: "_id", + whenMatched: [ + { $addFields: { + thumbsup: { $add:[ "$thumbsup", "$$new.thumbsup" ] }, + thumbsdown: { $add: [ "$thumbsdown", "$$new.thumbsdown" ] } + } } ], + whenNotMatched: "insert" + } } + ]) + +First stage: + The :pipeline:`$match` stage finds the specific day's votes. For + example: - At the end of each day, that day's votes is inserted into the - ``votes`` collection: - .. code-block:: javascript + :copyable: false - db.votes.insertOne( - { date: new Date("2019-05-07"), "thumbsup" : 14, "thumbsdown" : 10 } - ) - - You can use :pipeline:`$merge` with an custom pipeline to update the - existing document in the collection ``monthlytotals``: + { "_id" : ObjectId("5ce6097c436eb7e1203064a6"), "date" : ISODate("2019-05-07T00:00:00Z"), "thumbsup" : 14, "thumbsdown" : 10 } + +Second stage: + The :pipeline:`$project` stage sets the ``_id`` field to a + year-month string. For example: .. code-block:: javascript + :copyable: false + + { "thumbsup" : 14, "thumbsdown" : 10, "_id" : "2019-05" } - db.votes.aggregate([ - { $match: { date: { $gte: new Date("2019-05-07"), $lt: new Date("2019-05-08") } } }, - { $project: { _id: { $dateToString: { format: "%Y-%m", date: "$date" } }, thumbsup: 1, thumbsdown: 1 } }, - { $merge: { - into: "monthlytotals", - on: "_id", - whenMatched: [ - { $addFields: { - thumbsup: { $add:[ "$thumbsup", "$$new.thumbsup" ] }, - thumbsdown: { $add: [ "$thumbsdown", "$$new.thumbsdown" ] } - } } ], - whenNotMatched: "insert" - } } - ]) - - First stage: - The :pipeline:`$match` stage finds the specific day's votes. For - example: +Third stage: + The :pipeline:`$merge` stage writes the documents to the + ``monthlytotals`` collection in the same database. If the stage + finds an existing document in the collection that :ref:`matches + on ` the ``_id`` field, the stage uses a pipeline to + add the ``thumbsup`` votes and the ``thumbsdown`` votes. - .. code-block:: javascript - :copyable: false + - This pipeline cannot directly accesses the fields from the + results document. To access the ``thumbsup`` field and the + ``thumbsdown`` field in the results document, the pipeline uses + the ``$$new`` variable; i.e. ``$$new.thumbsup`` and + ``$new.thumbsdown``. - { "_id" : ObjectId("5ce6097c436eb7e1203064a6"), "date" : ISODate("2019-05-07T00:00:00Z"), "thumbsup" : 14, "thumbsdown" : 10 } + - This pipeline can directly accesses the ``thumbsup`` field + and the ``thumbsdown`` field in the existing document in the + collection; i.e. ``$thumbsup`` and ``$thumbsdown``. - Second stage: - The :pipeline:`$project` stage sets the ``_id`` field to a - year-month string. For example: + The resulting document replaces the existing document. - .. code-block:: javascript - :copyable: false +To view documents in the ``monthlytotals`` collection after the merge +operation, run the following operation: - { "thumbsup" : 14, "thumbsdown" : 10, "_id" : "2019-05" } - - Third stage: - The :pipeline:`merge` stage writes the documents to the - ``monthlytotals`` collection in the same database. If the stage - finds an existing document in the collection that :ref:`matches - on ` the ``_id`` field, the stage uses a pipeline to - add the ``thumbsup`` votes and the ``thumbsdown`` votes. - - - This pipeline cannot directly accesses the fields from the - results document. To access the ``thumbsup`` field and the - ``thumbsdown`` field in the results document, the pipeline uses - the ``$$new`` variable. Specifically, ``$$new.thumbsup`` and - ``$new.thumbsdown``. - - - This pipeline can directly accesses the ``thumbsup`` field - and the ``thumbsdown`` field in the existing document in the - collection. Specifically, ``$thumbsup`` and ``$thumbsdown``. - - The resulting document replaces the existing document. - - To view documents in the ``monthlytotals`` collection after the merge - operation: - - .. code-block:: javascript - - db.monthlytotals.find() - - The collection contains the following document: +.. code-block:: javascript - .. code-block:: javascript - :copyable: false + db.monthlytotals.find() + +The collection contains the following document: + +.. code-block:: javascript + :copyable: false - { "_id" : "2019-05", "thumbsup" : 40, "thumbsdown" : 41 } + { "_id" : "2019-05", "thumbsup" : 40, "thumbsdown" : 41 } .. _merge-variables-example: Use Variables to Customize the Merge ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +You can use variables in the :pipeline:`$merge` stage +:ref:`whenMatched ` field. Variables must +be defined before they can be used. - You can use variables in the :pipeline:`$merge` stage - :ref:`whenMatched ` field. Variables must - be defined before they can be used. +Define variables in one or both of the following: - Define variables in one or both of the following: - - - :pipeline:`$merge` stage :ref:`let ` +- :pipeline:`$merge` stage :ref:`let ` - - :dbcommand:`aggregate` command - :ref:`let ` (starting in MongoDB 5.0) +- :dbcommand:`aggregate` command + :ref:`let ` (starting in MongoDB 5.0) - To use variables in :ref:`whenMatched `: - - .. include:: /includes/merge-stage-variables.rst +To use variables in :ref:`whenMatched `: - .. container:: +.. include:: /includes/merge-stage-variables.rst - .. tabs:: +.. tabs:: - .. tab:: Use Variables Defined in the Merge Stage - :tabid: merge-variables-in-merge-stage + .. tab:: Use Variables Defined in the Merge Stage + :tabid: merge-variables-in-merge-stage - You can define variables in the :pipeline:`$merge` stage - :ref:`let ` and use the variables in the - :ref:`whenMatched ` field. + You can define variables in the :pipeline:`$merge` stage + :ref:`let ` and use the variables in the + :ref:`whenMatched ` field. - Example: + Example: - .. code-block:: javascript - - db.cakeSales.insert( [ - { _id: 1, flavor: "chocolate", salesTotal: 1580, - salesTrend: "up" } - ] ) - - db.runCommand( { - aggregate: db.cakeSales.getName(), - pipeline: [ { - $merge: { - into: db.cakeSales.getName(), - let : { year: "2020" }, - whenMatched: [ { - $addFields: { "salesYear": "$$year" } - } ] - } - } ], - cursor: {} - } ) - - db.cakeSales.find() - - The example: - - - creates a collection named ``cakeSales`` - - - runs an :dbcommand:`aggregate` command that defines a - ``year`` variable in the :pipeline:`$merge` :ref:`let - ` and adds the year to ``cakeSales`` using - :ref:`whenMatched ` - - - retrieves the ``cakeSales`` document + .. code-block:: javascript - Output: + db.cakeSales.insert( [ + { _id: 1, flavor: "chocolate", salesTotal: 1580, + salesTrend: "up" } + ] ) - .. code-block:: javascript - :copyable: false + db.runCommand( { + aggregate: db.cakeSales.getName(), + pipeline: [ { + $merge: { + into: db.cakeSales.getName(), + let : { year: "2020" }, + whenMatched: [ { + $addFields: { "salesYear": "$$year" } + } ] + } + } ], + cursor: {} + } ) - { "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580, - "salesTrend" : "up", "salesYear" : "2020" } + db.cakeSales.find() - .. tab:: Use Variables Defined in the Aggregate Command - :tabid: merge-variables-in-aggregate-command + The example: - .. versionadded:: 5.0 + - creates a collection named ``cakeSales`` - You can define variables in the :dbcommand:`aggregate` - command :ref:`let ` and use the - variables in the :pipeline:`$merge` stage :ref:`whenMatched - ` field. + - runs an :dbcommand:`aggregate` command that defines a + ``year`` variable in the :pipeline:`$merge` :ref:`let + ` and adds the year to ``cakeSales`` using + :ref:`whenMatched ` - Example: + - retrieves the ``cakeSales`` document - .. code-block:: javascript + Output: - db.cakeSales.insert( [ - { _id: 1, flavor: "chocolate", salesTotal: 1580, - salesTrend: "up" } - ] ) + .. code-block:: javascript + :copyable: false - db.runCommand( { - aggregate: db.cakeSales.getName(), - pipeline: [ { - $merge: { - into: db.cakeSales.getName(), - whenMatched: [ { - $addFields: { "salesYear": "$$year" } } - ] } - } - ], - cursor: {}, - let : { year: "2020" } - } ) + { "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580, + "salesTrend" : "up", "salesYear" : "2020" } - db.cakeSales.find() + .. tab:: Use Variables Defined in the Aggregate Command + :tabid: merge-variables-in-aggregate-command - The example: + .. versionadded:: 5.0 - - creates a collection named ``cakeSales`` + You can define variables in the :dbcommand:`aggregate` + command :ref:`let ` and use the + variables in the :pipeline:`$merge` stage :ref:`whenMatched + ` field. - - runs an :dbcommand:`aggregate` command that defines a - ``year`` variable in the :dbcommand:`aggregate` command - :ref:`let ` and adds the year to - ``cakeSales`` using :ref:`whenMatched - ` - - - retrieves the ``cakeSales`` document + Example: - Output: + .. code-block:: javascript - .. code-block:: javascript - :copyable: false + db.cakeSales.insert( [ + { _id: 1, flavor: "chocolate", salesTotal: 1580, + salesTrend: "up" } + ] ) - { "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580, - "salesTrend" : "up", "salesYear" : "2020" } + db.runCommand( { + aggregate: db.cakeSales.getName(), + pipeline: [ { + $merge: { + into: db.cakeSales.getName(), + whenMatched: [ { + $addFields: { "salesYear": "$$year" } } + ] } + } + ], + cursor: {}, + let : { year: "2020" } + } ) - .. tab:: Use Variables Defined in the Merge Stage and Aggregate - Command - :tabid: merge-variables-scope + db.cakeSales.find() - You can define variables in the :pipeline:`$merge` stage - and, starting in MongoDB 5.0, the :dbcommand:`aggregate` - command. - - If two variables with the same name are defined in the - :pipeline:`$merge` stage and the :dbcommand:`aggregate` - command, the :pipeline:`$merge` stage variable is used. - - In this example, the ``year: "2020"`` :pipeline:`$merge` - stage variable is used instead of the ``year: "2019"`` - :dbcommand:`aggregate` command variable: - - .. code-block:: javascript - - db.cakeSales.insert( [ - { _id: 1, flavor: "chocolate", salesTotal: 1580, - salesTrend: "up" } - ] ) - - db.runCommand( { - aggregate: db.cakeSales.getName(), - pipeline: [ { - $merge: { - into: db.cakeSales.getName(), - let : { year: "2020" }, - whenMatched: [ { - $addFields: { "salesYear": "$$year" } - } ] - } - } ], - cursor: {}, - let : { year: "2019" } - } ) - - db.cakeSales.find() - - Output: - - .. code-block:: javascript - :copyable: false - - { "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580, - "salesTrend" : "up", "salesYear" : "2020" } + The example: + + - creates a collection named ``cakeSales`` + + - runs an :dbcommand:`aggregate` command that defines a + ``year`` variable in the :dbcommand:`aggregate` command + :ref:`let ` and adds the year to + ``cakeSales`` using :ref:`whenMatched + ` + + - retrieves the ``cakeSales`` document + + Output: + + .. code-block:: javascript + :copyable: false + + { "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580, + "salesTrend" : "up", "salesYear" : "2020" } + + .. tab:: Use Variables Defined in the Merge Stage and Aggregate + Command + :tabid: merge-variables-scope + + You can define variables in the :pipeline:`$merge` stage + and, starting in MongoDB 5.0, the :dbcommand:`aggregate` + command. + + If two variables with the same name are defined in the + :pipeline:`$merge` stage and the :dbcommand:`aggregate` + command, the :pipeline:`$merge` stage variable is used. + + In this example, the ``year: "2020"`` :pipeline:`$merge` + stage variable is used instead of the ``year: "2019"`` + :dbcommand:`aggregate` command variable: + + .. code-block:: javascript + + db.cakeSales.insert( [ + { _id: 1, flavor: "chocolate", salesTotal: 1580, + salesTrend: "up" } + ] ) + + db.runCommand( { + aggregate: db.cakeSales.getName(), + pipeline: [ { + $merge: { + into: db.cakeSales.getName(), + let : { year: "2020" }, + whenMatched: [ { + $addFields: { "salesYear": "$$year" } + } ] + } + } ], + cursor: {}, + let : { year: "2019" } + } ) + + db.cakeSales.find() + + Output: + + .. code-block:: javascript + :copyable: false + + { "_id" : 1, "flavor" : "chocolate", "salesTotal" : 1580, + "salesTrend" : "up", "salesYear" : "2020" } diff --git a/source/reference/operator/aggregation/mergeObjects.txt b/source/reference/operator/aggregation/mergeObjects.txt index c1bbcf13538..8a496cffe05 100644 --- a/source/reference/operator/aggregation/mergeObjects.txt +++ b/source/reference/operator/aggregation/mergeObjects.txt @@ -39,11 +39,11 @@ Definition Behavior -------- -- :expression:`mergeObjects` ignores ``null`` operands. If all the - operands to :expression:`mergeObjects` resolves to null, - :expression:`mergeObjects` returns an empty document ``{ }``. +- :expression:`$mergeObjects` ignores ``null`` operands. If all the + operands to :expression:`$mergeObjects` resolves to null, + :expression:`$mergeObjects` returns an empty document ``{ }``. -- :expression:`mergeObjects` overwrites the field values as it merges +- :expression:`$mergeObjects` overwrites the field values as it merges the documents. If documents to merge include the same field name, the field, in the resulting document, has the value from the last document merged for the field. @@ -116,8 +116,6 @@ Examples Create a collection ``orders`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.insert([ @@ -127,8 +125,6 @@ Create a collection ``orders`` with the following documents: Create another collection ``items`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.items.insert([ @@ -142,8 +138,6 @@ join the two collections by the ``item`` fields and then uses :expression:`$mergeObjects` in the :pipeline:`$replaceRoot` to merge the joined documents from ``items`` and ``orders``: -.. cssclass:: copyable-code - .. code-block:: javascript db.orders.aggregate([ @@ -173,8 +167,6 @@ The operation returns the following documents: Create a collection ``sales`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.sales.insert( [ @@ -193,8 +185,6 @@ accumulator in a :pipeline:`$group` stage that groups documents by the When used as an accumulator, :expression:`$mergeObjects` operator accepts a single operand. -.. cssclass:: copyable-code - .. code-block:: javascript db.sales.aggregate( [ diff --git a/source/reference/operator/aggregation/meta.txt b/source/reference/operator/aggregation/meta.txt index 9186c853c43..35d6d247816 100644 --- a/source/reference/operator/aggregation/meta.txt +++ b/source/reference/operator/aggregation/meta.txt @@ -4,8 +4,7 @@ $meta .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -16,12 +15,6 @@ $meta Definition ---------- -.. COMMENT For now, hiding the .. projection:: $meta as part of DOCSP-9856 instead of removing since the docs would have a lot of :projection:`$meta` projection operator, etc. Can do a cleanup later, but don't want to subject DOCSP-9856 reviewers to all those changes. - -.. class:: hidden - - .. projection:: $meta - .. expression:: $meta Returns the metadata associated with a document, e.g. @@ -74,7 +67,7 @@ Text Score Metadata ``$meta: "textScore"`` - The ``{ $meta: "textScore" }`` expression can be a part of the :term:`projection` document to include the text score metadata. - - The :projection:`$meta` expression can be present in either an + - The :expression:`$meta` expression can be present in either an inclusion or an exclusion projection. - If you set the expression to a field name that already exists @@ -192,231 +185,227 @@ Examples ``$meta: "textScore"`` ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - Create an ``articles`` collection with the following documents: +Create an ``articles`` collection with the following documents: - .. code-block:: javascript +.. code-block:: javascript - db.articles.insertMany([ - { "_id" : 1, "title" : "cakes and ale" }, - { "_id" : 2, "title" : "more cakes" }, - { "_id" : 3, "title" : "bread" }, - { "_id" : 4, "title" : "some cakes" }, - { "_id" : 5, "title" : "two cakes to go" }, - { "_id" : 6, "title" : "pie" } - ]) + db.articles.insertMany([ + { "_id" : 1, "title" : "cakes and ale" }, + { "_id" : 2, "title" : "more cakes" }, + { "_id" : 3, "title" : "bread" }, + { "_id" : 4, "title" : "some cakes" }, + { "_id" : 5, "title" : "two cakes to go" }, + { "_id" : 6, "title" : "pie" } + ]) - Create a :ref:`text index ` on the ``title`` field: +Create a :ref:`text index ` on the ``title`` field: - .. code-block:: javascript +.. code-block:: javascript - db.articles.createIndex( { title: "text"} ) + db.articles.createIndex( { title: "text"} ) - .. tabs:: +.. tabs:: - .. tab:: Aggregation - :tabid: aggregation + .. tab:: Aggregation + :tabid: aggregation - The following aggregation operation performs a text search and uses the - :expression:`$meta` operator to group by the text search score: + The following aggregation operation performs a text search and uses the + :expression:`$meta` operator to group by the text search score: - .. code-block:: javascript + .. code-block:: javascript - db.articles.aggregate( - [ - { $match: { $text: { $search: "cake" } } }, - { $group: { _id: { $meta: "textScore" }, count: { $sum: 1 } } } - ] - ) + db.articles.aggregate( + [ + { $match: { $text: { $search: "cake" } } }, + { $group: { _id: { $meta: "textScore" }, count: { $sum: 1 } } } + ] + ) - The operation returns the following results: + The operation returns the following results: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - { "_id" : 0.75, "count" : 1 } - { "_id" : 0.6666666666666666, "count" : 1 } - { "_id" : 1, "count" : 2 } + { "_id" : 0.75, "count" : 1 } + { "_id" : 0.6666666666666666, "count" : 1 } + { "_id" : 1, "count" : 2 } - For more examples, see :doc:`/tutorial/text-search-in-aggregation`. + For more examples, see :doc:`/tutorial/text-search-in-aggregation`. - .. tab:: Find and Project - :tabid: find + .. tab:: Find and Project + :tabid: find - The following query performs a text search for the term ``cake`` and - uses the :projection:`$meta` operator in the projection document to - include the score assigned to each matching document: + The following query performs a text search for the term ``cake`` and + uses the :expression:`$meta` operator in the projection document to + include the score assigned to each matching document: - .. code-block:: javascript + .. code-block:: javascript - db.articles.find( - { $text: { $search: "cake" } }, - { score: { $meta: "textScore" } } - ) + db.articles.find( + { $text: { $search: "cake" } }, + { score: { $meta: "textScore" } } + ) - The operation returns the following documents with the text score: + The operation returns the following documents with the text score: - .. code-block:: javascript - :copyable: false + .. code-block:: javascript + :copyable: false - { "_id" : 4, "title" : "some cakes", "score" : 1 } - { "_id" : 1, "title" : "cakes and ale", "score" : 0.75 } - { "_id" : 5, "title" : "two cakes to go", "score" : 0.6666666666666666 } - { "_id" : 2, "title" : "more cakes", "score" : 1 } + { "_id" : 4, "title" : "some cakes", "score" : 1 } + { "_id" : 1, "title" : "cakes and ale", "score" : 0.75 } + { "_id" : 5, "title" : "two cakes to go", "score" : 0.6666666666666666 } + { "_id" : 2, "title" : "more cakes", "score" : 1 } - For additional examples of ``"textScore"`` projections and sorts, - see :ref:`ex-text-search-score`. + For additional examples of ``"textScore"`` projections and sorts, + see :ref:`ex-text-search-score`. ``$meta: "indexKey"`` ~~~~~~~~~~~~~~~~~~~~~ -.. container:: +.. note:: - .. note:: + The ``{ $meta: "indexKey" }`` expression is for debugging + purposes only and not for application logic. MongoDB returns the + value associated with the index chosen by the query system. The + system can choose a different index upon subsequent execution. - The ``{ $meta: "indexKey" }`` expression is for debugging - purposes only and not for application logic. MongoDB returns the - value associated with the index chosen by the query system. The - system can choose a different index upon subsequent execution. + For the selected index, the value returned depends on how the + database decides to represent values in an index and may change + across versions. The represented value may not be the actual + value for the field. - For the selected index, the value returned depends on how the - database decides to represent values in an index and may change - across versions. The represented value may not be the actual - value for the field. - - Create an ``orders`` collection with the following documents: +Create an ``orders`` collection with the following documents: - .. code-block:: javascript +.. code-block:: javascript - db.orders.insertMany([ - { "item" : "abc", "price" : NumberDecimal("12"), "quantity" : 2, "type": "apparel" }, - { "item" : "jkl", "price" : NumberDecimal("20"), "quantity" : 1, "type": "electronics" }, - { "item" : "abc", "price" : NumberDecimal("10"), "quantity" : 5, "type": "apparel" } - ]) + db.orders.insertMany([ + { "item" : "abc", "price" : NumberDecimal("12"), "quantity" : 2, "type": "apparel" }, + { "item" : "jkl", "price" : NumberDecimal("20"), "quantity" : 1, "type": "electronics" }, + { "item" : "abc", "price" : NumberDecimal("10"), "quantity" : 5, "type": "apparel" } + ]) - Create the following compound index on the ``type`` and ``item`` fields: +Create the following compound index on the ``type`` and ``item`` fields: - .. code-block:: javascript +.. code-block:: javascript - db.orders.createIndex( { type: 1, item: 1 } ) + db.orders.createIndex( { type: 1, item: 1 } ) - .. tabs:: +.. tabs:: - .. tab:: Aggregation - :tabid: aggregation + .. tab:: Aggregation + :tabid: aggregation - The following aggregation operation finds all documents with ``type`` - equal to ``apparel`` and uses the :expression:`$meta` operator to - include the index key value for the matching document if an index was - used: + The following aggregation operation finds all documents with ``type`` + equal to ``apparel`` and uses the :expression:`$meta` operator to + include the index key value for the matching document if an index was + used: - .. code-block:: javascript + .. code-block:: javascript - db.orders.aggregate( - [ - { $match: { type: "apparel" } }, - { $addFields: { idxKey: { $meta: "indexKey" } } } - ] - ) - - .. tab:: Find and Project - :tabid: find - - The following operation finds all documents with ``type`` - equal to ``apparel`` and uses the :expression:`$meta` operator to - include the index key value for the matching document if an index was - used: - - .. code-block:: javascript - - db.orders.find( { type: "apparel" }, { idxKey: { $meta: "indexKey" } } ) - - The operation returns the matching documents with their - corresponding index key: - - .. code-block:: javascript - :copyable: false - :emphasize-lines: 7,15 - - { - "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"), - "item" : "abc", - "price" : NumberDecimal("12"), - "quantity" : 2, - "type" : "apparel", - "idxKey" : { "type" : "apparel", "item" : "abc" } - } - { - "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"), - "item" : "abc", - "price" : NumberDecimal("10"), - "quantity" : 5, - "type" : "apparel", - "idxKey" : { "type" : "apparel", "item" : "abc" } - } - - - If :red:`no` index is used, the ``{ $meta: "indexKey" }`` does not - return anything. - - .. tabs:: - - .. tab:: Aggregation - :tabid: aggregation - - For example, the following operation does not use - an index since no index exists on the ``price`` field to support the - match condition: - - .. code-block:: javascript - - db.orders.aggregate( - [ - { $match: { price: { $gte: NumberDecimal("10") } } }, - { $addFields: { idxKey: { $meta: "indexKey" } } } - ] - ) - - .. tab:: Find and Project - :tabid: find - - For example, the following operation does not use an index - since no index exists on the ``price`` field to support the - match condition: - - .. code-block:: javascript - - db.orders.find( - { price: { $gte: NumberDecimal("10") } }, - { idxKey: { $meta: "indexKey" } } - ) - - The operation returns the matching documents without the ``idxKey`` - field: - - .. code-block:: javascript - :copyable: false - - { - "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"), - "item" : "abc", - "price" : NumberDecimal("12"), - "quantity" : 2, - "type" : "apparel" - } - { - "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcdf"), - "item" : "jkl", - "price" : NumberDecimal("20"), - "quantity" : 1, - "type" : "electronics" - } - { - "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"), - "item" : "abc", - "price" : NumberDecimal("10"), - "quantity" : 5, - "type" : "apparel" - } + db.orders.aggregate( + [ + { $match: { type: "apparel" } }, + { $addFields: { idxKey: { $meta: "indexKey" } } } + ] + ) + + .. tab:: Find and Project + :tabid: find + + The following operation finds all documents with ``type`` + equal to ``apparel`` and uses the :expression:`$meta` operator to + include the index key value for the matching document if an index was + used: + + .. code-block:: javascript + + db.orders.find( { type: "apparel" }, { idxKey: { $meta: "indexKey" } } ) + +The operation returns the matching documents with their +corresponding index key: + +.. code-block:: javascript + :copyable: false + :emphasize-lines: 7,15 + + { + "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"), + "item" : "abc", + "price" : NumberDecimal("12"), + "quantity" : 2, + "type" : "apparel", + "idxKey" : { "type" : "apparel", "item" : "abc" } + } + { + "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"), + "item" : "abc", + "price" : NumberDecimal("10"), + "quantity" : 5, + "type" : "apparel", + "idxKey" : { "type" : "apparel", "item" : "abc" } + } + + +If :red:`no` index is used, the ``{ $meta: "indexKey" }`` does not +return anything. + +.. tabs:: + + .. tab:: Aggregation + :tabid: aggregation + + For example, the following operation does not use + an index since no index exists on the ``price`` field to support the + match condition: + + .. code-block:: javascript + + db.orders.aggregate( + [ + { $match: { price: { $gte: NumberDecimal("10") } } }, + { $addFields: { idxKey: { $meta: "indexKey" } } } + ] + ) + + .. tab:: Find and Project + :tabid: find + + For example, the following operation does not use an index + since no index exists on the ``price`` field to support the + match condition: + + .. code-block:: javascript + + db.orders.find( + { price: { $gte: NumberDecimal("10") } }, + { idxKey: { $meta: "indexKey" } } + ) + +The operation returns the matching documents without the ``idxKey`` +field: + +.. code-block:: javascript + :copyable: false + + { + "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcde"), + "item" : "abc", + "price" : NumberDecimal("12"), + "quantity" : 2, + "type" : "apparel" + } + { + "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dcdf"), + "item" : "jkl", + "price" : NumberDecimal("20"), + "quantity" : 1, + "type" : "electronics" + } + { + "_id" : ObjectId("5e98a33ceaf5e9dcf2b8dce0"), + "item" : "abc", + "price" : NumberDecimal("10"), + "quantity" : 5, + "type" : "apparel" + } diff --git a/source/reference/operator/aggregation/millisecond.txt b/source/reference/operator/aggregation/millisecond.txt index bd3257cfe65..4b04ed4255e 100644 --- a/source/reference/operator/aggregation/millisecond.txt +++ b/source/reference/operator/aggregation/millisecond.txt @@ -107,7 +107,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -121,7 +121,7 @@ Consider a ``sales`` collection with the following document: The following aggregation uses the :expression:`$millisecond` and other date operators to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 12 diff --git a/source/reference/operator/aggregation/min.txt b/source/reference/operator/aggregation/min.txt index 67d55231522..db5c426383d 100644 --- a/source/reference/operator/aggregation/min.txt +++ b/source/reference/operator/aggregation/min.txt @@ -21,7 +21,7 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-min.rst - When used in the :pipeline:`$group` stage, :expression:`$min` has the + When used in the :pipeline:`$group` stage, :group:`$min` has the following syntax and returns the minimum value that results from applying an expression to each document in a group of documents that share the same group by key: @@ -31,16 +31,16 @@ Definition { $min: } When used in the other supported stages, - :expression:`$min` returns the minimum of the specified expression + :group:`$min` returns the minimum of the specified expression or list of expressions for each document and has one of two syntaxes: - - :expression:`$min` has one specified expression as its operand: + - :group:`$min` has one specified expression as its operand: .. code-block:: javascript { $min: } - - :expression:`$min` has a list of specified expressions as its + - :group:`$min` has a list of specified expressions as its operand: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/objectToArray.txt b/source/reference/operator/aggregation/objectToArray.txt index 307ea7f2fc5..b4b4c0832db 100644 --- a/source/reference/operator/aggregation/objectToArray.txt +++ b/source/reference/operator/aggregation/objectToArray.txt @@ -124,7 +124,6 @@ Consider a ``inventory`` collection with the following documents: The following aggregation pipeline operation use the :expression:`$objectToArray` to return the ``dimensions`` field as an array: -.. cssclass:: copyable-code .. code-block:: javascript db.inventory.aggregate( @@ -160,7 +159,6 @@ The following aggregation pipeline operation uses the :expression:`$objectToArray` along with :pipeline:`$unwind` and :pipeline:`$group` to calculate the total items in stock per warehouse. -.. cssclass:: copyable-code .. code-block:: javascript db.inventory.aggregate([ @@ -182,4 +180,6 @@ The operation returns the following: .. include:: /includes/example-objectToArray-arrayToObject.rst -.. seealso:: :expression:`$arrayToObject` +.. seealso:: + + :expression:`$arrayToObject` diff --git a/source/reference/operator/aggregation/planCacheStats.txt b/source/reference/operator/aggregation/planCacheStats.txt index d2a515fccf6..b97499c158d 100644 --- a/source/reference/operator/aggregation/planCacheStats.txt +++ b/source/reference/operator/aggregation/planCacheStats.txt @@ -28,12 +28,14 @@ Definition { $planCacheStats: { } } - .. admonition:: 4.4 Changes - :class: note + .. note:: 4.4 Changes + .. include:: /includes/extracts/4.4-changes-planCache-changes.rst -.. seealso:: :doc:`/core/query-plans` +.. seealso:: + + :doc:`/core/query-plans` Considerations -------------- @@ -54,7 +56,7 @@ Restrictions - :pipeline:`$facet` aggregation stage - :pipeline:`$planCacheStats` requires read concern level - :readconcern:`local`. + :readconcern:`"local"`. Access Control @@ -170,7 +172,9 @@ including: - If inactive, the query planner is not currently using the entry to generate query plans. - .. seealso:: :ref:`cache-entry-state` + .. seealso:: + + :ref:`cache-entry-state` * - :ref:`queryHash ` diff --git a/source/reference/operator/aggregation/project.txt b/source/reference/operator/aggregation/project.txt index befcbff2dce..87685a47865 100644 --- a/source/reference/operator/aggregation/project.txt +++ b/source/reference/operator/aggregation/project.txt @@ -402,8 +402,6 @@ Consider a ``books`` collection with the following document: The following :pipeline:`$project` stage uses the :variable:`REMOVE` variable to excludes the ``author.middle`` field only if it equals ``""``: -.. cssclass:: copyable-code - .. code-block:: javascript db.books.aggregate( [ @@ -561,6 +559,8 @@ The operation returns the following document: { "_id" : ObjectId("55ad167f320c6be244eb3b95"), "myArray" : [ 1, 1, null ] } -.. seealso:: +.. seealso:: + + :doc:`/tutorial/aggregation-zip-code-data-set`, :doc:`/tutorial/aggregation-with-user-preference-data` diff --git a/source/reference/operator/aggregation/push.txt b/source/reference/operator/aggregation/push.txt index 0aad20780d0..1488c00d787 100644 --- a/source/reference/operator/aggregation/push.txt +++ b/source/reference/operator/aggregation/push.txt @@ -21,7 +21,7 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-push.rst - :expression:`$push` has the following syntax: + :group:`$push` has the following syntax: .. code-block:: javascript @@ -45,7 +45,7 @@ Consider a ``sales`` collection with the following documents: { "_id" : 7, "item" : "xyz", "price" : 5, "quantity" : 10, "date" : ISODate("2014-02-15T14:12:12Z") } Grouping the documents by the day and the year of the ``date`` field, -the following operation uses the :expression:`$push` accumulator to +the following operation uses the :group:`$push` accumulator to compute the list of items and quantities sold for each group: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/redact.txt b/source/reference/operator/aggregation/redact.txt index 6961177e1fe..ee37adc2551 100644 --- a/source/reference/operator/aggregation/redact.txt +++ b/source/reference/operator/aggregation/redact.txt @@ -151,7 +151,9 @@ The aggregation operation returns the following "redacted" document: ] } -.. seealso:: :expression:`$size`, :expression:`$setIntersection` +.. seealso:: + + :expression:`$size`, :expression:`$setIntersection` Exclude All Fields at a Given Level ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -237,5 +239,7 @@ the field ``cc`` as a whole, including the ``shipping_addr`` field which contained embedded documents that had ``level`` field values equal to ``3`` and not ``5``. -.. seealso:: :doc:`/tutorial/implement-field-level-redaction` for +.. seealso:: + + :doc:`/tutorial/implement-field-level-redaction` for steps to set up multiple combinations of access for the same data. diff --git a/source/reference/operator/aggregation/regexFind.txt b/source/reference/operator/aggregation/regexFind.txt index 74b64851b2d..04cb0d96ad7 100644 --- a/source/reference/operator/aggregation/regexFind.txt +++ b/source/reference/operator/aggregation/regexFind.txt @@ -287,246 +287,232 @@ For example, the following aggregation performs a case-*sensitive* :expression:`$regexFind` on the ``description`` field. The regex pattern ``/line/`` does not specify any grouping: -.. container:: - - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /line/ } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /line/ } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ ] } } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ ] } } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ ] } } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ ] } } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ ] } } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ ] } } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } The following regex pattern ``/lin(e|k)/`` specifies a grouping ``(e|k)`` in the pattern: -.. container:: - - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /lin(e|k)/ } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /lin(e|k)/ } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ "e" ] } } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ "e" ] } } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ "e" ] } } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : { "match" : "link", "idx" : 9, "captures" : [ "k" ] } } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ "e" ] } } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ "e" ] } } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ "e" ] } } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : { "match" : "link", "idx" : 9, "captures" : [ "k" ] } } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } In the return option, the ``idx`` field is the `code point `_ index and not the byte index. To illustrate, consider the following example that uses the regex pattern ``/tier/``: -.. container:: - - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /tier/ } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /tier/ } } } } + ]) - The operation returns the following where only the last record - matches the pattern and the returned ``idx`` is ``2`` (instead of 3 - if using a byte index) +The operation returns the following where only the last record +matches the pattern and the returned ``idx`` is ``2`` (instead of 3 +if using a byte index) - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : null } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : null } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : null } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } - { "_id" : 6, "description" : "métier work vocation", - "returnObject" : { "match" : "tier", "idx" : 2, "captures" : [ ] } } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : null } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : null } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : null } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } + { "_id" : 6, "description" : "métier work vocation", + "returnObject" : { "match" : "tier", "idx" : 2, "captures" : [ ] } } .. _regexFind-example-i-options: ``i`` Option ```````````` -.. container:: +.. include:: /includes/extracts/agg-regex-options-one-place-only.rst - .. include:: /includes/extracts/agg-regex-options-one-place-only.rst +To perform case-*insensitive* pattern matching, include the :ref:`i +` option as part of the :ref:`regex ` field or +in the :ref:`options ` field: - To perform case-*insensitive* pattern matching, include the :ref:`i - ` option as part of the :ref:`regex ` field or - in the :ref:`options ` field: +.. code-block:: none + :copyable: false - .. code-block:: none - :copyable: false + // Specify i as part of the regex field + { $regexFind: { input: "$description", regex: /line/i } } - // Specify i as part of the regex field - { $regexFind: { input: "$description", regex: /line/i } } + // Specify i in the options field + { $regexFind: { input: "$description", regex: /line/, options: "i" } } + { $regexFind: { input: "$description", regex: "line", options: "i" } } - // Specify i in the options field - { $regexFind: { input: "$description", regex: /line/, options: "i" } } - { $regexFind: { input: "$description", regex: "line", options: "i" } } - - For example, the following aggregation performs a case-*insensitive* - :expression:`$regexFind` on the ``description`` field. The regex - pattern ``/line/`` does not specify any grouping: +For example, the following aggregation performs a case-*insensitive* +:expression:`$regexFind` on the ``description`` field. The regex +pattern ``/line/`` does not specify any grouping: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /line/i } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /line/i } } } } + ]) - The operation returns the following documents: +The operation returns the following documents: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : { "match" : "LINE", "idx" : 7, "captures" : [ ] } } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ ] } } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ ] } } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ ] } } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : { "match" : "LINE", "idx" : 7, "captures" : [ ] } } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ ] } } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ ] } } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ ] } } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } ``m`` Option ```````````` -.. container:: - - .. include:: /includes/extracts/agg-regex-options-one-place-only.rst +.. include:: /includes/extracts/agg-regex-options-one-place-only.rst - To match the specified anchors (e.g. ``^``, ``$``) for each line of a - multiline string, include the :ref:`m ` option as - part of the :ref:`regex ` field or in the - :ref:`options ` field: +To match the specified anchors (e.g. ``^``, ``$``) for each line of a +multiline string, include the :ref:`m ` option as +part of the :ref:`regex ` field or in the +:ref:`options ` field: - .. code-block:: none - :copyable: false +.. code-block:: none + :copyable: false - // Specify m as part of the regex field - { $regexFind: { input: "$description", regex: /line/m } } + // Specify m as part of the regex field + { $regexFind: { input: "$description", regex: /line/m } } - // Specify m in the options field - { $regexFind: { input: "$description", regex: /line/, options: "m" } } - { $regexFind: { input: "$description", regex: "line", options: "m" } } + // Specify m in the options field + { $regexFind: { input: "$description", regex: /line/, options: "m" } } + { $regexFind: { input: "$description", regex: "line", options: "m" } } - The following example includes both the ``i`` and the ``m`` options to - match lines starting with either the letter ``s`` or ``S`` for - multiline strings: +The following example includes both the ``i`` and the ``m`` options to +match lines starting with either the letter ``s`` or ``S`` for +multiline strings: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /^s/im } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /^s/im } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : { "match" : "S", "idx" : 0, "captures" : [ ] } } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "s", "idx" : 12, "captures" : [ ] } } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : null } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : null } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : { "match" : "S", "idx" : 0, "captures" : [ ] } } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "s", "idx" : 12, "captures" : [ ] } } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : null } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : null } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } ``x`` Option ```````````` -.. container:: - - .. include:: /includes/extracts/agg-regex-options-one-place-only.rst +.. include:: /includes/extracts/agg-regex-options-one-place-only.rst - To ignore all unescaped white space characters and comments (denoted by - the un-escaped hash ``#`` character and the next new-line character) in - the pattern, include the :ref:`s ` option in the - :ref:`options ` field: +To ignore all unescaped white space characters and comments (denoted by +the un-escaped hash ``#`` character and the next new-line character) in +the pattern, include the :ref:`s ` option in the +:ref:`options ` field: - .. code-block:: none - :copyable: false +.. code-block:: none + :copyable: false - // Specify x in the options field - { $regexFind: { input: "$description", regex: /line/, options: "x" } } - { $regexFind: { input: "$description", regex: "line", options: "x" } } + // Specify x in the options field + { $regexFind: { input: "$description", regex: /line/, options: "x" } } + { $regexFind: { input: "$description", regex: "line", options: "x" } } - The following example includes the ``x`` option to skip unescaped white - spaces and comments: +The following example includes the ``x`` option to skip unescaped white +spaces and comments: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /lin(e|k) # matches line or link/, options:"x" } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFind: { input: "$description", regex: /lin(e|k) # matches line or link/, options:"x" } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ "e" ] } } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ "e" ] } } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ "e" ] } } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : { "match" : "link", "idx" : 9, "captures" : [ "k" ] } } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : { "match" : "line", "idx" : 6, "captures" : [ "e" ] } } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "line", "idx" : 23, "captures" : [ "e" ] } } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "line", "idx" : 9, "captures" : [ "e" ] } } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : { "match" : "link", "idx" : 9, "captures" : [ "k" ] } } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } ``s`` Option ```````````` -.. container:: - - .. include:: /includes/extracts/agg-regex-options-one-place-only.rst +.. include:: /includes/extracts/agg-regex-options-one-place-only.rst - To allow the dot character (i.e. ``.``) in the pattern to match all - characters including the new line character, include the :ref:`s - ` option in the :ref:`options ` - field: +To allow the dot character (i.e. ``.``) in the pattern to match all +characters including the new line character, include the :ref:`s +` option in the :ref:`options ` +field: - .. code-block:: none - :copyable: false +.. code-block:: none + :copyable: false - // Specify s in the options field - { $regexFind: { input: "$description", regex: /m.*line/, options: "s" } } - { $regexFind: { input: "$description", regex: "m.*line", options: "s" } } + // Specify s in the options field + { $regexFind: { input: "$description", regex: /m.*line/, options: "s" } } + { $regexFind: { input: "$description", regex: "m.*line", options: "s" } } - The following example includes the ``s`` option to allow the dot - character (i.e. .) to match all characters including new line as well - as the ``i`` option to perform a case-insensitive match: +The following example includes the ``s`` option to allow the dot +character (i.e. .) to match all characters including new line as well +as the ``i`` option to perform a case-insensitive match: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFind: { input: "$description", regex:/m.*line/, options: "si" } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFind: { input: "$description", regex:/m.*line/, options: "si" } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : null } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "Many spaces before line", "idx" : 0, "captures" : [ ] } } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "Multiple\nline", "idx" : 0, "captures" : [ ] } } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : null } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : null } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : { "match" : "Many spaces before line", "idx" : 0, "captures" : [ ] } } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : { "match" : "Multiple\nline", "idx" : 0, "captures" : [ ] } } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : null } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : null } Use ``$regexFind`` to Parse Email from String ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -612,7 +598,8 @@ the ``details`` array into an embedded document with an ``email`` and ]) First Stage - The stage :pipeline:`$unwinds` the array into separate documents: + The stage :pipeline:`$unwinds <$unwind>` the array into separate + documents: .. code-block:: javascript :copyable: false diff --git a/source/reference/operator/aggregation/regexFindAll.txt b/source/reference/operator/aggregation/regexFindAll.txt index 6d88f12073c..435433ac04c 100644 --- a/source/reference/operator/aggregation/regexFindAll.txt +++ b/source/reference/operator/aggregation/regexFindAll.txt @@ -285,126 +285,121 @@ For example, the following aggregation performs a case-*sensitive* :expression:`$regexFindAll` on the ``description`` field. The regex pattern ``/line/`` does not specify any grouping: -.. container:: - .. code-block:: javascript - - db.products.aggregate([ - { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /line/ } } } } - ]) +.. code-block:: javascript - The operation returns the following: + db.products.aggregate([ + { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /line/ } } } } + ]) - .. code-block:: javascript - :copyable: false +The operation returns the following: - { - "_id" : 1, - "description" : "Single LINE description.", - "returnObject" : [ ] - } - { - "_id" : 2, - "description" : "First lines\nsecond line", - "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ ]}, { "match" : "line", "idx" : 19, "captures" : [ ] } ] - } - { - "_id" : 3, - "description" : "Many spaces before line", - "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ ] } ] - } - { - "_id" : 4, - "description" : "Multiple\nline descriptions", - "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ ] } - ] } +.. code-block:: javascript + :copyable: false - { - "_id" : 5, - "description" : "anchors, links and hyperlinks", - "returnObject" : [ ] - } - { - "_id" : 6, - "description" : "métier work vocation", - "returnObject" : [ ] - } + { + "_id" : 1, + "description" : "Single LINE description.", + "returnObject" : [ ] + } + { + "_id" : 2, + "description" : "First lines\nsecond line", + "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ ]}, { "match" : "line", "idx" : 19, "captures" : [ ] } ] + } + { + "_id" : 3, + "description" : "Many spaces before line", + "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ ] } ] + } + { + "_id" : 4, + "description" : "Multiple\nline descriptions", + "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ ] } + ] } + + { + "_id" : 5, + "description" : "anchors, links and hyperlinks", + "returnObject" : [ ] + } + { + "_id" : 6, + "description" : "métier work vocation", + "returnObject" : [ ] + } The following regex pattern ``/lin(e|k)/`` specifies a grouping ``(e|k)`` in the pattern: -.. container:: - - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /lin(e|k)/ } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /lin(e|k)/ } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { - "_id" : 1, - "description" : "Single LINE description.", - "returnObject": [ ] - } - { - "_id" : 2, - "description" : "First lines\nsecond line", - "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ "e" ] }, { "match" : "line", "idx" : 19, "captures" : [ "e" ] } ] - } - { - "_id" : 3, - "description" : "Many spaces before line", - "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ "e" ] } ] - } - { - "_id" : 4, - "description" : "Multiple\nline descriptions", - "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ "e" ] } ] - } - { - "_id" : 5, - "description" : "anchors, links and hyperlinks", - "returnObject" : [ { "match" : "link", "idx" : 9, "captures" : [ "k" ] }, { "match" : "link", "idx" : 24, "captures" : [ "k" ] } ] - } - { - "_id" : 6, - "description" : "métier work vocation", - "returnObject" : [ ] - } + { + "_id" : 1, + "description" : "Single LINE description.", + "returnObject": [ ] + } + { + "_id" : 2, + "description" : "First lines\nsecond line", + "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ "e" ] }, { "match" : "line", "idx" : 19, "captures" : [ "e" ] } ] + } + { + "_id" : 3, + "description" : "Many spaces before line", + "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ "e" ] } ] + } + { + "_id" : 4, + "description" : "Multiple\nline descriptions", + "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ "e" ] } ] + } + { + "_id" : 5, + "description" : "anchors, links and hyperlinks", + "returnObject" : [ { "match" : "link", "idx" : 9, "captures" : [ "k" ] }, { "match" : "link", "idx" : 24, "captures" : [ "k" ] } ] + } + { + "_id" : 6, + "description" : "métier work vocation", + "returnObject" : [ ] + } In the return option, the ``idx`` field is the `code point `_ index and not the byte index. To illustrate, consider the following example that uses the regex pattern ``/tier/``: -.. container:: +.. code-block:: javascript - .. code-block:: javascript + db.products.aggregate([ + { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /tier/ } } } } + ]) - db.products.aggregate([ - { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /tier/ } } } } - ]) +The operation returns the following where only the last record +matches the pattern and the returned ``idx`` is ``2`` (instead of 3 +if using a byte index) - The operation returns the following where only the last record - matches the pattern and the returned ``idx`` is ``2`` (instead of 3 - if using a byte index) +.. code-block:: javascript + :copyable: false - .. code-block:: javascript - :copyable: false - - { "_id" : 1, "description" : "Single LINE description.", "returnObject" : [ ] } - { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : [ ] } - { "_id" : 3, "description" : "Many spaces before line", "returnObject" : [ ] } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : [ ] } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : [ ] } - { "_id" : 6, "description" : "métier work vocation", - "returnObject" : [ { "match" : "tier", "idx" : 2, "captures" : [ ] } ] } + { "_id" : 1, "description" : "Single LINE description.", "returnObject" : [ ] } + { "_id" : 2, "description" : "First lines\nsecond line", "returnObject" : [ ] } + { "_id" : 3, "description" : "Many spaces before line", "returnObject" : [ ] } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returnObject" : [ ] } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returnObject" : [ ] } + { "_id" : 6, "description" : "métier work vocation", + "returnObject" : [ { "match" : "tier", "idx" : 2, "captures" : [ ] } ] } .. _regexFindAll-example-i-options: @@ -413,64 +408,62 @@ regex pattern ``/tier/``: .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: +To perform case-*insensitive* pattern matching, include the :ref:`i +` option as part of the :ref:`regex +` field or in the :ref:`options ` +field: - To perform case-*insensitive* pattern matching, include the :ref:`i - ` option as part of the :ref:`regex - ` field or in the :ref:`options ` - field: - - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - // Specify i as part of the regex field - { $regexFindAll: { input: "$description", regex: /line/i } } + // Specify i as part of the regex field + { $regexFindAll: { input: "$description", regex: /line/i } } - // Specify i in the options field - { $regexFindAll: { input: "$description", regex: /line/, options: "i" } } - { $regexFindAll: { input: "$description", regex: "line", options: "i" } } + // Specify i in the options field + { $regexFindAll: { input: "$description", regex: /line/, options: "i" } } + { $regexFindAll: { input: "$description", regex: "line", options: "i" } } - For example, the following aggregation performs a case-*insensitive* - :expression:`$regexFindAll` on the ``description`` field. The regex - pattern ``/line/`` does not specify any grouping: +For example, the following aggregation performs a case-*insensitive* +:expression:`$regexFindAll` on the ``description`` field. The regex +pattern ``/line/`` does not specify any grouping: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /line/i } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /line/i } } } } + ]) - The operation returns the following documents: +The operation returns the following documents: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { - "_id" : 1, - "description" : "Single LINE description.", - "returnObject" : [ { "match" : "LINE", "idx" : 7, "captures" : [ ] } ] - } - { - "_id" : 2, - "description" : "First lines\nsecond line", - "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ ] }, { "match" : "line", "idx" : 19, "captures" : [ ] } ] - } - { - "_id" : 3, - "description" : "Many spaces before line", - "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ ] } ] - } - { - "_id" : 4, - "description" : "Multiple\nline descriptions", - "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ ] } ] - } - { - "_id" : 5, - "description" : "anchors, links and hyperlinks", - "returnObject" : [ ] - } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } + { + "_id" : 1, + "description" : "Single LINE description.", + "returnObject" : [ { "match" : "LINE", "idx" : 7, "captures" : [ ] } ] + } + { + "_id" : 2, + "description" : "First lines\nsecond line", + "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ ] }, { "match" : "line", "idx" : 19, "captures" : [ ] } ] + } + { + "_id" : 3, + "description" : "Many spaces before line", + "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ ] } ] + } + { + "_id" : 4, + "description" : "Multiple\nline descriptions", + "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ ] } ] + } + { + "_id" : 5, + "description" : "anchors, links and hyperlinks", + "returnObject" : [ ] + } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } ``m`` Option @@ -478,186 +471,180 @@ regex pattern ``/tier/``: .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: +To match the specified anchors (e.g. ``^``, ``$``) for each line of a +multiline string, include the :ref:`m ` option +as part of the :ref:`regex ` field or in the +:ref:`options ` field: - To match the specified anchors (e.g. ``^``, ``$``) for each line of a - multiline string, include the :ref:`m ` option - as part of the :ref:`regex ` field or in the - :ref:`options ` field: +.. code-block:: javascript + :copyable: false - .. code-block:: javascript - :copyable: false + // Specify m as part of the regex field + { $regexFindAll: { input: "$description", regex: /line/m } } - // Specify m as part of the regex field - { $regexFindAll: { input: "$description", regex: /line/m } } + // Specify m in the options field + { $regexFindAll: { input: "$description", regex: /line/, options: "m" } } + { $regexFindAll: { input: "$description", regex: "line", options: "m" } } - // Specify m in the options field - { $regexFindAll: { input: "$description", regex: /line/, options: "m" } } - { $regexFindAll: { input: "$description", regex: "line", options: "m" } } +The following example includes both the ``i`` and the ``m`` options to +match lines starting with either the letter ``s`` or ``S`` for +multiline strings: - The following example includes both the ``i`` and the ``m`` options to - match lines starting with either the letter ``s`` or ``S`` for - multiline strings: +.. code-block:: javascript - .. code-block:: javascript + db.products.aggregate([ + { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /^s/im } } } } + ]) - db.products.aggregate([ - { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /^s/im } } } } - ]) +The operation returns the following: - The operation returns the following: +.. code-block:: javascript + :copyable: false - .. code-block:: javascript - :copyable: false - - { - "_id" : 1, - "description" : "Single LINE description.", - "returnObject" : [ { "match" : "S", "idx" : 0, "captures" : [ ] } ] - } - { - "_id" : 2, - "description" : "First lines\nsecond line", - "returnObject" : [ { "match" : "s", "idx" : 12, "captures" : [ ] } ] - } - { - "_id" : 3, - "description" : "Many spaces before line", - "returnObject" : [ ] - } - { - "_id" : 4, - "description" : "Multiple\nline descriptions", - "returnObject" : [ ] - } - { - "_id" : 5, - "description" : "anchors, links and hyperlinks", - "returnObject" : [ ] - } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } + { + "_id" : 1, + "description" : "Single LINE description.", + "returnObject" : [ { "match" : "S", "idx" : 0, "captures" : [ ] } ] + } + { + "_id" : 2, + "description" : "First lines\nsecond line", + "returnObject" : [ { "match" : "s", "idx" : 12, "captures" : [ ] } ] + } + { + "_id" : 3, + "description" : "Many spaces before line", + "returnObject" : [ ] + } + { + "_id" : 4, + "description" : "Multiple\nline descriptions", + "returnObject" : [ ] + } + { + "_id" : 5, + "description" : "anchors, links and hyperlinks", + "returnObject" : [ ] + } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } ``x`` Option ```````````` .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: +To ignore all unescaped white space characters and comments (denoted by +the un-escaped hash ``#`` character and the next new-line character) in +the pattern, include the :ref:`s ` option in the +:ref:`options ` field: - To ignore all unescaped white space characters and comments (denoted by - the un-escaped hash ``#`` character and the next new-line character) in - the pattern, include the :ref:`s ` option in the - :ref:`options ` field: - - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - // Specify x in the options field - { $regexFindAll: { input: "$description", regex: /line/, options: "x" } } - { $regexFindAll: { input: "$description", regex: "line", options: "x" } } + // Specify x in the options field + { $regexFindAll: { input: "$description", regex: /line/, options: "x" } } + { $regexFindAll: { input: "$description", regex: "line", options: "x" } } - The following example includes the ``x`` option to skip unescaped white - spaces and comments: +The following example includes the ``x`` option to skip unescaped white +spaces and comments: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /lin(e|k) # matches line or link/, options:"x" } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex: /lin(e|k) # matches line or link/, options:"x" } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { - "_id" : 1, - "description" : "Single LINE description.", - "returnObject" : [ ] - } - { - "_id" : 2, - "description" : "First lines\nsecond line", - "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ "e" ] }, { "match" : "line", "idx" : 19, "captures" : [ "e" ] } ] - } - { - "_id" : 3, - "description" : "Many spaces before line", - "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ "e" ] } ] - } - { - "_id" : 4, - "description" : "Multiple\nline descriptions", - "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ "e" ] } ] - } - { - "_id" : 5, - "description" : "anchors, links and hyperlinks", - "returnObject" : [ { "match" : "link", "idx" : 9, "captures" : [ "k" ] }, { "match" : "link", "idx" : 24, "captures" : [ "k" ] } ] - } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } + { + "_id" : 1, + "description" : "Single LINE description.", + "returnObject" : [ ] + } + { + "_id" : 2, + "description" : "First lines\nsecond line", + "returnObject" : [ { "match" : "line", "idx" : 6, "captures" : [ "e" ] }, { "match" : "line", "idx" : 19, "captures" : [ "e" ] } ] + } + { + "_id" : 3, + "description" : "Many spaces before line", + "returnObject" : [ { "match" : "line", "idx" : 23, "captures" : [ "e" ] } ] + } + { + "_id" : 4, + "description" : "Multiple\nline descriptions", + "returnObject" : [ { "match" : "line", "idx" : 9, "captures" : [ "e" ] } ] + } + { + "_id" : 5, + "description" : "anchors, links and hyperlinks", + "returnObject" : [ { "match" : "link", "idx" : 9, "captures" : [ "k" ] }, { "match" : "link", "idx" : 24, "captures" : [ "k" ] } ] + } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } ``s`` Option ```````````` .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: +To allow the dot character (i.e. ``.``) in the pattern to match all +characters including the new line character, include the :ref:`s +` option in the :ref:`options +` field: - To allow the dot character (i.e. ``.``) in the pattern to match all - characters including the new line character, include the :ref:`s - ` option in the :ref:`options - ` field: - - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - // Specify s in the options field - { $regexFindAll: { input: "$description", regex: /m.*line/, options: "s" } } - { $regexFindAll: { input: "$description", regex: "m.*line", options: "s" } } + // Specify s in the options field + { $regexFindAll: { input: "$description", regex: /m.*line/, options: "s" } } + { $regexFindAll: { input: "$description", regex: "m.*line", options: "s" } } - The following example includes the ``s`` option to allow the dot - character (i.e. .) to match all characters including new line as well - as the ``i`` option to perform a case-insensitive match: +The following example includes the ``s`` option to allow the dot +character (i.e. .) to match all characters including new line as well +as the ``i`` option to perform a case-insensitive match: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex:/m.*line/, options: "si" } } } } - ]) + db.products.aggregate([ + { $addFields: { returnObject: { $regexFindAll: { input: "$description", regex:/m.*line/, options: "si" } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { - "_id" : 1, - "description" : "Single LINE description.", - "returnObject" : [ ] - } - { - "_id" : 2, - "description" : "First lines\nsecond line", - "returnObject" : [ ] - } - { - "_id" : 3, - "description" : "Many spaces before line", - "returnObject" : [ { "match" : "Many spaces before line", "idx" : 0, "captures" : [ ] } ] - } - { - "_id" : 4, - "description" : "Multiple\nline descriptions", - "returnObject" : [ { "match" : "Multiple\nline", "idx" : 0, "captures" : [ ] } ] - } - { - "_id" : 5, - "description" : "anchors, links and hyperlinks", - "returnObject" : [ ] - } - { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } + { + "_id" : 1, + "description" : "Single LINE description.", + "returnObject" : [ ] + } + { + "_id" : 2, + "description" : "First lines\nsecond line", + "returnObject" : [ ] + } + { + "_id" : 3, + "description" : "Many spaces before line", + "returnObject" : [ { "match" : "Many spaces before line", "idx" : 0, "captures" : [ ] } ] + } + { + "_id" : 4, + "description" : "Multiple\nline descriptions", + "returnObject" : [ { "match" : "Multiple\nline", "idx" : 0, "captures" : [ ] } ] + } + { + "_id" : 5, + "description" : "anchors, links and hyperlinks", + "returnObject" : [ ] + } + { "_id" : 6, "description" : "métier work vocation", "returnObject" : [ ] } Use ``$regexFindAll`` to Parse Email from String ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/operator/aggregation/regexMatch.txt b/source/reference/operator/aggregation/regexMatch.txt index d2f113bfe03..7e2e67cff90 100644 --- a/source/reference/operator/aggregation/regexMatch.txt +++ b/source/reference/operator/aggregation/regexMatch.txt @@ -175,49 +175,45 @@ For example, the following aggregation performs a case-*sensitive* :expression:`$regexMatch` on the ``description`` field. The regex pattern ``/line/`` does not specify any grouping: -.. container:: - - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { result: { $regexMatch: { input: "$description", regex: /line/ } } } } - ]) + db.products.aggregate([ + { $addFields: { result: { $regexMatch: { input: "$description", regex: /line/ } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "result" : false } - { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } - { "_id" : 3, "description" : "Many spaces before line", "result" : true } - { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : true } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : false } - { "_id" : 6, "description" : "métier work vocation", "result" : false } - + { "_id" : 1, "description" : "Single LINE description.", "result" : false } + { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } + { "_id" : 3, "description" : "Many spaces before line", "result" : true } + { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : true } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : false } + { "_id" : 6, "description" : "métier work vocation", "result" : false } + The following regex pattern ``/lin(e|k)/`` specifies a grouping ``(e|k)`` in the pattern: -.. container:: - - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { result: { $regexMatch: { input: "$description", regex: /lin(e|k)/ } } } } - ]) + db.products.aggregate([ + { $addFields: { result: { $regexMatch: { input: "$description", regex: /lin(e|k)/ } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "result" : false } - { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } - { "_id" : 3, "description" : "Many spaces before line", "result" : true } - { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : true } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : true } - { "_id" : 6, "description" : "métier work vocation", "result" : false } + { "_id" : 1, "description" : "Single LINE description.", "result" : false } + { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } + { "_id" : 3, "description" : "Many spaces before line", "result" : true } + { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : true } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : true } + { "_id" : 6, "description" : "métier work vocation", "result" : false } .. _regexMatch-example-i-options: @@ -226,88 +222,84 @@ The following regex pattern ``/lin(e|k)/`` specifies a grouping .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: - - To perform case-*insensitive* pattern matching, include the :ref:`i - ` option as part of the :ref:`regex - ` field or in the :ref:`options ` - field: +To perform case-*insensitive* pattern matching, include the :ref:`i +` option as part of the :ref:`regex +` field or in the :ref:`options ` +field: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - // Specify i as part of the regex field - { $regexMatch: { input: "$description", regex: /line/i } } + // Specify i as part of the regex field + { $regexMatch: { input: "$description", regex: /line/i } } - // Specify i in the options field - { $regexMatch: { input: "$description", regex: /line/, options: "i" } } - { $regexMatch: { input: "$description", regex: "line", options: "i" } } + // Specify i in the options field + { $regexMatch: { input: "$description", regex: /line/, options: "i" } } + { $regexMatch: { input: "$description", regex: "line", options: "i" } } - For example, the following aggregation performs a case-*insensitive* - :expression:`$regexMatch` on the ``description`` field. The regex - pattern ``/line/`` does not specify any grouping: +For example, the following aggregation performs a case-*insensitive* +:expression:`$regexMatch` on the ``description`` field. The regex +pattern ``/line/`` does not specify any grouping: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { result: { $regexMatch: { input: "$description", regex: /line/i } } } } - ]) + db.products.aggregate([ + { $addFields: { result: { $regexMatch: { input: "$description", regex: /line/i } } } } + ]) - The operation returns the following documents: +The operation returns the following documents: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "result" : true } - { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } - { "_id" : 3, "description" : "Many spaces before line", "result" : true } - { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : true } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : false } - { "_id" : 6, "description" : "métier work vocation", "result" : false } + { "_id" : 1, "description" : "Single LINE description.", "result" : true } + { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } + { "_id" : 3, "description" : "Many spaces before line", "result" : true } + { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : true } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : false } + { "_id" : 6, "description" : "métier work vocation", "result" : false } ``m`` Option ```````````` .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: - - To match the specified anchors (e.g. ``^``, ``$``) for each line of a - multiline string, include the :ref:`m ` option - as part of the :ref:`regex ` field or in the - :ref:`options ` field: +To match the specified anchors (e.g. ``^``, ``$``) for each line of a +multiline string, include the :ref:`m ` option +as part of the :ref:`regex ` field or in the +:ref:`options ` field: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - // Specify m as part of the regex field - { $regexMatch: { input: "$description", regex: /line/m } } + // Specify m as part of the regex field + { $regexMatch: { input: "$description", regex: /line/m } } - // Specify m in the options field - { $regexMatch: { input: "$description", regex: /line/, options: "m" } } - { $regexMatch: { input: "$description", regex: "line", options: "m" } } + // Specify m in the options field + { $regexMatch: { input: "$description", regex: /line/, options: "m" } } + { $regexMatch: { input: "$description", regex: "line", options: "m" } } - The following example includes both the ``i`` and the ``m`` options to - match lines starting with either the letter ``s`` or ``S`` for - multiline strings: +The following example includes both the ``i`` and the ``m`` options to +match lines starting with either the letter ``s`` or ``S`` for +multiline strings: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { result: { $regexMatch: { input: "$description", regex: /^s/im } } } } - ]) + db.products.aggregate([ + { $addFields: { result: { $regexMatch: { input: "$description", regex: /^s/im } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "result" : true } - { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } - { "_id" : 3, "description" : "Many spaces before line", "result" : false } - { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : false } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : false } - { "_id" : 6, "description" : "métier work vocation", "result" : false } + { "_id" : 1, "description" : "Single LINE description.", "result" : true } + { "_id" : 2, "description" : "First lines\nsecond line", "result" : true } + { "_id" : 3, "description" : "Many spaces before line", "result" : false } + { "_id" : 4, "description" : "Multiple\nline descriptions", "result" : false } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "result" : false } + { "_id" : 6, "description" : "métier work vocation", "result" : false } ``x`` Option @@ -315,82 +307,78 @@ The following regex pattern ``/lin(e|k)/`` specifies a grouping .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: - - To ignore all unescaped white space characters and comments (denoted by - the un-escaped hash ``#`` character and the next new-line character) in - the pattern, include the :ref:`s ` option in the - :ref:`options ` field: +To ignore all unescaped white space characters and comments (denoted by +the un-escaped hash ``#`` character and the next new-line character) in +the pattern, include the :ref:`s ` option in the +:ref:`options ` field: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - // Specify x in the options field - { $regexMatch: { input: "$description", regex: /line/, options: "x" } } - { $regexMatch: { input: "$description", regex: "line", options: "x" } } + // Specify x in the options field + { $regexMatch: { input: "$description", regex: /line/, options: "x" } } + { $regexMatch: { input: "$description", regex: "line", options: "x" } } - The following example includes the ``x`` option to skip unescaped white - spaces and comments: +The following example includes the ``x`` option to skip unescaped white +spaces and comments: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returns: { $regexMatch: { input: "$description", regex: /lin(e|k) # matches line or link/, options:"x" } } } } - ]) + db.products.aggregate([ + { $addFields: { returns: { $regexMatch: { input: "$description", regex: /lin(e|k) # matches line or link/, options:"x" } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returns" : false } - { "_id" : 2, "description" : "First lines\nsecond line", "returns" : true } - { "_id" : 3, "description" : "Many spaces before line", "returns" : true } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returns" : true } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returns" : true } - { "_id" : 6, "description" : "métier work vocation", "returns" : false } + { "_id" : 1, "description" : "Single LINE description.", "returns" : false } + { "_id" : 2, "description" : "First lines\nsecond line", "returns" : true } + { "_id" : 3, "description" : "Many spaces before line", "returns" : true } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returns" : true } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returns" : true } + { "_id" : 6, "description" : "métier work vocation", "returns" : false } ``s`` Option ```````````` .. include:: /includes/extracts/agg-regex-options-one-place-only.rst -.. container:: +To allow the dot character (i.e. ``.``) in the pattern to match all +characters including the new line character, include the :ref:`s +` option in the :ref:`options +` field: - To allow the dot character (i.e. ``.``) in the pattern to match all - characters including the new line character, include the :ref:`s - ` option in the :ref:`options - ` field: - - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - // Specify s in the options field - { $regexMatch: { input: "$description", regex: /m.*line/, options: "s" } } - { $regexMatch: { input: "$description", regex: "m.*line", options: "s" } } + // Specify s in the options field + { $regexMatch: { input: "$description", regex: /m.*line/, options: "s" } } + { $regexMatch: { input: "$description", regex: "m.*line", options: "s" } } - The following example includes the ``s`` option to allow the dot - character (i.e. .) to match all characters including new line as well - as the ``i`` option to perform a case-insensitive match: +The following example includes the ``s`` option to allow the dot +character (i.e. .) to match all characters including new line as well +as the ``i`` option to perform a case-insensitive match: - .. code-block:: javascript +.. code-block:: javascript - db.products.aggregate([ - { $addFields: { returns: { $regexMatch: { input: "$description", regex:/m.*line/, options: "si" } } } } - ]) + db.products.aggregate([ + { $addFields: { returns: { $regexMatch: { input: "$description", regex:/m.*line/, options: "si" } } } } + ]) - The operation returns the following: +The operation returns the following: - .. code-block:: javascript - :copyable: false +.. code-block:: javascript + :copyable: false - { "_id" : 1, "description" : "Single LINE description.", "returns" : false } - { "_id" : 2, "description" : "First lines\nsecond line", "returns" : false } - { "_id" : 3, "description" : "Many spaces before line", "returns" : true } - { "_id" : 4, "description" : "Multiple\nline descriptions", "returns" : true } - { "_id" : 5, "description" : "anchors, links and hyperlinks", "returns" : false } - { "_id" : 6, "description" : "métier work vocation", "returns" : false } + { "_id" : 1, "description" : "Single LINE description.", "returns" : false } + { "_id" : 2, "description" : "First lines\nsecond line", "returns" : false } + { "_id" : 3, "description" : "Many spaces before line", "returns" : true } + { "_id" : 4, "description" : "Multiple\nline descriptions", "returns" : true } + { "_id" : 5, "description" : "anchors, links and hyperlinks", "returns" : false } + { "_id" : 6, "description" : "métier work vocation", "returns" : false } Use ``$regexMatch`` to Check Email Address ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/operator/aggregation/replaceWith.txt b/source/reference/operator/aggregation/replaceWith.txt index a00672c109f..1acf48b3a99 100644 --- a/source/reference/operator/aggregation/replaceWith.txt +++ b/source/reference/operator/aggregation/replaceWith.txt @@ -273,7 +273,7 @@ First stage: Second stage: The :pipeline:`$group` stage groups by the quarter and uses - :expression:`$push` to accumulate the ``obj`` fields into a new + :group:`$push` to accumulate the ``obj`` fields into a new ``items`` array field. For example: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/rtrim.txt b/source/reference/operator/aggregation/rtrim.txt index 32bb27a6998..1ff05f1ef64 100644 --- a/source/reference/operator/aggregation/rtrim.txt +++ b/source/reference/operator/aggregation/rtrim.txt @@ -59,7 +59,9 @@ Definition characters, including the null character. For the list of whitespace characters, see :ref:`rtrim-white-space`. - .. seealso:: :expression:`$ltrim` and :expression:`$trim` + .. seealso:: + + :expression:`$ltrim` and :expression:`$trim` Behavior -------- diff --git a/source/reference/operator/aggregation/second.txt b/source/reference/operator/aggregation/second.txt index 62f8353811d..d9dcd0ac2d2 100644 --- a/source/reference/operator/aggregation/second.txt +++ b/source/reference/operator/aggregation/second.txt @@ -107,7 +107,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -121,7 +121,7 @@ Consider a ``sales`` collection with the following document: The following aggregation uses the :expression:`$second` and other date expressions to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 11 diff --git a/source/reference/operator/aggregation/sort.txt b/source/reference/operator/aggregation/sort.txt index 21905be5778..3d2521d8020 100644 --- a/source/reference/operator/aggregation/sort.txt +++ b/source/reference/operator/aggregation/sort.txt @@ -28,24 +28,22 @@ Definition sort by and the respective sort order. ```` can have one of the following values: - .. container:: + .. list-table:: + :header-rows: 1 + :widths: 35 65 - .. list-table:: - :header-rows: 1 - :widths: 35 65 + * - Value + - Description - * - Value - - Description + * - ``1`` + - Sort ascending. - * - ``1`` - - Sort ascending. + * - ``-1`` + - Sort descending. - * - ``-1`` - - Sort descending. - - * - ``{ $meta: "textScore" }`` - - Sort by the computed ``textScore`` metadata in descending - order. See :ref:`sort-pipeline-metadata` for an example. + * - ``{ $meta: "textScore" }`` + - Sort by the computed ``textScore`` metadata in descending + order. See :ref:`sort-pipeline-metadata` for an example. If sorting on multiple fields, sort order is evaluated from left to right. For example, in the form above, documents are first sorted by @@ -222,6 +220,8 @@ is not preceded by a :pipeline:`$project`, :pipeline:`$unwind`, or .. todo:: if a sort precedes the first $group in a sharded system, all documents must go to the mongos for sorting. -.. seealso:: +.. seealso:: + + :doc:`/tutorial/aggregation-zip-code-data-set`, :doc:`/tutorial/aggregation-with-user-preference-data` diff --git a/source/reference/operator/aggregation/sortByCount.txt b/source/reference/operator/aggregation/sortByCount.txt index c509c97aaf9..d3ddf267a90 100644 --- a/source/reference/operator/aggregation/sortByCount.txt +++ b/source/reference/operator/aggregation/sortByCount.txt @@ -61,7 +61,7 @@ Definition ``employee`` and ``business`` fields are document fields, then the following :expression:`$mergeObjects` expression, which evaluates to a document, is a valid argument to - :pipeline:`$sortByCounts`: + :pipeline:`$sortByCount`: .. code-block:: javascript @@ -74,7 +74,9 @@ Definition { $sortByCount: { lname: "$employee.last", fname: "$employee.first" } } - .. seealso:: :doc:`/reference/bson-type-comparison-order/` + .. seealso:: + + :doc:`/reference/bson-type-comparison-order/` Behavior -------- diff --git a/source/reference/operator/aggregation/stdDevPop.txt b/source/reference/operator/aggregation/stdDevPop.txt index 819d90275f7..8bcadc4d613 100644 --- a/source/reference/operator/aggregation/stdDevPop.txt +++ b/source/reference/operator/aggregation/stdDevPop.txt @@ -28,12 +28,12 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-stdDevPop.rst - When used in the :pipeline:`$group` stage, :expression:`$stdDevPop` returns + When used in the :pipeline:`$group` stage, :group:`$stdDevPop` returns the population standard deviation of the specified expression for a group of documents that share the same group by key and has the following syntax: - - :expression:`$stdDevPop` has one specified expression as its + - :group:`$stdDevPop` has one specified expression as its operand: .. code-block:: javascript @@ -41,24 +41,24 @@ Definition { $stdDevPop: } When used in the other supported stages, - :expression:`$stdDevPop` returns the standard deviation of the + :group:`$stdDevPop` returns the standard deviation of the specified expression or list of expressions for each document and has one of two syntaxes: - - :expression:`$stdDevPop` has one specified expression as its operand: + - :group:`$stdDevPop` has one specified expression as its operand: .. code-block:: javascript { $stdDevPop: } - - :expression:`$stdDevPop` has a list of specified expressions as its + - :group:`$stdDevPop` has a list of specified expressions as its operand: .. code-block:: javascript { $stdDevPop: [ , ... ] } - The argument for :expression:`$stdDevPop` can be any + The argument for :group:`$stdDevPop` can be any :ref:`expression ` as long as it resolves to an array. For more information on expressions, see :ref:`aggregation-expressions` diff --git a/source/reference/operator/aggregation/stdDevSamp.txt b/source/reference/operator/aggregation/stdDevSamp.txt index 81ce6967171..f5d1276eca0 100644 --- a/source/reference/operator/aggregation/stdDevSamp.txt +++ b/source/reference/operator/aggregation/stdDevSamp.txt @@ -28,7 +28,7 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-stdDevSamp.rst - When used in the :pipeline:`$group` stage, :expression:`$stdDevSamp` has the + When used in the :pipeline:`$group` stage, :group:`$stdDevSamp` has the following syntax and returns the sample standard deviation of the specified expression for a group of documents that share the same group by key: @@ -38,24 +38,24 @@ Definition { $stdDevSamp: } When used in the other supported stages, - :expression:`$stdDevSamp` returns the sample standard deviation of + :group:`$stdDevSamp` returns the sample standard deviation of the specified expression or list of expressions for each document and has one of two syntaxes: - - :expression:`$stdDevSamp` has one specified expression as its operand: + - :group:`$stdDevSamp` has one specified expression as its operand: .. code-block:: javascript { $stdDevSamp: } - - :expression:`$stdDevSamp` has a list of specified expressions as its + - :group:`$stdDevSamp` has a list of specified expressions as its operand: .. code-block:: javascript { $stdDevSamp: [ , ... ] } - The argument for :expression:`$stdDevSamp` can be any + The argument for :group:`$stdDevSamp` can be any :ref:`expression ` as long as it resolves to an array. For more information on expressions, see :ref:`aggregation-expressions`. diff --git a/source/reference/operator/aggregation/strLenCP.txt b/source/reference/operator/aggregation/strLenCP.txt index d8069432977..3d39e7fefb7 100644 --- a/source/reference/operator/aggregation/strLenCP.txt +++ b/source/reference/operator/aggregation/strLenCP.txt @@ -117,4 +117,6 @@ The operation returns the following results: { "_id" : 7, "name" : "tacos", "length" : 5 } { "_id" : 8, "name" : "寿司", "length" : 2 } -.. seealso:: :expression:`$strLenBytes` \ No newline at end of file +.. seealso:: + + :expression:`$strLenBytes` diff --git a/source/reference/operator/aggregation/substrBytes.txt b/source/reference/operator/aggregation/substrBytes.txt index 549d41102b8..5686d9fe73e 100644 --- a/source/reference/operator/aggregation/substrBytes.txt +++ b/source/reference/operator/aggregation/substrBytes.txt @@ -256,4 +256,6 @@ The operation returns the following results: { "_id" : 7, "name" : "tacos", "menuCode" : "tac" } { "_id" : 8, "name" : "寿司sushi", "menuCode" : "寿" } -.. seealso:: :expression:`$substrCP` \ No newline at end of file +.. seealso:: + + :expression:`$substrCP` diff --git a/source/reference/operator/aggregation/substrCP.txt b/source/reference/operator/aggregation/substrCP.txt index 5cc29e33564..a63324dc843 100644 --- a/source/reference/operator/aggregation/substrCP.txt +++ b/source/reference/operator/aggregation/substrCP.txt @@ -199,4 +199,6 @@ The operation returns the following results: { "_id" : 7, "name" : "tacos", "menuCode" : "tac" } { "_id" : 8, "name" : "寿司sushi", "menuCode" : "寿司s" } -.. seealso:: :expression:`$substrBytes` \ No newline at end of file +.. seealso:: + + :expression:`$substrBytes` diff --git a/source/reference/operator/aggregation/sum.txt b/source/reference/operator/aggregation/sum.txt index d1b7d9421f8..dd5f3a0bae7 100644 --- a/source/reference/operator/aggregation/sum.txt +++ b/source/reference/operator/aggregation/sum.txt @@ -20,7 +20,7 @@ Definition .. include:: /includes/extracts/fact-aggregation-accumulator-sum.rst - When used in the :pipeline:`$group` stage, :expression:`$sum` has the + When used in the :pipeline:`$group` stage, :group:`$sum` has the following syntax and returns the collective sum of all the numeric values that result from applying a specified expression to each document in a group of documents that share the same group by key: @@ -29,17 +29,17 @@ Definition { $sum: } - When used in the other supported stages, :expression:`$sum` returns the + When used in the other supported stages, :group:`$sum` returns the sum of the specified expression or list of expressions for each document and has one of two syntaxes: - - :expression:`$sum` has one specified expression as its operand: + - :group:`$sum` has one specified expression as its operand: .. code-block:: javascript { $sum: } - - :expression:`$sum` has a list of specified expressions as its + - :group:`$sum` has a list of specified expressions as its operand: .. code-block:: javascript diff --git a/source/reference/operator/aggregation/switch.txt b/source/reference/operator/aggregation/switch.txt index 5893abd095a..eaa034b53b1 100644 --- a/source/reference/operator/aggregation/switch.txt +++ b/source/reference/operator/aggregation/switch.txt @@ -206,4 +206,6 @@ The operation returns the following: { "_id" : 2, "name" : "Bob Hanna", "summary" : "Needs improvement." } { "_id" : 3, "name" : "James Torrelio", "summary" : "Doing great!" } -.. seealso:: :expression:`$cond` +.. seealso:: + + :expression:`$cond` diff --git a/source/reference/operator/aggregation/tan.txt b/source/reference/operator/aggregation/tan.txt index 4382aeadbdc..b88a37844aa 100644 --- a/source/reference/operator/aggregation/tan.txt +++ b/source/reference/operator/aggregation/tan.txt @@ -99,7 +99,7 @@ Example } The following aggregation operation uses the - :expression:`$tans` expression to calculate the side opposite + :expression:`$tan` expression to calculate the side opposite to ``angle_a`` and add it to the input document using the :pipeline:`$addFields` pipeline stage. diff --git a/source/reference/operator/aggregation/toBool.txt b/source/reference/operator/aggregation/toBool.txt index e0b89043d2f..5c9d993a180 100644 --- a/source/reference/operator/aggregation/toBool.txt +++ b/source/reference/operator/aggregation/toBool.txt @@ -43,7 +43,9 @@ Definition { $convert: { input: , to: "bool" } } - .. seealso:: :expression:`$convert` + .. seealso:: + + :expression:`$convert` Behavior diff --git a/source/reference/operator/aggregation/toDate.txt b/source/reference/operator/aggregation/toDate.txt index 5ffa7d2ca90..8edcf9ad29d 100644 --- a/source/reference/operator/aggregation/toDate.txt +++ b/source/reference/operator/aggregation/toDate.txt @@ -43,7 +43,9 @@ Definition { $convert: { input: , to: "date" } } - .. seealso:: :expression:`$convert` and :expression:`$dateFromString` + .. seealso:: + + :expression:`$convert` and :expression:`$dateFromString` Behavior diff --git a/source/reference/operator/aggregation/toDecimal.txt b/source/reference/operator/aggregation/toDecimal.txt index 652c8091910..36ff6a30b9b 100644 --- a/source/reference/operator/aggregation/toDecimal.txt +++ b/source/reference/operator/aggregation/toDecimal.txt @@ -44,7 +44,9 @@ Definition { $convert: { input: , to: "decimal" } } - .. seealso:: :expression:`$convert` + .. seealso:: + + :expression:`$convert` Behavior -------- diff --git a/source/reference/operator/aggregation/toInt.txt b/source/reference/operator/aggregation/toInt.txt index 26f87fdf8af..a20683213b9 100644 --- a/source/reference/operator/aggregation/toInt.txt +++ b/source/reference/operator/aggregation/toInt.txt @@ -43,7 +43,9 @@ Definition { $convert: { input: , to: "int" } } - .. seealso:: :expression:`$convert` + .. seealso:: + + :expression:`$convert` Behavior diff --git a/source/reference/operator/aggregation/toLong.txt b/source/reference/operator/aggregation/toLong.txt index 0f65caed344..e8eabe0767c 100644 --- a/source/reference/operator/aggregation/toLong.txt +++ b/source/reference/operator/aggregation/toLong.txt @@ -43,7 +43,9 @@ Definition { $convert: { input: , to: "long" } } - .. seealso:: :expression:`$convert` + .. seealso:: + + :expression:`$convert` Behavior diff --git a/source/reference/operator/aggregation/toObjectId.txt b/source/reference/operator/aggregation/toObjectId.txt index 443a2d3fe31..a363fd5ca69 100644 --- a/source/reference/operator/aggregation/toObjectId.txt +++ b/source/reference/operator/aggregation/toObjectId.txt @@ -43,7 +43,9 @@ Definition { $convert: { input: , to: "objectId" } } - .. seealso:: :expression:`$convert` + .. seealso:: + + :expression:`$convert` Behavior diff --git a/source/reference/operator/aggregation/toString.txt b/source/reference/operator/aggregation/toString.txt index 7595472d2f1..9737e555ddb 100644 --- a/source/reference/operator/aggregation/toString.txt +++ b/source/reference/operator/aggregation/toString.txt @@ -39,7 +39,9 @@ Definition { $convert: { input: , to: "string" } } - .. seealso:: :expression:`$convert` and :expression:`$dateToString` + .. seealso:: + + :expression:`$convert` and :expression:`$dateToString` Behavior diff --git a/source/reference/operator/aggregation/trim.txt b/source/reference/operator/aggregation/trim.txt index 9cc383fe91c..df934fc4243 100644 --- a/source/reference/operator/aggregation/trim.txt +++ b/source/reference/operator/aggregation/trim.txt @@ -58,7 +58,9 @@ Definition characters, including the null character. For the list of whitespace characters, see :ref:`trim-white-space`. - .. seealso:: :expression:`$ltrim` and :expression:`$rtrim` + .. seealso:: + + :expression:`$ltrim` and :expression:`$rtrim` Behavior -------- diff --git a/source/reference/operator/aggregation/trunc.txt b/source/reference/operator/aggregation/trunc.txt index 3a9a2c0a685..d184f67647f 100644 --- a/source/reference/operator/aggregation/trunc.txt +++ b/source/reference/operator/aggregation/trunc.txt @@ -80,7 +80,7 @@ Definition fifth digit left of the decimal. This exceeds the number of digits left of the decimal and returns ``0``. - - If ```` resolves to ``0``, :expression:`trunc` + - If ```` resolves to ``0``, :expression:`$trunc` truncates all digits to the right of the decimal and returns the whole integer value. diff --git a/source/reference/operator/aggregation/type.txt b/source/reference/operator/aggregation/type.txt index 300a16a8e05..3426045599f 100644 --- a/source/reference/operator/aggregation/type.txt +++ b/source/reference/operator/aggregation/type.txt @@ -30,7 +30,9 @@ Definition The argument can be any valid :ref:`expression `. -.. seealso:: +.. seealso:: + + - :expression:`$isNumber` - checks if the argument is a number. *New in MongoDB 4.4* - :query:`$type (Query) <$type>` - filters fields based on BSON type. diff --git a/source/reference/operator/aggregation/unionWith.txt b/source/reference/operator/aggregation/unionWith.txt index ec7bf1b7b55..da4181d741f 100644 --- a/source/reference/operator/aggregation/unionWith.txt +++ b/source/reference/operator/aggregation/unionWith.txt @@ -431,7 +431,7 @@ that lists the yearly sales quantity per item: ... - The :pipeline:`$group` stage groups by the ``item`` field and uses - :expression:`$sum` to calculate the yearly total sales quantity per ``item``: + :group:`$sum` to calculate the yearly total sales quantity per ``item``: .. code-block:: javascript :copyable: false diff --git a/source/reference/operator/aggregation/week.txt b/source/reference/operator/aggregation/week.txt index 9434af28049..41cecdb28e8 100644 --- a/source/reference/operator/aggregation/week.txt +++ b/source/reference/operator/aggregation/week.txt @@ -111,7 +111,7 @@ Example Consider a ``sales`` collection with the following document: -.. class:: copyable-code + .. code-block:: javascript { @@ -125,7 +125,7 @@ Consider a ``sales`` collection with the following document: The following aggregation uses the :expression:`$week` and other date operators to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 15 diff --git a/source/reference/operator/aggregation/year.txt b/source/reference/operator/aggregation/year.txt index 3ec22f73f47..cbaf023208d 100644 --- a/source/reference/operator/aggregation/year.txt +++ b/source/reference/operator/aggregation/year.txt @@ -106,7 +106,7 @@ Example Consider a ``sales`` collection with the following documents: -.. class:: copyable-code + .. code-block:: javascript { @@ -120,7 +120,7 @@ Consider a ``sales`` collection with the following documents: The following aggregation uses the :expression:`$year` and other date operators to break down the ``date`` field: -.. class:: copyable-code + .. code-block:: javascript :emphasize-lines: 6 diff --git a/source/reference/operator/meta/comment.txt b/source/reference/operator/meta/comment.txt index 3c70597fcf8..18d21530ee6 100644 --- a/source/reference/operator/meta/comment.txt +++ b/source/reference/operator/meta/comment.txt @@ -26,4 +26,6 @@ $comment :method:`db.collection.update()`, use the :query:`$comment` query operator instead of the meta-operator. -.. seealso:: :query:`$comment` query operator +.. seealso:: + + :query:`$comment` query operator diff --git a/source/reference/operator/meta/query.txt b/source/reference/operator/meta/query.txt index ec42cb9e986..ec9e95b2f78 100644 --- a/source/reference/operator/meta/query.txt +++ b/source/reference/operator/meta/query.txt @@ -49,7 +49,9 @@ Definition db.documents.find( { "$query": { query: { a: 1 } } } ) - .. seealso:: For more information about queries in MongoDB see + .. seealso:: + + For more information about queries in MongoDB see :doc:`/tutorial/query-documents`, :method:`db.collection.find()`, and `Getting Started with MongoDB `_. diff --git a/source/reference/operator/meta/showDiskLoc.txt b/source/reference/operator/meta/showDiskLoc.txt index 05a2e5eee63..8c798921139 100644 --- a/source/reference/operator/meta/showDiskLoc.txt +++ b/source/reference/operator/meta/showDiskLoc.txt @@ -26,7 +26,7 @@ $showDiskLoc } The :binary:`~bin.mongo` shell provides the - :method:`cursor.showDiskLoc()` method for :operator:`$showDiskLoc`: + ``cursor.showDiskLoc()`` method for :operator:`$showDiskLoc`: .. code-block:: javascript diff --git a/source/reference/operator/projection.txt b/source/reference/operator/projection.txt index 64555535b09..7634958956f 100644 --- a/source/reference/operator/projection.txt +++ b/source/reference/operator/projection.txt @@ -32,7 +32,7 @@ Projection Operators - Projects the first element in an array that matches the specified :projection:`$elemMatch` condition. - * - :projection:`$meta` + * - :expression:`$meta` - Projects the available per-document metadata. diff --git a/source/reference/operator/projection/elemMatch.txt b/source/reference/operator/projection/elemMatch.txt index b671c8ff61b..9b2ab309788 100644 --- a/source/reference/operator/projection/elemMatch.txt +++ b/source/reference/operator/projection/elemMatch.txt @@ -2,7 +2,9 @@ $elemMatch (projection) ======================= -.. seealso:: :doc:`/reference/operator/query/elemMatch` +.. seealso:: + + :doc:`/reference/operator/query/elemMatch` .. default-domain:: mongodb diff --git a/source/reference/operator/projection/positional.txt b/source/reference/operator/projection/positional.txt index f28407fb342..7d2b7333274 100644 --- a/source/reference/operator/projection/positional.txt +++ b/source/reference/operator/projection/positional.txt @@ -28,7 +28,7 @@ Definition See the aggregation operator :expression:`$filter` to return an array with only those elements that match the specified condition. - .. admonition:: Disambiguation + .. see:: Disambiguation To specify an array element to update, see the :doc:`positional $ operator for updates diff --git a/source/reference/operator/projection/slice.txt b/source/reference/operator/projection/slice.txt index 44797632247..1c269f8a9e6 100644 --- a/source/reference/operator/projection/slice.txt +++ b/source/reference/operator/projection/slice.txt @@ -18,7 +18,7 @@ Definition The :projection:`$slice` projection operator specifies the number of elements in an array to return in the query result. - .. admonition:: Disambiguation + .. see:: Disambiguation For information on limiting the size of an array during an update with :update:`$push`, see the :update:`$slice` modifier instead. @@ -122,7 +122,9 @@ Path Collision: ``$slice`` of an Array and Embedded Fields .. |findoperation| replace:: :method:`find ` and :method:`findAndModify ` -.. seealso:: :ref:`find-projection` +.. seealso:: + + :ref:`find-projection` Examples -------- diff --git a/source/reference/operator/query.txt b/source/reference/operator/query.txt index 5ca0878f8ce..f718ac42005 100644 --- a/source/reference/operator/query.txt +++ b/source/reference/operator/query.txt @@ -21,9 +21,7 @@ Query Selectors Comparison ~~~~~~~~~~ -.. only:: website - - .. include:: /includes/fact-comparison-order.rst +.. include:: /includes/fact-comparison-order.rst .. list-table:: :widths: 30,70 @@ -75,8 +73,6 @@ Comparison Logical ~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -111,8 +107,6 @@ Logical Element ~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -139,8 +133,6 @@ Element Evaluation ~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -183,8 +175,6 @@ Evaluation Geospatial ~~~~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -236,8 +226,6 @@ Geospatial Array ~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -268,8 +256,6 @@ Array Bitwise ~~~~~~~ -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -306,8 +292,6 @@ Bitwise Projection Operators -------------------- -.. only:: website - .. list-table:: :widths: 30,70 :header-rows: 1 @@ -324,7 +308,7 @@ Projection Operators - Projects the first element in an array that matches the specified :projection:`$elemMatch` condition. - * - :projection:`$meta` + * - :expression:`$meta` - Projects the document's score assigned during :query:`$text` operation. @@ -343,8 +327,6 @@ Projection Operators Miscellaneous Operators ----------------------- -.. only:: website - .. list-table:: :widths: 25,75 :header-rows: 1 diff --git a/source/reference/operator/query/bitsAllClear.txt b/source/reference/operator/query/bitsAllClear.txt index 744cf519dfa..189e54d4dea 100644 --- a/source/reference/operator/query/bitsAllClear.txt +++ b/source/reference/operator/query/bitsAllClear.txt @@ -83,7 +83,7 @@ BinData Bitmask ~~~~~~~~~~~~~~~ The following query uses the :query:`$bitsAllClear` operator to test -whether field ``a`` has bits clear at positions `2` and `4` +whether field ``a`` has bits clear at positions ``2`` and ``4`` (the binary representation of ``BinData(0, "ID==")`` is ``00010100``. .. code-block:: javascript diff --git a/source/reference/operator/query/bitsAllSet.txt b/source/reference/operator/query/bitsAllSet.txt index fec376109f4..24a31738320 100644 --- a/source/reference/operator/query/bitsAllSet.txt +++ b/source/reference/operator/query/bitsAllSet.txt @@ -82,7 +82,7 @@ BinData Bitmask ~~~~~~~~~~~~~~~ The following query uses the :query:`$bitsAllSet` operator to test -whether field ``a`` has bits set at positions `4` and `5` +whether field ``a`` has bits set at positions ``4`` and ``5`` (the binary representation of ``BinData(0, "MC==")`` is ``00110000``). .. code-block:: javascript diff --git a/source/reference/operator/query/bitsAnyClear.txt b/source/reference/operator/query/bitsAnyClear.txt index 6ccefa27b34..7856493d26f 100644 --- a/source/reference/operator/query/bitsAnyClear.txt +++ b/source/reference/operator/query/bitsAnyClear.txt @@ -84,7 +84,7 @@ The query matches the following documents: BinData Bitmask ~~~~~~~~~~~~~~~ The following query uses the :query:`$bitsAnyClear` operator to test -whether field ``a`` has any bits clear at positions `4` and `5` +whether field ``a`` has any bits clear at positions ``4`` and ``5`` (the binary representation of ``BinData(0, "MC==")`` is ``00110000``). .. code-block:: javascript diff --git a/source/reference/operator/query/bitsAnySet.txt b/source/reference/operator/query/bitsAnySet.txt index ee661853977..ec5801b8efd 100644 --- a/source/reference/operator/query/bitsAnySet.txt +++ b/source/reference/operator/query/bitsAnySet.txt @@ -83,7 +83,7 @@ BinData Bitmask ~~~~~~~~~~~~~~~ The following query uses the :query:`$bitsAnySet` operator to test -whether field ``a`` has any bits set at positions `4`, and `5` +whether field ``a`` has any bits set at positions ``4``, and ``5`` (the binary representation of ``BinData(0, "MC==")`` is ``00110000``). .. code-block:: javascript diff --git a/source/reference/operator/query/comment.txt b/source/reference/operator/query/comment.txt index 148723a616c..4c113b1b684 100644 --- a/source/reference/operator/query/comment.txt +++ b/source/reference/operator/query/comment.txt @@ -87,7 +87,7 @@ parameters: db.setProfilingLevel(2, 0) -The comment for the previous :method:`db.records.find()` example +The comment for the previous ``db.records.find()`` example then appears as follows in the :doc:`MongoDB log `: @@ -119,4 +119,6 @@ The following example uses the :query:`$comment` operator in the { $group : { _id: { $mod: [ "$x", 2 ] }, total: { $sum: "$x" } } } ] ) -.. seealso:: :operator:`$comment` +.. seealso:: + + :operator:`$comment` diff --git a/source/reference/operator/query/eq.txt b/source/reference/operator/query/eq.txt index 9911914520a..2f66d3c39b7 100644 --- a/source/reference/operator/query/eq.txt +++ b/source/reference/operator/query/eq.txt @@ -132,7 +132,9 @@ Both queries match the following document: { _id: 1, item: { name: "ab", code: "123" }, qty: 15, tags: [ "A", "B", "C" ] } -.. seealso:: :ref:`Query Embedded Documents ` +.. seealso:: + + :ref:`Query Embedded Documents ` Array Element Equals a Value ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -160,7 +162,9 @@ Both queries match the following documents: { _id: 3, item: { name: "ij", code: "456" }, qty: 25, tags: [ "A", "B" ] } { _id: 4, item: { name: "xy", code: "456" }, qty: 30, tags: [ "B", "A" ] } -.. seealso:: :query:`$elemMatch`, :ref:`Query Arrays ` +.. seealso:: + + :query:`$elemMatch`, :ref:`Query Arrays ` .. [#match-string-value] The query will also match documents where the value of the ``tags`` field is the string ``"B"``. diff --git a/source/reference/operator/query/exists.txt b/source/reference/operator/query/exists.txt index ab40dcd99c7..cd24733c62d 100644 --- a/source/reference/operator/query/exists.txt +++ b/source/reference/operator/query/exists.txt @@ -22,11 +22,13 @@ Definition ``null``. If ```` is false, the query returns only the documents that do not contain the field. [#type0]_ - MongoDB `$exists` does **not** correspond to SQL operator + MongoDB ``$exists`` does **not** correspond to SQL operator ``exists``. For SQL ``exists``, refer to the :query:`$in` operator. -.. seealso:: :query:`$nin`, :query:`$in`, and +.. seealso:: + + :query:`$nin`, :query:`$in`, and :ref:`faq-developers-query-for-nulls`. .. [#type0] @@ -110,5 +112,7 @@ The results consist of those documents that do not contain the field .. include:: /includes/extracts/4.2-changes-type-0.rst -.. seealso:: :doc:`/tutorial/query-for-null-fields` +.. seealso:: + + :doc:`/tutorial/query-for-null-fields` diff --git a/source/reference/operator/query/near.txt b/source/reference/operator/query/near.txt index 31f2077f9b3..402c394168f 100644 --- a/source/reference/operator/query/near.txt +++ b/source/reference/operator/query/near.txt @@ -94,7 +94,10 @@ Sort Operation .. |geo-operation| replace:: :query:`$near` -.. seealso:: :ref:`3.0-geo-near-compatibility` +.. seealso:: + + :ref:`3.0-geo-near-compatibility` + Examples -------- diff --git a/source/reference/operator/query/nearSphere.txt b/source/reference/operator/query/nearSphere.txt index ca4b42c65b8..29e83d315eb 100644 --- a/source/reference/operator/query/nearSphere.txt +++ b/source/reference/operator/query/nearSphere.txt @@ -75,7 +75,10 @@ Definition If you use longitude and latitude for legacy coordinates, specify the longitude first, then latitude. - .. seealso:: :ref:`3.0-geo-near-compatibility` + .. seealso:: + + :ref:`3.0-geo-near-compatibility` + Behavior -------- diff --git a/source/reference/operator/query/not.txt b/source/reference/operator/query/not.txt index e03a3371c4b..5d86f33ffad 100644 --- a/source/reference/operator/query/not.txt +++ b/source/reference/operator/query/not.txt @@ -79,7 +79,7 @@ data types like arrays. - driver language's regular expression objects For example, the following PyMongo query uses Python's - :py:meth:`re.compile()` method to compile a regular + ``re.compile()`` method to compile a regular expression: .. code-block:: python diff --git a/source/reference/operator/query/or.txt b/source/reference/operator/query/or.txt index bb89db44b7e..885c1e2032e 100644 --- a/source/reference/operator/query/or.txt +++ b/source/reference/operator/query/or.txt @@ -79,10 +79,10 @@ error. ``$or`` and GeoSpatial Queries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:operator:`$or` supports :doc:`geospatial clauses +:query:`$or` supports :doc:`geospatial clauses ` with the following exception for the near clause (near clause includes :query:`$nearSphere` and -:query:`$near`). :operator:`$or` cannot contain a near clause with any +:query:`$near`). :query:`$or` cannot contain a near clause with any other clause. ``$or`` and Sort Operations @@ -112,5 +112,8 @@ Nested ``$or`` Clauses You may nest :query:`$or` operations. -.. seealso:: :query:`$and`, :method:`~db.collection.find()`, +.. seealso:: + + :query:`$and`, :method:`~db.collection.find()`, + :method:`~cursor.sort()`, :query:`$in` diff --git a/source/reference/operator/query/text.txt b/source/reference/operator/query/text.txt index 828171bc244..95fa4cbfdbd 100644 --- a/source/reference/operator/query/text.txt +++ b/source/reference/operator/query/text.txt @@ -149,17 +149,17 @@ restrictions also apply. .. include:: /includes/list-text-search-restrictions-in-agg.rst .. |text-object| replace:: :query:`$text` -.. |meta-object| replace:: :projection:`$meta` projection operator +.. |meta-object| replace:: :expression:`$meta` projection operator .. |sort-object| replace:: :method:`~cursor.sort()` method ``$search`` Field ~~~~~~~~~~~~~~~~~ In the ``$search`` field, specify a string of words that the -:query:`text` operator parses and uses to query the :doc:`text index +:query:`$text` operator parses and uses to query the :doc:`text index `. -The :query:`text` operator treats most punctuation +The :query:`$text` operator treats most punctuation in the string as delimiters, except a hyphen-minus (``-``) that negates term or an escaped double quotes ``\"`` that specifies a phrase. @@ -380,39 +380,21 @@ The following examples assume a collection ``articles`` that has a Populate the collection with the following documents: -.. only:: (not latex) - - .. code-block:: javascript - - db.articles.insert( - [ - { _id: 1, subject: "coffee", author: "xyz", views: 50 }, - { _id: 2, subject: "Coffee Shopping", author: "efg", views: 5 }, - { _id: 3, subject: "Baking a cake", author: "abc", views: 90 }, - { _id: 4, subject: "baking", author: "xyz", views: 100 }, - { _id: 5, subject: "Café Con Leche", author: "abc", views: 200 }, - { _id: 6, subject: "Сырники", author: "jkl", views: 80 }, - { _id: 7, subject: "coffee and cream", author: "efg", views: 10 }, - { _id: 8, subject: "Cafe con Leche", author: "xyz", views: 10 } - ] - ) - -.. only:: latex +.. code-block:: javascript - .. code-block:: javascript + db.articles.insert( + [ + { _id: 1, subject: "coffee", author: "xyz", views: 50 }, + { _id: 2, subject: "Coffee Shopping", author: "efg", views: 5 }, + { _id: 3, subject: "Baking a cake", author: "abc", views: 90 }, + { _id: 4, subject: "baking", author: "xyz", views: 100 }, + { _id: 5, subject: "Café Con Leche", author: "abc", views: 200 }, + { _id: 6, subject: "Сырники", author: "jkl", views: 80 }, + { _id: 7, subject: "coffee and cream", author: "efg", views: 10 }, + { _id: 8, subject: "Cafe con Leche", author: "xyz", views: 10 } + ] + ) - db.articles.insert( - [ - { _id: 1, subject: "coffee", author: "xyz", views: 50 }, - { _id: 2, subject: "Coffee Shopping", author: "efg", views: 5 }, - { _id: 3, subject: "Baking a cake", author: "abc", views: 90 }, - { _id: 4, subject: "baking", author: "xyz", views: 100 }, - { _id: 5, subject: "Café Con Leche", author: "abc", views: 200 }, - { _id: 6, subject: "", author: "jkl", views: 80 }, - { _id: 7, subject: "coffee and cream", author: "efg", views: 10 }, - { _id: 8, subject: "Cafe con Leche", author: "xyz", views: 10 } - ] - ) Search for a Single Word ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -484,7 +466,9 @@ This query returns documents that contain the phrase ``coffee shop``: { "_id" : 2, "subject" : "Coffee Shopping", "author" : "efg", "views" : 5 } -.. seealso:: :ref:`text-operator-phrases` +.. seealso:: + + :ref:`text-operator-phrases` Exclude Documents That Contain a Term ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -541,7 +525,9 @@ The :query:`$text` expression can also accept the language by name, ``spanish``. See :ref:`text-search-languages` for the supported languages. -.. seealso:: :ref:`text-operator-case-sensitivity` +.. seealso:: + + :ref:`text-operator-case-sensitivity` Case and Diacritic Insensitive Search ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -556,40 +542,21 @@ see :ref:`text Index Case Insensitivity ` and :ref:`text Index Diacritic Insensitivity `. -.. only:: (not latex) - - The following query performs a case and diacritic insensitive text - search for the terms ``сы́рники`` or ``CAFÉS``: - - .. code-block:: javascript - - db.articles.find( { $text: { $search: "сы́рники CAFÉS" } } ) - - Using the version 3 ``text`` index, the query matches the following - documents. - - .. code-block:: javascript +The following query performs a case and diacritic insensitive text +search for the terms ``сы́рники`` or ``CAFÉS``: - { "_id" : 6, "subject" : "Сырники", "author" : "jkl", "views" : 80 } - { "_id" : 5, "subject" : "Café Con Leche", "author" : "abc", "views" : 200 } - { "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz", "views" : 10 } - -.. only:: latex - - The following query performs a case and diacritic insensitive text - search for the term ``CAFÉS``: - - .. code-block:: javascript +.. code-block:: javascript - db.articles.find( { $text: { $search: "CAFÉS" } } ) + db.articles.find( { $text: { $search: "сы́рники CAFÉS" } } ) - Using the version 3 ``text`` index, the query matches the following - documents. +Using the version 3 ``text`` index, the query matches the following +documents. - .. code-block:: javascript +.. code-block:: javascript - { "_id" : 5, "subject" : "Café Con Leche", "author" : "abc", "views" : 200 } - { "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz", "views" : 10 } + { "_id" : 6, "subject" : "Сырники", "author" : "jkl", "views" : 80 } + { "_id" : 5, "subject" : "Café Con Leche", "author" : "abc", "views" : 200 } + { "_id" : 8, "subject" : "Cafe con Leche", "author" : "xyz", "views" : 10 } With the previous versions of the ``text`` index, the query would not match any document. @@ -749,7 +716,7 @@ Return the Text Search Score ```````````````````````````` The following query performs a text search for the term ``cake`` and -uses the :projection:`$meta` operator in the projection document to +uses the :expression:`$meta` operator in the projection document to append the relevance score to each matching document: .. code-block:: javascript @@ -767,7 +734,9 @@ contains the document's relevance score: { "_id" : 3, "subject" : "Baking a cake", "author" : "abc", "views" : 90, "score" : 0.75 } -.. seealso:: :projection:`$meta` +.. seealso:: + + :expression:`$meta` .. _ex-sort-text-search-score: @@ -778,7 +747,7 @@ Sort by Text Search Score - In MongoDB 4.2 and earlier, to sort by the text score, include the - **same** :projection:`$meta` expression in **both** the projection + **same** :expression:`$meta` expression in **both** the projection document and the sort expression. The following query searches for the term ``coffee`` and sorts the results by the descending score: @@ -792,7 +761,9 @@ Sort by Text Search Score The query returns the matching documents sorted by descending score. -.. seealso:: :projection:`$meta` +.. seealso:: + + :expression:`$meta` .. _ex-sort-limit-two: @@ -813,7 +784,9 @@ matching documents: { score: { $meta: "textScore" } } ).sort( { score: { $meta: "textScore" } } ).limit(2) -.. seealso:: :projection:`$meta` +.. seealso:: + + :expression:`$meta` .. _text-operator-example-compound-sort: @@ -832,4 +805,6 @@ ascending ``date``, then descending text search score: { score: { $meta: "textScore" } } ).sort( { date: 1, score: { $meta: "textScore" } } ) -.. seealso:: :doc:`/tutorial/text-search-in-aggregation` +.. seealso:: + + :doc:`/tutorial/text-search-in-aggregation` diff --git a/source/reference/operator/query/type.txt b/source/reference/operator/query/type.txt index e4bf3164afb..8bdab8a3b26 100644 --- a/source/reference/operator/query/type.txt +++ b/source/reference/operator/query/type.txt @@ -48,7 +48,9 @@ Definition :ref:`document-type-available-types` describes the BSON types and their corresponding numeric and string aliases. -.. seealso:: +.. seealso:: + + - :expression:`$isNumber` - checks if the argument is a number. *New in MongoDB 4.4* - :expression:`$type (Aggregation) <$type>` - returns the BSON type of the argument. @@ -113,7 +115,10 @@ For examples, see :ref:`query-type-examples`. .. include:: /includes/extracts/4.2-changes-type-0.rst -.. seealso:: :expression:`$isNumber` *New in MongoDB 4.4* +.. seealso:: + + :expression:`$isNumber` *New in MongoDB 4.4* + MinKey and MaxKey ~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/operator/query/where.txt b/source/reference/operator/query/where.txt index 03e663aa8df..7d3e32a5a23 100644 --- a/source/reference/operator/query/where.txt +++ b/source/reference/operator/query/where.txt @@ -38,8 +38,8 @@ Definition with scope for :query:`$where` has been deprecated since MongoDB 4.2.1. -.. admonition:: Aggregation Alternatives Preferred - :class: note +.. note:: Aggregation Alternatives Preferred + Starting in MongoDB 3.6, the :query:`$expr` operator allows the use of :ref:`aggregation expressions ` within the diff --git a/source/reference/operator/update/addToSet.txt b/source/reference/operator/update/addToSet.txt index e1118964ec8..3377b648ab0 100644 --- a/source/reference/operator/update/addToSet.txt +++ b/source/reference/operator/update/addToSet.txt @@ -159,6 +159,9 @@ field. .. include:: /includes/example-addToSet-each.rst -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()`, :update:`$push`, :update:`$pull` diff --git a/source/reference/operator/update/bit.txt b/source/reference/operator/update/bit.txt index cc53b3d0a7e..3b9542e98ca 100644 --- a/source/reference/operator/update/bit.txt +++ b/source/reference/operator/update/bit.txt @@ -157,5 +157,8 @@ And the updated document has the following value for ``expdata``: { "_id" : 3, "expdata" : NumberLong(4) } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/currentDate.txt b/source/reference/operator/update/currentDate.txt index d67b5649f1e..0155d12bd2d 100644 --- a/source/reference/operator/update/currentDate.txt +++ b/source/reference/operator/update/currentDate.txt @@ -154,7 +154,9 @@ The query should return the following document: } } -.. seealso:: +.. seealso:: + + - :method:`db.collection.updateOne()`, - :method:`db.collection.updateMany()`, diff --git a/source/reference/operator/update/inc.txt b/source/reference/operator/update/inc.txt index b49bbeaf9dd..4c426cee03a 100644 --- a/source/reference/operator/update/inc.txt +++ b/source/reference/operator/update/inc.txt @@ -82,5 +82,8 @@ The updated document would resemble: } } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/max.txt b/source/reference/operator/update/max.txt index b3e285ee18b..5a5befc3ac4 100644 --- a/source/reference/operator/update/max.txt +++ b/source/reference/operator/update/max.txt @@ -116,5 +116,8 @@ The operation does *not* update the ``dateExpired`` field: dateExpired: ISODate("2013-10-01T16:38:16.163Z") } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/min.txt b/source/reference/operator/update/min.txt index ecf055b3bc6..48823174acd 100644 --- a/source/reference/operator/update/min.txt +++ b/source/reference/operator/update/min.txt @@ -117,5 +117,8 @@ The operation updates the ``dateEntered`` field: dateExpired: ISODate("2013-10-01T16:38:16Z") } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/mul.txt b/source/reference/operator/update/mul.txt index d33233deff3..a04f3e91232 100644 --- a/source/reference/operator/update/mul.txt +++ b/source/reference/operator/update/mul.txt @@ -174,5 +174,8 @@ The value in the ``price`` field is of type :ref:`shell-type-long`. See :ref:`Multiplication Type Conversion Rules ` for details. -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/pop.txt b/source/reference/operator/update/pop.txt index 5da54553eb4..afac9d004d7 100644 --- a/source/reference/operator/update/pop.txt +++ b/source/reference/operator/update/pop.txt @@ -87,5 +87,8 @@ removed from its ``scores`` array: { _id: 1, scores: [ 9 ] } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/position.txt b/source/reference/operator/update/position.txt index db80a79f32d..244cf1a0a8a 100644 --- a/source/reference/operator/update/position.txt +++ b/source/reference/operator/update/position.txt @@ -153,8 +153,6 @@ add ``90`` at the position two places before the last element, and then the :update:`$each` array, the last added element is in the specified position from the end. -.. cssclass:: copyable-code - .. code-block:: javascript db.students.update( diff --git a/source/reference/operator/update/positional-all.txt b/source/reference/operator/update/positional-all.txt index e48ee8224df..0a3a6b51b74 100644 --- a/source/reference/operator/update/positional-all.txt +++ b/source/reference/operator/update/positional-all.txt @@ -55,8 +55,6 @@ For example, the following upsert operation, which uses ``$[]`` in the update document, specifies an exact equality match condition on the array field: -.. cssclass:: copyable-code - .. code-block:: javascript db.collection.update( @@ -121,8 +119,6 @@ To increment all elements in the ``grades`` array by ``10`` for all documents in the collection, use the all positional :update:`$[]` operator: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.update( @@ -183,8 +179,6 @@ Consider a collection ``students2`` with the following documents: To modify the value of the ``std`` field for all elements in the ``grades`` array, use the positional :update:`$[]` operator: -.. cssclass:: copyable-code - .. code-block:: javascript db.students2.update( @@ -229,8 +223,6 @@ To increment all elements in the ``grades`` array by ``10`` for all documents **except** those with the value ``100`` in the ``grades`` array, use the all positional :update:`$[]` operator: -.. cssclass:: copyable-code - .. code-block:: javascript db.results.update( @@ -262,8 +254,6 @@ arrays. Create a collection ``students3`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.students3.insert([ @@ -288,7 +278,9 @@ nested ``grades.questions`` array, regardless of ``type``: { arrayFilters: [ { "score": { $gte: 8 } } ], multi: true} ) -.. seealso:: +.. seealso:: + + - :update:`$[\]`, diff --git a/source/reference/operator/update/positional-filtered.txt b/source/reference/operator/update/positional-filtered.txt index 32f6e69681e..22f5a5134b9 100644 --- a/source/reference/operator/update/positional-filtered.txt +++ b/source/reference/operator/update/positional-filtered.txt @@ -63,8 +63,6 @@ For example, the following upsert operation, which uses ``$[]`` in the update document, specifies an exact equality match condition on the array field: -.. cssclass:: copyable-code - .. code-block:: javascript db.collection.update( @@ -138,8 +136,6 @@ To update all elements that are greater than or equal to ``100`` in the ``grades`` array, use the filtered positional operator :update:`$[\]` with the :ref:`3.6-arrayFilters`: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.update( @@ -206,8 +202,6 @@ To modify the value of the ``mean`` field for all elements in the use the positional ``$[]`` operator and :ref:`3.6-arrayFilters`: -.. cssclass:: copyable-code - .. code-block:: javascript db.students2.update( @@ -269,8 +263,6 @@ To modify the value of the ``std`` field for all elements in the ``80`` and the ``std`` is greater than or equal to ``5``, use the positional ``$[]`` operator and :ref:`3.6-arrayFilters`: -.. cssclass:: copyable-code - .. code-block:: javascript db.students2.update( @@ -340,11 +332,9 @@ Consider a collection ``alumni`` with the following documents: } To modify all elements in the ``degrees`` array that do not have -``"level": "Bachelor"``, use the positional :update:`[]` +``"level": "Bachelor"``, use the positional :update:`$[\]` operation with the :query:`$ne` query operator: -.. cssclass:: copyable-code - .. code-block:: javascript db.alumni.update( @@ -456,7 +446,9 @@ nested ``grades.questions`` array, regardless of ``type``: { arrayFilters: [ { "score": { $gte: 8 } } ], multi: true} ) -.. seealso:: +.. seealso:: + + - :update:`$[]` diff --git a/source/reference/operator/update/positional.txt b/source/reference/operator/update/positional.txt index 05cc017f582..cc161f7a2fa 100644 --- a/source/reference/operator/update/positional.txt +++ b/source/reference/operator/update/positional.txt @@ -19,7 +19,7 @@ Definition an array to update without explicitly specifying the position of the element in the array. - .. admonition:: Disambiguation + .. see:: Disambiguation - To project, or return, an array element from a read operation, see the :projection:`$` projection operator instead. @@ -102,8 +102,6 @@ Update Values in an Array Create a collection ``students`` with the following documents: -.. cssclass:: copyable-code - .. code-block:: javascript db.students.insert([ @@ -120,8 +118,6 @@ not know the position of the element in the array: You must include the array field as part of the ``query`` document. -.. cssclass:: copyable-code - .. code-block:: javascript db.students.updateOne( @@ -180,8 +176,6 @@ condition: You must include the array field as part of the ``query`` document. -.. cssclass:: copyable-code - .. code-block:: javascript db.students.updateOne( @@ -254,5 +248,8 @@ criteria, namely the second embedded document in the array: ] } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()`, :query:`$elemMatch()` diff --git a/source/reference/operator/update/pull.txt b/source/reference/operator/update/pull.txt index bd41e5143ec..e5e0e70fdb6 100644 --- a/source/reference/operator/update/pull.txt +++ b/source/reference/operator/update/pull.txt @@ -236,5 +236,8 @@ with ``q`` equal to ``2`` and ``a`` greater than or equal to ``8``: ] } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/pullAll.txt b/source/reference/operator/update/pullAll.txt index d6ac5191582..845068bf122 100644 --- a/source/reference/operator/update/pullAll.txt +++ b/source/reference/operator/update/pullAll.txt @@ -60,5 +60,8 @@ and ``5`` removed from the ``scores`` field: { "_id" : 1, "scores" : [ 2, 1 ] } -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/push.txt b/source/reference/operator/update/push.txt index 2c8affbb453..2cfe81315e5 100644 --- a/source/reference/operator/update/push.txt +++ b/source/reference/operator/update/push.txt @@ -82,7 +82,7 @@ When used with modifiers, the :update:`$push` operator has the form: { $push: { : { : , ... }, ... } } -The processing of the :update:`push` operation with modifiers occur +The processing of the :update:`$push` operation with modifiers occur in the following order, regardless of the order in which the modifiers appear: @@ -124,5 +124,8 @@ Use ``$push`` Operator with Multiple Modifiers .. include:: /includes/example-push-with-multiple-modifiers.rst -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/rename.txt b/source/reference/operator/update/rename.txt index 9e976f69d8b..fdbf62036ec 100644 --- a/source/reference/operator/update/rename.txt +++ b/source/reference/operator/update/rename.txt @@ -162,5 +162,8 @@ the following: This operation does nothing because there is no field named ``wife``. -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/set.txt b/source/reference/operator/update/set.txt index 7da40e8f6a4..3b2a6a1a0a4 100644 --- a/source/reference/operator/update/set.txt +++ b/source/reference/operator/update/set.txt @@ -133,5 +133,8 @@ element (array index of ``0``) of the ``ratings`` array. For additional update operators for arrays, see :doc:`/reference/operator/update-array`. -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/setOnInsert.txt b/source/reference/operator/update/setOnInsert.txt index 811fe8544c0..cee0f168821 100644 --- a/source/reference/operator/update/setOnInsert.txt +++ b/source/reference/operator/update/setOnInsert.txt @@ -74,5 +74,8 @@ If the :method:`db.collection.update()` with :ref:`upsert: true performs an update, applying the :update:`$set` operation but ignoring the :update:`$setOnInsert` operation. -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/operator/update/unset.txt b/source/reference/operator/update/unset.txt index 41452fdad73..4560a1d0f20 100644 --- a/source/reference/operator/update/unset.txt +++ b/source/reference/operator/update/unset.txt @@ -61,5 +61,8 @@ where the field ``sku`` has a value of ``unknown``. { $unset: { quantity: "", instock: "" } } ) -.. seealso:: :method:`db.collection.update()`, +.. seealso:: + + :method:`db.collection.update()`, + :method:`db.collection.findAndModify()` diff --git a/source/reference/parameters.txt b/source/reference/parameters.txt index cec4c81d62e..0ef3053790f 100644 --- a/source/reference/parameters.txt +++ b/source/reference/parameters.txt @@ -578,9 +578,10 @@ Authentication Parameters db.adminCommand( { setParameter: 1, sslMode: "preferSSL" } ) - .. seealso:: :parameter:`tlsMode` + .. seealso:: + -.. parameter:: tlsMode + :parameter:`tlsMode`.. parameter:: tlsMode .. versionadded:: 4.2 @@ -602,9 +603,10 @@ Authentication Parameters .. include:: /includes/extracts/ssl-facts-see-more.rst - .. seealso:: :parameter:`sslMode` + .. seealso:: + -.. parameter:: tlsOCSPStaplingTimeoutSecs + :parameter:`sslMode`.. parameter:: tlsOCSPStaplingTimeoutSecs .. versionadded:: 4.4 @@ -893,9 +895,10 @@ General Parameters mongos --setParameter connPoolMaxShardedInUseConnsPerHost=100 - .. seealso:: :parameter:`connPoolMaxShardedConnsPerHost` + .. seealso:: + -.. parameter:: shardedConnPoolIdleTimeoutMinutes + :parameter:`connPoolMaxShardedConnsPerHost`.. parameter:: shardedConnPoolIdleTimeoutMinutes .. versionadded:: 3.6.3 @@ -913,9 +916,10 @@ General Parameters mongos --setParameter shardedConnPoolIdleTimeoutMinutes=10 - .. seealso:: :parameter:`connPoolMaxShardedConnsPerHost` + .. seealso:: + -.. parameter:: connPoolMaxConnsPerHost + :parameter:`connPoolMaxShardedConnsPerHost`.. parameter:: connPoolMaxConnsPerHost *Default*: 200 @@ -961,9 +965,10 @@ General Parameters mongod --setParameter connPoolMaxInUseConnsPerHost=100 - .. seealso:: :parameter:`connPoolMaxConnsPerHost` + .. seealso:: + -.. parameter:: globalConnPoolIdleTimeoutMinutes + :parameter:`connPoolMaxConnsPerHost`.. parameter:: globalConnPoolIdleTimeoutMinutes .. versionadded:: 3.6.3 @@ -982,10 +987,10 @@ General Parameters mongos --setParameter globalConnPoolIdleTimeoutMinutes=10 - .. seealso:: :parameter:`connPoolMaxShardedConnsPerHost` + .. seealso:: -.. parameter:: cursorTimeoutMillis + :parameter:`connPoolMaxShardedConnsPerHost`.. parameter:: cursorTimeoutMillis *Default*: 600000 (10 minutes) @@ -1175,7 +1180,10 @@ General Parameters See :ref:`4.4-rel-notes-tcp-fast-open` for more information on MongoDB TFO support. - .. seealso:: `RFC7413 `__. + .. seealso:: + + `RFC7413 `__. + .. parameter:: tcpFastOpenClient @@ -1210,7 +1218,10 @@ General Parameters See :ref:`4.4-rel-notes-tcp-fast-open` for more information on MongoDB TFO support. - .. seealso:: `RFC7413 `__. + .. seealso:: + + `RFC7413 `__. + .. parameter:: tcpFastOpenQueueSize @@ -1436,17 +1447,12 @@ General Parameters Specifies the tcmalloc release rate (`TCMALLOC_RELEASE_RATE `_). Per https://gperftools.github.io/gperftools/tcmalloc.html#runtime - TCMALLOC_RELEASE_RATE is described as: - - .. epigraph:: - - Rate at which we release unused memory to the system, via - madvise(MADV_DONTNEED), on systems that support it. Zero means we - never release memory back to the system. Increase this flag to - return memory faster; decrease it to return memory slower. - Reasonable rates are in the range [0,10]. - - -- https://gperftools.github.io/gperftools/tcmalloc.html#runtime + TCMALLOC_RELEASE_RATE is described as the "Rate at which we release + unused memory to the system, via + madvise(MADV_DONTNEED), on systems that support it. Zero means we + never release memory back to the system. Increase this flag to + return memory faster; decrease it to return memory slower. + Reasonable rates are in the range [0,10]." To modify the release rate during runtime, you can use the :dbcommand:`setParameter` command; for example: @@ -1665,7 +1671,10 @@ Logging Parameters db.adminCommand( { setParameter: 1, quiet: 1 } ) - .. seealso:: :setting:`systemLog.quiet` + .. seealso:: + + :setting:`systemLog.quiet` + .. parameter:: redactClientLogData @@ -1696,7 +1705,10 @@ Logging Parameters db.adminCommand( { setParameter: 1, redactClientLogData : true } ) - .. seealso:: :setting:`security.redactClientLogData` + .. seealso:: + + :setting:`security.redactClientLogData` + .. parameter:: traceExceptions @@ -1713,7 +1725,10 @@ Logging Parameters db.adminCommand( { setParameter: 1, traceExceptions: true } ) - .. seealso:: :setting:`systemLog.traceAllExceptions` + .. seealso:: + + :setting:`systemLog.traceAllExceptions` + .. parameter:: suppressNoTLSPeerCertificateWarning @@ -1922,8 +1937,8 @@ Logical Session .. parameter:: logicalSessionRefreshMillis - .. admonition:: Availability - :class: note + .. note:: Availability + New in version 4.0.4 (and version 3.6.9). @@ -1958,8 +1973,8 @@ Logical Session *Default*: 30 - .. admonition:: For testing purposes only - :class: warning + .. warning:: For testing purposes only + This parameter is intended for testing purposes only and not for production use. @@ -2059,13 +2074,10 @@ Logical Session mongod --setParameter TransactionRecordMinimumLifetimeMinutes=20 - .. seealso:: :parameter:`localLogicalSessionTimeoutMinutes` - + .. seealso:: -Replication Parameters -~~~~~~~~~~~~~~~~~~~~~~ -.. parameter:: enableFlowControl + :parameter:`localLogicalSessionTimeoutMinutes`.. parameter:: enableFlowControl .. versionadded:: 4.2 @@ -2410,32 +2422,24 @@ Replication Parameters the primary mirrors reads to each electable secondary at the specified sampling rate. - .. only:: (not man) - - Valid values are: - - .. list-table:: - :widths: 40 60 - - * - ``0.0`` - - Turns off mirroring. - - * - ``1.0`` + Valid values are: - - The primary mirrors all :ref:`operations that supports - mirroring ` to - each electable secondary. + .. list-table:: + :widths: 40 60 - * - Number between ``0.0`` and ``1.0`` (exclusive) + * - ``0.0`` + - Turns off mirroring. - - The primary randomly samples each electable secondary - at the specified rate to be sent mirrored reads. + * - ``1.0`` - .. only:: man + - The primary mirrors all :ref:`operations that supports + mirroring ` to + each electable secondary. - Valid values are greater than or equal to ``0.0`` and less - than or equal to ``1.0``. Value of ``0.0`` turns off mirroring. + * - Number between ``0.0`` and ``1.0`` (exclusive) + - The primary randomly samples each electable secondary + at the specified rate to be sent mirrored reads. For example, given a replica set with a primary and two electable secondaries and a sampling rate of ``0.10``, the @@ -2631,11 +2635,10 @@ Sharding Parameters mongod --setParameter enableFinerGrainedCatalogCacheRefresh=true mongos --setParameter enableFinerGrainedCatalogCacheRefresh=true - .. seealso:: - - - :ref:`sharding-background` + .. seealso:: - - :serverstatus:`shardingStatistics.catalogCache` + + - :serverstatus:`shardingStatistics.catalogCache` .. parameter:: maxTimeMSForHedgedReads @@ -2727,8 +2730,8 @@ Sharding Parameters db.adminCommand( { setParameter: 1, readHedgingMode: "off" } ) - .. seealso:: - + .. seealso:: + - :ref:`mongos-hedged-reads` - :parameter:`maxTimeMSForHedgedReads` @@ -2922,9 +2925,10 @@ Sharding Parameters pools, where ``n`` is the number of cores. See :parameter:`taskExecutorPoolSize`. - .. seealso:: :parameter:`ShardingTaskExecutorPoolMinSize` + .. seealso:: + -.. parameter:: ShardingTaskExecutorPoolMinSize + :parameter:`ShardingTaskExecutorPoolMinSize`.. parameter:: ShardingTaskExecutorPoolMinSize Type: integer @@ -2965,10 +2969,10 @@ Sharding Parameters pools, where ``n`` is the number of cores. See :parameter:`taskExecutorPoolSize`. - .. seealso:: - :parameter:`ShardingTaskExecutorPoolMaxSize` - - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartup` + .. seealso:: + -.. parameter:: ShardingTaskExecutorPoolRefreshRequirementMS + - :parameter:`ShardingTaskExecutorPoolMaxSize`.. parameter:: ShardingTaskExecutorPoolRefreshRequirementMS Type: integer @@ -3262,10 +3266,10 @@ Sharding Parameters :setting:`setParameter` configuration file setting or the :option:`--setParameter ` command line option. - .. seealso:: - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartupWaitMS` - - :parameter:`ShardingTaskExecutorPoolMinSize` + .. seealso:: + -.. parameter:: warmMinConnectionsInShardingTaskExecutorPoolOnStartupWaitMS + - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartupWaitMS`.. parameter:: warmMinConnectionsInShardingTaskExecutorPoolOnStartupWaitMS .. versionadded:: 4.4 @@ -3287,10 +3291,10 @@ Sharding Parameters :setting:`setParameter` configuration file setting or the :option:`--setParameter ` command line option. - .. seealso:: - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartup` - - :parameter:`ShardingTaskExecutorPoolMinSize` + .. seealso:: + -.. parameter:: migrateCloneInsertionBatchDelayMS + - :parameter:`warmMinConnectionsInShardingTaskExecutorPoolOnStartup`.. parameter:: migrateCloneInsertionBatchDelayMS .. versionadded:: 4.0.5 @@ -3639,8 +3643,8 @@ WiredTiger Parameters .. parameter:: wiredTigerMaxCacheOverflowSizeGB - .. admonition:: Deprecated in MongoDB 4.4 - :class: note + .. note:: Deprecated in MongoDB 4.4 + MongoDB deprecates the ``wiredTigerMaxCacheOverflowSizeGB`` parameter. The parameter has no effect starting in MongoDB 4.4. @@ -3702,7 +3706,10 @@ WiredTiger Parameters db.adminCommand( { setParameter: 1, wiredTigerConcurrentReadTransactions: } ) - .. seealso:: :serverstatus:`wiredTiger.concurrentTransactions` + .. seealso:: + + :serverstatus:`wiredTiger.concurrentTransactions` + .. parameter:: wiredTigerConcurrentWriteTransactions @@ -3717,7 +3724,10 @@ WiredTiger Parameters db.adminCommand( { setParameter: 1, wiredTigerConcurrentWriteTransactions: } ) - .. seealso:: :serverstatus:`wiredTiger.concurrentTransactions` + .. seealso:: + + :serverstatus:`wiredTiger.concurrentTransactions` + .. parameter:: wiredTigerEngineRuntimeConfig @@ -3775,7 +3785,9 @@ Auditing Parameters .. include:: /includes/fact-auditAuthorizationSuccess-performance-impact.rst -.. seealso:: :dbcommand:`getParameter` +.. seealso:: + + :dbcommand:`getParameter` Transaction Parameters ~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/privilege-actions.txt b/source/reference/privilege-actions.txt index 052920beea6..508969b5a2c 100644 --- a/source/reference/privilege-actions.txt +++ b/source/reference/privilege-actions.txt @@ -322,7 +322,7 @@ Deployment Management Actions .. authaction:: authSchemaUpgrade - User can perform the :dbcommand:`authSchemaUpgrade` command. Apply this + User can perform the ``authSchemaUpgrade`` command. Apply this action to the ``cluster`` resource. .. authaction:: cleanupOrphaned @@ -378,7 +378,7 @@ Deployment Management Actions .. authaction:: storageDetails - User can perform the :dbcommand:`storageDetails` command. Apply this + User can perform the deprecated ``storageDetails`` command. Apply this action to database or collection resources. Change Stream Actions @@ -419,7 +419,7 @@ Replication Actions .. authaction:: replSetHeartbeat - User can perform the :dbcommand:`replSetHeartbeat` command. Apply this + User can perform the deprecated ``replSetHeartbeat`` command. Apply this action to the ``cluster`` resource. .. authaction:: replSetStateChange @@ -431,7 +431,7 @@ Replication Actions .. authaction:: resync - User can perform the :dbcommand:`resync` command. Apply this action to + User can perform the deprecated ``resync`` command. Apply this action to the ``cluster`` resource. Sharding Actions @@ -460,8 +460,8 @@ Sharding Actions rewrite can be confusing for those commands that are admin commands but affect other databases, such as this one. - .. admonition:: Applicable Resources - :class: note + .. note:: Applicable Resources + The action can apply to either: @@ -578,7 +578,7 @@ Server Administration Actions .. authaction:: closeAllDatabases - User can perform the :dbcommand:`closeAllDatabases` command. Apply this + User can perform the deprecated ``closeAllDatabases`` command. Apply this action to the ``cluster`` resource. .. authaction:: collMod @@ -689,7 +689,7 @@ Server Administration Actions .. authaction:: touch - User can perform the :dbcommand:`touch` command. Apply this action to + User can perform the deprecated ``touch`` command. Apply this action to the ``cluster`` resource. Session Actions @@ -723,7 +723,9 @@ Session Actions :dbcommand:`killAllSessionsByPattern` command. Apply this action to the ``cluster`` resource. - .. seealso:: :authaction:`impersonate` + .. seealso:: + + :authaction:`impersonate` Free Monitoring Actions ----------------------- @@ -782,11 +784,11 @@ Diagnostic Actions .. authaction:: indexStats - User can perform the :dbcommand:`indexStats` command. Apply this action + User can perform the ``indexStats`` command. Apply this action to database or collection resources. .. versionchanged:: 3.0 - MongoDB 3.0 removes the :dbcommand:`indexStats` command. + MongoDB 3.0 removes the ``indexStats`` command. .. authaction:: listDatabases diff --git a/source/reference/program.txt b/source/reference/program.txt index 51e7bffe537..216f8c0a548 100644 --- a/source/reference/program.txt +++ b/source/reference/program.txt @@ -65,8 +65,8 @@ dump files from the :binary:`~bin.mongod` instances, while dumps. :binary:`~bin.bsondump` converts BSON dump files into :term:`JSON`. -.. admonition:: Tools documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: Tools documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for these tools have been migrated to `docs.mongodb.com/database-tools @@ -108,8 +108,8 @@ a :binary:`~bin.mongod` instance into JSON, CSV, or TSV. type fidelity. Therefore you cannot use :binary:`~bin.mongoimport` and :binary:`~bin.mongoexport` for round-trip import and export operations. -.. admonition:: Tools documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: Tools documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for these tools have been migrated to `docs.mongodb.com/database-tools @@ -148,8 +148,8 @@ Diagnostic Tools provide diagnostic information related to the current operation of a :binary:`~bin.mongod` instance. -.. admonition:: Tools documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: Tools documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for these tools have been migrated to `docs.mongodb.com/database-tools @@ -197,8 +197,8 @@ GridFS :binary:`~bin.mongofiles` provides a command-line interact to a MongoDB :term:`GridFS` storage system. -.. admonition:: Tools documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: Tools documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for this tool has been migrated to `docs.mongodb.com/database-tools @@ -227,7 +227,7 @@ MongoDB Compass .. versionadded:: 3.6 - MongoDB is packaged with an :binary:`~bin.install_compass` script, which + MongoDB is packaged with an ``install_compass`` script, which is a platform-specific installer for :ref:`MongoDB Compass Community Edition `. diff --git a/source/reference/program/bsondump.txt b/source/reference/program/bsondump.txt index 29847e392e3..ee278c68a75 100644 --- a/source/reference/program/bsondump.txt +++ b/source/reference/program/bsondump.txt @@ -17,8 +17,8 @@ for reading the output files generated by :binary:`~bin.mongodump`. .. important:: :binary:`~bin.bsondump` is a diagnostic tool for inspecting BSON files, not a tool for data ingestion or other application use. -.. admonition:: ``bsondump`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``bsondump`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``bsondump`` has migrated to: diff --git a/source/reference/program/install_compass.txt b/source/reference/program/install_compass.txt index 32be320b91b..53e5705dd89 100644 --- a/source/reference/program/install_compass.txt +++ b/source/reference/program/install_compass.txt @@ -17,7 +17,7 @@ Synopsis -------- -:binary:`~bin.install_compass` (``Install-Compass`` in Windows) is a +``install_compass`` (``Install-Compass`` in Windows) is a platform-specific installation script for :ref:`MongoDB Compass `. @@ -57,14 +57,14 @@ is packaged with the download for each platform. 1. Change to the ``bin`` directory under the MongoDB Server download directory: - .. class:: copyable-code + .. code-block:: sh cd /bin 2. Install |compass| using the ``install_compass`` script: - .. class:: copyable-code + .. code-block:: sh ./install_compass @@ -81,14 +81,14 @@ From the Windows Command Prompt: 1. Change to the ``bin`` directory under the MongoDB Server download directory: - .. class:: copyable-code + .. code-block:: none cd \bin 2. Install |compass| using the ``install_compass`` script: - .. class:: copyable-code + .. code-block:: none powershell .\Install-Compass.ps1 diff --git a/source/reference/program/mongo.txt b/source/reference/program/mongo.txt index 463d1b67bdd..c21052b43a6 100644 --- a/source/reference/program/mongo.txt +++ b/source/reference/program/mongo.txt @@ -18,11 +18,10 @@ :depth: 1 :class: singlecol -.. only:: html - .. meta:: - :description: The mongo shell command man page. - :keywords: mongo, mongodb, man page, mongo process, mongo shell +.. meta:: + :description: The mongo shell command man page. + :keywords: mongo, mongodb, man page, mongo process, mongo shell Description ----------- @@ -92,7 +91,7 @@ Syntax Options ------- -.. admonition:: Starting in version 4.2 +.. versionchanged:: 4.2 - .. include:: /includes/extracts/4.2-changes-options-tls-ssl.rst @@ -469,7 +468,9 @@ TLS Options .. include:: /includes/fact-tls-1.0.rst -.. see:: :doc:`/tutorial/configure-ssl` for full +.. see:: + + :doc:`/tutorial/configure-ssl` for full documentation of MongoDB's support. .. option:: --tls @@ -1022,7 +1023,7 @@ Files time value to attempt to create a unique file. :file:`%TEMP%\mongo_edit{}.js` - Created by :binary:`~bin.mongo.exe` on Windows when editing a file. If + Created by :binary:`mongo.exe ` on Windows when editing a file. If the file exists, :binary:`~bin.mongo` will append an integer from ``1`` to ``10`` to the time value to attempt to create a unique file. @@ -1386,7 +1387,9 @@ rather than provided on the command-line, use the following form: mongo script-file.js -u -p -.. seealso:: :method:`isInteractive()` +.. seealso:: + + :method:`isInteractive()` Use :option:`--eval ` to Execute JavaScript Code ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/reference/program/mongod.txt b/source/reference/program/mongod.txt index dd07cbeb458..6f1815f83e3 100644 --- a/source/reference/program/mongod.txt +++ b/source/reference/program/mongod.txt @@ -31,7 +31,9 @@ for testing: In common operation, use the :doc:`configuration file options ` to control the behavior of your database. -.. seealso:: :ref:`conf-file-command-line-mapping` +.. seealso:: + + :ref:`conf-file-command-line-mapping` .. note:: @@ -44,7 +46,7 @@ your database. Options ------- -.. admonition:: Starting in version 4.2 +.. note:: - .. include:: /includes/extracts/4.2-changes-options-tls-ssl.rst @@ -52,12 +54,12 @@ Options .. |tlsClusterCAFile| replace:: :option:`--tlsClusterCAFile ` -.. admonition:: Starting in version 4.4 +.. versionchanged:: 4.4 - MongoDB removes the ``--noIndexBuildRetry`` command-line option and the corresponding ``storage.indexBuildRetry`` option. -.. admonition:: Starting in version 5.0 +.. note:: Starting in version 5.0 - MongoDB removes the ``--serviceExecutor`` command-line option and the corresponding ``net.serviceExecutor`` configuration option. @@ -498,8 +500,8 @@ Core Options specified, the process does not create a PID file. This option is generally only useful in combination with the :option:`--fork` option. - .. admonition:: Linux - :class: note + .. note:: Linux + On Linux, PID file management is generally the responsibility of your distro's init system: usually a service file in the ``/etc/init.d`` @@ -508,8 +510,8 @@ Core Options systems. For more information, please see the respective :doc:`Installation Guide ` for your operating system. - .. admonition:: macOS - :class: note + .. note:: macOS + On macOS, PID file management is generally handled by ``brew``. Only use the :option:`--pidfilepath` option if you are not using ``brew`` on your macOS system. @@ -779,7 +781,10 @@ Core Options unzip timezonedb-latest.zip mongod --timeZoneInfo timezonedb-2017b/ - .. seealso:: :setting:`processManagement.timeZoneInfo`. + .. seealso:: + + :setting:`processManagement.timeZoneInfo`. + @@ -1610,8 +1615,8 @@ WiredTiger Options .. option:: --wiredTigerMaxCacheOverflowFileSizeGB - .. admonition:: Deprecated in MongoDB 4.4 - :class: note + .. note:: Deprecated in MongoDB 4.4 + MongoDB deprecates the ``--wiredTigerMaxCacheOverflowFileSizeGB`` option. The option has no effect starting in MongoDB 4.4. @@ -1951,7 +1956,9 @@ Sharded Cluster Options TLS Options ~~~~~~~~~~~ -.. see:: :doc:`/tutorial/configure-ssl` for full +.. see:: + + :doc:`/tutorial/configure-ssl` for full documentation of MongoDB's support. .. option:: --tlsMode @@ -2413,7 +2420,9 @@ TLS Options Members of replica sets and sharded clusters must speak at least one protocol in common. - .. seealso:: :ref:`ssl-disallow-protocols` + .. seealso:: + + :ref:`ssl-disallow-protocols` .. option:: --tlsFIPSMode @@ -2439,7 +2448,9 @@ SSL Options (Deprecated) SSL options. The SSL protocol is deprecated and MongoDB supports TLS 1.0 and later. -.. see:: :doc:`/tutorial/configure-ssl` for full +.. see:: + + :doc:`/tutorial/configure-ssl` for full documentation of MongoDB's support. .. option:: --sslOnNormalPorts @@ -2893,7 +2904,9 @@ SSL Options (Deprecated) Members of replica sets and sharded clusters must speak at least one protocol in common. - .. seealso:: :ref:`ssl-disallow-protocols` + .. seealso:: + + :ref:`ssl-disallow-protocols` .. option:: --sslFIPSMode @@ -2938,7 +2951,9 @@ Profiler Options For :binary:`~bin.mongod` instances, :option:`--slowms` affects the diagnostic log and, if enabled, the profiler. - .. seealso:: :doc:`/tutorial/manage-the-database-profiler` + .. seealso:: + + :doc:`/tutorial/manage-the-database-profiler` .. _cli-mongod-profiler-slowOpSampleRate: @@ -3226,7 +3241,9 @@ Encryption Key Management Options .. include:: /includes/fact-enterprise-only-admonition.rst - .. seealso:: :ref:`kmip-master-key-rotation` + .. seealso:: + + :ref:`kmip-master-key-rotation` diff --git a/source/reference/program/mongodump.txt b/source/reference/program/mongodump.txt index 7a4375d38f2..2f13de3e5b8 100644 --- a/source/reference/program/mongodump.txt +++ b/source/reference/program/mongodump.txt @@ -4,8 +4,7 @@ .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -19,8 +18,8 @@ from either :binary:`~bin.mongod` or :binary:`~bin.mongos` instances; i.e. can export data from standalone, replica set, and sharded cluster deployments. -.. admonition:: ``mongodump`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``mongodump`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``mongodump`` has migrated to: diff --git a/source/reference/program/mongoexport.txt b/source/reference/program/mongoexport.txt index 7329d637bd1..66022c8b108 100644 --- a/source/reference/program/mongoexport.txt +++ b/source/reference/program/mongoexport.txt @@ -4,8 +4,7 @@ .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -16,8 +15,8 @@ :binary:`~bin.mongoexport` is a command-line tool that produces a JSON or CSV export of data stored in a MongoDB instance. -.. admonition:: ``mongoexport`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``mongoexport`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``mongoexport`` has migrated to: diff --git a/source/reference/program/mongofiles.txt b/source/reference/program/mongofiles.txt index 32ca1b1c82f..98823f84a35 100644 --- a/source/reference/program/mongofiles.txt +++ b/source/reference/program/mongofiles.txt @@ -15,8 +15,8 @@ stored in your MongoDB instance in :term:`GridFS` objects from the command line. It is particularly useful as it provides an interface between objects stored in your file system and GridFS. -.. admonition:: ``mongofiles`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``mongofiles`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``mongofiles`` has migrated to: diff --git a/source/reference/program/mongoimport.txt b/source/reference/program/mongoimport.txt index b1d9c4eacba..f47d6f53ad0 100644 --- a/source/reference/program/mongoimport.txt +++ b/source/reference/program/mongoimport.txt @@ -15,8 +15,8 @@ The :binary:`~bin.mongoimport` tool imports content from an export created by :binary:`~bin.mongoexport`, or potentially, another third-party export tool. -.. admonition:: ``mongoimport`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``mongoimport`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``mongoimport`` has migrated to: diff --git a/source/reference/program/mongoreplay.txt b/source/reference/program/mongoreplay.txt index f997f94a339..3ec135dd039 100644 --- a/source/reference/program/mongoreplay.txt +++ b/source/reference/program/mongoreplay.txt @@ -13,8 +13,7 @@ that you can use to inspect and record commands sent to a MongoDB instance, and then replay those commands back onto another host at a later time. -.. admonition:: ``mongoreplay`` removed from MongoDB Packaging - :class: note +.. note:: ``mongoreplay`` removed from MongoDB Packaging Starting in MongoDB 4.4, ``mongoreplay`` is removed from MongoDB packaging. ``mongoreplay`` and its related documentation are migrated diff --git a/source/reference/program/mongorestore.txt b/source/reference/program/mongorestore.txt index 7681646df95..6d212b1680c 100644 --- a/source/reference/program/mongorestore.txt +++ b/source/reference/program/mongorestore.txt @@ -14,8 +14,8 @@ The :binary:`~bin.mongorestore` program loads data from either a binary database dump created by :binary:`~bin.mongodump` or the standard input into a :binary:`~bin.mongod` or :binary:`~bin.mongos` instance. -.. admonition:: ``mongorestore`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``mongorestore`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``mongorestore`` has migrated to: diff --git a/source/reference/program/mongos.txt b/source/reference/program/mongos.txt index 6c247835a3d..047f2c1f029 100644 --- a/source/reference/program/mongos.txt +++ b/source/reference/program/mongos.txt @@ -50,18 +50,19 @@ Considerations Options ------- -.. seealso:: :ref:`conf-file-command-line-mapping` +.. seealso:: + :ref:`conf-file-command-line-mapping` -.. admonition:: Starting in version 4.2 +.. note:: - .. include:: /includes/extracts/4.2-changes-options-tls-ssl.rst - .. include:: /includes/extracts/4.2-changes-options-tlsClusterCAFile.rst -.. admonition:: Starting in version 5.0 +.. note:: - - MongoDB removes the ``--serviceExecutor`` command-line option and the + - MongoDB 5.0 removes the ``--serviceExecutor`` command-line option and the corresponding ``net.serviceExecutor`` configuration option. .. |tlsClusterCAFile| replace:: :option:`--tlsClusterCAFile ` @@ -418,8 +419,8 @@ Core Options specified, the process does not create a PID file. This option is generally only useful in combination with the :option:`--fork` option. - .. admonition:: Linux - :class: note + .. note:: Linux + On Linux, PID file management is generally the responsibility of your distro's init system: usually a service file in the ``/etc/init.d`` @@ -428,8 +429,8 @@ Core Options systems. For more information, please see the respective :doc:`Installation Guide ` for your operating system. - .. admonition:: macOS - :class: note + .. note:: macOS + On macOS, PID file management is generally handled by ``brew``. Only use the :option:`--pidfilepath` option if you are not using ``brew`` on your macOS system. @@ -667,8 +668,8 @@ Sharded Cluster Options Specifies the ping time, in milliseconds, that :binary:`~bin.mongos` uses to determine which secondary replica set members to pass read operations from clients. The default value of ``15`` corresponds to - the default value in all of the client :ecosystem:`drivers - `. + the default value in all of the client :driver:`drivers + `. When :binary:`~bin.mongos` receives a request that permits reads to :term:`secondary` members, the :binary:`~bin.mongos` will: @@ -1077,7 +1078,9 @@ TLS Options Members of replica sets and sharded clusters must speak at least one protocol in common. - .. seealso:: :ref:`ssl-disallow-protocols` + .. seealso:: + + :ref:`ssl-disallow-protocols` .. option:: --tlsFIPSMode @@ -1102,7 +1105,9 @@ SSL Options (Deprecated) instead, as they have identical functionality to the SSL options. The SSL protocol is deprecated and MongoDB supports TLS 1.0 and later. -.. see:: :doc:`/tutorial/configure-ssl` for full +.. see:: + + :doc:`/tutorial/configure-ssl` for full documentation of MongoDB's support. .. option:: --sslOnNormalPorts @@ -1494,7 +1499,9 @@ SSL Options (Deprecated) Members of replica sets and sharded clusters must speak at least one protocol in common. - .. seealso:: :ref:`ssl-disallow-protocols` + .. seealso:: + + :ref:`ssl-disallow-protocols` .. option:: --sslFIPSMode @@ -1628,11 +1635,11 @@ Profiler Options The *slow* operation time threshold, in milliseconds. Operations that run for longer than this threshold are considered *slow*. - When :setting:`~param.logLevel` is set to ``0``, MongoDB records *slow* + When :parameter:`logLevel` is set to ``0``, MongoDB records *slow* operations to the diagnostic log at a rate determined by :setting:`~operationProfiling.slowOpSampleRate`. - At higher :setting:`~param.logLevel` settings, all operations appear + At higher :parameter:`logLevel` settings, all operations appear in the diagnostic log regardless of their latency. For :binary:`~bin.mongos` instances, affects the diagnostic diff --git a/source/reference/program/mongostat.txt b/source/reference/program/mongostat.txt index e58e7711122..c61638dc837 100644 --- a/source/reference/program/mongostat.txt +++ b/source/reference/program/mongostat.txt @@ -17,8 +17,8 @@ similar to the UNIX/Linux file system utility ``vmstat``, but provides data regarding :binary:`~bin.mongod` and :binary:`~bin.mongos` instances. -.. admonition:: ``mongostat`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``mongostat`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``mongostat`` has migrated to: diff --git a/source/reference/program/mongotop.txt b/source/reference/program/mongotop.txt index 0a0a1e97428..a8e792f1139 100644 --- a/source/reference/program/mongotop.txt +++ b/source/reference/program/mongotop.txt @@ -15,8 +15,8 @@ MongoDB instance :binary:`~bin.mongod` spends reading and writing data. :binary:`~bin.mongotop` provides statistics on a per-collection level. By default, :binary:`~bin.mongotop` returns values every second. -.. admonition:: ``mongotop`` documentation migrated to `MongoDB Database Tools `__ - :class: note +.. note:: ``mongotop`` documentation migrated to `MongoDB Database Tools `__ + Starting in MongoDB 4.4, the documentation for ``mongotop`` has migrated to: diff --git a/source/reference/read-concern-available.txt b/source/reference/read-concern-available.txt index 16eadc7dfc1..dffec2ac9c7 100644 --- a/source/reference/read-concern-available.txt +++ b/source/reference/read-concern-available.txt @@ -1,11 +1,6 @@ .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger - -.. class:: hidden - - .. readconcern:: "available" +.. .. class:: hidden ============================ Read Concern ``"available"`` @@ -15,13 +10,15 @@ Read Concern ``"available"`` :description: Using read concern available returns data with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back). Read concern available can return orphan documents. :keywords: read concern, available read concern, read isolation +.. readconcern:: "available" + .. versionadded:: 3.6 -A query with read concern `"available"` returns data from the instance +A query with read concern ``"available"`` returns data from the instance with no guarantee that the data has been written to a majority of the replica set members (i.e. may be rolled back). -Read concern `"available"` is the default for reads against secondaries +Read concern ``"available"`` is the default for reads against secondaries if the reads are not associated with :ref:`causally consistent sessions `. @@ -41,12 +38,14 @@ deployment or a replica set deployment), :readconcern:`"local"` and .. include:: /includes/fact-readConcern-most-recent-data-in-node.rst -.. seealso:: :parameter:`orphanCleanupDelaySecs` +.. seealso:: + + :parameter:`orphanCleanupDelaySecs` Availability ------------ -Read concern :readconcern:`available` is :red:`unavailable for use` +Read concern :readconcern:`"available"` is :red:`unavailable for use` with causally consistent sessions and transactions. diff --git a/source/reference/read-concern-linearizable.txt b/source/reference/read-concern-linearizable.txt index f4ce41db56c..5df04aa80e9 100644 --- a/source/reference/read-concern-linearizable.txt +++ b/source/reference/read-concern-linearizable.txt @@ -1,13 +1,11 @@ .. default-domain:: mongodb -.. class:: hidden - - .. readconcern:: "linearizable" - =============================== Read Concern ``"linearizable"`` =============================== +.. readconcern:: "linearizable" + .. versionadded:: 3.4 The query returns data that reflects all successful @@ -40,7 +38,7 @@ single document. Causally Consistent Sessions ---------------------------- -Read concern :readconcern:`linearizable` is unavailable for use with +Read concern :readconcern:`"linearizable"` is unavailable for use with causally consistent sessions. Aggregation Restriction diff --git a/source/reference/read-concern-local.txt b/source/reference/read-concern-local.txt index c73333484f6..99ce1e31e75 100644 --- a/source/reference/read-concern-local.txt +++ b/source/reference/read-concern-local.txt @@ -1,8 +1,5 @@ .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger - .. class:: hidden .. readconcern:: "local" @@ -32,7 +29,7 @@ Read concern ``"local"`` is the default for: Availability ------------- -Read concern :readconcern:`local` is available for use with or without +Read concern :readconcern:`"local"` is available for use with or without causally consistent sessions and transactions. .. _readconcern-local-txn: diff --git a/source/reference/read-concern-majority.txt b/source/reference/read-concern-majority.txt index 0fd5b2eaa3d..225d35309ed 100644 --- a/source/reference/read-concern-majority.txt +++ b/source/reference/read-concern-majority.txt @@ -1,9 +1,5 @@ .. default-domain:: mongodb -.. class:: hidden - - .. readconcern:: "majority" - =========================== Read Concern ``"majority"`` =========================== @@ -14,6 +10,8 @@ Read Concern ``"majority"`` :depth: 1 :class: singlecol +.. readconcern:: "majority" + For read operations not associated with :doc:`multi-document transactions `, read concern ``"majority"`` guarantees that the data read has been acknowledged by a majority of diff --git a/source/reference/read-concern.txt b/source/reference/read-concern.txt index e66ae6e162c..6facbe2871f 100644 --- a/source/reference/read-concern.txt +++ b/source/reference/read-concern.txt @@ -12,8 +12,7 @@ Read Concern :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + The ``readConcern`` option allows you to control the consistency and isolation properties of the data read from replica sets and replica set @@ -69,7 +68,7 @@ The following read concern levels are available: associated write operations use :writeconcern:`"majority"` write concern. - **Availability:** Read concern :readconcern:`local` is available + **Availability:** Read concern :readconcern:`"local"` is available for use with or without causally consistent sessions and transactions. @@ -85,7 +84,7 @@ The following read concern levels are available: **Default for:** reads against secondaries if the reads are :red:`not` associated with :ref:`causally consistent sessions `. - **Availability:** Read concern :readconcern:`available` is + **Availability:** Read concern :readconcern:`"available"` is :red:`unavailable for use` with causally consistent sessions and transactions. diff --git a/source/reference/replica-configuration.txt b/source/reference/replica-configuration.txt index 8961b4afd0e..6a878abc1cf 100644 --- a/source/reference/replica-configuration.txt +++ b/source/reference/replica-configuration.txt @@ -41,7 +41,7 @@ Replica Set Configuration Fields The name of the replica set. :rsconf:`_id` *must* be identical to the - :setting:`replication.replSetName` or the value of `--replSet` + :setting:`replication.replSetName` or the value of ``--replSet`` specified to :binary:`~bin.mongod` on the command line. .. see:: @@ -108,7 +108,10 @@ Replica Set Configuration Fields config servers. Set to ``true`` if the replica set is for a sharded cluster's config servers. - .. seealso:: :ref:`3.2-rel-notes-sharded-cluster` + .. seealso:: + + :ref:`3.2-rel-notes-sharded-cluster` + .. rsconf:: protocolVersion @@ -122,7 +125,9 @@ Replica Set Configuration Fields longer supports ``protocolVersion: 0``. - .. seealso:: :doc:`/reference/replica-set-protocol-versions` + .. seealso:: + + :doc:`/reference/replica-set-protocol-versions` .. rsconf:: writeConcernMajorityJournalDefault @@ -174,7 +179,9 @@ Replica Set Configuration Fields .. include:: /includes/extracts/transactions-shards-wcmajority-disabled.rst - .. seealso:: :ref:`wc-ack-behavior`, :doc:`/reference/replica-set-protocol-versions` + .. seealso:: + + :ref:`wc-ack-behavior`, :doc:`/reference/replica-set-protocol-versions` ``members`` ~~~~~~~~~~~ @@ -460,7 +467,9 @@ Replica Set Configuration Fields :rsconf:`settings.chainingAllowed` is ``false``, secondaries can replicate only from the :term:`primary`. - .. seealso:: :doc:`/tutorial/manage-chained-replication` + .. seealso:: + + :doc:`/tutorial/manage-chained-replication` .. rsconf:: settings.getLastErrorDefaults @@ -559,7 +568,7 @@ Replica Set Configuration Fields - Lower values result in faster failover, but increased sensitivity to primary node or network slowness or spottiness. - The setting only applies when using :rsconf:`protocolVersion: 1`. + The setting only applies when using :rsconf:`protocolVersion: 1`. .. note:: @@ -590,7 +599,8 @@ Replica Set Configuration Fields writes from clients. Use :dbcommand:`replSetAbortPrimaryCatchUp` to abort the catchup then complete the transition to primary. - The setting only applies when using :rsconf:`protocolVersion: 1`. + The setting only applies when using + :rsconf:`protocolVersion: 1`. .. note:: @@ -637,7 +647,8 @@ Replica Set Configuration Fields .. note:: Setting ``catchUpTakeoverDelayMillis`` to ``-1`` disables - catchup takeover. Setting :rsconf:`catchUpTimeoutMillis` to + catchup takeover. Setting :rsconf:`catchUpTimeoutMillis + ` to ``0`` disables *primary catchup* and consequently also catchup takeover. @@ -657,5 +668,5 @@ Replica Set Configuration Fields The ObjectId associated with the replica set and automatically created during :method:`rs.initiate()` or - :dbcommand:`replSetInitate`. You cannot change the - :setting:`~settings.replicaSetId`. + :dbcommand:`replSetInitiate`. You cannot change the + :rsconf:`~settings.replicaSetId`. diff --git a/source/reference/replication.txt b/source/reference/replication.txt index 293d8da0d06..c2c4f1d685e 100644 --- a/source/reference/replication.txt +++ b/source/reference/replication.txt @@ -147,24 +147,22 @@ Replication Database Commands Replica Set Reference Documentation ----------------------------------- -.. class:: toc +:doc:`/reference/replica-configuration` + Complete documentation of the :term:`replica set` configuration + object returned by :method:`rs.conf()`. - :doc:`/reference/replica-configuration` - Complete documentation of the :term:`replica set` configuration - object returned by :method:`rs.conf()`. +:doc:`/reference/replica-set-protocol-versions` + Reference on the replica set protocol version. - :doc:`/reference/replica-set-protocol-versions` - Reference on the replica set protocol version. +:doc:`/tutorial/troubleshoot-replica-sets` + Replica set trouble shooting guide. - :doc:`/tutorial/troubleshoot-replica-sets` - Replica set trouble shooting guide. +:doc:`/reference/local-database` + Complete documentation of the content of the ``local`` database + that :binary:`~bin.mongod` instances use to support replication. - :doc:`/reference/local-database` - Complete documentation of the content of the ``local`` database - that :binary:`~bin.mongod` instances use to support replication. - - :doc:`/reference/replica-states` - Reference for the replica set member states. +:doc:`/reference/replica-states` + Reference for the replica set member states. .. toctree:: diff --git a/source/reference/security-client-side-query-aggregation-support.txt b/source/reference/security-client-side-query-aggregation-support.txt index 4bed23e19b4..a7ad28fab99 100644 --- a/source/reference/security-client-side-query-aggregation-support.txt +++ b/source/reference/security-client-side-query-aggregation-support.txt @@ -233,7 +233,7 @@ aggregation pipeline stages: - :pipeline:`$replaceRoot` - :pipeline:`$redact` - :pipeline:`$lookup` and :pipeline:`$graphLookup` (*See* - :ref:`csfle-lookup-graphlookup-behavior` *for usage requirements*) + :ref:`csfle-lookup-graphLookup-behavior` *for usage requirements*) Aggregation pipelines operating on collections configured for automatic encryption that specify any other stage return an error. diff --git a/source/reference/security.txt b/source/reference/security.txt index 556cb4da9d2..2e44579d3eb 100644 --- a/source/reference/security.txt +++ b/source/reference/security.txt @@ -155,21 +155,19 @@ Role Management Methods Security Reference Documentation -------------------------------- -.. class:: toc +:doc:`/reference/system-roles-collection` + Describes the content of the collection that stores user-defined + roles. - :doc:`/reference/system-roles-collection` - Describes the content of the collection that stores user-defined - roles. +:doc:`/reference/system-users-collection` + Describes the content of the collection that stores users' + credentials and role assignments. - :doc:`/reference/system-users-collection` - Describes the content of the collection that stores users' - credentials and role assignments. +:doc:`/reference/resource-document` + Describes the resource document for roles. - :doc:`/reference/resource-document` - Describes the resource document for roles. - - :doc:`/reference/privilege-actions` - List of the actions available for privileges. +:doc:`/reference/privilege-actions` + List of the actions available for privileges. .. toctree:: diff --git a/source/reference/server-sessions.txt b/source/reference/server-sessions.txt index a02ac6286cf..0bd0cadc10c 100644 --- a/source/reference/server-sessions.txt +++ b/source/reference/server-sessions.txt @@ -55,4 +55,6 @@ session. If the deployment transitions to authentication without any downtime, any sessions without an owner cannot be used. -.. seealso:: :parameter:`maxSessions` +.. seealso:: + + :parameter:`maxSessions` diff --git a/source/reference/sharding.txt b/source/reference/sharding.txt index 540f5e784d8..c47550d6615 100644 --- a/source/reference/sharding.txt +++ b/source/reference/sharding.txt @@ -287,17 +287,15 @@ The following database commands support :term:`sharded clusters Reference Documentation ----------------------- -.. class:: toc +:doc:`Operational Restrictions ` + Requirement for deploying a sharded cluster - :doc:`Operational Restrictions ` - Requirement for deploying a sharded cluster +:doc:`/tutorial/troubleshoot-sharded-clusters` + Common strategies for troubleshooting sharded cluster deployments. - :doc:`/tutorial/troubleshoot-sharded-clusters` - Common strategies for troubleshooting sharded cluster deployments. - - :doc:`/reference/config-database` - Complete documentation of the content of the ``local`` database - that MongoDB uses to store sharded cluster metadata. +:doc:`/reference/config-database` + Complete documentation of the content of the ``local`` database + that MongoDB uses to store sharded cluster metadata. .. toctree:: diff --git a/source/reference/sql-aggregation-comparison.txt b/source/reference/sql-aggregation-comparison.txt index 30a954c1415..aff92d43a57 100644 --- a/source/reference/sql-aggregation-comparison.txt +++ b/source/reference/sql-aggregation-comparison.txt @@ -59,7 +59,9 @@ terms, functions, and concepts and the corresponding MongoDB For a list of all aggregation pipeline and expression operators, see :doc:`/meta/aggregation-quick-reference`. -.. seealso:: :doc:`/reference/sql-comparison` +.. seealso:: + + :doc:`/reference/sql-comparison` Examples -------- diff --git a/source/reference/system-collections.txt b/source/reference/system-collections.txt index d0be118fc2a..b459866ceae 100644 --- a/source/reference/system-collections.txt +++ b/source/reference/system-collections.txt @@ -1,7 +1,7 @@ -.. index:: collection; system -.. index:: system; collections -.. index:: system; namespace -.. index:: namespace; system + + + + .. _metadata-system-collections: ================== @@ -69,8 +69,8 @@ each database: .. data:: .system.namespaces - .. admonition:: Removed in 4.2 - :class: note + .. note:: Removed in 4.2 + Starting in MongoDB 4.2, ``.system.namespaces`` has been removed (access to the collection has been deprecated since @@ -79,8 +79,8 @@ each database: .. data:: .system.indexes - .. admonition:: Removed in 4.2 - :class: note + .. note:: Removed in 4.2 + Starting in MongoDB 4.2, ``.system.indexes`` has been removed (access to the collection has been deprecated since 3.0). diff --git a/source/reference/system-users-collection.txt b/source/reference/system-users-collection.txt index 4f68275c184..5f36c9abcef 100644 --- a/source/reference/system-users-collection.txt +++ b/source/reference/system-users-collection.txt @@ -78,7 +78,9 @@ Each ``system.users`` document has the following fields: :ref:`authentication-scram` user credentials, the information includes the mechanism, iteration count, and authentication parameters. - .. seealso:: + .. seealso:: + + - :parameter:`scramSHA256IterationCount` diff --git a/source/reference/text-search-languages.txt b/source/reference/text-search-languages.txt index cb91cf761b3..51dbdacf9bf 100644 --- a/source/reference/text-search-languages.txt +++ b/source/reference/text-search-languages.txt @@ -70,11 +70,9 @@ language name: .. |text-obj| replace:: text search -.. note:: +.. include:: /includes/fact-text-search-language-none.rst - .. include:: /includes/fact-text-search-language-none.rst +.. seealso:: -.. include:: /includes/fact-atlas-search-languages.rst - -.. seealso:: :doc:`/tutorial/specify-language-for-text-index` + :doc:`/tutorial/specify-language-for-text-index` diff --git a/source/reference/ulimit.txt b/source/reference/ulimit.txt index c1385a6d594..8e805398965 100644 --- a/source/reference/ulimit.txt +++ b/source/reference/ulimit.txt @@ -133,7 +133,7 @@ grows too high. For this reason, it is extremely important to set *both* ``ulimit`` values to the recommended values. ``ulimit`` will modify both "hard" and "soft" values unless the -:setting:`-H` or :setting:`-S` modifiers are specified when +``-H`` or ``-S`` modifiers are specified when modifying limit values. For many distributions of Linux you can change values by substituting diff --git a/source/reference/write-concern.txt b/source/reference/write-concern.txt index 0c35e95d580..17fc081f4a7 100644 --- a/source/reference/write-concern.txt +++ b/source/reference/write-concern.txt @@ -15,8 +15,7 @@ Write Concern :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + Write concern describes the level of acknowledgment requested from MongoDB for write operations to a standalone :binary:`~bin.mongod` or @@ -174,7 +173,9 @@ available: See :ref:`wc-ack-behavior` for when :binary:`~bin.mongod` instances acknowledge the write. -.. seealso:: +.. seealso:: + + - :doc:`/reference/mongodb-defaults` diff --git a/source/release-notes/2.0.txt b/source/release-notes/2.0.txt index 431c65ee9f1..4f0ff250b05 100644 --- a/source/release-notes/2.0.txt +++ b/source/release-notes/2.0.txt @@ -200,7 +200,7 @@ During normal operation, the set will always chose ``B`` as primary. If ``B`` becomes unavailable, the set will elect ``A`` as primary. For more information, see the -:data:`~local.system.replset.members[n].priority` documentation. +:rsconf:`priority ` documentation. Data-Center Awareness `````````````````````` @@ -227,7 +227,7 @@ For more information, see :doc:`/data-center-awareness`. Drivers may also support tag-aware reads. Instead of specifying ``slaveOk``, you specify ``slaveOk`` with tags indicating which data-centers to read from. For details, see the -:ecosystem:`Drivers ` documentation. +:driver:`Drivers ` documentation. ``w`` : ``majority`` ```````````````````` @@ -321,7 +321,7 @@ New ``ContinueOnError`` Option for Bulk Insert ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Set the ``continueOnError`` option for bulk inserts, in the -:ecosystem:`driver `, so that bulk insert will +:driver:`driver `, so that bulk insert will continue to insert any remaining documents even if an insert fails, as is the case with duplicate key exceptions or network interruptions. The :dbcommand:`getLastError` command will report whether any inserts have failed, not just the diff --git a/source/release-notes/2.2.txt b/source/release-notes/2.2.txt index 844320bcdf1..23cbcf1da24 100644 --- a/source/release-notes/2.2.txt +++ b/source/release-notes/2.2.txt @@ -25,7 +25,7 @@ Synopsis - :binary:`~bin.mongod`, 2.2 is a drop-in replacement for 2.0 and 1.8. -- Check your :ecosystem:`driver ` documentation for +- Check your :driver:`driver ` documentation for information regarding required compatibility upgrades, and always run the recent release of your driver. @@ -522,7 +522,7 @@ MongoDB extended JSON now includes a new ``Timestamp()`` type to represent the Timestamp type that MongoDB uses for timestamps in the :term:`oplog` among other contexts. -This permits tools like :binary:`~bin.mongooplog` and :binary:`~bin.mongodump` +This permits tools like ``mongooplog`` and :binary:`~bin.mongodump` to query for specific timestamps. Consider the following :binary:`~bin.mongodump` operation: @@ -555,7 +555,7 @@ consistency of the user interface for the :binary:`~bin.mongo` shell: Helper to load Server-Side Functions ```````````````````````````````````` -The :method:`db.loadServerScripts()` loads the contents of the current +The ``db.loadServerScripts()`` method loads the contents of the current database's ``system.js`` collection into the current :binary:`~bin.mongo` shell session. See :issue:`SERVER-1651` for more information. @@ -582,9 +582,9 @@ and :option:`mongos --syslog` command line-options. ``touch`` Command ````````````````` -Added the :dbcommand:`touch` command to read the data and/or indexes +Added the ``touch`` command to read the data and/or indexes from a collection into memory. See: :issue:`SERVER-2023` and -:dbcommand:`touch` for more information. +``touch`` for more information. ``indexCounters`` No Longer Report Sampled Data ``````````````````````````````````````````````` @@ -667,11 +667,11 @@ Replica Set Members will not Sync from Members Without Indexes Unless ``buildInd To prevent inconsistency between members of replica sets, if the member of a replica set has -:data:`~local.system.replset.members[n].buildIndexes` set to ``true``, +:rsconf:`buildIndexes ` set to ``true``, other members of the replica set will *not* sync from this member, unless they also have -:data:`~local.system.replset.members[n].buildIndexes` set to -``true``. See :issue:`SERVER-4160` for more information. +:rsconf:`buildIndexes ` set to ``true``. See +:issue:`SERVER-4160` for more information. New Option To Configure Index Pre-Fetching during Replication ````````````````````````````````````````````````````````````` @@ -680,7 +680,7 @@ New Option To Configure Index Pre-Fetching during Replication By default, when replicating options, :term:`secondaries ` will pre-fetch :ref:`indexes` associated with a query to improve replication -throughput in most cases. The :setting:`replication.secondaryIndexPrefetch` setting and +throughput in most cases. The ``replication.secondaryIndexPrefetch`` setting and ```--replIndexPrefetch`` option allow administrators to disable this feature or allow the :binary:`~bin.mongod` to pre-fetch only the index on the ``_id`` field. See :issue:`SERVER-6718` for more information. diff --git a/source/release-notes/2.4-upgrade.txt b/source/release-notes/2.4-upgrade.txt index e9eecd123bb..334fdaba8a9 100644 --- a/source/release-notes/2.4-upgrade.txt +++ b/source/release-notes/2.4-upgrade.txt @@ -231,7 +231,7 @@ operations. :option:`--fork `.) You can upgrade an existing - :binary:`~bin.mongos` instance to 2.4 or you can start a new `mongos` + :binary:`~bin.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 :binary:`~bin.mongos`. diff --git a/source/release-notes/2.4.txt b/source/release-notes/2.4.txt index 6840c7333ff..83ff75d7fdd 100644 --- a/source/release-notes/2.4.txt +++ b/source/release-notes/2.4.txt @@ -18,11 +18,9 @@ engine, security enhancements, and text search (beta) and hashed index. Minor Releases -------------- -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/2.4-changelog + /release-notes/2.4-changelog 2.4.14 -- April 28, 2015 ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -115,7 +113,7 @@ Minor Releases - Increase future compatibility for 2.6 authorization features :issue:`SERVER-11478`. -- Fix :dbcommand:`dbhash` cache issue for config servers +- Fix :dbcommand:`dbHash` cache issue for config servers :issue:`SERVER-11421`. - `All 2.4.8 improvements `_. @@ -323,18 +321,16 @@ Performance Improvements V8 JavaScript Engine ~~~~~~~~~~~~~~~~~~~~ -.. class:: hidden - - .. toctree:: +.. toctree:: - /release-notes/2.4-javascript + /release-notes/2.4-javascript Change default JavaScript engine from SpiderMonkey to V8. The change provides improved concurrency for JavaScript operations, modernized JavaScript implementation, and the removal of non-standard SpiderMonkey features, and affects all JavaScript behavior including the commands :dbcommand:`mapReduce`, :v2.4:`group `, and -:dbcommand:`eval` and the query operator :query:`$where`. +``eval`` and the query operator :query:`$where`. See :doc:`/release-notes/2.4-javascript` for more information about all changes . @@ -431,12 +427,10 @@ more information on platform support. Upgrade Process ~~~~~~~~~~~~~~~ -.. class:: hidden - - .. toctree:: +.. toctree:: - /release-notes/2.4-upgrade - /release-notes/2.4-index-types + /release-notes/2.4-upgrade + /release-notes/2.4-index-types See :doc:`/release-notes/2.4-upgrade` for full upgrade instructions. diff --git a/source/release-notes/2.6-changelog.txt b/source/release-notes/2.6-changelog.txt index ab0b480da33..a661df478de 100644 --- a/source/release-notes/2.6-changelog.txt +++ b/source/release-notes/2.6-changelog.txt @@ -45,7 +45,7 @@ Indexing - :issue:`SERVER-19559` Document growth of "key too large" document makes it disappear from the index - :issue:`SERVER-16348` ``Assertion failure n >= 0 && n < static_cast(_files.size()) src/mongo/db/storage/extent_manager.cpp 109`` -- :issue:`SERVER-13875` \ :method:`~db.collection.ensureIndex()` of ``2dsphere`` index breaks after upgrading to 2.6 (with the new :dbcommand:`createIndex` command) +- :issue:`SERVER-13875` \ :method:`~db.collection.ensureIndex()` of ``2dsphere`` index breaks after upgrading to 2.6 (with the new ``createIndex`` command) Networking ~~~~~~~~~~ @@ -149,7 +149,7 @@ Testing Security ~~~~~~~~ -:issue:`SERVER-16073` Create hidden :setting:`net.ssl.sslCipherConfig` flag +:issue:`SERVER-16073` Create hidden ``net.ssl.sslCipherConfig`` flag Querying ~~~~~~~~ @@ -245,7 +245,7 @@ Build and Packaging Usability ~~~~~~~~~ -:issue:`SERVER-14756` The YAML :setting:`storage.quota.enforced` option is not found +:issue:`SERVER-14756` The YAML ``storage.quota.enforced`` option is not found Testing ~~~~~~~ @@ -326,7 +326,7 @@ Querying Replication ~~~~~~~~~~~ -- :issue:`SERVER-16107` 2.6 :dbcommand:`mongod` crashes with segfault when added to a 2.8 replica set with >= 12 nodes. +- :issue:`SERVER-16107` 2.6 :binary:`~bin.mongod` crashes with segfault when added to a 2.8 replica set with >= 12 nodes. - :issue:`SERVER-15994` ``listIndexes`` and ``listCollections`` can be run on secondaries without slaveOk bit - :issue:`SERVER-15849` do not forward replication progress for nodes that are no longer part of a replica set - :issue:`SERVER-15491` ``SyncSourceFeedback`` can crash due to a ``SocketException`` in ``authenticateInternalUser`` diff --git a/source/release-notes/2.6-compatibility.txt b/source/release-notes/2.6-compatibility.txt index 18eb47eb667..fbe7590b2fb 100644 --- a/source/release-notes/2.6-compatibility.txt +++ b/source/release-notes/2.6-compatibility.txt @@ -36,11 +36,11 @@ Description such documents. - Because :method:`db.collection.reIndex()`, :dbcommand:`compact`, - and :dbcommand:`repairDatabase` drop *all* the indexes from a + and ``repairDatabase`` drop *all* the indexes from a collection and then recreate them sequentially, the error from the index key limit prevents these operations from rebuilding any remaining indexes for the collection and, in the case of the - :dbcommand:`repairDatabase` command, from continuing with the + ``repairDatabase`` command, from continuing with the remainder of the process. Inserts will error: @@ -118,7 +118,7 @@ Description with an invalid or empty key name. - :method:`db.collection.reIndex()`, :dbcommand:`compact`, and - :dbcommand:`repairDatabase` will error if an index exists with an + ``repairDatabase`` will error if an index exists with an invalid or empty key name. - Chunk migration will fail if an index exists with an @@ -289,7 +289,10 @@ Solution :method:`db.collection.aggregate()` to return a document with a ``results`` array to handle cursors instead. -.. seealso:: :ref:`rn-2.6-aggregation-cursor`, +.. seealso:: + + :ref:`rn-2.6-aggregation-cursor`, + :method:`db.collection.aggregate()`, Write Concern Validation @@ -335,7 +338,10 @@ Solution .. include:: /includes/important-upgrade-auth-model-prerequisites.rst -.. seealso:: :ref:`2.6-relnotes-security` +.. seealso:: + + :ref:`2.6-relnotes-security` + .. _ssl-hostname-validation: @@ -393,7 +399,9 @@ Solution "2dsphereIndexVersion" : 1 }`` to create a version 1 index. However, version 1 index cannot use the new GeoJSON geometries. -.. seealso:: :ref:`2dsphere-v2` +.. seealso:: + + :ref:`2dsphere-v2` Log Messages ------------ @@ -601,7 +609,7 @@ Description - ``-1`` to specify descending order for a field, or - - :projection:`$meta` expression to specify sort by the text search + - :expression:`$meta` expression to specify sort by the text search score. Any other value will result in an error. @@ -635,7 +643,10 @@ Description In previous versions, :method:`~cursor.explain()` would have the side effect of clearing the query plan cache for that query shape. -.. seealso:: The :method:`PlanCache() ` reference. +.. seealso:: + + The :method:`PlanCache() ` reference. + Geospatial Changes ~~~~~~~~~~~~~~~~~~ @@ -904,13 +915,13 @@ Replica Set Vote Configuration Validation Description MongoDB now deprecates giving any :term:`replica set` member more than a single vote. During configuration, - :data:`local.system.replset.members[n].votes` should only have a + :rsconf:`members[n].votes` should only have a value of 1 for voting members and 0 for non-voting members. MongoDB treats values other than 1 or 0 as a value of 1 and produces a warning message. Solution - Update :data:`local.system.replset.members[n].votes` with values + Update :rsconf:`members[n].votes` with values other than 1 or 0 to 1 or 0 as appropriate. .. _2.6-time-format-changes: diff --git a/source/release-notes/2.6-upgrade.txt b/source/release-notes/2.6-upgrade.txt index 66bf528c4c6..671007a93ac 100644 --- a/source/release-notes/2.6-upgrade.txt +++ b/source/release-notes/2.6-upgrade.txt @@ -90,7 +90,7 @@ authentication and authorization: - If your application performs CRUD operations on the :data:`.system.users` collection or uses a - :method:`db.addUser()`\ -like method, then you **must** + ``db.addUser()``\ -like method, then you **must** upgrade those drivers (i.e. client libraries) **before** :binary:`~bin.mongod` or :binary:`~bin.mongos` instances. diff --git a/source/release-notes/2.6.txt b/source/release-notes/2.6.txt index 6aebae6bbc1..4806d9adc48 100644 --- a/source/release-notes/2.6.txt +++ b/source/release-notes/2.6.txt @@ -19,11 +19,9 @@ write-operation protocol, and security enhancements. Minor Releases -------------- -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/2.6-changelog + /release-notes/2.6-changelog 2.6.12 -- Mar 24, 2016 ~~~~~~~~~~~~~~~~~~~~~~ @@ -300,7 +298,7 @@ the aggregation pipeline :pipeline:`$match` stage, includes the :query:`$text` operator, which resolves text-search queries. MongoDB 2.6 includes an updated :doc:`text index -` format and deprecates the :dbcommand:`text` +` format and deprecates the ``text`` command. .. _rel-notes-data-modification: @@ -333,7 +331,9 @@ data. - The :update:`$mul` operator for multiplicative increments for insert and update operations. -.. seealso:: :ref:`update-operations-incompatibility` +.. seealso:: + + :ref:`update-operations-incompatibility` .. _rel-notes-write-operations: @@ -353,7 +353,9 @@ The :binary:`~bin.mongo` shell now includes methods to perform bulk-write operations. See :method:`Bulk()` for more information. -.. seealso:: :ref:`write-methods-incompatibility` +.. seealso:: + + :ref:`write-methods-incompatibility` MSI Package for MongoDB Available for Windows ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -405,10 +407,11 @@ Specifically these changes include: an old or malicious client from forcing use of a weak cipher. - MongoDB disables the http interface by default, limiting - :doc:`network exposure `. To enable the - interface, see :setting:`~net.http.enabled`. + :doc:`network exposure `. + +.. seealso:: -.. seealso:: :ref:`authentication-incompatibility`, + :ref:`authentication-incompatibility`, :ref:`ssl-hostname-validation`, and :doc:`/administration/security-checklist`. @@ -475,12 +478,15 @@ Index Build Enhancements command-line option. - :method:`~db.collection.ensureIndex()` now wraps a new - :dbcommand:`createIndex` command. + ``createIndex`` command. - The ``dropDups`` option to :method:`~db.collection.ensureIndex()` - and :dbcommand:`createIndex` is deprecated. + and ``createIndex`` is deprecated. + +.. seealso:: + + :ref:`2.6-index-key-length-incompatibility` -.. seealso:: :ref:`2.6-index-key-length-incompatibility` Enhanced Sharding and Replication Administration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -523,14 +529,14 @@ To use the previous *exact-fit allocation strategy*: :collflag:`usePowerOf2Sizes` set to ``false``. - For all new collections on an entire :binary:`~bin.mongod` instance, - set :parameter:`newCollectionsUsePowerOf2Sizes` to ``false``. + set ``newCollectionsUsePowerOf2Sizes`` to ``false``. New collections include those: created during :ref:`initial sync `, as well as those created by the :binary:`~bin.mongorestore` and :binary:`~bin.mongoimport` tools, by running :binary:`~bin.mongod` with the :option:`--repair ` option, as well as the - :dbcommand:`restoreDatabase` command. + deprecated ``restoreDatabase`` command. See :v2.6:`/core/storage` for more information about MongoDB's storage system. @@ -631,7 +637,10 @@ MongoDB Enterprise has greatly expanded its SNMP support to provide SNMP access to nearly the full range of metrics provided by :method:`db.serverStatus()`. -.. seealso:: :ref:`2.6-snmp-iana-mib-incompatibility` +.. seealso:: + + :ref:`2.6-snmp-iana-mib-incompatibility` + Additional Information ---------------------- @@ -639,11 +648,9 @@ Additional Information Changes Affecting Compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. class:: hidden - - .. toctree:: +.. toctree:: - /release-notes/2.6-compatibility + /release-notes/2.6-compatibility Some changes in 2.6 can affect :doc:`compatibility ` and may require user actions. The @@ -660,13 +667,11 @@ compatibility changes. Upgrade Process ~~~~~~~~~~~~~~~ -.. class:: hidden - - .. toctree:: +.. toctree:: - /release-notes/2.6-upgrade - /release-notes/2.6-upgrade-authorization - /release-notes/2.6-downgrade + /release-notes/2.6-upgrade + /release-notes/2.6-upgrade-authorization + /release-notes/2.6-downgrade See :doc:`/release-notes/2.6-upgrade` for full upgrade instructions. diff --git a/source/release-notes/3.0-changelog.txt b/source/release-notes/3.0-changelog.txt index 0851478fed7..e0d4c5c5729 100644 --- a/source/release-notes/3.0-changelog.txt +++ b/source/release-notes/3.0-changelog.txt @@ -216,7 +216,7 @@ Internal Code and Testing Security ~~~~~~~~ -- :issue:`SERVER-18475` \ :dbcommand:`authSchemaUpgrade` fails when the :data:`system.users ` contains non ``MONGODB-CR`` users +- :issue:`SERVER-18475` \ ``authSchemaUpgrade`` fails when the :data:`system.users ` contains non ``MONGODB-CR`` users - :issue:`SERVER-18312` Upgrade PCRE to latest Querying @@ -225,7 +225,7 @@ Querying - :issue:`SERVER-18364` Ensure non-negation predicates get chosen over negation predicates for multikey index bounds construction - :issue:`SERVER-16265` Add query details to getmore entry in profiler and :method:`db.currentOp()` - :issue:`SERVER-15225` ``CachedPlanStage`` should execute for trial period and re-plan if query performs poorly -- :issue:`SERVER-13875` \ :method:`~db.collection.ensureIndex()` of ``2dsphere`` index breaks after upgrading to 2.6 (with the new :dbcommand:`createIndex` command) +- :issue:`SERVER-13875` \ :method:`~db.collection.ensureIndex()` of ``2dsphere`` index breaks after upgrading to 2.6 (with the new ``createIndex`` command) Replication ~~~~~~~~~~~ @@ -322,14 +322,14 @@ Replication ~~~~~~~~~~~ - :issue:`SERVER-18211` MongoDB fails to correctly roll back collection creation -- :issue:`SERVER-17273` Add support for ``secondaryCatchupPeriodSecs`` to :method:`rs.stepdown()` shell helper +- :issue:`SERVER-17273` Add support for ``secondaryCatchupPeriodSecs`` to :method:`rs.stepDown()` shell helper Sharding ~~~~~~~~ - :issue:`SERVER-17812` LockPinger has audit-related GLE failure - :issue:`SERVER-17749` :dbcommand:`collMod` :collflag:`usePowerOf2Sizes` fails on :binary:`~bin.mongos` -- :issue:`SERVER-16987` :method:`sh.getRecentMigrations()` shows aborted migration as success +- :issue:`SERVER-16987` ``sh.getRecentMigrations`` shows aborted migration as success Storage ~~~~~~~ @@ -403,8 +403,8 @@ Build and Packaging - :issue:`SERVER-18082` Change ``smoke.py`` buildlogger command line options to environment variables - :issue:`SERVER-17730` Parsing of Variables on Windows doesn't respect windows conventions - :issue:`SERVER-17694` support ``RPATH=value`` in top-level ``SConstruct`` -- :issue:`SERVER-17465` ``--use-system-tcmalloc`` does not support ``tcmalloc`` :dbcommand:`setParameters` and extension -- :issue:`SERVER-17961` `THIRD-PARTY-NOTICES.windows`` needs to be updated +- :issue:`SERVER-17465` ``--use-system-tcmalloc`` does not support ``tcmalloc`` :dbcommand:`setParameter` and extension +- :issue:`SERVER-17961` ``THIRD-PARTY-NOTICES.windows`` needs to be updated - :issue:`SERVER-17780` Init script sets process ulimit to different value compared to documentation JavaScript @@ -417,7 +417,7 @@ Shell - :issue:`SERVER-17951` db.currentOp() fails with read preference set - :issue:`SERVER-17273` Add support for secondaryCatchupPeriodSecs to rs.stepdown shell helper -- :issue:`SERVER-16987` sh.getRecentMigrations shows aborted migration as success +- :issue:`SERVER-16987` ``sh.getRecentMigrations`` shows aborted migration as success Testing ~~~~~~~ @@ -504,7 +504,7 @@ HTTP Console Admin ~~~~~ -- :issue:`SERVER-17570` MongoDB 3.0 NT Service shutdown race condition with :method:`db.serverShutdown()` +- :issue:`SERVER-17570` MongoDB 3.0 NT Service shutdown race condition with :method:`db.shutdownServer()` - :issue:`SERVER-17699` "locks" section empty in diagnostic log and profiler output for some operations - :issue:`SERVER-17337` RPM Init script breaks with quotes in ``yaml`` config file - :issue:`SERVER-16731` Remove unused DBPATH init script variable diff --git a/source/release-notes/3.0-compatibility.txt b/source/release-notes/3.0-compatibility.txt index 90969282d9b..00b7938f1c2 100644 --- a/source/release-notes/3.0-compatibility.txt +++ b/source/release-notes/3.0-compatibility.txt @@ -107,13 +107,13 @@ consistency for the purposes of creating backups. Support for ``touch`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If a storage engine does not support the :dbcommand:`touch`, then the -:dbcommand:`touch` command will return an error. +If a storage engine does not support the ``touch``, then the +``touch`` command will return an error. -- The MMAPv1 storage engine supports :dbcommand:`touch`. +- The MMAPv1 storage engine supports ``touch``. - The WiredTiger storage engine *does not* support - :dbcommand:`touch`. + ``touch``. .. _3.0-compatiblity-record-alloc: @@ -234,7 +234,7 @@ The ``FATAL`` replica set state does not exist as of 3.0.0. HTTP Interface ~~~~~~~~~~~~~~ -The HTTP Interface (i.e. :setting:`net.http.enabled`) no longer +The HTTP Interface (i.e. ``net.http.enabled``) no longer reports replication data. .. _3.0-compatibility-tools: @@ -271,7 +271,10 @@ Removed Options ``--type`` option to specify the export format type (``csv`` or ``json``). -.. seealso:: :ref:`3.0-tools-enhancements` +.. seealso:: + + :ref:`3.0-tools-enhancements` + .. _3.0-compatibility-sharded-cluster: @@ -350,7 +353,7 @@ TLS/SSL Configuration Option Changes MongoDB 3.0 introduced new :setting:`net.ssl.allowConnectionsWithoutCertificates` configuration file setting and ``--sslAllowConnectionsWithoutCertificates`` command line option for :binary:`~bin.mongod` and :binary:`~bin.mongos`. These -options replace previous :setting:`net.ssl.weakCertificateValidation` and +options replace previous ``net.ssl.weakCertificateValidation`` and ``--sslWeakCertificateValidation`` options, which became aliases. Update your configuration to ensure future compatibility. @@ -360,7 +363,7 @@ TLS/SSL Certificates Validation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, when running in SSL mode, MongoDB instances will *only* -start if its certificate (i.e. :setting:`net.ssl.PemKeyFile`) is valid. +start if its certificate (i.e. :setting:`net.ssl.PEMKeyFile`) is valid. You can disable this behavior with the :setting:`net.ssl.allowInvalidCertificates` setting or the ``--sslAllowInvalidCertificates`` command line option. @@ -539,11 +542,11 @@ The following commands and methods are deprecated in MongoDB 3.0: - :dbcommand:`diagLogging` -- :dbcommand:`eval`, :method:`db.eval()` +- ``eval``, :method:`db.eval()` - :method:`db.collection.copyTo()` -In addition, you cannot use the now deprecated :dbcommand:`eval` +In addition, you cannot use the now deprecated ``eval`` command or the :method:`db.eval()` method to invoke :dbcommand:`mapReduce` or :method:`db.collection.mapReduce()`. diff --git a/source/release-notes/3.0-downgrade.txt b/source/release-notes/3.0-downgrade.txt index bf3c35bbce3..7022381b20c 100644 --- a/source/release-notes/3.0-downgrade.txt +++ b/source/release-notes/3.0-downgrade.txt @@ -30,7 +30,7 @@ Downgrade Path .. important:: If you upgrade to MongoDB 3.0 and have run - :dbcommand:`authSchemaUpgrade`, you **cannot** downgrade to the 2.6 + ``authSchemaUpgrade``, you **cannot** downgrade to the 2.6 series without disabling ``--auth``. Procedures diff --git a/source/release-notes/3.0-scram.txt b/source/release-notes/3.0-scram.txt index 4183ffea526..d9e357cda84 100644 --- a/source/release-notes/3.0-scram.txt +++ b/source/release-notes/3.0-scram.txt @@ -76,7 +76,7 @@ upgrade procedure to upgrade the cluster's authentication data. By default, the procedure will upgrade the authentication data of the shards as well. -To override this behavior, run :dbcommand:`authSchemaUpgrade` with the +To override this behavior, run ``authSchemaUpgrade`` with the ``upgradeShards: false`` option. If you choose to override, you must run the upgrade procedure on the :binary:`~bin.mongos` first, and then run the procedure on the :term:`primary` members of @@ -99,7 +99,7 @@ SCRAM. The minimum driver versions that support SCRAM are: .. include:: /includes/list-table-3.0-driver-compatibility.rst -See the :ecosystem:`MongoDB Drivers Page ` for links to +See the :driver:`MongoDB Drivers Page ` for links to download upgraded drivers. Prerequisites diff --git a/source/release-notes/3.0-upgrade.txt b/source/release-notes/3.0-upgrade.txt index 5eaa5efeeb3..e6a35abb796 100644 --- a/source/release-notes/3.0-upgrade.txt +++ b/source/release-notes/3.0-upgrade.txt @@ -64,9 +64,9 @@ Downgrade Limitations .. include:: /includes/fact-3.0-downgrade-path.rst -If you upgrade to 3.0 and have run :dbcommand:`authSchemaUpgrade`, you +If you upgrade to 3.0 and have run ``authSchemaUpgrade``, you **cannot** downgrade to 2.6 without disabling ``--auth`` or -restoring a pre-upgrade backup, as :dbcommand:`authSchemaUpgrade` +restoring a pre-upgrade backup, as ``authSchemaUpgrade`` discards the ``MONGODB-CR`` credentials used in 2.6. See :ref:`3.0-upgrade-auth-schema`. diff --git a/source/release-notes/3.0.txt b/source/release-notes/3.0.txt index 98b918da9d8..c927a31389e 100644 --- a/source/release-notes/3.0.txt +++ b/source/release-notes/3.0.txt @@ -27,11 +27,9 @@ for more information. Minor Releases -------------- -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/3.0-changelog + /release-notes/3.0-changelog .. _3.0.15-release-notes: @@ -220,7 +218,7 @@ Issues fixed and improvements: :issue:`SERVER-17836`). - Performance improvements for longer running queries, particularly - :operator:`$text` and :operator:`$near` queries + :query:`$text` and :query:`$near` queries :issue:`SERVER-18926`. - `All issues closed in 3.0.5 @@ -250,7 +248,7 @@ Issues fixed: - `All issues closed in 3.0.4 `_ -.. _3.0.3-release-notes: +.. _3.0.3-release-notes: 3.0.3 -- May 12, 2015 ~~~~~~~~~~~~~~~~~~~~~ @@ -266,7 +264,7 @@ Issues fixed: - Crash caused by update with a *key too large to index* on WiredTiger and RocksDB storage engines: :issue:`SERVER-17882` -- Inconsistent support for :dbcommand:`mapReduce` in :dbcommand:`eval` +- Inconsistent support for :dbcommand:`mapReduce` in ``eval`` environment: :issue:`SERVER-17889` - `All issues closed in 3.0.3 @@ -357,14 +355,17 @@ The WiredTiger storage engine requires the latest official MongoDB drivers. For more information, see :ref:`3.0-compatibility-drivers-wired-tiger`. -.. seealso:: :ref:`3.0-compatibility-touch`, :doc:`/core/wiredtiger` +.. seealso:: + + :ref:`3.0-compatibility-touch`, :doc:`/core/wiredtiger` + documentation WiredTiger Configuration ```````````````````````` To configure the behavior and properties of the WiredTiger storage -engine, see :setting:`storage.wiredTiger` configuration options. You +engine, see ``storage.wiredTiger`` configuration options. You can set :ref:`WiredTiger options on the command line `. @@ -436,7 +437,10 @@ When low on disk space, MongoDB 3.0 no longer errors on all writes but only when the required disk allocation fails. As such, MongoDB now allows in-place updates and removes when low on disk space. -.. seealso:: :ref:`3.0-compatiblity-record-alloc` +.. seealso:: + + :ref:`3.0-compatiblity-record-alloc` + .. _3.0-replica-sets: @@ -508,7 +512,10 @@ Other Replica Set Operational Changes - For pre-existing collections on secondary members, MongoDB 3.0 no longer automatically builds missing ``_id`` indexes. -.. seealso:: :ref:`3.0-compatibility-rs` in +.. seealso:: + + :ref:`3.0-compatibility-rs` in + :doc:`/release-notes/3.0-compatibility` .. _3.0-sharded-clusters: @@ -540,7 +547,10 @@ MongoDB 3.0 provides the following enhancements to sharded clusters: includes information about the state of the balancer. See :method:`sh.status()` for details. -.. seealso:: :ref:`3.0-compatibility-sharded-cluster` in +.. seealso:: + + :ref:`3.0-compatibility-sharded-cluster` in + :doc:`/release-notes/3.0-compatibility` Security Improvements @@ -621,7 +631,10 @@ project. with the ``--prefix`` option so that you can use custom namespaces and store multiple GridFS namespaces in a single database. -.. seealso:: :ref:`3.0-compatibility-tools` +.. seealso:: + + :ref:`3.0-compatibility-tools` + Indexes ~~~~~~~ @@ -667,7 +680,10 @@ MongoDB 3.0 includes the following query enhancements: - Adds the :query:`$eq` query operator to query for equality conditions. -.. seealso:: :ref:`3.0-geo-near-compatibility` +.. seealso:: + + :ref:`3.0-geo-near-compatibility` + Distributions and Supported Versions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -718,11 +734,9 @@ Additional Information Changes Affecting Compatibility ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/3.0-compatibility + /release-notes/3.0-compatibility Some changes in 3.0 can affect :doc:`compatibility ` and may require user actions. For a @@ -732,13 +746,11 @@ detailed list of compatibility changes, see Upgrade Process ~~~~~~~~~~~~~~~ -.. class:: hidden - - .. toctree:: +.. toctree:: - /release-notes/3.0-upgrade - /release-notes/3.0-scram - /release-notes/3.0-downgrade + /release-notes/3.0-upgrade + /release-notes/3.0-scram + /release-notes/3.0-downgrade See :doc:`/release-notes/3.0-upgrade` for full upgrade instructions. diff --git a/source/release-notes/3.2-compatibility.txt b/source/release-notes/3.2-compatibility.txt index de50c862ec6..c4f2f9073d6 100644 --- a/source/release-notes/3.2-compatibility.txt +++ b/source/release-notes/3.2-compatibility.txt @@ -142,11 +142,9 @@ Aggregation Compatibility Changes SpiderMonkey Compatibility Changes ---------------------------------- -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/3.2-javascript + /release-notes/3.2-javascript MongoDB 3.2 changes the JavaScript engine from V8 to SpiderMonkey. The change allows the use of more modern JavaScript language features, and comes along with diff --git a/source/release-notes/3.2.txt b/source/release-notes/3.2.txt index 230e30311ab..42dfedaf51a 100644 --- a/source/release-notes/3.2.txt +++ b/source/release-notes/3.2.txt @@ -26,11 +26,9 @@ for more information. Minor Releases -------------- -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/3.2-changelog + /release-notes/3.2-changelog .. _3.2.22-release-notes: @@ -211,7 +209,7 @@ Issues fixed: if they can see a healthy primary of equal or greater priority to the candidate. -- :issue:`SERVER-25012`: :dbcommand:`createIndex` blocks for duration +- :issue:`SERVER-25012`: ``createIndex`` blocks for duration of checkpoint while holding locks. - :issue:`SERVER-25865`: :pipeline:`$group` operation is slow on @@ -486,7 +484,10 @@ engine setting either: :binary:`~bin.mongod` will not start if ``dbPath`` contains data files created by a storage engine other than the one specified. -.. seealso:: :ref:`3.2-storage-engine-compatibility` +.. seealso:: + + :ref:`3.2-storage-engine-compatibility` + WiredTiger Default Cache Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -530,7 +531,9 @@ milliseconds for detecting when a replica set's primary is unreachable. :rsconf:`~settings.electionTimeoutMillis` only applies if using the version 1 of the :rsconf:`replication protocol `. -.. seealso:: :doc:`/reference/replica-set-protocol-versions` +.. seealso:: + + :doc:`/reference/replica-set-protocol-versions` .. _3.2-rel-notes-sharded-cluster: @@ -962,7 +965,10 @@ MongoDB 3.2 introduces a version 3 of the :doc:`text index Starting in MongoDB 3.2, version 3 is the default version for new :doc:`text ` indexes. -.. seealso:: :ref:`3.2-text-index-compatibility` +.. seealso:: + + :ref:`3.2-text-index-compatibility` + .. _3.2-relnotes-text-operator: @@ -1069,7 +1075,10 @@ This change affects all JavaScript behavior including the commands :query:`$where`; *however*, this change should be completely transparent to the user. -.. seealso:: :ref:`3.2-spidermonkey-compatibility` +.. seealso:: + + :ref:`3.2-spidermonkey-compatibility` + ``mongo`` Shell and CRUD API ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1223,7 +1232,10 @@ smaller regions. In addition, for both :doc:`2d indexes ` and :doc:`2dsphere indexes `, the performance of geoNear queries has been improved for dense datasets. -.. seealso:: :ref:`3.2-2dsphere-index-compatibility` +.. seealso:: + + :ref:`3.2-2dsphere-index-compatibility` + .. _3.2-diagnostic-data-capture: @@ -1294,22 +1306,18 @@ Some MongoDB 3.2 changes can affect compatibility and may require user actions. For a detailed list of compatibility changes, see :doc:`/release-notes/3.2-compatibility`. -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/3.2-compatibility + /release-notes/3.2-compatibility Upgrade Process --------------- -.. class:: hidden - - .. toctree:: +.. toctree:: - /release-notes/3.2-upgrade - /release-notes/3.2-downgrade + /release-notes/3.2-upgrade + /release-notes/3.2-downgrade See :doc:`/release-notes/3.2-upgrade` for full upgrade instructions. diff --git a/source/release-notes/3.4-compatibility.txt b/source/release-notes/3.4-compatibility.txt index 9d9eaa1feb8..66ef720e4e5 100644 --- a/source/release-notes/3.4-compatibility.txt +++ b/source/release-notes/3.4-compatibility.txt @@ -74,7 +74,9 @@ To convert your existing config servers from SCCC to CSRS, see the MongoDB 3.4 manual :v3.4:`Upgrade Config Servers to Replica Set `. -.. seealso:: +.. seealso:: + + :ref:`Sharded Cluster Release Notes Section <3.4-rel-notes-sharded-cluster>` @@ -217,9 +219,9 @@ General Compatibility Changes - Removal of deprecated ``textSearchEnabled`` parameter. Starting from version 2.6, MongoDB enables the text search feature by default. -- Removal of :binary:`~bin.mongosniff`. In MongoDB 3.4, - :binary:`~bin.mongosniff` is replaced by :binary:`~bin.mongoreplay`, which - offers a more flexible superset of :binary:`~bin.mongosniff`'s +- Removal of ``mongosniff``. In MongoDB 3.4, + ``mongosniff`` is replaced by :binary:`~bin.mongoreplay`, which + offers a more flexible superset of ``mongosniff``'s functionality. - Updates to :pipeline:`$project` specification behavior: empty @@ -315,8 +317,8 @@ like an equality statement for upserts. If the query includes this condition on a field, the field value is set to the element. As a result of this behavior, certain upsert operations may fail in 3.4. In -example above, the :query:`$addToSet` upsert would fail because the ``a`` -field would be seeded with a single value, and :query:`$addToSet` cannot be +example above, the :update:`$addToSet` upsert would fail because the ``a`` +field would be seeded with a single value, and :update:`$addToSet` cannot be applied to a scalar field. To avoid this error, you must wrap the :query:`$in` expression in an :query:`$elemMatch` expression: diff --git a/source/release-notes/3.4-downgrade.txt b/source/release-notes/3.4-downgrade.txt index 0f1ea49cc14..dfe8f872086 100644 --- a/source/release-notes/3.4-downgrade.txt +++ b/source/release-notes/3.4-downgrade.txt @@ -96,12 +96,10 @@ Procedures - :doc:`/release-notes/3.4-downgrade-sharded-cluster`. -.. class:: hidden +.. toctree:: + :titlesonly: - .. toctree:: - :titlesonly: - - /release-notes/3.4-downgrade-standalone - /release-notes/3.4-downgrade-replica-set - /release-notes/3.4-downgrade-sharded-cluster + /release-notes/3.4-downgrade-standalone + /release-notes/3.4-downgrade-replica-set + /release-notes/3.4-downgrade-sharded-cluster diff --git a/source/release-notes/3.4.txt b/source/release-notes/3.4.txt index e7cf9414317..6a650d50350 100644 --- a/source/release-notes/3.4.txt +++ b/source/release-notes/3.4.txt @@ -10,25 +10,21 @@ Release Notes for MongoDB 3.4 :depth: 1 :class: twocols -.. admonition:: MongoDB 3.4 Released Nov 29, 2016 +.. note:: MongoDB 3.4 Released Nov 29, 2016 MongoDB 3.4 is now available. Key features include linearizable read concerns, views, and collation. - OpsManager 3.4 is also available. See the `Ops Manager documentation - `_ and the `Ops Manager - release notes - `_ + OpsManager 3.4 is also available. See the :opsmgr:`Ops Manager documentation ` + and the :opsmgr:`Ops Manager Release Notes ` for more information. Minor Releases -------------- -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/3.4-changelog + /release-notes/3.4-changelog .. _3.4.24-release-notes: @@ -342,8 +338,8 @@ Issues fixed: - :issue:`SERVER-29287`: Upgrade pcre to 8.41 -- :issue:`SERVER-31204`: Calling `shardCollection` after - `enableSharding` may fail if executed against different mongos +- :issue:`SERVER-31204`: Calling ``shardCollection`` after + ``enableSharding`` may fail if executed against different mongos - :ref:`3.4.10-changelog` @@ -534,22 +530,22 @@ config servers. To support this awareness: -- ``shardsvr`` Requirement - For a 3.4 sharded cluster, :binary:`~bin.mongod` instances for the - shards **must** explicitly specify its role as a ``shardsvr``, - either via the configuration file setting - :setting:`sharding.clusterRole` or via the command line option - :option:`--shardsvr `. +``shardsvr`` Requirement + For a 3.4 sharded cluster, :binary:`~bin.mongod` instances for the + shards **must** explicitly specify its role as a ``shardsvr``, + either via the configuration file setting + :setting:`sharding.clusterRole` or via the command line option + :option:`--shardsvr `. - .. note:: + .. note:: - Default port for :binary:`~bin.mongod` instances with the ``shardsvr`` - role is ``27018``. To use a different port, specify - :setting:`net.port` setting or ``--port`` option. + Default port for :binary:`~bin.mongod` instances with the ``shardsvr`` + role is ``27018``. To use a different port, specify + :setting:`net.port` setting or ``--port`` option. - .. COMMENT To DOCS TEAM: Ensure that in all our sharding tutorials we specify shardsvr. + .. COMMENT To DOCS TEAM: Ensure that in all our sharding tutorials we specify shardsvr. -- 3.4 ``mongos`` Incompatibility with Earlier Versions of ``mongod`` +3.4 ``mongos`` Incompatibility with Earlier Versions of ``mongod`` Version 3.4 :binary:`~bin.mongos` instances cannot connect to earlier versions of :binary:`~bin.mongod` instances. @@ -587,10 +583,10 @@ change: - MongoDB 3.4 removes the following configuration options from the :binary:`~bin.mongos`: - - :setting:`sharding.chunkSize` configuration file setting and + - ``sharding.chunkSize`` configuration file setting and ``--chunkSize`` command-line option - - :setting:`sharding.autoSplit` configuration file setting and + - ``sharding.autoSplit`` configuration file setting and ``--noAutoSplit`` command-line option Faster Balancing @@ -639,7 +635,7 @@ To support zones, MongoDB introduces the following commands and :header-rows: 1 * - Commands - - `mongo` Shell Methods + - ``mongo`` Shell Methods * - :dbcommand:`addShardToZone` - :method:`sh.addShardToZone()` @@ -802,7 +798,10 @@ New Aggregation Stage for Recursive Search document, adds a new array field that contains the traversal results of the recursive search for that document. -.. seealso:: `Webinar: Working with Graph Data in MongoDB `_ +.. seealso:: + + `Webinar: Working with Graph Data in MongoDB `_ + New Aggregation Stages for Faceted Search ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1146,7 +1145,7 @@ MongoDB Tools ~~~~~~~~~~~~~~~ MongoDB introduces :binary:`~bin.mongoreplay`, a workload capture and -analysis tool that replaces :binary:`~bin.mongosniff`. You can use +analysis tool that replaces ``mongosniff``. You can use :binary:`~bin.mongoreplay` to inspect and record commands sent to a MongoDB instance, and then replay the commands back onto another host at a later time. @@ -1286,11 +1285,9 @@ Some changes can affect compatibility and may require user actions. For a detailed list of compatibility changes, see :doc:`/release-notes/3.4-compatibility`. -.. class:: hidden +.. toctree:: - .. toctree:: - - /release-notes/3.4-compatibility + /release-notes/3.4-compatibility .. _3.4-upgrade: @@ -1318,16 +1315,13 @@ To download the MongoDB 3.4, go to the `MongoDB Download Center - `All Third Party License Notices `_. +.. toctree:: + :titlesonly: -.. class:: hidden - - .. toctree:: - :titlesonly: - - /release-notes/3.4-upgrade-standalone - /release-notes/3.4-upgrade-replica-set - /release-notes/3.4-upgrade-sharded-cluster - /release-notes/3.4-downgrade + /release-notes/3.4-upgrade-standalone + /release-notes/3.4-upgrade-replica-set + /release-notes/3.4-upgrade-sharded-cluster + /release-notes/3.4-downgrade Known Issues in 3.4.0 --------------------- diff --git a/source/release-notes/3.6-upgrade-replica-set.txt b/source/release-notes/3.6-upgrade-replica-set.txt index 3ab602c26d4..591ef33e225 100644 --- a/source/release-notes/3.6-upgrade-replica-set.txt +++ b/source/release-notes/3.6-upgrade-replica-set.txt @@ -87,8 +87,6 @@ Prerequisites ``featureCompatibilityVersion`` set to ``3.4``, connect to each replica set member and check the ``featureCompatibilityVersion``: - .. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -100,8 +98,6 @@ Prerequisites following command on the primary. A majority of the data-bearing members must be available: - .. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) diff --git a/source/release-notes/3.6-upgrade-sharded-cluster.txt b/source/release-notes/3.6-upgrade-sharded-cluster.txt index da7e77abe29..3ceaa0419f7 100644 --- a/source/release-notes/3.6-upgrade-sharded-cluster.txt +++ b/source/release-notes/3.6-upgrade-sharded-cluster.txt @@ -106,8 +106,6 @@ Prerequisites connect to the member as a :ref:`shard local user `. - .. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -118,8 +116,6 @@ Prerequisites To set or update ``featureCompatibilityVersion``, run the following command on the :binary:`~bin.mongos`: - .. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) diff --git a/source/release-notes/3.6-upgrade-standalone.txt b/source/release-notes/3.6-upgrade-standalone.txt index a488b18cfa4..66ce43bb172 100644 --- a/source/release-notes/3.6-upgrade-standalone.txt +++ b/source/release-notes/3.6-upgrade-standalone.txt @@ -55,8 +55,6 @@ Prerequisites The |oldversion| instance must have ``featureCompatibilityVersion`` set to ``3.4``. To check ``featureCompatibilityVersion``: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -67,8 +65,6 @@ The operation should return a result that includes To set or update ``featureCompatibilityVersion``, run the following command: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "3.4" } ) diff --git a/source/release-notes/3.6.txt b/source/release-notes/3.6.txt index c7fb9cc7e8d..2104da9c60e 100644 --- a/source/release-notes/3.6.txt +++ b/source/release-notes/3.6.txt @@ -253,7 +253,7 @@ Issues fixed: - :issue:`SERVER-32146`: Log slow oplog entry application -- :issue:`SERVER-9043`: Link `flushRouterConfig` on the config server and shards +- :issue:`SERVER-9043`: Link ``flushRouterConfig`` on the config server and shards - :issue:`SERVER-37624`: Sessions never expire when you change value of localLogicalSessionTimeoutMinutes @@ -539,7 +539,10 @@ Additional Security Enhancements - Added the :authaction:`convertToCapped` action to :authrole:`restore` role. - .. seealso:: :ref:`3.6-compatibility-enabled` + .. seealso:: + + :ref:`3.6-compatibility-enabled` + .. _3.6-rel-notes-aggregation: @@ -657,7 +660,9 @@ Support for Time Zones MongoDB 3.6 adds support for time zones to :ref:`aggregation date operators `. -.. seealso:: :ref:`Aggregation Compatibility Changes ` +.. seealso:: + + :ref:`Aggregation Compatibility Changes ` Array Update Operator Enhancements @@ -867,7 +872,8 @@ Parameters The following new parameters are available for server sessions: -- :parameter:`logicalSessionRefreshMinutes` +- ``logicalSessionRefreshMinutes`` (replaced with + :parameter:`logicalSessionRefreshMillis` in 3.6.9) - :parameter:`localLogicalSessionTimeoutMinutes` @@ -920,7 +926,10 @@ Schema. For details, see :query:`$jsonSchema`. To use :query:`$jsonSchema`, ``featureCompatibilityVersion`` must be set to "3.6". -.. seealso:: :ref:`3.6-compatibility-enabled` +.. seealso:: + + :ref:`3.6-compatibility-enabled` + Replica Sets ------------ @@ -1012,7 +1021,10 @@ Collections have an immutable :ref:`unique identifier `. The ``featureCompatibilityVersion`` must be set to ``"3.6"``. -.. seealso:: :ref:`3.6-compatibility-enabled` +.. seealso:: + + :ref:`3.6-compatibility-enabled` + New Query Operators ~~~~~~~~~~~~~~~~~~~ @@ -1112,7 +1124,9 @@ Read Concern tolerance for partitions but may return orphan documents if the shard is undergoing chunk migrations. - .. seealso:: :parameter:`orphanCleanupDelaySecs` + .. seealso:: + + :parameter:`orphanCleanupDelaySecs` - Starting in MongoDB 3.6, MongoDB enables support for :v3.6:`"majority" ` read concern by @@ -1169,8 +1183,8 @@ MongoDB 3.6 includes the following enhancements: of a database, which indicates the maximum number of write operations permitted in a write batch, raises from ``1,000`` to ``100,000``. -- The :dbcommand:`planCacheListPlans` database command produces the same - output as the :method:`PlanCache.getPlansByQuery()` shell method. The +- The ``planCacheListPlans`` database command produces the same + output as the ``PlanCache.getPlansByQuery()`` shell method. The output from both operations now includes a timestamp for when the plans were generated. @@ -1194,7 +1208,7 @@ a detailed list of compatibility changes, see Upgrade Procedures ------------------ -.. admonition:: Feature Compatibility Version 3.4 +.. important:: Feature Compatibility Version 3.4 To upgrade, the 3.4 instances must have ``featureCompatibilityVersion`` set to 3.4. To check the version: @@ -1317,16 +1331,13 @@ https://github.com/mongodb/mongo/wiki/Submit-Bug-Reports for instructions on how to file a JIRA ticket for the MongoDB server or one of the related projects. +.. toctree:: -.. class:: hidden - - .. toctree:: - - /release-notes/3.6-changelog - /release-notes/3.6-compatibility - /release-notes/3.6-upgrade-standalone - /release-notes/3.6-upgrade-replica-set - /release-notes/3.6-upgrade-sharded-cluster - /release-notes/3.6-downgrade-standalone - /release-notes/3.6-downgrade-replica-set - /release-notes/3.6-downgrade-sharded-cluster + /release-notes/3.6-changelog + /release-notes/3.6-compatibility + /release-notes/3.6-upgrade-standalone + /release-notes/3.6-upgrade-replica-set + /release-notes/3.6-upgrade-sharded-cluster + /release-notes/3.6-downgrade-standalone + /release-notes/3.6-downgrade-replica-set + /release-notes/3.6-downgrade-sharded-cluster diff --git a/source/release-notes/4.0-compatibility.txt b/source/release-notes/4.0-compatibility.txt index 00269e3bdca..0cf02c650d4 100644 --- a/source/release-notes/4.0-compatibility.txt +++ b/source/release-notes/4.0-compatibility.txt @@ -35,7 +35,7 @@ Removal of ``authSchemaUpgrade`` Command MongoDB 4.0 removes the ``authSchemaUpgrade`` command . The command, available in MongoDB 3.0 through MongoDB 3.6, supports the upgrade -process for systems with ``MONGDB-CR`` users to ``SCRAM`` users. +process for systems with ``MONGODB-CR`` users to ``SCRAM`` users. If your deployment has user credentials stored in ``MONGODB-CR`` schema, you must upgrade to :ref:`Salted Challenge Response @@ -52,7 +52,7 @@ The method :method:`db.copyDatabase()` cannot copy from a :binary:`~bin.mongod` instance that enforces ``MONGODB-CR`` authentication. -The command :dbcommand:`copydb` cannot copy from a +The command ``copydb`` cannot copy from a :binary:`~bin.mongod` instance that enforces ``MONGODB-CR`` authentication. In conjunction with this change, MongoDB 4.0 removes the ``copydbgetnonce`` command. diff --git a/source/release-notes/4.0-upgrade-replica-set.txt b/source/release-notes/4.0-upgrade-replica-set.txt index c909b48eb4d..e19ed494517 100644 --- a/source/release-notes/4.0-upgrade-replica-set.txt +++ b/source/release-notes/4.0-upgrade-replica-set.txt @@ -70,8 +70,8 @@ MongoDB 4.0 introduces new hex-encoded string change stream .. include:: /includes/extracts/changestream-resume-token-versions-4.0.rst -.. admonition:: When upgrading from MongoDB 3.6 to MongoDB 4.0.7 or greater - :class: important +.. important:: When upgrading from MongoDB 3.6 to MongoDB 4.0.7 or greater + When upgrading from MongoDB 3.6 to MongoDB 4.0.7 or later, a client may try to resume change streams using the new ``v1`` resume token @@ -106,7 +106,9 @@ MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism. .. include:: /includes/extracts/4.0-upgrade-prereq-mongodb-cr.rst -.. seealso:: |compatibility| +.. seealso:: + + |compatibility| Remove ``pv0`` for Replica Sets @@ -134,8 +136,6 @@ To ensure that all members of the replica set have ``featureCompatibilityVersion`` set to ``3.6``, connect to each replica set member and check the ``featureCompatibilityVersion``: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -147,8 +147,6 @@ To set or update ``featureCompatibilityVersion``, run the following command on the primary. A majority of the data-bearing members must be available: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) diff --git a/source/release-notes/4.0-upgrade-sharded-cluster.txt b/source/release-notes/4.0-upgrade-sharded-cluster.txt index afe98302c28..ee2b4835e23 100644 --- a/source/release-notes/4.0-upgrade-sharded-cluster.txt +++ b/source/release-notes/4.0-upgrade-sharded-cluster.txt @@ -68,8 +68,8 @@ MongoDB 4.0 introduces new hex-encoded string change stream .. include:: /includes/extracts/changestream-resume-token-versions-4.0.rst -.. admonition:: When upgrading from MongoDB 3.6 to MongoDB 4.0.7 - :class: important +.. important:: When upgrading from MongoDB 3.6 to MongoDB 4.0.7 + When upgrading from MongoDB 3.6 to MongoDB 4.0.7 or later, the upgraded sharded cluster members continue to produce ``v0`` token @@ -110,7 +110,9 @@ MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism. .. include:: /includes/extracts/4.0-upgrade-prereq-mongodb-cr.rst -.. seealso:: |compatibility| +.. seealso:: + + |compatibility| Remove ``pv0`` for Replica Sets @@ -146,8 +148,6 @@ and check the ``featureCompatibilityVersion``: connect to the member as a :ref:`shard local user `. -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -158,8 +158,6 @@ All members should return a result that includes To set or update ``featureCompatibilityVersion``, run the following command on the :binary:`~bin.mongos`: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) diff --git a/source/release-notes/4.0-upgrade-standalone.txt b/source/release-notes/4.0-upgrade-standalone.txt index 3bbb9252de6..67964c22803 100644 --- a/source/release-notes/4.0-upgrade-standalone.txt +++ b/source/release-notes/4.0-upgrade-standalone.txt @@ -39,7 +39,9 @@ MongoDB Challenge-Response (``MONGODB-CR``) authentication mechanism. .. include:: /includes/extracts/4.0-upgrade-prereq-mongodb-cr.rst -.. seealso:: |compatibility| +.. seealso:: + + |compatibility| Remove Support for ``$isolated`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -52,8 +54,6 @@ Feature Compatibility Version The |oldversion| instance must have ``featureCompatibilityVersion`` set to ``3.6``. To check ``featureCompatibilityVersion``: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -64,8 +64,6 @@ The operation should return a result that includes To set or update ``featureCompatibilityVersion``, run the following command: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "3.6" } ) diff --git a/source/release-notes/4.0.txt b/source/release-notes/4.0.txt index 760d5cc7b31..e989e73e50a 100644 --- a/source/release-notes/4.0.txt +++ b/source/release-notes/4.0.txt @@ -929,7 +929,10 @@ AES-GCM .. include:: /includes/fact-aes.rst -.. seealso:: :ref:`4.0-ssl-systemstore` +.. seealso:: + + :ref:`4.0-ssl-systemstore` + New Privilege Actions ~~~~~~~~~~~~~~~~~~~~~~ @@ -1229,7 +1232,7 @@ following command and shell helper: - :dbcommand:`getFreeMonitoringStatus` The :dbcommand:`serverStatus` and the helper -:method:`db.getServerStatus()` also includes free monitoring statistics +:method:`db.serverStatus()` also includes free monitoring statistics in the :serverstatus:`freeMonitoring` field. Access Control @@ -1469,7 +1472,7 @@ a detailed list of compatibility changes, see Upgrade Procedures ------------------ -.. admonition:: Feature Compatibility Version +.. important:: Feature Compatibility Version To upgrade, the 3.6 instances must have ``featureCompatibilityVersion`` set to ``3.6``. To check the version: @@ -1574,15 +1577,13 @@ https://github.com/mongodb/mongo/wiki/Submit-Bug-Reports for instructions on how to file a JIRA ticket for the MongoDB server or one of the related projects. -.. class:: hidden - - .. toctree:: +.. toctree:: - /release-notes/4.0-compatibility - /release-notes/4.0-upgrade-standalone - /release-notes/4.0-upgrade-replica-set - /release-notes/4.0-upgrade-sharded-cluster - /release-notes/4.0-downgrade-standalone - /release-notes/4.0-downgrade-replica-set - /release-notes/4.0-downgrade-sharded-cluster - /release-notes/4.0-changelog + /release-notes/4.0-compatibility + /release-notes/4.0-upgrade-standalone + /release-notes/4.0-upgrade-replica-set + /release-notes/4.0-upgrade-sharded-cluster + /release-notes/4.0-downgrade-standalone + /release-notes/4.0-downgrade-replica-set + /release-notes/4.0-downgrade-sharded-cluster + /release-notes/4.0-changelog diff --git a/source/release-notes/4.2-compatibility.txt b/source/release-notes/4.2-compatibility.txt index e393ae26ab5..ae8baf0f667 100644 --- a/source/release-notes/4.2-compatibility.txt +++ b/source/release-notes/4.2-compatibility.txt @@ -171,7 +171,10 @@ The options for :pipeline:`$geoNear` are similar to the removed { $max: "$dis" }, avgDistance: { $avg: "$dis" } } } ]) - .. seealso:: :ref:`4.2-compat-geoNear` + .. seealso:: + + :ref:`4.2-compat-geoNear` + .. _4.2-compat-remove-repairDatabase: @@ -210,8 +213,8 @@ Starting in version 4.2, MongoDB removes the deprecated Deprecate Support for ``cloneCollection`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -MongoDB deprecates the :dbcommand:`cloneCollection` command and its -:binary:`~bin.mongo` shell helper :method:`db.cloneCollection()` +MongoDB deprecates the ``cloneCollection`` command and its +:binary:`~bin.mongo` shell helper ``db.cloneCollection()`` As alternatives, @@ -231,15 +234,15 @@ Deprecated Plan Cache Commands/Methods MongoDB deprecates the following: -- :method:`PlanCache.getPlansByQuery()` - method/:dbcommand:`planCacheListPlans` command. +- ``PlanCache.getPlansByQuery()`` + method/``planCacheListPlans`` command. | To get the cached query plans for a shape, use the :pipeline:`$planCacheStats` aggregation stage instead. See :ref:`planCacheStats-cache-entry-for-query-shape`. -- :method:`PlanCache.listQueryShapes()` - method/:dbcommand:`planCacheListQueryShapes` command. +- ``PlanCache.listQueryShapes()`` + method/``planCacheListQueryShapes`` command. | To list the cached query shapes, use the :pipeline:`$planCacheStats` aggregation stage instead. See @@ -258,54 +261,46 @@ Aggregation ``$out`` and Views `````````````````` -.. container:: - - The :doc:`view ` definition ``pipeline`` cannot include - the :pipeline:`$out` stage. If you already have an existing view - that includes the :pipeline:`$out` stage, you can no longer create - new views from this existing view. +The :doc:`view ` definition ``pipeline`` cannot include +the :pipeline:`$out` stage. If you already have an existing view +that includes the :pipeline:`$out` stage, you can no longer create +new views from this existing view. - For existing views that include the :pipeline:`$out` stage, you - should either :method:`drop ` and - :method:`recreate ` the views without the - :pipeline:`$out` stage or use :dbcommand:`replace the view - definition ` with a new pipeline that does not contain the - :pipeline:`$out` stage. +For existing views that include the :pipeline:`$out` stage, you +should either :method:`drop ` and +:method:`recreate ` the views without the +:pipeline:`$out` stage or use :dbcommand:`replace the view +definition ` with a new pipeline that does not contain the +:pipeline:`$out` stage. ``$out`` and ``$lookup`` ```````````````````````` -.. container:: - - The :pipeline:`$lookup` stage cannot include the :pipeline:`$out` - stage in its nested :ref:`pipeline field for the joined collection - `. +The :pipeline:`$lookup` stage cannot include the :pipeline:`$out` +stage in its nested :ref:`pipeline field for the joined collection +`. ``$out`` and ``linearizable`` Read Concern Level ```````````````````````````````````````````````` -.. container:: - - The :pipeline:`$out` stage cannot be used in conjunction with read - concern :readconcern:`"linearizable"`. +The :pipeline:`$out` stage cannot be used in conjunction with read +concern :readconcern:`"linearizable"`. ``$out`` and Explain ```````````````````` -.. container:: +You cannot run the :method:`db.collection.explain()` method (or the +:dbcommand:`explain` command) in ``executionStats`` mode or +``allPlansExecution`` mode if the aggregation pipeline contains the +:pipeline:`$out` stage. - You cannot run the :method:`db.collection.explain()` method (or the - :dbcommand:`explain` command) in ``executionStats`` mode or - ``allPlansExecution`` mode if the aggregation pipeline contains the - :pipeline:`$out` stage. +If the aggregation pipeline contains the :pipeline:`$out` stage, to +view ``executionStats`` or ``allPlansExecution`` information, run +explain without the :pipeline:`$out` stage in order to return +explain results for the preceding stages. - If the aggregation pipeline contains the :pipeline:`$out` stage, to - view ``executionStats`` or ``allPlansExecution`` information, run - explain without the :pipeline:`$out` stage in order to return - explain results for the preceding stages. - - Alternatively, you can run explain in ``queryPlanner`` mode for an - aggregation pipeline that contains the :pipeline:`$out` stage. +Alternatively, you can run explain in ``queryPlanner`` mode for an +aggregation pipeline that contains the :pipeline:`$out` stage. ``$out`` and ``majority`` Read Concern Level ```````````````````````````````````````````` @@ -351,7 +346,10 @@ Instead, you can rewrite the aggregation to the following pipeline: { $limit: 5 } ]) -.. seealso:: :ref:`4.2-agg` +.. seealso:: + + :ref:`4.2-agg` + .. _4.2-compatibility-txn: @@ -384,7 +382,10 @@ Availability .. include:: /includes/extracts/changestream-rc-majority-4.2.rst -.. seealso:: :ref:`4.2 Changes to Change Streams <4.2-change-stream>` +.. seealso:: + + :ref:`4.2 Changes to Change Streams <4.2-change-stream>` + Default Collation ~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/4.2-downgrade-replica-set.txt b/source/release-notes/4.2-downgrade-replica-set.txt index a28bbd89caf..042a58b90cc 100644 --- a/source/release-notes/4.2-downgrade-replica-set.txt +++ b/source/release-notes/4.2-downgrade-replica-set.txt @@ -108,34 +108,28 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 2a. Index Key Size `````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst .. _4.2-downgrade-index-name-repl: 2b. Index Name Length ````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst 2c. Unique Index Version ```````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-unique-index.rst - .. tip:: +.. tip:: - Perform this operation after you have resolved any :ref:`index - key size <4.2-downgrade-index-key-repl>` and :ref:`index name - length <4.2-downgrade-index-name-repl>` issues first. + Perform this operation after you have resolved any :ref:`index + key size <4.2-downgrade-index-key-repl>` and :ref:`index name + length <4.2-downgrade-index-name-repl>` issues first. - Script - .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script.rst +Script + .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script.rst 2d. Remove ``user_1_db_1`` System Unique Index `````````````````````````````````````````````` @@ -147,25 +141,18 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 2e. Remove Wildcard Indexes ```````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-wildcard-index.rst - +.. include:: /includes/extracts/4.2-downgrade-fcv-wildcard-index.rst 2f. View Definitions/Collection Validation Definitions that Include 4.2 Operators ````````````````````````````````````````````````````````````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-view-definitions.rst +.. include:: /includes/extracts/4.2-downgrade-view-definitions.rst 3. Update ``tls``-Prefixed Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. include:: /includes/extracts/4.2-changes-options-tls-ssl-downgrade.rst +.. include:: /includes/extracts/4.2-changes-options-tls-ssl-downgrade.rst 4. Prepare Downgrade from ``zstd`` Compression ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -181,182 +168,174 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 :ref:`downgrade-repl-prereq-zstd-journal`, perform these steps *after* you perform the :ref:`prerequisite steps for the journal compressor `. - -.. container:: - - The :term:`zstd` compression library is available starting in - version 4.2. For any member that has data stored using :term:`zstd` - compression, the downgrade procedure will require an initial sync - for that member. To prepare: +The :term:`zstd` compression library is available starting in +version 4.2. For any member that has data stored using :term:`zstd` +compression, the downgrade procedure will require an initial sync +for that member. To prepare: - .. include:: /includes/extracts/4.2-changes-zstd-downgrade-prereq.rst +.. include:: /includes/extracts/4.2-changes-zstd-downgrade-prereq.rst - Repeat for any other members that used :term:`zstd` compression. +Repeat for any other members that used :term:`zstd` compression. .. _downgrade-repl-prereq-zstd-journal: ``zstd`` Journal Compression ```````````````````````````` -.. container:: +The :term:`zstd` compression library is available for journal data +compression starting in version 4.2. - The :term:`zstd` compression library is available for journal data - compression starting in version 4.2. +For any member that uses :term:`zstd` library for its journal +compressor: - For any member that uses :term:`zstd` library for its journal - compressor: +If the member uses ``zstd`` for journal compression and :ref:`data compression `, + .. include:: /includes/extracts/4.2-changes-zstd-journal-compression-config-only.rst - If the member uses ``zstd`` for journal compression and :ref:`data compression `, - .. include:: /includes/extracts/4.2-changes-zstd-journal-compression-config-only.rst +If the member uses ``zstd`` for journal compression only, + .. note:: - If the member uses ``zstd`` for journal compression only, - .. note:: + The following procedure involves restarting the replica member as a + standalone without the journal. - The following procedure involves restarting the replica member as a - standalone without the journal. + #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: - #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: + .. code-block:: javascript - .. code-block:: javascript + db.getSiblingDB('admin').shutdownServer() - db.getSiblingDB('admin').shutdownServer() + #. Update the :doc:`configuration file + ` to prepare to restart as a + standalone: - #. Update the :doc:`configuration file - ` to prepare to restart as a - standalone: - - - Set :setting:`storage.journal.enabled` to ``false``. + - Set :setting:`storage.journal.enabled` to ``false``. - - Comment out the :ref:`replication ` settings - for your deployment. + - Comment out the :ref:`replication ` settings + for your deployment. - - Set parameter ``disableLogicalSessionCacheRefresh`` to - ``true`` in the :setting:`setParameter` section. + - Set parameter ``disableLogicalSessionCacheRefresh`` to + ``true`` in the :setting:`setParameter` section. - For example: + For example: - .. code-block:: none + .. code-block:: none - storage: - journal: - enabled: false - #replication: - # replSetName: replA - setParameter: - disableLogicalSessionCacheRefresh: true + storage: + journal: + enabled: false + #replication: + # replSetName: replA + setParameter: + disableLogicalSessionCacheRefresh: true - If you use command-line options instead of a configuration file, you - will have to update the command-line option during the restart. - - #. Restart the :binary:`~bin.mongod` instance: + If you use command-line options instead of a configuration file, you + will have to update the command-line option during the restart. + + #. Restart the :binary:`~bin.mongod` instance: - - If you are using a configuration file: + - If you are using a configuration file: - .. code-block:: sh + .. code-block:: sh - mongod -f + mongod -f - - If you are using command-line options instead of a - configuration file, + - If you are using command-line options instead of a + configuration file, - - Include the :option:`--nojournal ` option - - - Remove any :ref:`replication command-line options - ` (such as :option:`--replSet - `): - - - Set parameter ``disableLogicalSessionCacheRefresh`` - to ``true`` in the :option:`--setParameter ` option. - - .. code-block:: sh + - Include the :option:`--nojournal ` option + + - Remove any :ref:`replication command-line options + ` (such as :option:`--replSet + `): + + - Set parameter ``disableLogicalSessionCacheRefresh`` + to ``true`` in the :option:`--setParameter ` option. + + .. code-block:: sh - mongod --nojournal --setParameter disableLogicalSessionCacheRefresh=true ... + mongod --nojournal --setParameter disableLogicalSessionCacheRefresh=true ... - #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: + #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: - .. code-block:: javascript + .. code-block:: javascript - db.getSiblingDB('admin').shutdownServer() + db.getSiblingDB('admin').shutdownServer() - Confirm that the process is no longer running. + Confirm that the process is no longer running. - #. Update the configuration file to prepare to restart as a replica set - member with the new journal compressor: + #. Update the configuration file to prepare to restart as a replica set + member with the new journal compressor: - - Remove the :setting:`storage.journal.enabled` setting. + - Remove the :setting:`storage.journal.enabled` setting. - - Uncomment the :ref:`replication ` - settings for your deployment. + - Uncomment the :ref:`replication ` + settings for your deployment. - - Remove the ``disableLogicalSessionCacheRefresh`` parameter. + - Remove the ``disableLogicalSessionCacheRefresh`` parameter. - - Remove - :setting:`storage.wiredTiger.engineConfig.journalCompressor` setting - to use the default journal compressor or specify a new value. - - For example: + - Remove + :setting:`storage.wiredTiger.engineConfig.journalCompressor` setting + to use the default journal compressor or specify a new value. - .. code-block:: none + For example: - storage: - wiredTiger: - engineConfig: - journalCompressor: - replication: - replSetName: replA + .. code-block:: none - If you use command-line options instead of a configuration file, you - will have to update the command-line options during the restart - below. + storage: + wiredTiger: + engineConfig: + journalCompressor: + replication: + replSetName: replA + If you use command-line options instead of a configuration file, you + will have to update the command-line options during the restart + below. - #. Restart the :binary:`~bin.mongod` instance as a replica set member: - - If you are using a configuration file: + #. Restart the :binary:`~bin.mongod` instance as a replica set member: - .. code-block:: sh + - If you are using a configuration file: - mongod -f + .. code-block:: sh - - If you are using command-line options instead of a configuration - file: + mongod -f - - Remove the :option:`--nojournal ` option. + - If you are using command-line options instead of a configuration + file: - - Remove the :option:`--wiredTigerJournalCompressor ` command-line option to use - the default journal compressor or update to a new value. + - Remove the :option:`--nojournal ` option. - - Include your :ref:`replication command-line options - ` as well as any additional - options for your replica set member. + - Remove the :option:`--wiredTigerJournalCompressor ` command-line option to use + the default journal compressor or update to a new value. - - Remove the ``disableLogicalSessionCacheRefresh`` parameter. + - Include your :ref:`replication command-line options + ` as well as any additional + options for your replica set member. - .. code-block:: sh + - Remove the ``disableLogicalSessionCacheRefresh`` parameter. - mongod --wiredTigerJournalCompressor --replSet ... + .. code-block:: sh - .. note:: + mongod --wiredTigerJournalCompressor --replSet ... - If you encounter an unclean shutdown for a :binary:`~bin.mongod` - during the downgrade procedure such that you need to use the - journal files to recover, recover the - instance using the 4.2 :binary:`~bin.mongod` and then retry the - downgrade of the instance. +.. note:: + If you encounter an unclean shutdown for a :binary:`~bin.mongod` + during the downgrade procedure such that you need to use the + journal files to recover, recover the + instance using the 4.2 :binary:`~bin.mongod` and then retry the + downgrade of the instance. .. _downgrade-repl-prereq-zstd-network: ``zstd`` Network Compression ```````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-changes-zstd-network-compression.rst +.. include:: /includes/extracts/4.2-changes-zstd-network-compression.rst 5. Remove Client-Side Field Level Encryption Document Validation Keywords ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/4.2-downgrade-sharded-cluster.txt b/source/release-notes/4.2-downgrade-sharded-cluster.txt index ad80b17abf5..25f524c47b1 100644 --- a/source/release-notes/4.2-downgrade-sharded-cluster.txt +++ b/source/release-notes/4.2-downgrade-sharded-cluster.txt @@ -103,32 +103,25 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 2a. Index Key Size `````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst .. _4.2-downgrade-index-name-sharded: 2b. Index Name Length ````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst 2c. Unique Index Version ```````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-unique-index.rst +Script to run on ``mongos`` + .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script.rst - Script to run on ``mongos`` - .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script.rst - - Script to run on shards - .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script-local-users.rst +Script to run on shards + .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script-local-users.rst 2d. Remove ``user_1_db_1`` System Unique Index `````````````````````````````````````````````` @@ -140,24 +133,18 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 2e. Remove Wildcard Indexes ``````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-wildcard-index.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-wildcard-index.rst 2f. View Definitions/Collection Validation Definitions that Include 4.2 Operators ````````````````````````````````````````````````````````````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-view-definitions.rst +.. include:: /includes/extracts/4.2-downgrade-view-definitions.rst 3. Update ``tls``-Prefixed Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. include:: /includes/extracts/4.2-changes-options-tls-ssl-downgrade.rst +.. include:: /includes/extracts/4.2-changes-options-tls-ssl-downgrade.rst 4. Prepare Downgrade from ``zstd`` Compression ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -167,189 +154,186 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 ``zstd`` Journal Compression ```````````````````````````` -.. container:: +The :term:`zstd` compression library is available for journal data +compression starting in version 4.2. - The :term:`zstd` compression library is available for journal data - compression starting in version 4.2. +For any shard or config server member that uses :term:`zstd` library +for its journal compressor: - For any shard or config server member that uses :term:`zstd` library - for its journal compressor: - - If the member uses ``zstd`` for journal compression and :ref:`downgrade-sharded-cluster-prereq-zstd`, - .. include:: /includes/extracts/4.2-changes-zstd-journal-compression-config-only.rst +If the member uses ``zstd`` for journal compression and :ref:`downgrade-sharded-cluster-prereq-zstd`, + .. include:: /includes/extracts/4.2-changes-zstd-journal-compression-config-only.rst - If the member only uses ``zstd`` for journal compression only, - .. note:: +If the member only uses ``zstd`` for journal compression only, + .. note:: - The following procedure involves restarting the replica member as a - standalone without the journal. + The following procedure involves restarting the replica member as a + standalone without the journal. - #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: + #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: - .. code-block:: javascript + .. code-block:: javascript - db.getSiblingDB('admin').shutdownServer() + db.getSiblingDB('admin').shutdownServer() - #. Update the :doc:`configuration file - ` to prepare to restart as a - standalone: + #. Update the :doc:`configuration file + ` to prepare to restart as a + standalone: - - Set :setting:`storage.journal.enabled` to ``false``. + - Set :setting:`storage.journal.enabled` to ``false``. - - Set parameter :parameter:`skipShardingConfigurationChecks` to true. + - Set parameter :parameter:`skipShardingConfigurationChecks` to true. - - Set parameter ``disableLogicalSessionCacheRefresh`` to - ``true`` in the :setting:`setParameter` section. - - - Comment out the :ref:`replication ` - settings for your deployment. + - Set parameter ``disableLogicalSessionCacheRefresh`` to + ``true`` in the :setting:`setParameter` section. + + - Comment out the :ref:`replication ` + settings for your deployment. - - Comment out the :setting:`sharding.clusterRole` setting. + - Comment out the :setting:`sharding.clusterRole` setting. - - Set the :setting:`net.port` to the member's - current port, if it is not explicitly set. - - For example: + - Set the :setting:`net.port` to the member's + current port, if it is not explicitly set. - .. code-block:: none + For example: - storage: - journal: - enabled: false - setParameter: - skipShardingConfigurationChecks: true - disableLogicalSessionCacheRefresh: true - #replication: - # replSetName: shardA - #sharding: - # clusterRole: shardsvr - net: - port: 27218 + .. code-block:: none - If you use command-line options instead of a configuration file, you - will have to update the command-line option during the restart. - - #. Restart the :binary:`~bin.mongod` instance: + storage: + journal: + enabled: false + setParameter: + skipShardingConfigurationChecks: true + disableLogicalSessionCacheRefresh: true + #replication: + # replSetName: shardA + #sharding: + # clusterRole: shardsvr + net: + port: 27218 - - If you are using a configuration file: + If you use command-line options instead of a configuration file, you + will have to update the command-line option during the restart. + + #. Restart the :binary:`~bin.mongod` instance: - .. code-block:: sh + - If you are using a configuration file: - mongod -f + .. code-block:: sh - - If you are using command-line options instead of a - configuration file: - - - Include the :option:`--nojournal ` - option. - - - Set parameter :parameter:`skipShardingConfigurationChecks` to true. + mongod -f - - Set parameter ``disableLogicalSessionCacheRefresh`` to - ``true`` in the :option:`--setParameter ` option. + - If you are using command-line options instead of a + configuration file: + + - Include the :option:`--nojournal ` + option. + + - Set parameter :parameter:`skipShardingConfigurationChecks` to true. - - Remove any :ref:`replication command-line options - ` (such as :option:`--replSet - `). + - Set parameter ``disableLogicalSessionCacheRefresh`` to + ``true`` in the :option:`--setParameter ` option. - - Remove :option:`--shardsvr `/:option:`--configsvr ` option. + - Remove any :ref:`replication command-line options + ` (such as :option:`--replSet + `). - - Explicitly include :option:`--port ` set to - the instance's current port. + - Remove :option:`--shardsvr `/:option:`--configsvr ` option. - .. code-block:: sh + - Explicitly include :option:`--port ` set to + the instance's current port. - mongod --nojournal --setParameter skipShardingConfigurationChecks=true --setParameter disableLogicalSessionCacheRefresh=true --port ... + .. code-block:: sh - #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: + mongod --nojournal --setParameter skipShardingConfigurationChecks=true --setParameter disableLogicalSessionCacheRefresh=true --port ... - .. code-block:: javascript + #. Perform a clean shutdown of the :binary:`~bin.mongod` instance: - db.getSiblingDB('admin').shutdownServer() + .. code-block:: javascript - Confirm that the process is no longer running. + db.getSiblingDB('admin').shutdownServer() - #. Update the configuration file to prepare to restart with the new journal compressor: + Confirm that the process is no longer running. - - Remove the :setting:`storage.journal.enabled` setting. + #. Update the configuration file to prepare to restart with the new journal compressor: - - Remove the :parameter:`skipShardingConfigurationChecks` parameter setting. + - Remove the :setting:`storage.journal.enabled` setting. - - Remove the ``disableLogicalSessionCacheRefresh`` parameter - setting. + - Remove the :parameter:`skipShardingConfigurationChecks` parameter setting. - - Uncomment the :ref:`replication ` - settings for your deployment. + - Remove the ``disableLogicalSessionCacheRefresh`` parameter + setting. - - Uncomment the :setting:`sharding.clusterRole` setting. + - Uncomment the :ref:`replication ` + settings for your deployment. - - Remove - :setting:`storage.wiredTiger.engineConfig.journalCompressor` setting - to use the default journal compressor or specify a new value. + - Uncomment the :setting:`sharding.clusterRole` setting. - For example: + - Remove + :setting:`storage.wiredTiger.engineConfig.journalCompressor` setting + to use the default journal compressor or specify a new value. - .. code-block:: none + For example: - storage: - wiredTiger: - engineConfig: - journalCompressor: - replication: - replSetName: shardA - sharding: - clusterRole: shardsvr - net: - port: 27218 + .. code-block:: none - If you use command-line options instead of a configuration file, you - will have to update the command-line options during the restart - below. + storage: + wiredTiger: + engineConfig: + journalCompressor: + replication: + replSetName: shardA + sharding: + clusterRole: shardsvr + net: + port: 27218 + If you use command-line options instead of a configuration file, you + will have to update the command-line options during the restart + below. - #. Restart the :binary:`~bin.mongod` instance as a replica set member: - - If you are using a configuration file: + #. Restart the :binary:`~bin.mongod` instance as a replica set member: - .. code-block:: sh + - If you are using a configuration file: - mongod -f + .. code-block:: sh - - If you are using command-line options instead of a configuration - file: + mongod -f - - Remove the :option:`--nojournal ` option. + - If you are using command-line options instead of a configuration + file: - - Remove the :parameter:`skipShardingConfigurationChecks` parameter setting. + - Remove the :option:`--nojournal ` option. - - Remove the ``disableLogicalSessionCacheRefresh`` parameter - setting. + - Remove the :parameter:`skipShardingConfigurationChecks` parameter setting. - - Remove the :option:`--wiredTigerJournalCompressor ` command-line option to use - the default journal compressor or update to a new value. + - Remove the ``disableLogicalSessionCacheRefresh`` parameter + setting. - - Include :option:`--shardsvr `/:option:`--configsvr ` option. + - Remove the :option:`--wiredTigerJournalCompressor ` command-line option to use + the default journal compressor or update to a new value. - - Include your :ref:`replication command-line options - ` as well as any additional - options for your replica set member. + - Include :option:`--shardsvr `/:option:`--configsvr ` option. - .. code-block:: sh + - Include your :ref:`replication command-line options + ` as well as any additional + options for your replica set member. - mongod --shardsvr --wiredTigerJournalCompressor --replSet ... + .. code-block:: sh - .. note:: + mongod --shardsvr --wiredTigerJournalCompressor --replSet ... - If you encounter an unclean shutdown for a :binary:`~bin.mongod` - during the downgrade procedure such that you need to use the - journal files to recover, recover the - instance using the 4.2 :binary:`~bin.mongod` and then retry the - downgrade of the instance. +.. note:: + If you encounter an unclean shutdown for a :binary:`~bin.mongod` + during the downgrade procedure such that you need to use the + journal files to recover, recover the + instance using the 4.2 :binary:`~bin.mongod` and then retry the + downgrade of the instance. .. _downgrade-sharded-cluster-prereq-zstd: @@ -363,25 +347,21 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 steps *after* you perform the :ref:`prerequisite steps for the journal compressor `. -.. container:: - - The :term:`zstd` compression library is available starting in - version 4.2. For any config server member or shard member that has data - stored using :term:`zstd` compression, the downgrade procedure will - require an initial sync for that member. To prepare: +The :term:`zstd` compression library is available starting in +version 4.2. For any config server member or shard member that has data +stored using :term:`zstd` compression, the downgrade procedure will +require an initial sync for that member. To prepare: - .. include:: /includes/extracts/4.2-changes-zstd-downgrade-prereq.rst +.. include:: /includes/extracts/4.2-changes-zstd-downgrade-prereq.rst - Repeat for any other members that used :term:`zstd` compression. +Repeat for any other members that used :term:`zstd` compression. .. _downgrade-sharded-cluster-prereq-zstd-network: ``zstd`` Network Compression ```````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-changes-zstd-network-compression.rst +.. include:: /includes/extracts/4.2-changes-zstd-network-compression.rst 5. Remove Client-Side Field Level Encryption Document Validation Keywords ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/4.2-downgrade-standalone.txt b/source/release-notes/4.2-downgrade-standalone.txt index 068ad2b453d..1b9517c66a2 100644 --- a/source/release-notes/4.2-downgrade-standalone.txt +++ b/source/release-notes/4.2-downgrade-standalone.txt @@ -71,34 +71,27 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 2a. Index Key Size `````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-index-key.rst .. _4.2-downgrade-index-name-standalone: 2b. Index Name Length ````````````````````` - -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-index-name.rst 2c. Unique Index Version ```````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-unique-index.rst - .. tip:: +.. tip:: - Perform this operation after you have resolved any :ref:`index - key size <4.2-downgrade-index-key-standalone>` and :ref:`index - name length <4.2-downgrade-index-name-standalone>` issues first. + Perform this operation after you have resolved any :ref:`index + key size <4.2-downgrade-index-key-standalone>` and :ref:`index + name length <4.2-downgrade-index-name-standalone>` issues first. - Script - .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script.rst +Script + .. include:: /includes/extracts/4.2-downgrade-fcv-unique-index-script.rst 2d. Remove ``user_1_db_1`` System Unique Index `````````````````````````````````````````````` @@ -110,23 +103,17 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 2e. Remove Wildcard Indexes ``````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-fcv-wildcard-index.rst +.. include:: /includes/extracts/4.2-downgrade-fcv-wildcard-index.rst 2f. View Definitions/Collection Validation Definitions that Include 4.2 Operators ````````````````````````````````````````````````````````````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-downgrade-view-definitions.rst +.. include:: /includes/extracts/4.2-downgrade-view-definitions.rst 3. Update ``tls``-Prefixed Configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - .. include:: /includes/extracts/4.2-changes-options-tls-ssl-downgrade.rst +.. include:: /includes/extracts/4.2-changes-options-tls-ssl-downgrade.rst 4. Prepare Downgrade from ``zstd`` Compression ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -136,87 +123,81 @@ Remove all persisted 4.2 features that are :ref:`incompatible with 4.0 ``zstd`` Data Compression ````````````````````````` -.. container:: - - The :term:`zstd` compression library is available starting in - version 4.2. +The :term:`zstd` compression library is available starting in +version 4.2. - If your standalone has any data using :term:`zstd` compression: +If your standalone has any data using :term:`zstd` compression: - .. tip:: +.. tip:: - Perform this step after all the other prerequisite steps have - been performed. + Perform this step after all the other prerequisite steps have + been performed. - #. Stop all writes to your instance. +#. Stop all writes to your instance. - #. Create a :binary:`~bin.mongodump` of your database before - starting the downgrade; :binary:`~bin.mongodump` outputs - uncompressed data. +#. Create a :binary:`~bin.mongodump` of your database before + starting the downgrade; :binary:`~bin.mongodump` outputs + uncompressed data. - .. code-block:: sh + .. code-block:: sh - mongodump --host= --port= --out=mystandalone.uncompressed.fcv4.0 + mongodump --host= --port= --out=mystandalone.uncompressed.fcv4.0 - Include any other options, such as ``--username``, ``--password``, - and ``--authenticationDatabase`` if your standalone enforces - access control. + Include any other options, such as ``--username``, ``--password``, + and ``--authenticationDatabase`` if your standalone enforces + access control. - #. Create a new empty :option:`data directory ` for - the :binary:`~bin.mongod` instance. This directory will be used - in the downgrade procedure below. +#. Create a new empty :option:`data directory ` for + the :binary:`~bin.mongod` instance. This directory will be used + in the downgrade procedure below. - .. important:: + .. important:: - Ensure that the user account running :binary:`~bin.mongod` has - read and write permissions for the new directory. + Ensure that the user account running :binary:`~bin.mongod` has + read and write permissions for the new directory. - #. If you use a :doc:`configuration file - `, update the file to prepare for - the downgrade procedure: +#. If you use a :doc:`configuration file + `, update the file to prepare for + the downgrade procedure: - a. Delete - :setting:`storage.wiredTiger.collectionConfig.blockCompressor` - to use the default compressor (``snappy``) or - set to another 4.0 supported compressor. + a. Delete + :setting:`storage.wiredTiger.collectionConfig.blockCompressor` + to use the default compressor (``snappy``) or + set to another 4.0 supported compressor. - #. Update :setting:`storage.dbPath` to the new - data directory. + #. Update :setting:`storage.dbPath` to the new + data directory. - | If you use command-line options instead, you will have to update - the options in the procedure below. + | If you use command-line options instead, you will have to update + the options in the procedure below. .. _downgrade-standalone-prereq-zstd-journal: ``zstd`` Journal Compression ```````````````````````````` -.. container:: - - The :term:`zstd` compression library is available for journal data - compression starting in version 4.2. +The :term:`zstd` compression library is available for journal data +compression starting in version 4.2. - If the :binary:`~bin.mongod` instance uses :term:`zstd` library for - its journal compressor: +If the :binary:`~bin.mongod` instance uses :term:`zstd` library for +its journal compressor: - .. include:: /includes/extracts/4.2-changes-zstd-journal-compression-config-only.rst +.. include:: /includes/extracts/4.2-changes-zstd-journal-compression-config-only.rst - .. note:: +.. note:: - If you encounter an unclean shutdown for a :binary:`~bin.mongod` - during the downgrade procedure such that you need to use the - journal files to recover, recover the - instance using the 4.2 :binary:`~bin.mongod` and then retry the - downgrade of the instance. + If you encounter an unclean shutdown for a :binary:`~bin.mongod` + during the downgrade procedure such that you need to use the + journal files to recover, recover the + instance using the 4.2 :binary:`~bin.mongod` and then retry the + downgrade of the instance. .. _downgrade-standalone-prereq-zstd-network: ``zstd`` Network Compression ```````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.2-changes-zstd-network-compression.rst +.. include:: /includes/extracts/4.2-changes-zstd-network-compression.rst 5. Remove Client-Side Field Level Encryption Document Validation Keywords ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/release-notes/4.2-upgrade-replica-set.txt b/source/release-notes/4.2-upgrade-replica-set.txt index 3ebb9d901b7..90497d20f76 100644 --- a/source/release-notes/4.2-upgrade-replica-set.txt +++ b/source/release-notes/4.2-upgrade-replica-set.txt @@ -51,8 +51,8 @@ version 4.0.7. .. include:: /includes/extracts/changestream-resume-token-versions-4.2-greater.rst -.. admonition:: When upgrading from MongoDB 4.0.6 or earlier to MongoDB |newversion| - :class: important +.. important:: When upgrading from MongoDB 4.0.6 or earlier to MongoDB |newversion| + During the upgrade process, a client may try to resume change streams using the new ``v1`` resume token when connected to a member @@ -101,8 +101,6 @@ To ensure that all members of the replica set have ``featureCompatibilityVersion`` set to ``4.0``, connect to each replica set member and check the ``featureCompatibilityVersion``: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -114,8 +112,6 @@ To set or update ``featureCompatibilityVersion``, run the following command on the primary. A majority of the data-bearing members must be available: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } ) diff --git a/source/release-notes/4.2-upgrade-sharded-cluster.txt b/source/release-notes/4.2-upgrade-sharded-cluster.txt index 334b402ccfc..c6a2d429a68 100644 --- a/source/release-notes/4.2-upgrade-sharded-cluster.txt +++ b/source/release-notes/4.2-upgrade-sharded-cluster.txt @@ -50,8 +50,8 @@ version 4.0.7. .. include:: /includes/extracts/changestream-resume-token-versions-4.2-greater.rst -.. admonition:: When upgrading from MongoDB 4.0.6 or earlier to MongoDB |newversion| - :class: note +.. note:: When upgrading from MongoDB 4.0.6 or earlier to MongoDB |newversion| + During the upgrade process, the members of the sharded clusters will continue to produce ``v0`` tokens until the first diff --git a/source/release-notes/4.2-upgrade-standalone.txt b/source/release-notes/4.2-upgrade-standalone.txt index 114ee2f2e5f..e6523d2898b 100644 --- a/source/release-notes/4.2-upgrade-standalone.txt +++ b/source/release-notes/4.2-upgrade-standalone.txt @@ -49,8 +49,6 @@ Feature Compatibility Version The |oldversion| instance must have ``featureCompatibilityVersion`` set to ``4.0``. To check ``featureCompatibilityVersion``: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { getParameter: 1, featureCompatibilityVersion: 1 } ) @@ -61,8 +59,6 @@ The operation should return a result that includes To set or update ``featureCompatibilityVersion``, run the following command: -.. cssclass:: copyable-code - .. code-block:: javascript db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } ) diff --git a/source/release-notes/4.2.txt b/source/release-notes/4.2.txt index d183e568897..ef28b5013b2 100644 --- a/source/release-notes/4.2.txt +++ b/source/release-notes/4.2.txt @@ -4,8 +4,7 @@ Release Notes for MongoDB 4.2 .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -378,7 +377,10 @@ Distributed transactions: For more information, see :doc:`/core/transactions`. -.. seealso:: :ref:`4.2 Transaction Compatibility Changes <4.2-compatibility-txn>` +.. seealso:: + + :ref:`4.2 Transaction Compatibility Changes <4.2-compatibility-txn>` + Removed MMAPv1 Storage Engine ----------------------------- @@ -628,7 +630,10 @@ has always supported TLS 1.0 and later. - :option:`--tlsCertificateKeyFile ` vs. :option:`--sslPEMKeyFile ` - :option:`--tlsCertificateKeyFilePassword ` vs. :option:`--sslPEMKeyPassword ` -.. seealso:: :ref:`4.2-tlsclustercafile` +.. seealso:: + + :ref:`4.2-tlsclustercafile` + Deprecated ``SSL`` Options ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -684,7 +689,10 @@ establishing a connection. This lets you use separate Certificate Authorities to verify the client to server and server to client portions of the TLS handshake. -.. seealso:: :ref:`4.2-tls` +.. seealso:: + + :ref:`4.2-tls` + Forward Secrecy ~~~~~~~~~~~~~~~ @@ -768,8 +776,8 @@ for client-side field level encryption, see For an end-to-end procedure for configuring field level encryption using select MongoDB 4.2-compatible drivers, see the -:ecosystem:`Client Side Field Level Encryption Guide -`. +:driver:`Client Side Field Level Encryption Guide +`. Explicit (manual) encryption of fields Official MongoDB 4.2-compatible drivers and the MongoDB 4.2 @@ -980,7 +988,10 @@ MongoDB 4.2 adds the following new aggregation pipeline stages: .. include:: /includes/extracts/4.2-changes-planCacheStats-pref.rst - .. seealso:: :ref:`4.2-deprecated-plan-cache` + .. seealso:: + + :ref:`4.2-deprecated-plan-cache` + * - :pipeline:`$replaceWith` @@ -1042,7 +1053,9 @@ field values or updating one field using the value of another field(s). See the individual reference pages for details and examples. -.. seealso:: +.. seealso:: + + - :doc:`/tutorial/update-documents-with-aggregation-pipeline` @@ -1089,7 +1102,10 @@ to modify the change stream output (i.e. the event documents): .. include:: /includes/extracts/4.2-changes-change-stream-modification-error.rst -.. seealso:: :ref:`Change Streams Compatibility Changes <4.2-compatibility-change-streams>` +.. seealso:: + + :ref:`Change Streams Compatibility Changes <4.2-compatibility-change-streams>` + Update Enhancements ------------------- @@ -1212,7 +1228,10 @@ Extended JSON v2 For details on MongoDB extended JSON v2, see :doc:`/reference/mongodb-extended-json`. -.. seealso:: :ref:`4.2-compatibility-v2-query` +.. seealso:: + + :ref:`4.2-compatibility-v2-query` + ``mongofiles`` ~~~~~~~~~~~~~~ @@ -1662,14 +1681,19 @@ Starting in MongoDB 4.2, for :ref:`featureCompatibilityVersion :limit:`Index Key Limit`. For fCV set to ``"4.0"``, the limit still applies. -.. seealso:: :ref:`4.2 Indexes Compatibility Changes <4.2-index-compat-changes>` +.. seealso:: + + :ref:`4.2 Indexes Compatibility Changes <4.2-index-compat-changes>` + Remove Index Name Length Limit ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/extracts/4.2-changes-index-names.rst -.. seealso:: +.. seealso:: + + :ref:`4.2 Indexes Compatibility Changes <4.2-index-compat-changes>`, :ref:`4.2-compatibility-enabled` @@ -1750,7 +1774,9 @@ see :doc:`/core/query-plans`. ``planCacheKey`` .. include:: /includes/extracts/4.2-changes-plan-cache-key.rst - .. seealso:: :ref:`plan-cache-key` + .. seealso:: + + :ref:`plan-cache-key` - The ``queryHash`` and ``planCacheKey`` are available in: @@ -1770,13 +1796,16 @@ about the query plan cache: - :pipeline:`$planCacheStats` aggregation stage (*New in MongoDB 4.2*) -- :method:`PlanCache.listQueryShapes()` - method/:dbcommand:`planCacheListQueryShapes` command (*Deprecated in MongoDB 4.2*) +- ``PlanCache.listQueryShapes()`` + method/``planCacheListQueryShapes`` command (*Deprecated in MongoDB 4.2*) -- :method:`PlanCache.getPlansByQuery()` - method/:dbcommand:`planCacheListPlans` command (*Deprecated in MongoDB 4.2*) +- ``PlanCache.getPlansByQuery()`` + method/``planCacheListPlans`` command (*Deprecated in MongoDB 4.2*) -.. seealso:: :ref:`4.2-deprecated-plan-cache` +.. seealso:: + + :ref:`4.2-deprecated-plan-cache` + ``$regex`` and ``$not`` ~~~~~~~~~~~~~~~~~~~~~~~ @@ -1970,8 +1999,8 @@ supported in previous MongoDB versions. MongoDB ignores the :method:`~db.collection.createIndex()` and :method:`~db.collection.createIndexes()`. -.. admonition:: Requires featureCompatibilityVersion 4.2 - :class: note +.. note:: Requires featureCompatibilityVersion 4.2 + For MongoDB clusters upgraded from 4.0 to 4.2, you must set the :ref:`feature compatibility version (fcv) ` to ``4.2`` @@ -1997,7 +2026,7 @@ a detailed list of compatibility changes, see Upgrade Procedures ------------------ -.. admonition:: Feature Compatibility Version +.. important:: Feature Compatibility Version To upgrade, the 4.0 instances must have ``featureCompatibilityVersion`` set to ``4.0``. To check the version: diff --git a/source/release-notes/4.4-compatibility.txt b/source/release-notes/4.4-compatibility.txt index e1e193d2155..27718fa31f7 100644 --- a/source/release-notes/4.4-compatibility.txt +++ b/source/release-notes/4.4-compatibility.txt @@ -206,53 +206,50 @@ Map Reduce Changes Map-Reduce Output Change ~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Starting in MongoDB 4.4, :dbcommand:`mapReduce` removes the +``counts`` field from its output. - Starting in MongoDB 4.4, :dbcommand:`mapReduce` removes the - ``counts`` field from its output. +In earlier versions, the command includes a ``counts`` field in its +output. For example: - In earlier versions, the command includes a ``counts`` field in its - output. For example: - - .. code-block:: javascript +.. code-block:: javascript - "counts" : { - "input" : 4, - "emit" : 4, - "reduce" : 1, - "output" : 2 - }, + "counts" : { + "input" : 4, + "emit" : 4, + "reduce" : 1, + "output" : 2 + }, Map Function's Emit Limit ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Starting in MongoDB 4.4, the ``map`` function no longer restricts +the size of each ``emit()`` output to a half of MongoDB's +:ref:`maximum BSON document size `. - Starting in MongoDB 4.4, the ``map`` function no longer restricts - the size of each ``emit()`` output to a half of MongoDB's - :ref:`maximum BSON document size `. - - In earlier versions, a single emit can only hold half of MongoDB's - :ref:`maximum BSON document size ` +In earlier versions, a single emit can only hold half of MongoDB's +:ref:`maximum BSON document size ` Remove support for BSON Type JavaScript code with scope ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +:dbcommand:`mapReduce` no longer supports the deprecated BSON type +JavaScript code with scope (:doc:`BSON type 15 +`) for its functions. The ``map``, +``reduce``, and ``finalize`` functions must be either BSON type +String (:doc:`BSON type 2 `) or BSON type +JavaScript (:doc:`BSON type 13 `). To pass +constant values which will be accessible in the ``map``, ``reduce``, +and ``finalize`` functions, use the ``scope`` parameter. + +The use of JavaScript code with scope for the :dbcommand:`mapReduce` +functions has been deprecated since version 4.2.1. - :dbcommand:`mapReduce` no longer supports the deprecated BSON type - JavaScript code with scope (:doc:`BSON type 15 - `) for its functions. The ``map``, - ``reduce``, and ``finalize`` functions must be either BSON type - String (:doc:`BSON type 2 `) or BSON type - JavaScript (:doc:`BSON type 13 `). To pass - constant values which will be accessible in the ``map``, ``reduce``, - and ``finalize`` functions, use the ``scope`` parameter. +.. seealso:: - The use of JavaScript code with scope for the :dbcommand:`mapReduce` - functions has been deprecated since version 4.2.1. + :ref:`4.4-compatibility-deprecations` - .. seealso:: :ref:`4.4-compatibility-deprecations` Structured Logging ------------------ diff --git a/source/release-notes/4.4-downgrade-replica-set.txt b/source/release-notes/4.4-downgrade-replica-set.txt index c0e9f541150..b9d4000bb75 100644 --- a/source/release-notes/4.4-downgrade-replica-set.txt +++ b/source/release-notes/4.4-downgrade-replica-set.txt @@ -10,8 +10,7 @@ Downgrade |newversion| Replica Set to |oldversion| :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + .. include:: /includes/4.4-upgrade-replacements.rst @@ -51,42 +50,40 @@ that are persisted and/or update incompatible configuration settings. 1. Namespace Length ~~~~~~~~~~~~~~~~~~~ -.. container:: - - Starting in MongoDB 4.4: +Starting in MongoDB 4.4: - .. include:: /includes/fact-collection-namespace-limit.rst +.. include:: /includes/fact-collection-namespace-limit.rst - Before downgrading, resolve any collections or views with namespaces - that exceed the 120-byte :limit:`Namespace Length` limit for Feature - Compatibility Version (fCV) 4.2. +Before downgrading, resolve any collections or views with namespaces +that exceed the 120-byte :limit:`Namespace Length` limit for Feature +Compatibility Version (fCV) 4.2. - To determine if you have any collections or views with namespaces - that exceed the 120-byte limit, connect :binary:`~bin.mongo` shell - to the |target| and run: +To determine if you have any collections or views with namespaces +that exceed the 120-byte limit, connect :binary:`~bin.mongo` shell +to the |target| and run: - .. code-block:: javascript +.. code-block:: javascript - db.adminCommand("listDatabases").databases.forEach(function(d){ - let mdb = db.getSiblingDB(d.name); + db.adminCommand("listDatabases").databases.forEach(function(d){ + let mdb = db.getSiblingDB(d.name); - mdb.getCollectionInfos( ).forEach(function(c){ - namespace = d.name + "." + c.name - namespacelenBytes = encodeURIComponent(namespace).length + mdb.getCollectionInfos( ).forEach(function(c){ + namespace = d.name + "." + c.name + namespacelenBytes = encodeURIComponent(namespace).length - if (namespacelenBytes > 120) { - print (c.type.toUpperCase() + " namespace exceeds 120 bytes:: " + namespace ) - } - } ) - }) + if (namespacelenBytes > 120) { + print (c.type.toUpperCase() + " namespace exceeds 120 bytes:: " + namespace ) + } + } ) + }) - If any collection or view namespace exceeds 120 bytes, then :red:`prior` to - downgrading the fCV: +If any collection or view namespace exceeds 120 bytes, then :red:`prior` to +downgrading the fCV: - - Rename the collection using the :dbcommand:`renameCollection` command. +- Rename the collection using the :dbcommand:`renameCollection` command. - - For views, use :method:`db.createView()` to recreate the view - using a shorter name, then drop the original view. +- For views, use :method:`db.createView()` to recreate the view + using a shorter name, then drop the original view. .. _4.4-downgrade-feature-compatibility-rs: diff --git a/source/release-notes/4.4-downgrade-sharded-cluster.txt b/source/release-notes/4.4-downgrade-sharded-cluster.txt index 0c7ad226199..82e8b816d2b 100644 --- a/source/release-notes/4.4-downgrade-sharded-cluster.txt +++ b/source/release-notes/4.4-downgrade-sharded-cluster.txt @@ -10,8 +10,7 @@ Downgrade |newversion| Sharded Cluster to |oldversion| :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + .. include:: /includes/4.4-upgrade-replacements.rst @@ -46,52 +45,50 @@ configuration settings. 1. Namespace Length ~~~~~~~~~~~~~~~~~~~ -.. container:: - - Starting in MongoDB 4.4: +Starting in MongoDB 4.4: - .. include:: /includes/fact-collection-namespace-limit.rst +.. include:: /includes/fact-collection-namespace-limit.rst - Before downgrading, resolve any collections or views with namespaces - that exceed the 120-byte :limit:`Namespace Length` limit for Feature - Compatibility Version (fCV) 4.2. +Before downgrading, resolve any collections or views with namespaces +that exceed the 120-byte :limit:`Namespace Length` limit for Feature +Compatibility Version (fCV) 4.2. - To determine if you have any collections or views with namespaces - that exceed the 120-byte limit, connect :binary:`~bin.mongo` shell - to a |target| and run: +To determine if you have any collections or views with namespaces +that exceed the 120-byte limit, connect :binary:`~bin.mongo` shell +to a |target| and run: - .. code-block:: javascript +.. code-block:: javascript - db.adminCommand("listDatabases").databases.forEach(function(d){ - let mdb = db.getSiblingDB(d.name); + db.adminCommand("listDatabases").databases.forEach(function(d){ + let mdb = db.getSiblingDB(d.name); - mdb.getCollectionInfos( ).forEach(function(c){ - namespace = d.name + "." + c.name - namespacelenBytes = encodeURIComponent(namespace).length + mdb.getCollectionInfos( ).forEach(function(c){ + namespace = d.name + "." + c.name + namespacelenBytes = encodeURIComponent(namespace).length - if (namespacelenBytes > 120) { - print (c.type.toUpperCase() + " namespace exceeds 120 bytes:: " + namespace ) - } - } ) - }) + if (namespacelenBytes > 120) { + print (c.type.toUpperCase() + " namespace exceeds 120 bytes:: " + namespace ) + } + } ) + }) - If any collection or view namespace exceeds 120 bytes, then :red:`prior` to - downgrading the fCV: +If any collection or view namespace exceeds 120 bytes, then :red:`prior` to +downgrading the fCV: - - For unsharded collections, rename the collections using the - :dbcommand:`renameCollection` command. +- For unsharded collections, rename the collections using the + :dbcommand:`renameCollection` command. - - For sharded collections: +- For sharded collections: - - Use :pipeline:`$merge` to a new sharded collection with a shorter - name, then drop the original collection. + - Use :pipeline:`$merge` to a new sharded collection with a shorter + name, then drop the original collection. - - Use :binary:`~bin.mongoexport` and :binary:`~bin.mongoimport` into - a new collection with a shorter name, then drop the original collection. + - Use :binary:`~bin.mongoexport` and :binary:`~bin.mongoimport` into + a new collection with a shorter name, then drop the original collection. - - For views, use :method:`db.createView()` to recreate the view - using a shorter name, then drop the original view. - +- For views, use :method:`db.createView()` to recreate the view + using a shorter name, then drop the original view. + .. _4.4-downgrade-feature-compatibility-sharded-cluster: 2. Downgrade Feature Compatibility Version (fCV) @@ -203,43 +200,41 @@ include but are not limited to: 5. Update Missing Shard Keys ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +In MongoDB 4.4, shard key fields can be :ref:`missing from documents +` in a sharded collection. - In MongoDB 4.4, shard key fields can be :ref:`missing from documents - ` in a sharded collection. - - If you downgrade to 4.2 and a sharded collection contains documents - missing shard key fields, 4.2 :binary:`~bin.mongos` instances do not - return documents that are missing the shard key fields. To avoid - this situation, update the documents to includes the missing shard - key fields before you downgrade. +If you downgrade to 4.2 and a sharded collection contains documents +missing shard key fields, 4.2 :binary:`~bin.mongos` instances do not +return documents that are missing the shard key fields. To avoid +this situation, update the documents to includes the missing shard +key fields before you downgrade. - To find documents that are missing any part of the shard key, use the - :query:`$exists` operator. +To find documents that are missing any part of the shard key, use the +:query:`$exists` operator. - For example, if the collection ``contacts`` has the shard key ``{ - zipcode: 1 }``, to find documents without the ``zipcode`` field: +For example, if the collection ``contacts`` has the shard key ``{ +zipcode: 1 }``, to find documents without the ``zipcode`` field: - .. code-block:: javascript +.. code-block:: javascript - db.contacts.find( { zipcode: { $exists: false } } ) + db.contacts.find( { zipcode: { $exists: false } } ) - To set the missing shard key field to ``null`` for these documents, - you can use the :method:`db.collection.updateMany()` method: +To set the missing shard key field to ``null`` for these documents, +you can use the :method:`db.collection.updateMany()` method: - .. code-block:: javascript +.. code-block:: javascript - db.contacts.updateMany( { zipcode: { $exists: false } }, { $set: { zipcode: null } } ) + db.contacts.updateMany( { zipcode: { $exists: false } }, { $set: { zipcode: null } } ) - If setting the missing shard key field to a non-``null`` value, you - cannot use the :method:`db.collection.updateMany()` method and you - must perform the update within a transaction or as a retryable - write. For details, see :ref:`shard-key-missing-set`. +If setting the missing shard key field to a non-``null`` value, you +cannot use the :method:`db.collection.updateMany()` method and you +must perform the update within a transaction or as a retryable +write. For details, see :ref:`shard-key-missing-set`. 6. Update Shard Keys That Exceed 512 bytes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +.. versionchanged:: 4.4 In version 4.4, MongoDB removes the 512-byte limit on the shard key size. However, for MongoDB 4.2 and earlier, a shard key cannot diff --git a/source/release-notes/4.4-downgrade-standalone.txt b/source/release-notes/4.4-downgrade-standalone.txt index 71a6f30e7ca..c7a0cc7c686 100644 --- a/source/release-notes/4.4-downgrade-standalone.txt +++ b/source/release-notes/4.4-downgrade-standalone.txt @@ -10,8 +10,7 @@ Downgrade |newversion| Standalone to |oldversion| :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + .. include:: /includes/4.4-upgrade-replacements.rst @@ -51,42 +50,40 @@ configuration settings. These include: 1. Namespace Length ~~~~~~~~~~~~~~~~~~~ -.. container:: - - Starting in MongoDB 4.4: +Starting in MongoDB 4.4: - .. include:: /includes/fact-collection-namespace-limit.rst +.. include:: /includes/fact-collection-namespace-limit.rst - Before downgrading, resolve any collections or views with namespaces - that exceed the 120-byte :limit:`Namespace Length` limit for Feature - Compatibility Version (fCV) 4.2. +Before downgrading, resolve any collections or views with namespaces +that exceed the 120-byte :limit:`Namespace Length` limit for Feature +Compatibility Version (fCV) 4.2. - To determine if you have any collections or views with namespaces - that exceed the 120-byte limit, connect :binary:`~bin.mongo` shell - to the |target| and run: +To determine if you have any collections or views with namespaces +that exceed the 120-byte limit, connect :binary:`~bin.mongo` shell +to the |target| and run: - .. code-block:: javascript +.. code-block:: javascript - db.adminCommand("listDatabases").databases.forEach(function(d){ - let mdb = db.getSiblingDB(d.name); + db.adminCommand("listDatabases").databases.forEach(function(d){ + let mdb = db.getSiblingDB(d.name); - mdb.getCollectionInfos( ).forEach(function(c){ - namespace = d.name + "." + c.name - namespacelenBytes = encodeURIComponent(namespace).length + mdb.getCollectionInfos( ).forEach(function(c){ + namespace = d.name + "." + c.name + namespacelenBytes = encodeURIComponent(namespace).length - if (namespacelenBytes > 120) { - print (c.type.toUpperCase() + " namespace exceeds 120 bytes:: " + namespace ) - } - } ) - }) + if (namespacelenBytes > 120) { + print (c.type.toUpperCase() + " namespace exceeds 120 bytes:: " + namespace ) + } + } ) + }) - If any collection or view namespace exceeds 120 bytes, then :red:`prior` to - downgrading the fCV: +If any collection or view namespace exceeds 120 bytes, then :red:`prior` to +downgrading the fCV: - - Rename the collection using the :dbcommand:`renameCollection` command. +- Rename the collection using the :dbcommand:`renameCollection` command. - - For views, use :method:`db.createView()` to recreate the view - using a shorter name, then drop the original view. +- For views, use :method:`db.createView()` to recreate the view + using a shorter name, then drop the original view. .. _4.4-downgrade-feature-compatibility-standalone: diff --git a/source/release-notes/4.4-upgrade-replica-set.txt b/source/release-notes/4.4-upgrade-replica-set.txt index 72d8f04442b..220381cb36d 100644 --- a/source/release-notes/4.4-upgrade-replica-set.txt +++ b/source/release-notes/4.4-upgrade-replica-set.txt @@ -12,8 +12,7 @@ Upgrade a Replica Set to 4.4 :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + .. include:: /includes/4.4-upgrade-replacements.rst diff --git a/source/release-notes/4.4-upgrade-sharded-cluster.txt b/source/release-notes/4.4-upgrade-sharded-cluster.txt index 3ce770b19b7..05253075efa 100644 --- a/source/release-notes/4.4-upgrade-sharded-cluster.txt +++ b/source/release-notes/4.4-upgrade-sharded-cluster.txt @@ -12,8 +12,7 @@ Upgrade a Sharded Cluster to 4.4 :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + .. include:: /includes/4.4-upgrade-replacements.rst diff --git a/source/release-notes/4.4-upgrade-standalone.txt b/source/release-notes/4.4-upgrade-standalone.txt index c7823144307..4775fbb060d 100644 --- a/source/release-notes/4.4-upgrade-standalone.txt +++ b/source/release-notes/4.4-upgrade-standalone.txt @@ -13,8 +13,7 @@ Upgrade a Standalone to 4.4 :depth: 1 :class: singlecol -.. role:: red(strong) - :class: text-danger + .. include:: /includes/4.4-upgrade-replacements.rst diff --git a/source/release-notes/4.4.txt b/source/release-notes/4.4.txt index f932905e151..4e648d1f96b 100644 --- a/source/release-notes/4.4.txt +++ b/source/release-notes/4.4.txt @@ -219,24 +219,22 @@ to a collection to the same database where the aggregation is run. Starting in MongoDB 4.4 (also available starting in 4.2.4), :pipeline:`$indexStats` includes the following fields in its output: -.. container:: +.. list-table:: + :header-rows: 1 + :widths: 35 65 - .. list-table:: - :header-rows: 1 - :widths: 35 65 - - * - Field - - Description + * - Field + - Description - * - :ref:`shard ` + * - :ref:`shard ` - - Name of the shard, if applicable. + - Name of the shard, if applicable. - * - :ref:`spec ` - - Index specification document + * - :ref:`spec ` + - Index specification document - * - :ref:`building ` - - A boolean flag that indicates if the index is currently being built. + * - :ref:`building ` + - A boolean flag that indicates if the index is currently being built. ``$merge`` `````````` @@ -352,7 +350,9 @@ restart. exhaustion of system disk space due to a combination of high write volume and large retention period. -.. seealso:: :doc:`/core/replica-set-oplog` +.. seealso:: + + :doc:`/core/replica-set-oplog` Indexes Build Simultaneously on Data-Bearing Replica Set Members ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -380,18 +380,15 @@ Replica Set Reconfiguration Changes Changes to ``replSetReconfig`` `````````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.4-replSetReconfig-majority.rst - .. include:: /includes/extracts/4.4-replSetReconfig-single-node-voting-change.rst +.. include:: /includes/extracts/4.4-replSetReconfig-majority.rst + +.. include:: /includes/extracts/4.4-replSetReconfig-single-node-voting-change.rst Changes to ``replSetGetConfig`` ``````````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.4-replSetGetConfiguration-commitmentStatus.rst +.. include:: /includes/extracts/4.4-replSetGetConfiguration-commitmentStatus.rst .. |moreinfo| replace:: For more information, see the :ref:`replSetGetConfig ` command. @@ -399,9 +396,7 @@ Changes to ``replSetGetConfig`` Changes to Replica Configuration Document ````````````````````````````````````````` -.. container:: - - .. include:: /includes/extracts/4.4-replSetGetConfig-term-field.rst +.. include:: /includes/extracts/4.4-replSetGetConfig-term-field.rst Preferred Initial Sync Source ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -429,78 +424,72 @@ is :readmode:`primary`. You cannot specify a tag set or ``maxStalenessSeconds`` to :parameter:`initialSyncSourceReadPreference`. -.. seealso:: :ref:`replica-set-initial-sync-source-selection` +.. seealso:: + + :ref:`replica-set-initial-sync-source-selection` .. _4.4-mirrored-reads: Mirrored Reads ~~~~~~~~~~~~~~ -.. container:: +Starting in version 4.4, MongoDB provides :ref:`mirrored reads +` to pre-warm electable secondary members' cache with +the most recently accessed data. With mirrored reads, the primary can +mirror a subset of :ref:`operations +` that it receives and send them +to a subset of electable secondaries. Pre-warming the cache of a +secondary can help restore performance more quickly after an election. - Starting in version 4.4, MongoDB provides :ref:`mirrored reads - ` to pre-warm electable secondary members' cache with - the most recently accessed data. With mirrored reads, the primary can - mirror a subset of :ref:`operations - ` that it receives and send them - to a subset of electable secondaries. Pre-warming the cache of a - secondary can help restore performance more quickly after an election. - - .. note:: +.. note:: - The primary's response to the client is not affected by the - mirror reads. The mirrored reads are "fire-and-forget" operations - by the primary; i.e., the primary does not await the response for - the mirrored reads. + The primary's response to the client is not affected by the + mirror reads. The mirrored reads are "fire-and-forget" operations + by the primary; i.e., the primary does not await the response for + the mirrored reads. Mirrored Reads Parameter ```````````````````````` -.. container:: - - MongoDB 4.4 adds the following mirrored reads parameter. You can set - the parameter at startup using the :setting:`setParameter` - configuration file setting or the :option:`--setParameter ` command line option or at runtime with - :dbcommand:`setParameter` command: +MongoDB 4.4 adds the following mirrored reads parameter. You can set +the parameter at startup using the :setting:`setParameter` +configuration file setting or the :option:`--setParameter ` command line option or at runtime with +:dbcommand:`setParameter` command: - .. container:: +.. list-table:: + :widths: 20 80 + :header-rows: 1 - .. list-table:: - :widths: 20 80 - :header-rows: 1 + * - Parameter + - Description - * - Parameter - - Description - - * - :parameter:`mirrorReads` + * - :parameter:`mirrorReads` - - Specifies the ``samplingRate`` and ``maxTimeMS`` settings for - mirrored reads. + - Specifies the ``samplingRate`` and ``maxTimeMS`` settings for + mirrored reads. - ``{ samplingRate: , maxTimeMS: }`` + ``{ samplingRate: , maxTimeMS: }`` - A ``samplingRate`` of ``0`` turns off mirrored reads. + A ``samplingRate`` of ``0`` turns off mirrored reads. Mirrored Reads Metrics `````````````````````` -.. container:: +The command :dbcommand:`serverStatus` and its corresponding +:binary:`~bin.mongo` shell method :method:`db.serverStatus()` return +:serverstatus:`mirroredReads` if you specify the field's inclusion +in the operation: - The command :dbcommand:`serverStatus` and its corresponding - :binary:`~bin.mongo` shell method :method:`db.serverStatus()` return - :serverstatus:`mirroredReads` if you specify the field's inclusion - in the operation: - - .. code-block:: javascript +.. code-block:: javascript - db.runCommand( { serverStatus: 1, mirroredReads: 1 } ) + db.runCommand( { serverStatus: 1, mirroredReads: 1 } ) - or +or - .. code-block:: javascript +.. code-block:: javascript - db.serverStatus( { mirroredReads: 1 } ) + db.serverStatus( { mirroredReads: 1 } ) Replica Set Write Acknowledgement ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -518,43 +507,39 @@ Sharded Clusters Refinable Shard Keys ~~~~~~~~~~~~~~~~~~~~ -.. container:: - - Starting in 4.4, MongoDB provides the - :dbcommand:`refineCollectionShardKey` command. With the new command, - you can refine a collection's shard key by adding a suffix field or - fields to the existing key. Refining a collection's shard key allows - for a more fine-grained data distribution and can address situations - where the existing key has led to :ref:`jumbo (i.e. indivisible) - chunks ` due to insufficient cardinality. - - For example, you may have an existing ``orders`` collection with the - shard key ``{ customer_id: 1 }``. You can change the shard key by - adding a suffix ``order_id`` field to the shard key so that ``{ - customer_id: 1, order_id: 1 }`` becomes the new shard key, allowing - data distribution by both ``customer_id`` and ``order_id`` fields. - - To use the :dbcommand:`refineCollectionShardKey` command, the sharded - cluster must have :ref:`feature compatibility version (fcv) ` - of ``4.4``. For more information, see the - :dbcommand:`refineCollectionShardKey` command. - - .. note:: +Starting in 4.4, MongoDB provides the +:dbcommand:`refineCollectionShardKey` command. With the new command, +you can refine a collection's shard key by adding a suffix field or +fields to the existing key. Refining a collection's shard key allows +for a more fine-grained data distribution and can address situations +where the existing key has led to :ref:`jumbo (i.e. indivisible) +chunks ` due to insufficient cardinality. + +For example, you may have an existing ``orders`` collection with the +shard key ``{ customer_id: 1 }``. You can change the shard key by +adding a suffix ``order_id`` field to the shard key so that ``{ +customer_id: 1, order_id: 1 }`` becomes the new shard key, allowing +data distribution by both ``customer_id`` and ``order_id`` fields. + +To use the :dbcommand:`refineCollectionShardKey` command, the sharded +cluster must have :ref:`feature compatibility version (fcv) ` +of ``4.4``. For more information, see the +:dbcommand:`refineCollectionShardKey` command. - After you refine the shard key, it may be that not all documents in - the collection have the suffix field(s). To populate the missing - shard key field(s), see :ref:`shard-key-missing`. +.. note:: - Before refining the shard key, ensure that all or most documents in - the collection have the suffix fields, if possible, to avoid having - to populate the field afterwards. + After you refine the shard key, it may be that not all documents in + the collection have the suffix field(s). To populate the missing + shard key field(s), see :ref:`shard-key-missing`. - In earlier versions, once you select a shard key, you cannot modify the - shard key. + Before refining the shard key, ensure that all or most documents in + the collection have the suffix fields, if possible, to avoid having + to populate the field afterwards. -**Missing Shard Keys** +In earlier versions, once you select a shard key, you cannot modify the +shard key. -.. container:: +.. important:: Missing Shard Keys With the ability to refine a shard key with a suffix, it may be that not all documents in the collection have the suffix fields. Starting in @@ -566,90 +551,80 @@ Refinable Shard Keys Hedged Reads ~~~~~~~~~~~~ -.. container:: - - To minimize latencies, :binary:`~bin.mongos` instances, by default, can - use :ref:`hedge reads `. With hedged reads, the - :binary:`~bin.mongos` instances can route read operations to multiple - members per each queried shard and return results from the first - respondent per shard. By default, :binary:`~bin.mongos` instances - support using hedged reads. To turn off a :binary:`~bin.mongos` - instance's support for hedged reads, set the - :parameter:`readHedgingMode` parameter for the :binary:`~bin.mongos`. +To minimize latencies, :binary:`~bin.mongos` instances, by default, can +use :ref:`hedge reads `. With hedged reads, the +:binary:`~bin.mongos` instances can route read operations to multiple +members per each queried shard and return results from the first +respondent per shard. By default, :binary:`~bin.mongos` instances +support using hedged reads. To turn off a :binary:`~bin.mongos` +instance's support for hedged reads, set the +:parameter:`readHedgingMode` parameter for the :binary:`~bin.mongos`. - Hedged reads are specified per operation as part of the read - preference. Non-``primary`` :doc:`read preferences - ` support hedged reads. Read preference - :readmode:`nearest` specifies hedged read by default. +Hedged reads are specified per operation as part of the read +preference. Non-``primary`` :doc:`read preferences +` support hedged reads. Read preference +:readmode:`nearest` specifies hedged read by default. - For more information, see: +For more information, see: - - :ref:`mongos-hedged-reads` +- :ref:`mongos-hedged-reads` - - :ref:`replica-set-read-preference-behavior-mongos` +- :ref:`replica-set-read-preference-behavior-mongos` Hedged Read Parameters `````````````````````` -.. container:: - - .. list-table:: - :widths: 20 80 - :header-rows: 1 +.. list-table:: + :widths: 20 80 + :header-rows: 1 - * - Parameter - - Description + * - Parameter + - Description - * - :parameter:`readHedgingMode` + * - :parameter:`readHedgingMode` - - Enables or disables :binary:`~bin.mongos` instance's support for - hedged reads. + - Enables or disables :binary:`~bin.mongos` instance's support for + hedged reads. - * - :parameter:`maxTimeMSForHedgedReads` + * - :parameter:`maxTimeMSForHedgedReads` - - Specifies the maximimum time limit (in milliseconds) for the - additional read sent to :ref:`hedge a read operation - `. + - Specifies the maximimum time limit (in milliseconds) for the + additional read sent to :ref:`hedge a read operation + `. Hedged Read Option for Read Preference `````````````````````````````````````` -.. container:: +To specify hedged read for a read preference, MongoDB 4.4 introduces +the :ref:`read-preference-hedged-read`. To set using a MongoDB +driver, refer to the driver :driver:`read preference API +documentation`. - To specify hedged read for a read preference, MongoDB 4.4 introduces - the :ref:`read-preference-hedged-read`. To set using a MongoDB - driver, refer to the driver :ecosystem:`read preference API - documentation`. +The following :binary:`~bin.mongo` shell methods can accept hedge +options to enable hedged read for the specified read preference: - The following :binary:`~bin.mongo` shell methods can accept hedge - options to enable hedged read for the specified read preference: +- :method:`cursor.readPref()` - - :method:`cursor.readPref()` - - - :method:`Mongo.setReadPref()` +- :method:`Mongo.setReadPref()` Hedged Read Metrics ``````````````````` -.. container:: - - The command :dbcommand:`serverStatus` and its corresponding - :binary:`~bin.mongo` shell method :method:`db.serverStatus()` return - :serverstatus:`hedgingMetrics`. +The command :dbcommand:`serverStatus` and its corresponding +:binary:`~bin.mongo` shell method :method:`db.serverStatus()` return +:serverstatus:`hedgingMetrics`. ``balancerCollectionStatus`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - MongoDB 4.4 provides the command :dbcommand:`balancerCollectionStatus` - and the :binary:`~bin.mongo` shell helper method - :method:`sh.balancerCollectionStatus()` that return information about - whether the chunks of a sharded collection are balanced (i.e. do not - need to be moved) as of the time the command is run or need to be - moved. With the command, users can verify that initial chunk creation - and migration has finished. +MongoDB 4.4 provides the command :dbcommand:`balancerCollectionStatus` +and the :binary:`~bin.mongo` shell helper method +:method:`sh.balancerCollectionStatus()` that return information about +whether the chunks of a sharded collection are balanced (i.e. do not +need to be moved) as of the time the command is run or need to be +moved. With the command, users can verify that initial chunk creation +and migration has finished. Improved ``mongos`` Startup Procedure ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -743,7 +718,10 @@ where the hashed field is the shard key prefix: { "_id" : "hashed", "fieldA" : 1} ) -.. seealso:: :ref:`sharding-hashed-sharding` , :ref:`4.4-rel-notes-compound-hashed-index` +.. seealso:: + + :ref:`sharding-hashed-sharding` , :ref:`4.4-rel-notes-compound-hashed-index` + Chunk Migration Failover Resiliency Improvements ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -775,71 +753,61 @@ General Sharded Clusters Improvements Index Consistency Checks ```````````````````````` -.. container:: +Starting in MongoDB 4.4, the :doc:`config server +` primary, by default, checks for +index inconsistencies across the shards for sharded collections. The +command :dbcommand:`serverStatus` returns the field +:serverstatus:`shardedIndexConsistency` to report on index +inconsistencies when run on the config server primary. - Starting in MongoDB 4.4, the :doc:`config server - ` primary, by default, checks for - index inconsistencies across the shards for sharded collections. The - command :dbcommand:`serverStatus` returns the field - :serverstatus:`shardedIndexConsistency` to report on index - inconsistencies when run on the config server primary. +To configure the index consistency checks, MongoDB provides the +following parameters: - To configure the index consistency checks, MongoDB provides the - following parameters: +.. list-table:: + :header-rows: 1 + :widths: 40 65 - .. list-table:: - :header-rows: 1 - :widths: 40 65 - - * - Parameter - - - Description + * - Parameter - * - :parameter:`enableShardedIndexConsistencyCheck` - - - Enable or disable the index consistency checks. + - Description + + * - :parameter:`enableShardedIndexConsistencyCheck` + + - Enable or disable the index consistency checks. - * - :parameter:`shardedIndexConsistencyCheckIntervalMS` + * - :parameter:`shardedIndexConsistencyCheckIntervalMS` - - The interval at which the config server's primary checks the - index consistency of sharded collections. + - The interval at which the config server's primary checks the + index consistency of sharded collections. Concurrent ``removeShard`` Operations ````````````````````````````````````` -.. container:: +Starting in MongoDB 4.4, you can have more than one +:dbcommand:`removeShard` operation in progress. - Starting in MongoDB 4.4, you can have more than one - :dbcommand:`removeShard` operation in progress. - - In earlier versions, :dbcommand:`removeShard` returns an error if - another :dbcommand:`removeShard` operation is in progress. +In earlier versions, :dbcommand:`removeShard` returns an error if +another :dbcommand:`removeShard` operation is in progress. Shard Key Limit ``````````````` -.. container:: - - Starting in version 4.4, MongoDB removes the 512-byte limit on the - shard key size. For MongoDB 4.2 and earlier, a shard key cannot - exceed 512 bytes. +Starting in version 4.4, MongoDB removes the 512-byte limit on the +shard key size. For MongoDB 4.2 and earlier, a shard key cannot +exceed 512 bytes. Partial Results ``````````````` -.. container:: - - Starting in 4.4, if the :dbcommand:`find` or subsequent - :dbcommand:`getMore` commands return partial results due to the - unavailability of the queried shard(s), the output includes a - boolean flag ``partialResultsReturned``. +Starting in 4.4, if the :dbcommand:`find` or subsequent +:dbcommand:`getMore` commands return partial results due to the +unavailability of the queried shard(s), the output includes a +boolean flag ``partialResultsReturned``. Jumbo Chunk Migration ````````````````````` -.. container:: - - .. include:: /includes/extracts/4.4-changes-migrate-jumbo-chunks.rst +.. include:: /includes/extracts/4.4-changes-migrate-jumbo-chunks.rst Improved Catalog Cache Refresh `````````````````````````````` @@ -896,7 +864,10 @@ For more information, see: - :method:`db.collection.findOneAndUpdate()` - :method:`db.collection.findAndModify()` -.. seealso:: :ref:`4.4-compatibility-projection-restrictions` +.. seealso:: + + :ref:`4.4-compatibility-projection-restrictions` + .. _4.4-rel-notes-projection-meta-keyword: @@ -905,112 +876,111 @@ For more information, see: ``$meta`` Operator ~~~~~~~~~~~~~~~~~~ +``$meta`` Keyword Support + .. list-table:: -.. container:: - ``$meta`` Keyword Support - .. list-table:: + * - Starting in MongoDB 4.4, the :expression:`$meta` operator adds + support for retrieving the ``indexKey`` metadata. The ``indexKey`` + metadata is for debugging purposes only and not for application + logic. See :expression:`$meta` for more information. +``{ $meta: "textScore" }`` Usage with ``find()`` + .. list-table:: - * - Starting in MongoDB 4.4, the :expression:`$meta` operator adds - support for retrieving the ``indexKey`` metadata. The ``indexKey`` - metadata is for debugging purposes only and not for application - logic. See :expression:`$meta` for more information. - ``{ $meta: "textScore" }`` Usage with ``find()`` - .. list-table:: + * - Starting in version 4.4, MongoDB makes the following + :expression:`{ $meta: "textScore" } <$meta>` changes when used + with :method:`db.collection.find()`: + - You must specify the :query:`$text` operator in the query + predicate to use :expression:`{ $meta: "textScore" } <$meta>`. + + - You can sort the resulting documents by their search relevance, + i.e. :expression:`{ $meta: "textScore" } <$meta>`, without also + having to project the ``textScore``. - * - Starting in version 4.4, MongoDB makes the following - :expression:`{ $meta: "textScore" } <$meta>` changes when used - with :method:`db.collection.find()`: + | In earlier versions, to include :expression:`{ $meta: "textScore" + } <$meta>` expression in the :method:`~cursor.sort()`, you must + also include the same expression in the projection. + | - - You must specify the :query:`$text` operator in the query - predicate to use :expression:`{ $meta: "textScore" } <$meta>`. - - - You can sort the resulting documents by their search relevance, - i.e. :expression:`{ $meta: "textScore" } <$meta>`, without also - having to project the ``textScore``. + - If you include the :expression:`{ $meta: "textScore" } <$meta>` + expression in both the projection and sort, i.e. + ``db.collection.find(<$text search>, ).sort()``, + the projection and sort documents can have different field names + for the expression. - | In earlier versions, to include :expression:`{ $meta: "textScore" - } <$meta>` expression in the :method:`~cursor.sort()`, you must - also include the same expression in the projection. - | + | In previous versions of MongoDB, if you include the :expression:`{ + $meta: "textScore" } <$meta>` in both the projection and sort, you + must specify the same field name in both places. - - If you include the :expression:`{ $meta: "textScore" } <$meta>` - expression in both the projection and sort, i.e. - ``db.collection.find(<$text search>, ).sort()``, - the projection and sort documents can have different field names - for the expression. + For more information, see :ref:`project-meta-textscore-sort`. For + examples of ``"textScore"`` projections and sorts, see + :ref:`ex-text-search-score`. - | In previous versions of MongoDB, if you include the :expression:`{ - $meta: "textScore" } <$meta>` in both the projection and sort, you - must specify the same field name in both places. +.. seealso:: - For more information, see :ref:`project-meta-textscore-sort`. For - examples of ``"textScore"`` projections and sorts, see - :ref:`ex-text-search-score`. + -.. seealso:: :ref:`4.4-compatibility-meta-textscore` + :ref:`4.4-compatibility-meta-textscore` Transactions ------------ -.. container:: +Starting in MongoDB 4.4 with :ref:`feature compatibility version +(fcv) ` ``"4.4"``, you can create collections and indexes +inside a :doc:`multi-document transaction ` +unless the transaction is a cross-shard write transaction. - Starting in MongoDB 4.4 with :ref:`feature compatibility version - (fcv) ` ``"4.4"``, you can create collections and indexes - inside a :doc:`multi-document transaction ` - unless the transaction is a cross-shard write transaction. +When creating a collection inside a transaction: - When creating a collection inside a transaction: +- You can :ref:`implicitly create a collection + `, such as with: - - You can :ref:`implicitly create a collection - `, such as with: + - an insert operation against a non-existing collection; - - an insert operation against a non-existing collection; + - an update/findAndModify operation with ``upsert: true`` against + a non-existing collection. - - an update/findAndModify operation with ``upsert: true`` against - a non-existing collection. +- You can explicitly create a collection using the + :dbcommand:`create` command or its helper + :method:`db.createCollection()`. - - You can explicitly create a collection using the - :dbcommand:`create` command or its helper - :method:`db.createCollection()`. +When :ref:`creating an index ` +inside a transaction: - When :ref:`creating an index ` - inside a transaction: +- You can create an index on a non-existing collection. The + collection is created as part of the operation. - - You can create an index on a non-existing collection. The - collection is created as part of the operation. +- You can create an index on a new empty collection created earlier + in the same transaction. - - You can create an index on a new empty collection created earlier - in the same transaction. +For more details, see :ref:`transactions-create-collections-indexes`. - For more details, see :ref:`transactions-create-collections-indexes`. +MongoDB 4.4 adds a new parameter +:parameter:`shouldMultiDocTxnCreateCollectionAndIndexes` which can +enable (default) or disable collection and index creation inside a +transaction. When setting the parameter for a sharded cluster, set +the parameter on all shards. - MongoDB 4.4 adds a new parameter - :parameter:`shouldMultiDocTxnCreateCollectionAndIndexes` which can - enable (default) or disable collection and index creation inside a - transaction. When setting the parameter for a sharded cluster, set - the parameter on all shards. +For explicit creation of a collection or an index inside a +transaction, the transaction read concern level must be +:readconcern:`"local"`. Explicit creation is through: - For explicit creation of a collection or an index inside a - transaction, the transaction read concern level must be - :readconcern:`"local"`. Explicit creation is through: +.. list-table:: + :header-rows: 1 - .. list-table:: - :header-rows: 1 + * - Command + - Method - * - Command - - Method - - * - :dbcommand:`create` - - :method:`db.createCollection()` + * - :dbcommand:`create` + - :method:`db.createCollection()` - * - :dbcommand:`createIndexes` + * - :dbcommand:`createIndexes` - - | :method:`db.collection.createIndex()` - | :method:`db.collection.createIndexes()` + - | :method:`db.collection.createIndex()` + | :method:`db.collection.createIndexes()` .. seealso:: @@ -1073,24 +1043,20 @@ use of :setting:`system certificate store OCSP Stapling/Must Staple ````````````````````````` -.. container:: - - As part of its OCSP support, MongoDB 4.4 supports the following on - Linux: +As part of its OCSP support, MongoDB 4.4 supports the following on +Linux: - .. include:: /includes/list-ocsp-support.rst +.. include:: /includes/list-ocsp-support.rst OCSP Parameters ``````````````` -.. container:: +MongoDB 4.4 adds the following OCSP parameters. You can set these +parameters at startup using the :setting:`setParameter` configuration +file setting or the :option:`--setParameter ` +command line option: - MongoDB 4.4 adds the following OCSP parameters. You can set these - parameters at startup using the :setting:`setParameter` configuration - file setting or the :option:`--setParameter ` - command line option: - - .. include:: /includes/list-table-ocsp-parameters.rst +.. include:: /includes/list-table-ocsp-parameters.rst .. _4.4-rel-notes-certificate-expiration-warning: @@ -1104,7 +1070,7 @@ Specifically, the following connections to a ``mongod`` or ``mongos`` can trigger x.509 certificate expiry warnings: - A :binary:`~bin.mongo` shell or an application using a - :ecosystem:`MongoDB driver ` establishing a + :driver:`MongoDB driver ` establishing a :ref:`TLS connection ` *or* performing :ref:`x.509 client authentication ` with a certificate expiring in less than 30 days. (i.e. @@ -1409,7 +1375,10 @@ and ``_id``: Compound hashed indexes require :ref:`featureCompatibilityVersion ` set to ``4.4``. -.. seealso:: :ref:`4.4-rel-notes-sharding-compound-hashed` +.. seealso:: + + :ref:`4.4-rel-notes-sharding-compound-hashed` + Hidden Indexes ~~~~~~~~~~~~~~ @@ -1492,7 +1461,10 @@ For more complete documentation, see: .. include:: /includes/extracts/4.4-changes-drop-database-in-progress-indexes.rst -.. seealso:: :ref:`index-operations`. +.. seealso:: + + :ref:`index-operations`. + Deprecation of ``geoHaystack`` Index and ``geoSearch`` Command ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1631,7 +1603,9 @@ MongoDB returns an error *unless* the query specifies For more information on sorting and index use, see :ref:`sort-index-use`. -.. seealso:: +.. seealso:: + + | :method:`cursor.allowDiskUse()` | :limit:`Memory Limits on Sort Operations ` @@ -1660,9 +1634,11 @@ blocking sort requires less than 100 megabytes of memory. For instructions on enabling :ref:`allowDiskUse ` for queries issued through a MongoDB driver, defer to the documentation for your preferred -:ecosystem:`MongoDB 4.4-compatible driver `. +:driver:`MongoDB 4.4-compatible driver `. -.. seealso:: +.. seealso:: + + | :limit:`Memory Limits On Sort Operations ` | :ref:`sort-index-use` @@ -1679,7 +1655,10 @@ Validation Data Throughput Information .. include:: /includes/extracts/4.4-validate-data-throughput.rst -.. seealso:: :ref:`4.4-validate-method-signature` +.. seealso:: + + :ref:`4.4-validate-method-signature` + ``compact`` Behavior Change ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1715,7 +1694,9 @@ Previously, the ``force`` option, when set to ``true`` enabled set` and if set to ``false``, returned an error when run on a :term:`primary`. -.. seealso:: +.. seealso:: + + :ref:`compact` @@ -1749,85 +1730,83 @@ New Fields :dbcommand:`serverStatus` includes the following new fields in its output: -.. container:: +Aggregation Metrics + .. list-table:: - Aggregation Metrics - .. list-table:: - - * - | :serverstatus:`metrics.aggStageCounters` *(Also available in 4.2.6+ and 4.0.19+)* + * - | :serverstatus:`metrics.aggStageCounters` *(Also available in 4.2.6+ and 4.0.19+)* - Connections Metrics - .. list-table:: - - * - | :serverstatus:`connections.exhaustIsMaster` - | :serverstatus:`connections.awaitingTopologyChanges` +Connections Metrics + .. list-table:: - Default Read Concern Write Concern Metrics - .. list-table:: - - * - | :serverstatus:`defaultRWConcern` - | :serverstatus:`defaultRWConcern.defaultReadConcern` - | :serverstatus:`defaultRWConcern.defaultReadConcern.level` - | :serverstatus:`defaultRWConcern.defaultWriteConcern` - | :serverstatus:`defaultRWConcern.defaultWriteConcern.w` - | :serverstatus:`defaultRWConcern.defaultWriteConcern.wtimeout` - | :serverstatus:`defaultRWConcern.updateOpTime` - | :serverstatus:`defaultRWConcern.updateWallClockTime` - | :serverstatus:`defaultRWConcern.localUpdateWallClockTime` - * - | :serverstatus:`metrics.getLastError.default` - | :serverstatus:`metrics.getLastError.default.unsatisfiable` - | :serverstatus:`metrics.getLastError.default.wtimeouts` - - Latch Metrics - .. list-table:: - - * - | :serverstatus:`latchAnalysis` + * - | :serverstatus:`connections.exhaustIsMaster` + | :serverstatus:`connections.awaitingTopologyChanges` - Mirrored Reads Metrics - .. list-table:: - - * - | :serverstatus:`mirroredReads` - | :serverstatus:`mirroredReads.seen` - | :serverstatus:`mirroredReads.sent` - - Query Execution Metrics - .. list-table:: - - * - | :serverstatus:`metrics.queryExecutor.collectionScans` - | :serverstatus:`metrics.queryExecutor.collectionScans.nonTailable` - | :serverstatus:`metrics.queryExecutor.collectionScans.total` - - Replication Metrics - .. list-table:: - - * - | - | :serverstatus:`metrics.repl.network.replSetUpdatePosition.num` - | :serverstatus:`metrics.repl.network.getmores.numEmptyBatches` - | :serverstatus:`metrics.repl.network.oplogGetMoresProcessed` - | :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.num` - | :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.totalMillis` - | :serverstatus:`metrics.repl.syncSource.numSelections` - | :serverstatus:`metrics.repl.syncSource.numTimesChoseSame` - | :serverstatus:`metrics.repl.syncSource.numTimesChoseDifferent` - | :serverstatus:`metrics.repl.syncSource.numTimesCouldNotFind` - - Network Metrics - .. list-table:: - - * - | :serverstatus:`network.numSlowDNSOperations` - | :serverstatus:`network.numSlowSSLOperations` +Default Read Concern Write Concern Metrics + .. list-table:: - Security Metrics - .. list-table:: + * - | :serverstatus:`defaultRWConcern` + | :serverstatus:`defaultRWConcern.defaultReadConcern` + | :serverstatus:`defaultRWConcern.defaultReadConcern.level` + | :serverstatus:`defaultRWConcern.defaultWriteConcern` + | :serverstatus:`defaultRWConcern.defaultWriteConcern.w` + | :serverstatus:`defaultRWConcern.defaultWriteConcern.wtimeout` + | :serverstatus:`defaultRWConcern.updateOpTime` + | :serverstatus:`defaultRWConcern.updateWallClockTime` + | :serverstatus:`defaultRWConcern.localUpdateWallClockTime` + * - | :serverstatus:`metrics.getLastError.default` + | :serverstatus:`metrics.getLastError.default.unsatisfiable` + | :serverstatus:`metrics.getLastError.default.wtimeouts` + +Latch Metrics + .. list-table:: - * - | :serverstatus:`security.authentication.mechanisms` + * - | :serverstatus:`latchAnalysis` - Sharding Metrics - .. list-table:: - - * - | :serverstatus:`shardedIndexConsistency` - | :serverstatus:`shardingStatistics.rangeDeleterTasks` - | :serverstatus:`shardingStatistics.unfinishedMigrationFromPreviousPrimary` +Mirrored Reads Metrics + .. list-table:: + + * - | :serverstatus:`mirroredReads` + | :serverstatus:`mirroredReads.seen` + | :serverstatus:`mirroredReads.sent` + +Query Execution Metrics + .. list-table:: + + * - | :serverstatus:`metrics.queryExecutor.collectionScans` + | :serverstatus:`metrics.queryExecutor.collectionScans.nonTailable` + | :serverstatus:`metrics.queryExecutor.collectionScans.total` + +Replication Metrics + .. list-table:: + + * - | + | :serverstatus:`metrics.repl.network.replSetUpdatePosition.num` + | :serverstatus:`metrics.repl.network.getmores.numEmptyBatches` + | :serverstatus:`metrics.repl.network.oplogGetMoresProcessed` + | :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.num` + | :serverstatus:`metrics.repl.network.oplogGetMoresProcessed.totalMillis` + | :serverstatus:`metrics.repl.syncSource.numSelections` + | :serverstatus:`metrics.repl.syncSource.numTimesChoseSame` + | :serverstatus:`metrics.repl.syncSource.numTimesChoseDifferent` + | :serverstatus:`metrics.repl.syncSource.numTimesCouldNotFind` + +Network Metrics + .. list-table:: + + * - | :serverstatus:`network.numSlowDNSOperations` + | :serverstatus:`network.numSlowSSLOperations` + +Security Metrics + .. list-table:: + + * - | :serverstatus:`security.authentication.mechanisms` + +Sharding Metrics + .. list-table:: + + * - | :serverstatus:`shardedIndexConsistency` + | :serverstatus:`shardingStatistics.rangeDeleterTasks` + | :serverstatus:`shardingStatistics.unfinishedMigrationFromPreviousPrimary` ``replSetGetStatus`` Output Change ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -1970,8 +1949,8 @@ Earlier versions of MongoDB do not allow JavaScript execution on Global Default Read and Write Concern ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. admonition:: Requires ``featureCompatibilityVersion`` 4.4+ - :class: note +.. note:: Requires ``featureCompatibilityVersion`` 4.4+ + Each :binary:`~bin.mongod` in the replica set or sharded cluster *must* have :ref:`featureCompatibilityVersion ` set to at @@ -2186,7 +2165,7 @@ a detailed list of compatibility changes, see Upgrade Procedures ------------------ -.. admonition:: Feature Compatibility Version +.. important:: Feature Compatibility Version To upgrade from 4.2 deployment, the 4.2 deployment must have ``featureCompatibilityVersion`` set to ``4.2``. To check the version: @@ -2266,13 +2245,12 @@ https://github.com/mongodb/mongo/wiki/Submit-Bug-Reports for instructions on how to file a JIRA ticket for the MongoDB server or one of the related projects. -.. class:: hidden +.. toctree:: - .. toctree:: + /release-notes/4.4-compatibility + /release-notes/4.4-upgrade-standalone + /release-notes/4.4-upgrade-replica-set + /release-notes/4.4-upgrade-sharded-cluster + /release-notes/4.4-downgrade + /release-notes/4.4-changelog - /release-notes/4.4-compatibility - /release-notes/4.4-upgrade-standalone - /release-notes/4.4-upgrade-replica-set - /release-notes/4.4-upgrade-sharded-cluster - /release-notes/4.4-downgrade - /release-notes/4.4-changelog diff --git a/source/replication.txt b/source/replication.txt index acd541ded08..a672dfae020 100644 --- a/source/replication.txt +++ b/source/replication.txt @@ -129,9 +129,9 @@ Automatic Failover ------------------ When a primary does not communicate with the other members of the set -for more than the configured :rsconf:`electionTimeoutMillis` period -(10 seconds by default), an eligible secondary calls for an election -to nominate itself as the new primary. The cluster attempts to +for more than the configured :rsconf:`~settings.electionTimeoutMillis` +period (10 seconds by default), an eligible secondary calls for an +election to nominate itself as the new primary. The cluster attempts to complete the election of a new primary and resume normal operations. .. include:: /images/replica-set-trigger-election.rst diff --git a/source/security.txt b/source/security.txt index 3a1d29650cb..b539de24710 100644 --- a/source/security.txt +++ b/source/security.txt @@ -10,7 +10,7 @@ security features include: .. list-table:: :header-rows: 1 - :class: index-table index-table-less-padding + :widths: 33 33 33 * - Authentication - Authorization @@ -38,11 +38,10 @@ security features include: .. list-table:: :header-rows: 1 - :class: index-table index-table-less-padding + :widths: 50 50 * - Enterprise Only - Encryption - - * - :doc:`/core/kerberos` @@ -53,8 +52,7 @@ security features include: :doc:`/core/auditing` - :doc:`/core/security-client-side-encryption` - - - + Security Checklist ------------------ diff --git a/source/sharding.txt b/source/sharding.txt index 75f28e7eaf1..d843d3ea273 100644 --- a/source/sharding.txt +++ b/source/sharding.txt @@ -1,4 +1,4 @@ -.. index:: sharded clusters + .. _sharding-background: @@ -190,7 +190,7 @@ reads ` to minimize latencies. Storage Capacity ~~~~~~~~~~~~~~~~ -:term:`Sharding` distributes data across the :term:`shards ` in the +:term:`Sharding ` distributes data across the :term:`shards ` in the cluster, allowing each shard to contain a subset of the total cluster data. As the data set grows, additional shards increase the storage capacity of the cluster. @@ -260,7 +260,7 @@ perform read or write operations. You can connect to a :binary:`~bin.mongos` the same way you connect to a :binary:`~bin.mongod`, such as via the :binary:`~bin.mongo` shell or a MongoDB -:ecosystem:`driver `. +:driver:`driver `. .. _sharding-strategy: diff --git a/source/text-search.txt b/source/text-search.txt index b40f7780f9c..3d284fd1fc0 100644 --- a/source/text-search.txt +++ b/source/text-search.txt @@ -88,7 +88,7 @@ text search queries will compute a relevance score for each document that specifies how well a document matches the query. To sort the results in order of relevance score, you must explicitly -project the :projection:`$meta` ``textScore`` field and sort on it: +project the :expression:`$meta` ``textScore`` field and sort on it: .. code-block:: javascript diff --git a/source/tutorial.txt b/source/tutorial.txt index 4da1932b4ba..d1c25dc20d5 100644 --- a/source/tutorial.txt +++ b/source/tutorial.txt @@ -1,4 +1,4 @@ -.. index:: tutorials + .. _tutorial: .. _tutorials: @@ -26,8 +26,8 @@ Installation - :doc:`/tutorial/install-mongodb-on-os-x` - :doc:`/tutorial/install-mongodb-on-windows` -.. index:: tutorials; administration -.. index:: administration tutorials + + .. _administration-tutorials: .. _tutorials-administration: .. _tutorial-administration: @@ -101,8 +101,8 @@ Security - :doc:`/tutorial/control-access-to-mongodb-with-kerberos-authentication` - :doc:`/tutorial/create-a-vulnerability-report` -.. index:: tutorials; development patterns -.. index:: development tutorials + + .. _tutorials-development-patterns: .. _tutorial-development-patterns: @@ -117,8 +117,8 @@ Development Patterns - :doc:`/tutorial/troubleshoot-reduce-function` - :doc:`/tutorial/store-javascript-function-on-server` -.. index:: tutorials; text search -.. index:: text search tutorials + + .. _tutorials-text-search: .. _tutorial-text-search: diff --git a/source/tutorial/access-mongo-shell-help.txt b/source/tutorial/access-mongo-shell-help.txt index 0a06db77a54..fc2c8f960d3 100644 --- a/source/tutorial/access-mongo-shell-help.txt +++ b/source/tutorial/access-mongo-shell-help.txt @@ -92,7 +92,10 @@ In the :binary:`~bin.mongo` shell: show collections - .. seealso:: :ref:`4.0-compat-show-collections` + .. seealso:: + + :ref:`4.0-compat-show-collections` + - To see the help for methods available on the collection objects (e.g. ``db.``), use the ``db..help()`` @@ -175,4 +178,6 @@ shell, such as ``BinData()``, type ``help misc`` in the help misc -.. seealso:: :doc:`/reference/method` +.. seealso:: + + :doc:`/reference/method` diff --git a/source/tutorial/add-replica-set-arbiter.txt b/source/tutorial/add-replica-set-arbiter.txt index 22910ff2336..c80f27545b8 100644 --- a/source/tutorial/add-replica-set-arbiter.txt +++ b/source/tutorial/add-replica-set-arbiter.txt @@ -35,8 +35,8 @@ Considerations Read Concern ``majority`` and Three-Member PSA ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. admonition:: For 3-Member Primary-Secondary-Arbiter Architecture - :class: warning +.. warning:: For 3-Member Primary-Secondary-Arbiter Architecture + If you have a three-member replica set with a primary-secondary-arbiter (PSA) architecture or a sharded cluster diff --git a/source/tutorial/aggregation-zip-code-data-set.txt b/source/tutorial/aggregation-zip-code-data-set.txt index 853ac1d2e2f..116157ba4de 100644 --- a/source/tutorial/aggregation-zip-code-data-set.txt +++ b/source/tutorial/aggregation-zip-code-data-set.txt @@ -62,7 +62,7 @@ the stages in sequence. The :method:`aggregate() ` method in the :binary:`~bin.mongo` shell provides a wrapper around the :dbcommand:`aggregate` database command. See the documentation for your -:ecosystem:`driver ` for a more idiomatic interface +:driver:`driver ` for a more idiomatic interface for data aggregation operations. .. _aggregation-return-states-by-population: @@ -119,7 +119,9 @@ The equivalent :term:`SQL` for this aggregation operation is: GROUP BY state HAVING totalPop >= (10*1000*1000) -.. seealso:: :pipeline:`$group`, :pipeline:`$match`, :group:`$sum` +.. seealso:: + + :pipeline:`$group`, :pipeline:`$match`, :group:`$sum` Return Average City Population by State --------------------------------------- @@ -173,7 +175,9 @@ following: "avgCityPop" : 5335 } -.. seealso:: :pipeline:`$group`, :group:`$sum`, :group:`$avg` +.. seealso:: + + :pipeline:`$group`, :group:`$sum`, :group:`$avg` Return Largest and Smallest Cities by State ------------------------------------------- @@ -214,8 +218,8 @@ cities by population for each state: ] ) In this example, the :ref:`aggregation pipeline ` -consists of a :pipeline:`$group` stage, a :binary:`~bin.$sort` stage, -another :pipeline:`$group` stage, and a :binary:`~bin.$project` stage: +consists of a :pipeline:`$group` stage, a :pipeline:`$sort` stage, +another :pipeline:`$group` stage, and a :pipeline:`$project` stage: - The first :pipeline:`$group` stage groups the documents by the combination of the ``city`` and ``state``, calculates the :group:`sum diff --git a/source/tutorial/analyze-query-plan.txt b/source/tutorial/analyze-query-plan.txt index e1813386e20..c2b25e4ac01 100644 --- a/source/tutorial/analyze-query-plan.txt +++ b/source/tutorial/analyze-query-plan.txt @@ -76,7 +76,6 @@ Query with No Index ``quantity`` field has a value between ``100`` and ``200``, inclusive: - .. cssclass:: copyable-code .. code-block:: javascript db.inventory.find( { quantity: { $gte: 100, $lte: 200 } } ) @@ -93,7 +92,6 @@ Query with No Index :method:`cursor.explain("executionStats") ` cursor method to the end of the :command:`find` command: - .. cssclass:: copyable-code .. code-block:: javascript db.inventory.find( @@ -161,7 +159,7 @@ Query with No Index Copy the following filter into the Compass query bar and click :guilabel:`Find`: - .. class:: copyable-code + .. code-block:: javascript { quantity: { $gte: 100, $lte: 200 } } @@ -246,7 +244,6 @@ To support the query on the ``quantity`` field, add an index on the tabs: - id: shell content: | - .. cssclass:: copyable-code .. code-block:: javascript db.inventory.createIndex( { quantity: 1 } ) @@ -350,7 +347,7 @@ To support the query on the ``quantity`` field, add an index on the ``inventory`` collection and re-run the query from the previous step: - .. class:: copyable-code + .. code-block:: javascript { quantity: { $gte: 100, $lte: 200 } } @@ -429,7 +426,6 @@ in a very efficient query. Consider the following query: - .. cssclass:: copyable-code .. code-block:: javascript db.inventory.find( { @@ -455,7 +451,6 @@ in a very efficient query. ``type`` field. The second index orders by ``type`` first, and then the ``quantity`` field. - .. cssclass:: copyable-code .. code-block:: javascript db.inventory.createIndex( { quantity: 1, type: 1 } ) @@ -463,7 +458,6 @@ in a very efficient query. Evaluate the effect of the first index on the query: - .. cssclass:: copyable-code .. code-block:: javascript db.inventory.find( @@ -514,7 +508,6 @@ in a very efficient query. Evaluate the effect of the second index on the query: - .. cssclass:: copyable-code .. code-block:: javascript db.inventory.find( @@ -570,7 +563,9 @@ in a very efficient query. ``5`` when when using the compound index ``{ quantity: 1, type: 1 }``. - .. seealso:: :doc:`/core/query-optimization`, :doc:`/core/query-plans`, + .. seealso:: + + :doc:`/core/query-optimization`, :doc:`/core/query-plans`, :doc:`/tutorial/optimize-query-performance-with-indexes-and-projections`, :doc:`/applications/indexes` diff --git a/source/tutorial/avoid-text-index-name-limit.txt b/source/tutorial/avoid-text-index-name-limit.txt index 064d08bd41f..aa8130b3039 100644 --- a/source/tutorial/avoid-text-index-name-limit.txt +++ b/source/tutorial/avoid-text-index-name-limit.txt @@ -10,8 +10,8 @@ Specify Name for ``text`` Index :depth: 1 :class: singlecol -.. admonition:: Changed in MongoDB 4.2 - :class: note +.. note:: Changed in MongoDB 4.2 + .. include:: /includes/extracts/4.2-changes-index-names.rst diff --git a/source/tutorial/backup-and-restore-tools.txt b/source/tutorial/backup-and-restore-tools.txt index 65d697107ae..aa29050c707 100644 --- a/source/tutorial/backup-and-restore-tools.txt +++ b/source/tutorial/backup-and-restore-tools.txt @@ -4,8 +4,7 @@ Back Up and Restore with MongoDB Tools .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/backup-sharded-cluster-metadata.txt b/source/tutorial/backup-sharded-cluster-metadata.txt index 21112b6ec94..51c2d43c01d 100644 --- a/source/tutorial/backup-sharded-cluster-metadata.txt +++ b/source/tutorial/backup-sharded-cluster-metadata.txt @@ -35,7 +35,10 @@ When you perform this procedure, the cluster remains operational :ref:`sharding-balancing-disable-temporarily` section for more information on managing the balancer process. -.. seealso:: :doc:`/core/backups`. +.. seealso:: + + :doc:`/core/backups`. + .. [#read-only] While one of the three config servers is unavailable, the cluster cannot split any chunks nor can it migrate chunks diff --git a/source/tutorial/backup-sharded-cluster-with-database-dumps.txt b/source/tutorial/backup-sharded-cluster-with-database-dumps.txt index f1381384a1c..f0a4ae64607 100644 --- a/source/tutorial/backup-sharded-cluster-with-database-dumps.txt +++ b/source/tutorial/backup-sharded-cluster-with-database-dumps.txt @@ -6,8 +6,7 @@ Back Up a Sharded Cluster with Database Dumps .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. note:: diff --git a/source/tutorial/backup-sharded-cluster-with-filesystem-snapshots.txt b/source/tutorial/backup-sharded-cluster-with-filesystem-snapshots.txt index ae76c4f1cf1..78f1dcb7e9d 100644 --- a/source/tutorial/backup-sharded-cluster-with-filesystem-snapshots.txt +++ b/source/tutorial/backup-sharded-cluster-with-filesystem-snapshots.txt @@ -6,8 +6,7 @@ Back Up a Sharded Cluster with File System Snapshots .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/backup-with-filesystem-snapshots.txt b/source/tutorial/backup-with-filesystem-snapshots.txt index 4fab61ac474..f16e4975700 100644 --- a/source/tutorial/backup-with-filesystem-snapshots.txt +++ b/source/tutorial/backup-with-filesystem-snapshots.txt @@ -4,8 +4,7 @@ Back Up and Restore with Filesystem Snapshots .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -23,7 +22,9 @@ files. These methods complete quickly and work reliably, but require additional system configuration outside of MongoDB. -.. seealso:: :doc:`/core/backups` and +.. seealso:: + + :doc:`/core/backups` and :doc:`/tutorial/backup-and-restore-tools`. .. _snapshots-overview: diff --git a/source/tutorial/build-a-geohaystack-index.txt b/source/tutorial/build-a-geohaystack-index.txt index 8bae366f2de..eae09f97e82 100644 --- a/source/tutorial/build-a-geohaystack-index.txt +++ b/source/tutorial/build-a-geohaystack-index.txt @@ -12,8 +12,8 @@ Create a Haystack Index :depth: 1 :class: singlecol -.. admonition:: Deprecation - :class: important +.. important:: Deprecation + .. include:: /includes/extracts/4.4-changes-geo-deprecation.rst diff --git a/source/tutorial/build-indexes-on-replica-sets.txt b/source/tutorial/build-indexes-on-replica-sets.txt index 6c5df288f27..e7d17b08f07 100644 --- a/source/tutorial/build-indexes-on-replica-sets.txt +++ b/source/tutorial/build-indexes-on-replica-sets.txt @@ -1,5 +1,5 @@ -.. index:: index; replica set -.. index:: replica set; index + + .. _index-build-on-replica-sets: .. _index-building-replica-sets: @@ -89,70 +89,66 @@ Restart after making the following configuration updates: name: Configuration File content: | - .. container:: - - If you are using a configuration file, make the following - configuration updates: + If you are using a configuration file, make the following + configuration updates: - - Comment out the :setting:`replication.replSetName` option. + - Comment out the :setting:`replication.replSetName` option. - - Change the :setting:`net.port` to a different port. [#different-port]_ - Make a note of the original port setting as a comment. + - Change the :setting:`net.port` to a different port. [#different-port]_ + Make a note of the original port setting as a comment. - - Set parameter ``disableLogicalSessionCacheRefresh`` to - ``true`` in the :setting:`setParameter` section. + - Set parameter ``disableLogicalSessionCacheRefresh`` to + ``true`` in the :setting:`setParameter` section. - For example, the updated configuration file for a replica - set member will include content like the following example: + For example, the updated configuration file for a replica + set member will include content like the following example: - .. code-block:: yaml + .. code-block:: yaml - net: - bindIp: localhost, - port: 27217 - # port: 27017 - #replication: - # replSetName: myRepl - setParameter: - disableLogicalSessionCacheRefresh: true + net: + bindIp: localhost, + port: 27217 + # port: 27017 + #replication: + # replSetName: myRepl + setParameter: + disableLogicalSessionCacheRefresh: true - Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. + Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. - And restart: + And restart: - .. code-block:: sh + .. code-block:: sh - mongod --config + mongod --config - id: command-line name: Command-line Options content: | - .. container:: + If using command-line options, make the following + configuration updates: - If using command-line options, make the following - configuration updates: + - Remove :option:`--replSet `. - - Remove :option:`--replSet `. + - Modify :option:`--port ` to a different port. [#different-port]_ - - Modify :option:`--port ` to a different port. [#different-port]_ + - Set parameter ``disableLogicalSessionCacheRefresh`` + to ``true`` in the :option:`--setParameter ` option. - - Set parameter ``disableLogicalSessionCacheRefresh`` - to ``true`` in the :option:`--setParameter ` option. + For example, if your replica set member *normally* runs + with on the default port of ``27017`` and the + :option:`--replSet ` option, you would + specify a different port, omit the ``--replSet`` option, + and set ``disableLogicalSessionCacheRefresh`` parameter + to true: - For example, if your replica set member *normally* runs - with on the default port of ``27017`` and the - :option:`--replSet ` option, you would - specify a different port, omit the ``--replSet`` option, - and set ``disableLogicalSessionCacheRefresh`` parameter - to true: + .. code-block:: sh - .. code-block:: sh + mongod --port 27217 --setParameter disableLogicalSessionCacheRefresh=true - mongod --port 27217 --setParameter disableLogicalSessionCacheRefresh=true - - Other settings (e.g. :option:`--dbpath `, etc.) remain the same. + Other settings (e.g. :option:`--dbpath `, etc.) remain the same. .. [#different-port] By running the :binary:`~bin.mongod` on a different port, you ensure that the other members of the replica set and all @@ -200,57 +196,53 @@ For example, to restart your replica set member: name: Configuration File content: | - .. container:: - - If you are using a configuration file: + If you are using a configuration file: - - Revert to the original port number. + - Revert to the original port number. - - Uncomment the :setting:`replication.replSetName`. + - Uncomment the :setting:`replication.replSetName`. - - Remove parameter :parameter:`disableLogicalSessionCacheRefresh` - in the :setting:`setParameter` section. + - Remove parameter ``disableLogicalSessionCacheRefresh`` + in the :setting:`setParameter` section. - For example: + For example: - .. code-block:: yaml + .. code-block:: yaml - net: - bindIp: localhost, - port: 27017 - replication: - replSetName: myRepl + net: + bindIp: localhost, + port: 27017 + replication: + replSetName: myRepl - Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. + Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. - And restart: + And restart: - .. code-block:: sh + .. code-block:: sh - mongod --config + mongod --config - id: command-line name: Command-line Options content: | - .. container:: - - If you are using command-line options, + If you are using command-line options, - - Revert to the original port number + - Revert to the original port number - - Include the :option:`--replSet ` - option. + - Include the :option:`--replSet ` + option. - - Remove parameter ``disableLogicalSessionCacheRefresh``. + - Remove parameter ``disableLogicalSessionCacheRefresh``. - For example: + For example: - .. code-block:: sh + .. code-block:: sh - mongod --port 27017 --replSet myRepl + mongod --port 27017 --replSet myRepl - Other settings (e.g. :option:`--dbpath `, etc.) remain the same. + Other settings (e.g. :option:`--dbpath `, etc.) remain the same. Allow replication to catch up on this member. diff --git a/source/tutorial/build-indexes-on-sharded-clusters.txt b/source/tutorial/build-indexes-on-sharded-clusters.txt index 3b32fa1e9b4..15689005286 100644 --- a/source/tutorial/build-indexes-on-sharded-clusters.txt +++ b/source/tutorial/build-indexes-on-sharded-clusters.txt @@ -1,5 +1,5 @@ -.. index:: index; sharded clusters -.. index:: sharded clusters; index + + .. _index-build-on-sharded-clusters: @@ -173,104 +173,98 @@ procedure to build the index on the shard. C1. Stop One Secondary and Restart as a Standalone `````````````````````````````````````````````````` -.. container:: - - For an affected shard, stop the :binary:`~bin.mongod` process - associated with one of its secondary. Restart after making the following - configuration updates: - - .. tabs:: +For an affected shard, stop the :binary:`~bin.mongod` process +associated with one of its secondary. Restart after making the following +configuration updates: - tabs: - - id: config-file - name: Configuration File - content: | +.. tabs:: - .. container:: + tabs: + - id: config-file + name: Configuration File + content: | - If you are using a configuration file, make the following - configuration updates: + If you are using a configuration file, make the following + configuration updates: - - Change the :setting:`net.port` to a different port. [#different-port]_ - Make a note of the original port setting as a comment. + - Change the :setting:`net.port` to a different port. [#different-port]_ + Make a note of the original port setting as a comment. - - Comment out the :setting:`replication.replSetName` option. + - Comment out the :setting:`replication.replSetName` option. - - Comment out the :setting:`sharding.clusterRole` option. + - Comment out the :setting:`sharding.clusterRole` option. - - Set parameter :parameter:`skipShardingConfigurationChecks` - (also available for MongoDB 3.6.3+, 3.4.11+, 3.2.19+) to - ``true`` in the :setting:`setParameter` section. - - - Set parameter ``disableLogicalSessionCacheRefresh`` to - ``true`` in the :setting:`setParameter` section. + - Set parameter :parameter:`skipShardingConfigurationChecks` + (also available for MongoDB 3.6.3+, 3.4.11+, 3.2.19+) to + ``true`` in the :setting:`setParameter` section. + + - Set parameter ``disableLogicalSessionCacheRefresh`` to + ``true`` in the :setting:`setParameter` section. - For example, for a shard replica set member, the - updated configuration file will include content like - the following example: + For example, for a shard replica set member, the + updated configuration file will include content like + the following example: - .. code-block:: yaml + .. code-block:: yaml - net: - bindIp: localhost, - port: 27218 - # port: 27018 - #replication: - # replSetName: shardA - #sharding: - # clusterRole: shardsvr - setParameter: - skipShardingConfigurationChecks: true - disableLogicalSessionCacheRefresh: true + net: + bindIp: localhost, + port: 27218 + # port: 27018 + #replication: + # replSetName: shardA + #sharding: + # clusterRole: shardsvr + setParameter: + skipShardingConfigurationChecks: true + disableLogicalSessionCacheRefresh: true - And restart: + And restart: - .. code-block:: sh + .. code-block:: sh - mongod --config + mongod --config - Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. + Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. - - id: command-line - name: Command-line Options - content: | + - id: command-line + name: Command-line Options + content: | - .. container:: + If using command-line options, make the following + configuration updates: - If using command-line options, make the following - configuration updates: + - Modify :option:`--port ` to a different port. [#different-port]_ - - Modify :option:`--port ` to a different port. [#different-port]_ + - Remove :option:`--replSet `. - - Remove :option:`--replSet `. + - Remove :option:`--shardsvr ` if a + shard member and :option:`--configsvr ` if a config server member. - - Remove :option:`--shardsvr ` if a - shard member and :option:`--configsvr ` if a config server member. + - Set parameter + :parameter:`skipShardingConfigurationChecks` (also + available for MongoDB 3.6.3+, 3.4.11+, 3.2.19+) to + ``true`` in the :option:`--setParameter ` option. - - Set parameter - :parameter:`skipShardingConfigurationChecks` (also - available for MongoDB 3.6.3+, 3.4.11+, 3.2.19+) to - ``true`` in the :option:`--setParameter ` option. + - Set parameter ``disableLogicalSessionCacheRefresh`` + to ``true`` in the :option:`--setParameter ` option. - - Set parameter ``disableLogicalSessionCacheRefresh`` - to ``true`` in the :option:`--setParameter ` option. + For example, restart your shard replica set member + without the :option:`--replSet ` and + :option:`--shardsvr ` options. + Specify a new port number and set both the + :parameter:`skipShardingConfigurationChecks` and + ``disableLogicalSessionCacheRefresh`` parameters to + true: - For example, restart your shard replica set member - without the :option:`--replSet ` and - :option:`--shardsvr ` options. - Specify a new port number and set both the - :parameter:`skipShardingConfigurationChecks` and - ``disableLogicalSessionCacheRefresh`` parameters to - true: + .. code-block:: sh - .. code-block:: sh + mongod --port 27218 --setParameter skipShardingConfigurationChecks=true --setParameter disableLogicalSessionCacheRefresh=true - mongod --port 27218 --setParameter skipShardingConfigurationChecks=true --setParameter disableLogicalSessionCacheRefresh=true - - Other settings (e.g. :option:`--dbpath `, etc.) remain the same. + Other settings (e.g. :option:`--dbpath `, etc.) remain the same. .. [#different-port] By running the :binary:`~bin.mongod` on a different port, you ensure that the other members of the replica set and all @@ -282,145 +276,133 @@ C1. Stop One Secondary and Restart as a Standalone C2. Build the Index ``````````````````` -.. container:: - - Connect directly to the :binary:`~bin.mongod` instance running as a - standalone on the new port and create the new index for this - instance. +Connect directly to the :binary:`~bin.mongod` instance running as a +standalone on the new port and create the new index for this +instance. - For example, connect a :binary:`~bin.mongo` shell to the instance, - and use the :method:`db.collection.createIndex()` method to create - an ascending index on the ``username`` field of the ``records`` - collection: +For example, connect a :binary:`~bin.mongo` shell to the instance, +and use the :method:`db.collection.createIndex()` method to create +an ascending index on the ``username`` field of the ``records`` +collection: - .. code-block:: sh +.. code-block:: sh - db.records.createIndex( { username: 1 } ) + db.records.createIndex( { username: 1 } ) .. _tutorial-index-on-sharded-clusters-restart-mongod: C3. Restart the Program ``mongod`` as a Replica Set Member `````````````````````````````````````````````````````````` -.. container:: - - When the index build completes, shutdown the :binary:`~bin.mongod` - instance. Undo the configuration changes made when starting as a - standalone to return to its original configuration and restart. - - .. important:: - - Be sure to remove the - :parameter:`skipShardingConfigurationChecks` parameter and - ``disableLogicalSessionCacheRefresh`` parameter. +When the index build completes, shutdown the :binary:`~bin.mongod` +instance. Undo the configuration changes made when starting as a +standalone to return to its original configuration and restart. - For example, to restart your replica set shard member: - - .. tabs:: - - tabs: - - id: config-file - name: Configuration File - content: | +.. important:: - .. container:: + Be sure to remove the + :parameter:`skipShardingConfigurationChecks` parameter and + ``disableLogicalSessionCacheRefresh`` parameter. - If you are using a configuration file: +For example, to restart your replica set shard member: - - Revert to the original port number. +.. tabs:: - - Uncomment the :setting:`replication.replSetName`. + tabs: + - id: config-file + name: Configuration File + content: | - - Uncomment the :setting:`sharding.clusterRole`. + If you are using a configuration file: - - Remove parameter :parameter:`skipShardingConfigurationChecks` - in the :setting:`setParameter` section. + - Revert to the original port number. - - Remove parameter :parameter:`disableLogicalSessionCacheRefresh` - in the :setting:`setParameter` section. + - Uncomment the :setting:`replication.replSetName`. - .. code-block:: yaml + - Uncomment the :setting:`sharding.clusterRole`. - net: - bindIp: localhost, - port: 27018 - replication: - replSetName: shardA - sharding: - clusterRole: shardsvr + - Remove parameter :parameter:`skipShardingConfigurationChecks` + in the :setting:`setParameter` section. - Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. + - Remove parameter ``disableLogicalSessionCacheRefresh`` + in the :setting:`setParameter` section. - And restart: - - .. code-block:: sh - - mongod --config + .. code-block:: yaml - - id: command-line - name: Command-line Options - content: | + net: + bindIp: localhost, + port: 27018 + replication: + replSetName: shardA + sharding: + clusterRole: shardsvr - .. container:: + Other settings (e.g. :setting:`storage.dbPath`, etc.) remain the same. - If you are using command-line options: - - - Revert to the original port number. + And restart: - - Include :option:`--replSet `. + .. code-block:: sh - - Include :option:`--shardsvr ` if - a shard member or :option:`--configsvr ` if a config server member. + mongod --config - - Remove parameter - :parameter:`skipShardingConfigurationChecks`. + - id: command-line + name: Command-line Options + content: | - - Remove parameter ``disableLogicalSessionCacheRefresh``. + If you are using command-line options: + + - Revert to the original port number. + + - Include :option:`--replSet `. + + - Include :option:`--shardsvr ` if + a shard member or :option:`--configsvr ` if a config server member. - For example: + - Remove parameter + :parameter:`skipShardingConfigurationChecks`. - .. code-block:: sh + - Remove parameter ``disableLogicalSessionCacheRefresh``. - mongod --port 27018 --replSet shardA --shardsvr + For example: - Other settings (e.g. :option:`--dbpath `, etc.) remain the same. + .. code-block:: sh - Allow replication to catch up on this member. + mongod --port 27018 --replSet shardA --shardsvr + + Other settings (e.g. :option:`--dbpath `, etc.) remain the same. + +Allow replication to catch up on this member. C4. Repeat the Procedure for the Remaining Secondaries for the Shard ```````````````````````````````````````````````````````````````````` -.. container:: +Once the member catches up with the other members of the set, repeat +the procedure one member at a time for the remaining secondary +members for the shard: - Once the member catches up with the other members of the set, repeat - the procedure one member at a time for the remaining secondary - members for the shard: +#. :ref:`tutorial-index-on-sharded-clusters-stop-one-member` - #. :ref:`tutorial-index-on-sharded-clusters-stop-one-member` +#. :ref:`tutorial-index-on-sharded-clusters-build-index` - #. :ref:`tutorial-index-on-sharded-clusters-build-index` - - #. :ref:`tutorial-index-on-sharded-clusters-restart-mongod` +#. :ref:`tutorial-index-on-sharded-clusters-restart-mongod` C5. Build the Index on the Primary `````````````````````````````````` -.. container:: - - When all the secondaries for the shard have the new index, step down - the primary for the shard, restart it as a standalone using the - procedure described above, and build the index on the former primary: +When all the secondaries for the shard have the new index, step down +the primary for the shard, restart it as a standalone using the +procedure described above, and build the index on the former primary: - #. Use the :method:`rs.stepDown()` method in the :binary:`~bin.mongo` shell - to step down the primary. Upon successful stepdown, the current primary - becomes a secondary and the replica set members elect a new primary. +#. Use the :method:`rs.stepDown()` method in the :binary:`~bin.mongo` shell + to step down the primary. Upon successful stepdown, the current primary + becomes a secondary and the replica set members elect a new primary. - #. :ref:`tutorial-index-on-sharded-clusters-stop-one-member` +#. :ref:`tutorial-index-on-sharded-clusters-stop-one-member` - #. :ref:`tutorial-index-on-sharded-clusters-build-index` +#. :ref:`tutorial-index-on-sharded-clusters-build-index` - #. :ref:`tutorial-index-on-sharded-clusters-restart-mongod` +#. :ref:`tutorial-index-on-sharded-clusters-restart-mongod` D. Repeat for the Other Affected Shards ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/change-hostnames-in-a-replica-set.txt b/source/tutorial/change-hostnames-in-a-replica-set.txt index 1732481c7e1..f4664a8d18d 100644 --- a/source/tutorial/change-hostnames-in-a-replica-set.txt +++ b/source/tutorial/change-hostnames-in-a-replica-set.txt @@ -45,7 +45,9 @@ field. Use either of the following approaches: maintenance window, but the replica set will be unavailable during the operation. -.. seealso:: +.. seealso:: + + :ref:`Replica Set Reconfiguration Process `, diff --git a/source/tutorial/change-oplog-size.txt b/source/tutorial/change-oplog-size.txt index 3eaf32db930..8a218759021 100644 --- a/source/tutorial/change-oplog-size.txt +++ b/source/tutorial/change-oplog-size.txt @@ -58,7 +58,7 @@ database and run :method:`db.collection.stats()` against the ``oplog.rs`` collection. :method:`~db.collection.stats()` displays the oplog size as :data:`~collStats.maxSize`. -.. class:: copyable-code + .. code-block:: javascript use local diff --git a/source/tutorial/change-replica-set-wiredtiger.txt b/source/tutorial/change-replica-set-wiredtiger.txt index 96ff1123640..0ab11192396 100644 --- a/source/tutorial/change-replica-set-wiredtiger.txt +++ b/source/tutorial/change-replica-set-wiredtiger.txt @@ -52,16 +52,12 @@ For more information on PSA architecture and read concern MongoDB 3.0 or Greater ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: admonition - - .. include:: /includes/fact-wiredtiger-minimum-version.rst +.. include:: /includes/fact-wiredtiger-minimum-version.rst Default Bind to Localhost ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: admonition - - .. include:: /includes/fact-default-bind-ip-change.rst +.. include:: /includes/fact-default-bind-ip-change.rst XFS and WiredTiger ~~~~~~~~~~~~~~~~~~ @@ -94,9 +90,7 @@ A. Update the secondary members to WiredTiger. Update the secondary members one at a time: -.. container:: - - .. include:: /includes/steps/change-replica-set-wiredtiger.rst +.. include:: /includes/steps/change-replica-set-wiredtiger.rst Repeat the steps for the remaining secondary members, updating them one at a time. @@ -115,11 +109,9 @@ connect a :binary:`~bin.mongo` shell to the primary and use :method:`rs.stepDown()` to step down the primary and force an election of a new primary. -.. container:: admonition +.. code-block:: javascript - .. code-block:: javascript - - rs.stepDown() + rs.stepDown() C. Update the stepped down primary. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -127,9 +119,7 @@ C. Update the stepped down primary. When the primary has stepped down and become a secondary, update the secondary to use WiredTiger as before: -.. container:: admonition - - .. include:: /includes/steps/change-replica-set-wiredtiger.rst +.. include:: /includes/steps/change-replica-set-wiredtiger.rst .. |seemore| replace:: See :ref:`rs-mmapv1-wt-4.0-psa`. diff --git a/source/tutorial/change-sharded-cluster-wiredtiger.txt b/source/tutorial/change-sharded-cluster-wiredtiger.txt index 5f15b82a7ef..dd5a8ceb2da 100644 --- a/source/tutorial/change-sharded-cluster-wiredtiger.txt +++ b/source/tutorial/change-sharded-cluster-wiredtiger.txt @@ -70,16 +70,12 @@ For more information on PSA architecture and read concern MongoDB 3.0 or Greater ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: admonition - - .. include:: /includes/fact-wiredtiger-minimum-version.rst +.. include:: /includes/fact-wiredtiger-minimum-version.rst Default Bind to Localhost ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: admonition - - .. include:: /includes/fact-default-bind-ip-change.rst +.. include:: /includes/fact-default-bind-ip-change.rst Config Servers ~~~~~~~~~~~~~~ @@ -111,9 +107,7 @@ A. Update the secondary members to WiredTiger. Update the secondary members one at a time: -.. container:: admonition - - .. include:: /includes/steps/change-replica-set-wiredtiger.rst +.. include:: /includes/steps/change-replica-set-wiredtiger.rst Repeat the steps for the remaining secondary members, updating them one at a time. @@ -126,11 +120,9 @@ connect a :binary:`~bin.mongo` shell to the primary and use :method:`rs.stepDown()` to step down the primary and force an election of a new primary. -.. container:: admonition +.. code-block:: javascript - .. code-block:: javascript - - rs.stepDown() + rs.stepDown() C. Update the old primary. ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -138,9 +130,7 @@ C. Update the old primary. When the primary has stepped down and become a secondary, update the secondary to use WiredTiger as before: -.. container:: admonition - - .. include:: /includes/steps/change-replica-set-wiredtiger.rst +.. include:: /includes/steps/change-replica-set-wiredtiger.rst Repeat the procedure for the other shards. diff --git a/source/tutorial/change-standalone-wiredtiger.txt b/source/tutorial/change-standalone-wiredtiger.txt index d4910577c0c..d1e12870f1c 100644 --- a/source/tutorial/change-standalone-wiredtiger.txt +++ b/source/tutorial/change-standalone-wiredtiger.txt @@ -19,38 +19,32 @@ Considerations ``mongodump`` and ``mongorestore`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: admonition +This tutorial uses the :binary:`~bin.mongodump` and +:binary:`~bin.mongorestore` utilities to export and import data. - This tutorial uses the :binary:`~bin.mongodump` and - :binary:`~bin.mongorestore` utilities to export and import data. +- Ensure that these MongoDB package components are installed and + updated on your system. - - Ensure that these MongoDB package components are installed and - updated on your system. - - - Make sure you have sufficient drive space available for the - :binary:`~bin.mongodump` export file and the data files of your new - :binary:`~bin.mongod` instance running with WiredTiger. +- Make sure you have sufficient drive space available for the + :binary:`~bin.mongodump` export file and the data files of your new + :binary:`~bin.mongod` instance running with WiredTiger. Default Bind to Localhost ~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: admonition - - .. include:: /includes/fact-default-bind-ip-change.rst +.. include:: /includes/fact-default-bind-ip-change.rst - The tutorial runs :binary:`~bin.mongodump` and - :binary:`~bin.mongorestore` from the same host as the - :binary:`~bin.mongod` they are connecting to. If run remotely, - :binary:`~bin.mongodump` and :binary:`~bin.mongorestore` must specify - the ip address or the associated hostname in order to connect to the - :binary:`~bin.mongod`. +The tutorial runs :binary:`~bin.mongodump` and +:binary:`~bin.mongorestore` from the same host as the +:binary:`~bin.mongod` they are connecting to. If run remotely, +:binary:`~bin.mongodump` and :binary:`~bin.mongorestore` must specify +the ip address or the associated hostname in order to connect to the +:binary:`~bin.mongod`. MongoDB 3.0 or Greater ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: admonition - - .. include:: /includes/fact-wiredtiger-minimum-version.rst +.. include:: /includes/fact-wiredtiger-minimum-version.rst XFS and WiredTiger ~~~~~~~~~~~~~~~~~~ diff --git a/source/tutorial/clear-jumbo-flag.txt b/source/tutorial/clear-jumbo-flag.txt index 1444ab7e68b..96e8c884d03 100644 --- a/source/tutorial/clear-jumbo-flag.txt +++ b/source/tutorial/clear-jumbo-flag.txt @@ -35,9 +35,7 @@ The preferred manual way to clear the ``jumbo`` flag from a chunk is to attempt to split the chunk. If the chunk is divisible, MongoDB removes the flag upon successful split of the chunk. -.. container:: - - .. include:: /includes/steps/clear-jumbo-flag-preferred.rst +.. include:: /includes/steps/clear-jumbo-flag-preferred.rst Indivisible Chunks ~~~~~~~~~~~~~~~~~~ @@ -59,9 +57,7 @@ collection's shard key by adding a suffix field or fields to the existing key. By adding new field(s) to the shard key, indivisible jumbo chunks can become divisible. -.. container:: - - .. include:: /includes/steps/clear-jumbo-flag-refine-key.rst +.. include:: /includes/steps/clear-jumbo-flag-refine-key.rst .. _clear-jumbo-flag-manually: @@ -76,37 +72,39 @@ You can manually clear the flag using the following steps. chunk size, MongoDB will re-label the chunk as ``jumbo`` when MongoDB tries to move the chunk. -.. container:: +.. tabs:: - .. tabs:: - - .. tab:: MongoDB 4.2.3 and later (4.0.15 and later) - :tabid: clear-flag-command + .. tab:: MongoDB 4.2.3 and later (4.0.15 and later) + :tabid: clear-flag-command - Starting in version 4.2.3 and 4.0.15, MongoDB provides the - :dbcommand:`clearJumboFlag` command to manually clear the - ``jumbo`` flag. + Starting in version 4.2.3 and 4.0.15, MongoDB provides the + :dbcommand:`clearJumboFlag` command to manually clear the + ``jumbo`` flag. - .. important:: + .. important:: - Only use this method if the :ref:`preferred method - ` is *not* applicable. + Only use this method if the :ref:`preferred method + ` is *not* applicable. - .. include:: /includes/steps/clear-jumbo-flag-command.rst - + .. include:: /includes/steps/clear-jumbo-flag-command.rst + - .. tab:: MongoDB 4.2.2 and earlier (4.0.14 and earlier) - :tabid: clear-flag-manual + .. tab:: MongoDB 4.2.2 and earlier (4.0.14 and earlier) + :tabid: clear-flag-manual - .. important:: + .. important:: - Only use this method if the :ref:`preferred method - ` is *not* applicable. + Only use this method if the :ref:`preferred method + ` is *not* applicable. - Before modifying the :doc:`config database - `, *always* back up the config database. + Before modifying the :doc:`config database + `, *always* back up the config database. - .. include:: /includes/steps/clear-jumbo-flag.rst + .. include:: /includes/steps/clear-jumbo-flag.rst + +.. seealso:: + + - .. seealso:: :dbcommand:`refineCollectionShardKey` + :dbcommand:`refineCollectionShardKey` diff --git a/source/tutorial/configure-audit-filters.txt b/source/tutorial/configure-audit-filters.txt index a6e4d6374de..5973de55b19 100644 --- a/source/tutorial/configure-audit-filters.txt +++ b/source/tutorial/configure-audit-filters.txt @@ -12,8 +12,8 @@ Configure Audit Filters :depth: 1 :class: singlecol -.. admonition:: Auditing in MongoDB Atlas - :class: note +.. note:: Auditing in MongoDB Atlas + MongoDB Atlas supports auditing for all ``M10`` and larger clusters. Atlas supports specifying a JSON-formatted audit @@ -299,7 +299,9 @@ The following example audits the :method:`~db.collection.find()`, filter: '{ atype: "authCheck", "param.ns": "test.orders", "param.command": { $in: [ "find", "insert", "delete", "update", "findandmodify" ] } }' setParameter: { auditAuthorizationSuccess: true } -.. seealso:: +.. seealso:: + + :doc:`/tutorial/configure-auditing`, :doc:`/core/auditing`, :doc:`/reference/audit-message` diff --git a/source/tutorial/configure-auditing.txt b/source/tutorial/configure-auditing.txt index 346db5865ef..0207484adc9 100644 --- a/source/tutorial/configure-auditing.txt +++ b/source/tutorial/configure-auditing.txt @@ -10,8 +10,8 @@ Configure Auditing :depth: 1 :class: singlecol -.. admonition:: Auditing in MongoDB Atlas - :class: note +.. note:: Auditing in MongoDB Atlas + MongoDB Atlas supports auditing for all ``M10`` and larger clusters. Atlas supports specifying a JSON-formatted audit diff --git a/source/tutorial/configure-encryption.txt b/source/tutorial/configure-encryption.txt index fcbdda625a6..2b5043fef99 100644 --- a/source/tutorial/configure-encryption.txt +++ b/source/tutorial/configure-encryption.txt @@ -21,8 +21,8 @@ Overview Available for the WiredTiger Storage Engine Only. -.. admonition:: Changed in version 4.0 - :class: note +.. note:: Changed in version 4.0 + .. include:: /includes/fact-aes.rst @@ -56,7 +56,7 @@ to be compatible. .. include:: /includes/partners-security.rst -.. admonition:: Recommended +.. tip:: Recommended Using a key manager meets regulatory key management guidelines, such as HIPAA, PCI-DSS, and FERPA, and is recommended over the local key @@ -112,7 +112,9 @@ file. If successful, the process will log the following messages: [initandlisten] Created KMIP key with id: [initandlisten] Encryption key manager initialized using master key with id: -.. seealso:: :ref:`encryption-key-management-options` +.. seealso:: + + :ref:`encryption-key-management-options` .. _encrypt-with-existing-key: @@ -147,7 +149,9 @@ KMIP server. [#san]_ If ``SAN`` is present, :binary:`~bin.mongod` does not match against the ``CN``. If the hostname does not match the ``SAN`` (or ``CN``), the :binary:`~bin.mongod` will fail to connect. -.. seealso:: :ref:`encryption-key-management-options` +.. seealso:: + + :ref:`encryption-key-management-options` .. [#san] @@ -205,5 +209,7 @@ accessible by the owner of the :binary:`~bin.mongod` process. [initandlisten] Encryption key manager initialized with key file: -.. seealso:: :ref:`encryption-key-management-options` +.. seealso:: + + :ref:`encryption-key-management-options` diff --git a/source/tutorial/configure-fips.txt b/source/tutorial/configure-fips.txt index 438eb17f0fd..52a095341d9 100644 --- a/source/tutorial/configure-fips.txt +++ b/source/tutorial/configure-fips.txt @@ -24,7 +24,7 @@ command line. .. include:: /includes/extracts/security-prereq-configure-fips.rst -.. topic:: MongoDB and FIPS +.. important:: MongoDB and FIPS FIPS is property of the encryption system and not the access control system. However, if your environment requires FIPS compliant encryption @@ -54,22 +54,20 @@ FIPS mode is only available with `MongoDB Enterprise`_ edition. See FIPS mode is supported on the following platforms: -.. container:: +.. list-table:: + :header-rows: 1 - .. list-table:: - :header-rows: 1 + * - Platform + - TLS/SSL library - * - Platform - - TLS/SSL library + * - Linux + - OpenSSL - * - Linux - - OpenSSL + * - Windows + - Secure Channel (SChannel) - * - Windows - - Secure Channel (SChannel) - - * - macOS - - Secure Transport + * - macOS + - Secure Transport Configuring FIPS ---------------- diff --git a/source/tutorial/configure-replica-set-tag-sets.txt b/source/tutorial/configure-replica-set-tag-sets.txt index c8df0a12a2f..e0f4986a79e 100644 --- a/source/tutorial/configure-replica-set-tag-sets.txt +++ b/source/tutorial/configure-replica-set-tag-sets.txt @@ -1,6 +1,6 @@ -.. index:: replica set; tag sets -.. index:: read preference; tag sets -.. index:: tag sets; configuration + + + .. _replica-set-configuration-tag-sets: ============================== @@ -157,7 +157,10 @@ have been omitted for brevity): db.collection.find({}).readPref( "secondary", [ { "dc": "east"}, { "usage": "production" } ] ) - .. seealso:: :method:`Mongo.setReadPref()` + .. seealso:: + + :method:`Mongo.setReadPref()` + .. _configure-custom-write-concern: diff --git a/source/tutorial/configure-secondary-only-replica-set-member.txt b/source/tutorial/configure-secondary-only-replica-set-member.txt index f597484ef86..2eef5062719 100644 --- a/source/tutorial/configure-secondary-only-replica-set-member.txt +++ b/source/tutorial/configure-secondary-only-replica-set-member.txt @@ -15,7 +15,7 @@ Overview In a replica set, by default all :term:`secondary` members are eligible to become primary through the election process. You can use the -:data:`priority ` to affect the +:rsconf:`priority ` to affect the outcome of these elections by making some members more likely to become primary and other members less likely or unable to become primary. diff --git a/source/tutorial/configure-ssl-clients.txt b/source/tutorial/configure-ssl-clients.txt index c4e4cdffe95..7221bce5a2d 100644 --- a/source/tutorial/configure-ssl-clients.txt +++ b/source/tutorial/configure-ssl-clients.txt @@ -448,4 +448,6 @@ tools include: To use encrypted communication with these tools, use the same ``ssl`` options as the :binary:`~bin.mongo` shell. See :ref:`mongo-shell-ssl-connect`. -.. seealso:: :doc:`/tutorial/configure-ssl` +.. seealso:: + + :doc:`/tutorial/configure-ssl` diff --git a/source/tutorial/configure-ssl.txt b/source/tutorial/configure-ssl.txt index 5651441efb0..c0a7ebbc212 100644 --- a/source/tutorial/configure-ssl.txt +++ b/source/tutorial/configure-ssl.txt @@ -569,7 +569,9 @@ Next Steps To configure TLS/SSL support for clients, see :doc:`/tutorial/configure-ssl-clients`. -.. seealso:: :doc:`/tutorial/configure-x509-client-authentication` +.. seealso:: + + :doc:`/tutorial/configure-x509-client-authentication` .. _configure-ssl: @@ -1016,4 +1018,6 @@ Next Steps To configure TLS/SSL support for clients, see :doc:`/tutorial/configure-ssl-clients`. -.. seealso:: :doc:`/tutorial/configure-x509-client-authentication` +.. seealso:: + + :doc:`/tutorial/configure-x509-client-authentication` diff --git a/source/tutorial/configure-windows-netsh-firewall.txt b/source/tutorial/configure-windows-netsh-firewall.txt index d03df6d2b3f..3fbfd42601d 100644 --- a/source/tutorial/configure-windows-netsh-firewall.txt +++ b/source/tutorial/configure-windows-netsh-firewall.txt @@ -23,7 +23,10 @@ For a detailed over view of security practices and risk management for MongoDB, see :doc:`/security`. -.. seealso:: `Windows Firewall `_ +.. seealso:: + + `Windows Firewall `_ + documentation from Microsoft. Overview diff --git a/source/tutorial/configure-x509-client-authentication.txt b/source/tutorial/configure-x509-client-authentication.txt index 6266331d6a2..9c33ec92577 100644 --- a/source/tutorial/configure-x509-client-authentication.txt +++ b/source/tutorial/configure-x509-client-authentication.txt @@ -330,100 +330,98 @@ Authenticate with a x.509 Certificate (Using ``tls`` Options) as the ``ssl`` options since MongoDB has always supported TLS 1.0 and later. -.. container:: +After you have :ref:`added the x.509 client certificate subject as a +corresponding MongoDB user `, you can +authenticate with the client certificate. - After you have :ref:`added the x.509 client certificate subject as a - corresponding MongoDB user `, you can - authenticate with the client certificate. - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: connect - name: Connect with Authentication - content: | + - id: connect + name: Connect with Authentication + content: | - To authenticate during connection: + To authenticate during connection: - .. code-block:: sh + .. code-block:: sh - mongo --tls --tlsCertificateKeyFile --tlsCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 + mongo --tls --tlsCertificateKeyFile --tlsCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 - .. list-table:: - :header-rows: 1 - :widths: 30 70 + .. list-table:: + :header-rows: 1 + :widths: 30 70 - * - Option - - Notes + * - Option + - Notes - * - :option:`--tls ` - - + * - :option:`--tls ` + - - * - :option:`--tlsCertificateKeyFile ` - - Client's x.509 file. + * - :option:`--tlsCertificateKeyFile ` + - Client's x.509 file. - * - :option:`--tlsCAFile ` + * - :option:`--tlsCAFile ` - - Certificate Authority file to verify the - certificate presented by the - :binary:`~bin.mongod` - instance. + - Certificate Authority file to verify the + certificate presented by the + :binary:`~bin.mongod` + instance. - * - :option:`--authenticationDatabase ` - - Specify ``'$external'``. + * - :option:`--authenticationDatabase ` + - Specify ``'$external'``. - * - :option:`--authenticationMechanism ` - - Specify ``MONGODB-X509``. + * - :option:`--authenticationMechanism ` + - Specify ``MONGODB-X509``. - - id: authafter - name: Authenticate after Connection - content: | + - id: authafter + name: Authenticate after Connection + content: | - You can connect without authentication and use the - :method:`db.auth()` method to authenticate after - connection. + You can connect without authentication and use the + :method:`db.auth()` method to authenticate after + connection. - For example, if using the :binary:`~bin.mongo` shell, + For example, if using the :binary:`~bin.mongo` shell, - 1. Connect :binary:`~bin.mongo` shell to the :binary:`~bin.mongod` set up for - TLS/SSL: + 1. Connect :binary:`~bin.mongo` shell to the :binary:`~bin.mongod` set up for + TLS/SSL: - .. code-block:: sh + .. code-block:: sh - mongo --tls --tlsCertificateKeyFile --tlsCAFile + mongo --tls --tlsCertificateKeyFile --tlsCAFile - .. list-table:: - :header-rows: 1 - :widths: 25 75 + .. list-table:: + :header-rows: 1 + :widths: 25 75 - * - Option - - Notes + * - Option + - Notes - * - :option:`--tls ` - - + * - :option:`--tls ` + - - * - :option:`--tlsCertificateKeyFile ` - - Client's x.509 file. + * - :option:`--tlsCertificateKeyFile ` + - Client's x.509 file. - * - :option:`--tlsCAFile ` + * - :option:`--tlsCAFile ` - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. + - Certificate Authority file to verify the + certificate presented by + :binary:`~bin.mongod`/:binary:`~bin.mongos` + instance. - #. To perform the authentication, use the :method:`db.auth()` method in - the ``$external`` database. For the ``mechanism`` - field, specify ``"MONGODB-X509"``. + #. To perform the authentication, use the :method:`db.auth()` method in + the ``$external`` database. For the ``mechanism`` + field, specify ``"MONGODB-X509"``. - .. code-block:: javascript + .. code-block:: javascript - db.getSiblingDB("$external").auth( - { - mechanism: "MONGODB-X509" - } - ) + db.getSiblingDB("$external").auth( + { + mechanism: "MONGODB-X509" + } + ) .. _authenticate-with-x509-cert-ssl: @@ -440,97 +438,95 @@ Authenticate with a x.509 Certificate (Using ``ssl`` Options) as the ``ssl`` options since MongoDB has always supported TLS 1.0 and later. -.. container:: +After you have :ref:`added the x.509 client certificate subject as a +corresponding MongoDB user `, you can +authenticate with the client certificate. - After you have :ref:`added the x.509 client certificate subject as a - corresponding MongoDB user `, you can - authenticate with the client certificate. - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: connect - name: Connect with Authentication - content: | + - id: connect + name: Connect with Authentication + content: | - To authenticate during connection: + To authenticate during connection: - .. code-block:: sh + .. code-block:: sh - mongo --ssl --sslPEMKeyFile --sslCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 + mongo --ssl --sslPEMKeyFile --sslCAFile --authenticationDatabase '$external' --authenticationMechanism MONGODB-X509 - .. list-table:: - :header-rows: 1 - :widths: 30 70 + .. list-table:: + :header-rows: 1 + :widths: 30 70 - * - Option - - Notes + * - Option + - Notes - * - :option:`--ssl ` - - + * - :option:`--ssl ` + - - * - :option:`--sslPEMKeyFile ` - - Client's x.509 file. + * - :option:`--sslPEMKeyFile ` + - Client's x.509 file. - * - :option:`--sslCAFile ` + * - :option:`--sslCAFile ` - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. + - Certificate Authority file to verify the + certificate presented by + :binary:`~bin.mongod`/:binary:`~bin.mongos` + instance. - * - :option:`--authenticationDatabase ` - - Specify ``'$external'``. + * - :option:`--authenticationDatabase ` + - Specify ``'$external'``. - * - :option:`--authenticationMechanism ` - - Specify ``MONGODB-X509``. + * - :option:`--authenticationMechanism ` + - Specify ``MONGODB-X509``. - - id: authafter - name: Authenticate after Connection - content: | + - id: authafter + name: Authenticate after Connection + content: | - You can connect without authentication and use the - :method:`db.auth()` method to authenticate after - connection. + You can connect without authentication and use the + :method:`db.auth()` method to authenticate after + connection. - For example, if using the :binary:`~bin.mongo` shell, + For example, if using the :binary:`~bin.mongo` shell, - 1. Connect :binary:`~bin.mongo` shell to the :binary:`~bin.mongod` set up for - TLS/SSL: + 1. Connect :binary:`~bin.mongo` shell to the :binary:`~bin.mongod` set up for + TLS/SSL: - .. code-block:: sh + .. code-block:: sh - mongo --ssl --sslPEMKeyFile --sslCAFile + mongo --ssl --sslPEMKeyFile --sslCAFile - .. list-table:: - :header-rows: 1 - :widths: 25 75 + .. list-table:: + :header-rows: 1 + :widths: 25 75 - * - Option - - Notes + * - Option + - Notes - * - :option:`--ssl ` - - + * - :option:`--ssl ` + - - * - :option:`--sslPEMKeyFile ` - - Client's x.509 file. + * - :option:`--sslPEMKeyFile ` + - Client's x.509 file. - * - :option:`--sslCAFile ` + * - :option:`--sslCAFile ` - - Certificate Authority file to verify the - certificate presented by - :binary:`~bin.mongod`/:binary:`~bin.mongos` - instance. + - Certificate Authority file to verify the + certificate presented by + :binary:`~bin.mongod`/:binary:`~bin.mongos` + instance. - #. To perform the authentication, use the :method:`db.auth()` method in - the ``$external`` database. For the ``mechanism`` - field, specify ``"MONGODB-X509"``. + #. To perform the authentication, use the :method:`db.auth()` method in + the ``$external`` database. For the ``mechanism`` + field, specify ``"MONGODB-X509"``. - .. code-block:: javascript + .. code-block:: javascript - db.getSiblingDB("$external").auth( - { - mechanism: "MONGODB-X509" - } - ) + db.getSiblingDB("$external").auth( + { + mechanism: "MONGODB-X509" + } + ) diff --git a/source/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication.txt b/source/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication.txt index ac6174346ff..992c658f7db 100644 --- a/source/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication.txt +++ b/source/tutorial/control-access-to-mongodb-windows-with-kerberos-authentication.txt @@ -72,7 +72,8 @@ Assign Service Principal Name to MongoDB Windows Service ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use ``setspn.exe`` to assign the service principal name (SPN) to the -account running the ``mongod.exe`` and the ``mongos.exe`` service: +account running the :binary:`~bin.mongod.exe` and the +:binary:`~bin.mongos.exe` service: .. code-block:: sh diff --git a/source/tutorial/convert-standalone-to-replica-set.txt b/source/tutorial/convert-standalone-to-replica-set.txt index b4842b3f95d..9e1f7cc0182 100644 --- a/source/tutorial/convert-standalone-to-replica-set.txt +++ b/source/tutorial/convert-standalone-to-replica-set.txt @@ -64,4 +64,6 @@ To add members to this replica set, use the :method:`rs.add()` method. For more information on adding members to a replica set, see :doc:`/tutorial/expand-replica-set`. -.. seealso:: :doc:`/tutorial/convert-shard-standalone-to-shard-replica-set` +.. seealso:: + + :doc:`/tutorial/convert-shard-standalone-to-shard-replica-set` diff --git a/source/tutorial/create-chunks-in-sharded-cluster.txt b/source/tutorial/create-chunks-in-sharded-cluster.txt index 052de7a61c7..45a784b6125 100644 --- a/source/tutorial/create-chunks-in-sharded-cluster.txt +++ b/source/tutorial/create-chunks-in-sharded-cluster.txt @@ -65,4 +65,7 @@ To split empty chunks manually, you can run the :dbcommand:`split` command: - For information on manually migrating chunks, see :doc:`/tutorial/migrate-chunks-in-sharded-cluster`. -.. seealso:: :method:`sh.balancerCollectionStatus()` +.. seealso:: + + :method:`sh.balancerCollectionStatus()` + diff --git a/source/tutorial/deploy-replica-set-for-testing.txt b/source/tutorial/deploy-replica-set-for-testing.txt index 4d6f85e1e80..48cc196ab1a 100644 --- a/source/tutorial/deploy-replica-set-for-testing.txt +++ b/source/tutorial/deploy-replica-set-for-testing.txt @@ -222,7 +222,9 @@ Procedure Check the status of your replica set at any time with the :method:`rs.status()` operation. -.. seealso:: The documentation of the following shell functions for +.. seealso:: + + The documentation of the following shell functions for more information: - :method:`rs.initiate()` diff --git a/source/tutorial/deploy-replica-set.txt b/source/tutorial/deploy-replica-set.txt index e115894026b..d623ec839f1 100644 --- a/source/tutorial/deploy-replica-set.txt +++ b/source/tutorial/deploy-replica-set.txt @@ -41,4 +41,6 @@ access control is disabled. .. include:: /includes/steps/deploy-replica-set.rst -.. seealso:: :ref:`deploy-repl-set-with-auth` +.. seealso:: + + :ref:`deploy-repl-set-with-auth` diff --git a/source/tutorial/ensure-indexes-fit-ram.txt b/source/tutorial/ensure-indexes-fit-ram.txt index 389642bf2e2..e0373b6d8c8 100644 --- a/source/tutorial/ensure-indexes-fit-ram.txt +++ b/source/tutorial/ensure-indexes-fit-ram.txt @@ -36,7 +36,10 @@ fit in memory at the same time. There are some limited cases where indexes do not need to fit in memory. See :ref:`indexing-right-handed`. -.. seealso:: :dbcommand:`collStats` and :method:`db.collection.stats()` +.. seealso:: + + :dbcommand:`collStats` and :method:`db.collection.stats()` + .. _indexing-right-handed: diff --git a/source/tutorial/expand-replica-set.txt b/source/tutorial/expand-replica-set.txt index c82ab1495ea..596edae7afc 100644 --- a/source/tutorial/expand-replica-set.txt +++ b/source/tutorial/expand-replica-set.txt @@ -24,8 +24,7 @@ A replica set can have a maximum of seven :ref:`voting members `. To add a member to a replica set that already has seven voting members, you must either add the member as a :ref:`non-voting member ` or remove a -vote from an :data:`existing member -`. +vote from an :rsconf:`existing member `. Init Scripts ~~~~~~~~~~~~ @@ -171,10 +170,9 @@ Add a Member to an Existing Replica Set To check the state of the replica set members, run :method:`rs.status()`: - .. cssclass:: copyable-code .. code-block:: javascript - rs.status() + rs.status() #. Once the newly added member has transitioned into :replstate:`SECONDARY` state, use :method:`rs.reconfig()` to update diff --git a/source/tutorial/force-member-to-be-primary.txt b/source/tutorial/force-member-to-be-primary.txt index 8505d594bdc..b74681c3272 100644 --- a/source/tutorial/force-member-to-be-primary.txt +++ b/source/tutorial/force-member-to-be-primary.txt @@ -104,8 +104,8 @@ This procedure assumes this configuration: amount of time with no primary following failover. - The step down forces on election in which ``m3.example.net`` - becomes primary based on its :data:`priority - ` setting. + becomes primary based on its + :rsconf:`priority ` setting. #. Optionally, if ``m3.example.net`` is more than 10 seconds behind ``m1.example.net``'s optime, and if you don't need to have a primary diff --git a/source/tutorial/geospatial-tutorial.txt b/source/tutorial/geospatial-tutorial.txt index 7aa252d7571..d570ae3543a 100644 --- a/source/tutorial/geospatial-tutorial.txt +++ b/source/tutorial/geospatial-tutorial.txt @@ -196,7 +196,7 @@ Find Restaurants within a Distance To find restaurants within a specified distance of a point, you can use either :query:`$geoWithin` with :query:`$centerSphere` to return results -in unsorted order, or :query:`nearSphere` with :query:`$maxDistance` if you need +in unsorted order, or :query:`$nearSphere` with :query:`$maxDistance` if you need results sorted by distance. Unsorted with ``$geoWithin`` diff --git a/source/tutorial/getting-started.txt b/source/tutorial/getting-started.txt index 957f22556f9..257ba5b0556 100644 --- a/source/tutorial/getting-started.txt +++ b/source/tutorial/getting-started.txt @@ -11,231 +11,219 @@ The following page provides various examples for querying in the MongoDB shell. For examples using MongoDB drivers, refer to the links in the :ref:`gs-additional-examples` section. -.. only:: website +.. _mongo-web-shell: - .. _mongo-web-shell: - - Examples - -------- +Examples +-------- - .. include:: /includes/fact-mws.rst +.. include:: /includes/fact-mws.rst - Click inside the shell to connect. Once connected, you can run the - examples in the shell above. +Click inside the shell to connect. Once connected, you can run the +examples in the shell above. .. tabs:: .. tab:: 0. Switch Database :tabid: example-0 - .. container:: - - Within the :ref:`shell `, ``db`` refers to - your current database. Type ``db`` to display the current - database. + Within the :ref:`shell `, ``db`` refers to + your current database. Type ``db`` to display the current + database. - .. code-block:: javascript + .. code-block:: javascript - db + db - The operation should return ``test``, which is the default - database. + The operation should return ``test``, which is the default + database. - To switch databases, type ``use ``. For example, to switch - to the ``examples`` database: + To switch databases, type ``use ``. For example, to switch + to the ``examples`` database: - .. code-block:: javascript + .. code-block:: javascript - use examples + use examples - You do not need to create the database before you switch. - MongoDB creates the database when you first store data in that - database (such as create the first collection in the database). + You do not need to create the database before you switch. + MongoDB creates the database when you first store data in that + database (such as create the first collection in the database). - To verify that your database is now ``examples``, type ``db`` in - the :ref:`shell ` above. + To verify that your database is now ``examples``, type ``db`` in + the :ref:`shell ` above. - .. code-block:: javascript + .. code-block:: javascript - db + db - To create a collection in the database, see the next tab. + To create a collection in the database, see the next tab. .. tab:: 1. Populate a collection (Insert) :tabid: example-1 - .. container:: + MongoDB stores documents in :doc:`collections + `. Collections are analogous to + tables in relational databases. If a collection does not exist, + MongoDB creates the collection when you first store data for that + collection. - MongoDB stores documents in :doc:`collections - `. Collections are analogous to - tables in relational databases. If a collection does not exist, - MongoDB creates the collection when you first store data for that - collection. + The following example uses the + :method:`db.collection.insertMany()` method to insert new + :doc:`documents ` into the ``inventory`` + collection. You can copy and paste the example into the + :ref:`shell ` above. - The following example uses the - :method:`db.collection.insertMany()` method to insert new - :doc:`documents ` into the ``inventory`` - collection. You can copy and paste the example into the - :ref:`shell ` above. + .. code-block:: javascript - .. code-block:: javascript + db.inventory.insertMany([ + { item: "journal", qty: 25, status: "A", size: { h: 14, w: 21, uom: "cm" }, tags: [ "blank", "red" ] }, + { item: "notebook", qty: 50, status: "A", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank" ] }, + { item: "paper", qty: 10, status: "D", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank", "plain" ] }, + { item: "planner", qty: 0, status: "D", size: { h: 22.85, w: 30, uom: "cm" }, tags: [ "blank", "red" ] }, + { item: "postcard", qty: 45, status: "A", size: { h: 10, w: 15.25, uom: "cm" }, tags: [ "blue" ] } + ]); - db.inventory.insertMany([ - { item: "journal", qty: 25, status: "A", size: { h: 14, w: 21, uom: "cm" }, tags: [ "blank", "red" ] }, - { item: "notebook", qty: 50, status: "A", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank" ] }, - { item: "paper", qty: 10, status: "D", size: { h: 8.5, w: 11, uom: "in" }, tags: [ "red", "blank", "plain" ] }, - { item: "planner", qty: 0, status: "D", size: { h: 22.85, w: 30, uom: "cm" }, tags: [ "blank", "red" ] }, - { item: "postcard", qty: 45, status: "A", size: { h: 10, w: 15.25, uom: "cm" }, tags: [ "blue" ] } - ]); + // MongoDB adds an _id field with an ObjectId value if the field is not present in the document - // MongoDB adds an _id field with an ObjectId value if the field is not present in the document + The operation returns a document that contains the + acknowledgement indicator and an array that contains the + ``_id`` of each successfully inserted documents. - The operation returns a document that contains the - acknowledgement indicator and an array that contains the - ``_id`` of each successfully inserted documents. - - To verify the insert, you can query the collection (See the - next tab). + To verify the insert, you can query the collection (See the + next tab). .. tab:: 2. Select All Documents :tabid: example-2 - - .. container:: - - To select the documents from a collection, you can use the - :method:`db.collection.find()` method. To select all documents - in the collection, pass an empty document as the :ref:`query - filter document ` to the method. + + To select the documents from a collection, you can use the + :method:`db.collection.find()` method. To select all documents + in the collection, pass an empty document as the :ref:`query + filter document ` to the method. - In the :ref:`shell `, copy and paste the - following to return all documents in the ``inventory`` - collection. + In the :ref:`shell `, copy and paste the + following to return all documents in the ``inventory`` + collection. - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find({}) + db.inventory.find({}) - To format the results, append the ``.pretty()`` to the - ``find`` operation: + To format the results, append the ``.pretty()`` to the + ``find`` operation: - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find({}).pretty() + db.inventory.find({}).pretty() - .. note:: + .. note:: - The example assumes that you have populated the - ``inventory`` collection from the previous step. + The example assumes that you have populated the + ``inventory`` collection from the previous step. .. tab:: 3. Specify Equality Matches :tabid: example-3 - .. container:: + For an equality match (i.e. ```` equals ````), + specify ``: `` in the :ref:`query filter + document ` and pass to the + :method:`db.collection.find()` method. - For an equality match (i.e. ```` equals ````), - specify ``: `` in the :ref:`query filter - document ` and pass to the - :method:`db.collection.find()` method. + .. note:: - .. note:: + The examples assume that you have populated the + ``inventory`` collection. - The examples assume that you have populated the - ``inventory`` collection. + - In the :ref:`shell `, copy and paste the + following to return documents where ``status`` field equals + ``"D"``: - - In the :ref:`shell `, copy and paste the - following to return documents where ``status`` field equals - ``"D"``: + .. code-block:: javascript - .. code-block:: javascript + db.inventory.find( { status: "D" } ); - db.inventory.find( { status: "D" } ); + - In the :ref:`shell `, copy and paste the + following to return document where ``qty`` field equals + ``0``: - - In the :ref:`shell `, copy and paste the - following to return document where ``qty`` field equals - ``0``: - - .. code-block:: javascript - - db.inventory.find( { qty: 0 } ); + .. code-block:: javascript + + db.inventory.find( { qty: 0 } ); - - In the :ref:`shell `, copy and paste the - following to return document where ``qty`` field equals - ``0`` and ``status`` field equals ``"D"``: + - In the :ref:`shell `, copy and paste the + following to return document where ``qty`` field equals + ``0`` and ``status`` field equals ``"D"``: - .. code-block:: javascript - - db.inventory.find( { qty: 0, status: "D" } ); + .. code-block:: javascript + + db.inventory.find( { qty: 0, status: "D" } ); - - In the :ref:`shell `, copy and paste the - following to return document where the ``uom`` field, nested - inside the size document, equals ``"in"``: + - In the :ref:`shell `, copy and paste the + following to return document where the ``uom`` field, nested + inside the size document, equals ``"in"``: - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find( { "size.uom": "in" } ) + db.inventory.find( { "size.uom": "in" } ) - - In the :ref:`shell `, copy and paste the - following to return document where the ``size`` field equals - the document ``{ h: 14, w: 21, uom: "cm" }``: + - In the :ref:`shell `, copy and paste the + following to return document where the ``size`` field equals + the document ``{ h: 14, w: 21, uom: "cm" }``: - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } ) + db.inventory.find( { size: { h: 14, w: 21, uom: "cm" } } ) - Equality matches on the embedded document require an exact - match, including the field order. + Equality matches on the embedded document require an exact + match, including the field order. - - In the :ref:`shell `, copy and paste the - following to return documents where the ``tags`` array - contains ``"red"`` as one of its elements: + - In the :ref:`shell `, copy and paste the + following to return documents where the ``tags`` array + contains ``"red"`` as one of its elements: - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find( { tags: "red" } ) + db.inventory.find( { tags: "red" } ) - If the ``tags`` field is a string instead of an array, then - the query is just an equality match. + If the ``tags`` field is a string instead of an array, then + the query is just an equality match. - - In the :ref:`shell `, copy and paste the - following to return documents where the ``tags`` field - matches the specified array exactly, including the order: - - .. code-block:: javascript - - db.inventory.find( { tags: [ "red", "blank" ] } ) + - In the :ref:`shell `, copy and paste the + following to return documents where the ``tags`` field + matches the specified array exactly, including the order: + + .. code-block:: javascript + + db.inventory.find( { tags: [ "red", "blank" ] } ) .. tab:: 4. Specify Fields to Return (Projection) :tabid: example-4 - .. container:: - - To specify fields to return, pass a projection document to the - :method:`db.collection.find(\, \) ` method. In the projection - document, specify: - - - ``: 1`` to include a field in the returned documents - - - ``: 0`` to exclude a field in the returned documents + To specify fields to return, pass a projection document to the + :method:`db.collection.find(\, \) ` method. In the projection + document, specify: + + - ``: 1`` to include a field in the returned documents + + - ``: 0`` to exclude a field in the returned documents - In the :ref:`shell `, copy and paste the - following to return the ``_id``, ``item``, and the ``status`` - fields from all documents in the ``inventory`` collection: + In the :ref:`shell `, copy and paste the + following to return the ``_id``, ``item``, and the ``status`` + fields from all documents in the ``inventory`` collection: - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find( { }, { item: 1, status: 1 } ); + db.inventory.find( { }, { item: 1, status: 1 } ); - You do not have to specify the ``_id`` field to return the - field. It returns by default. To exclude the field, set it to - ``0`` in the projection document. For example, copy and paste - the following to return only the ``item``, and the ``status`` - fields in the matching documents: + You do not have to specify the ``_id`` field to return the + field. It returns by default. To exclude the field, set it to + ``0`` in the projection document. For example, copy and paste + the following to return only the ``item``, and the ``status`` + fields in the matching documents: - .. code-block:: javascript + .. code-block:: javascript - db.inventory.find( {}, { _id: 0, item: 1, status: 1 } ); + db.inventory.find( {}, { _id: 0, item: 1, status: 1 } ); Next Steps diff --git a/source/tutorial/implement-field-level-redaction.txt b/source/tutorial/implement-field-level-redaction.txt index 863c779609f..c215220d7e4 100644 --- a/source/tutorial/implement-field-level-redaction.txt +++ b/source/tutorial/implement-field-level-redaction.txt @@ -125,5 +125,7 @@ The aggregation operation returns the following "redacted" document for the user ] } -.. seealso:: :expression:`$map`, :expression:`$setIsSubset`, +.. seealso:: + + :expression:`$map`, :expression:`$setIsSubset`, :expression:`$anyElementTrue` diff --git a/source/tutorial/insert-documents.txt b/source/tutorial/insert-documents.txt index f33c68a665c..7c83344a226 100644 --- a/source/tutorial/insert-documents.txt +++ b/source/tutorial/insert-documents.txt @@ -19,8 +19,8 @@ This page provides examples in: This page provides examples of insert operations in MongoDB. -.. admonition:: Creating a Collection - :class: note +.. note:: Creating a Collection + If the collection does not currently exist, insert operations will create the collection. @@ -59,6 +59,7 @@ Insert a Single Document 2. Click the :guilabel:`Insert Document` button: .. figure:: /images/compass-insert-button.png + :alt: Compass insert button 3. For each field in the document, select the field type and fill in the field name and value. Add fields by clicking diff --git a/source/tutorial/install-mongodb-enterprise-on-red-hat-tarball.txt b/source/tutorial/install-mongodb-enterprise-on-red-hat-tarball.txt index 8bffd0ed128..138b2080cb8 100644 --- a/source/tutorial/install-mongodb-enterprise-on-red-hat-tarball.txt +++ b/source/tutorial/install-mongodb-enterprise-on-red-hat-tarball.txt @@ -101,9 +101,7 @@ Prerequisites ulimit `````` -.. container:: - - .. include:: /includes/fact-installation-ulimit.rst +.. include:: /includes/fact-installation-ulimit.rst Directory Paths ``````````````` @@ -111,63 +109,59 @@ Directory Paths To Use Default Directories ++++++++++++++++++++++++++ -.. container:: - - By default, MongoDB runs using the |mongod-user| user account and - uses the following default directories: +By default, MongoDB runs using the |mongod-user| user account and +uses the following default directories: - - |mongod-datadir| (the data directory) +- |mongod-datadir| (the data directory) - - ``/var/log/mongodb`` (the log directory) +- ``/var/log/mongodb`` (the log directory) - |arrow| If you installed via the package manager, - The default directories are created, and the owner and group for - these directories are set to |mongod-user|. +|arrow| If you installed via the package manager, + The default directories are created, and the owner and group for + these directories are set to |mongod-user|. - |arrow| If you installed by downloading the tarballs, - The default MongoDB directories are not created. To create the - MongoDB data and log directories: +|arrow| If you installed by downloading the tarballs, + The default MongoDB directories are not created. To create the + MongoDB data and log directories: - .. code-block:: sh + .. code-block:: sh - sudo mkdir -p /var/lib/mongo - sudo mkdir -p /var/log/mongodb + sudo mkdir -p /var/lib/mongo + sudo mkdir -p /var/log/mongodb - By default, MongoDB runs using the |mongod-user| user account. Once - created, set the owner and group of these directories to |mongod-user|: + By default, MongoDB runs using the |mongod-user| user account. Once + created, set the owner and group of these directories to |mongod-user|: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod To Use Non-Default Directories ++++++++++++++++++++++++++++++ -.. container:: +To use a data directory and/or log directory other than the default +directories: - To use a data directory and/or log directory other than the default - directories: +#. Create the new directory or directories. - #. Create the new directory or directories. +#. Edit the configuration file ``/etc/mongod.conf`` and modify the + following fields accordingly: - #. Edit the configuration file ``/etc/mongod.conf`` and modify the - following fields accordingly: + - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) - - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) + - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - #. Ensure that the user running MongoDB has access to the directory or - directories: +#. Ensure that the user running MongoDB has access to the directory or + directories: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod - If you change the user that runs the MongoDB process, you **must** - give the new user access to these directories. + If you change the user that runs the MongoDB process, you **must** + give the new user access to these directories. - #. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. +#. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. .. _install-enterprise-tarball-selinux-data-directory: diff --git a/source/tutorial/install-mongodb-enterprise-on-red-hat.txt b/source/tutorial/install-mongodb-enterprise-on-red-hat.txt index 4ef98cb7ec3..392bd4edca3 100644 --- a/source/tutorial/install-mongodb-enterprise-on-red-hat.txt +++ b/source/tutorial/install-mongodb-enterprise-on-red-hat.txt @@ -67,9 +67,7 @@ Prerequisites ulimit `````` -.. container:: - - .. include:: /includes/fact-installation-ulimit.rst +.. include:: /includes/fact-installation-ulimit.rst Directory Paths ``````````````` @@ -77,63 +75,59 @@ Directory Paths To Use Default Directories ++++++++++++++++++++++++++ -.. container:: - - By default, MongoDB runs using the |mongod-user| user account and - uses the following default directories: +By default, MongoDB runs using the |mongod-user| user account and +uses the following default directories: - - |mongod-datadir| (the data directory) +- |mongod-datadir| (the data directory) - - ``/var/log/mongodb`` (the log directory) +- ``/var/log/mongodb`` (the log directory) - |arrow| If you installed via the package manager, - The default directories are created, and the owner and group for - these directories are set to |mongod-user|. +|arrow| If you installed via the package manager, + The default directories are created, and the owner and group for + these directories are set to |mongod-user|. - |arrow| If you installed by downloading the tarballs, - The default MongoDB directories are not created. To create the - MongoDB data and log directories: +|arrow| If you installed by downloading the tarballs, + The default MongoDB directories are not created. To create the + MongoDB data and log directories: - .. code-block:: sh + .. code-block:: sh - sudo mkdir -p /var/lib/mongo - sudo mkdir -p /var/log/mongodb + sudo mkdir -p /var/lib/mongo + sudo mkdir -p /var/log/mongodb - By default, MongoDB runs using the |mongod-user| user account. Once - created, set the owner and group of these directories to |mongod-user|: + By default, MongoDB runs using the |mongod-user| user account. Once + created, set the owner and group of these directories to |mongod-user|: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod To Use Non-Default Directories ++++++++++++++++++++++++++++++ -.. container:: +To use a data directory and/or log directory other than the default +directories: - To use a data directory and/or log directory other than the default - directories: +#. Create the new directory or directories. - #. Create the new directory or directories. +#. Edit the configuration file ``/etc/mongod.conf`` and modify the + following fields accordingly: - #. Edit the configuration file ``/etc/mongod.conf`` and modify the - following fields accordingly: + - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) - - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) + - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - #. Ensure that the user running MongoDB has access to the directory or - directories: +#. Ensure that the user running MongoDB has access to the directory or + directories: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod - If you change the user that runs the MongoDB process, you **must** - give the new user access to these directories. + If you change the user that runs the MongoDB process, you **must** + give the new user access to these directories. - #. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. +#. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. .. _install-enterprise-selinux-data-directory: diff --git a/source/tutorial/install-mongodb-enterprise-on-ubuntu-tarball.txt b/source/tutorial/install-mongodb-enterprise-on-ubuntu-tarball.txt index 81b896cf51a..d99bdbed864 100644 --- a/source/tutorial/install-mongodb-enterprise-on-ubuntu-tarball.txt +++ b/source/tutorial/install-mongodb-enterprise-on-ubuntu-tarball.txt @@ -4,8 +4,7 @@ Install MongoDB Enterprise on Ubuntu using .tgz Tarball .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/install-mongodb-enterprise-on-ubuntu.txt b/source/tutorial/install-mongodb-enterprise-on-ubuntu.txt index 20e2f3268e3..26230bfd62c 100644 --- a/source/tutorial/install-mongodb-enterprise-on-ubuntu.txt +++ b/source/tutorial/install-mongodb-enterprise-on-ubuntu.txt @@ -4,8 +4,7 @@ Install MongoDB Enterprise Edition on Ubuntu .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/install-mongodb-on-amazon-tarball.txt b/source/tutorial/install-mongodb-on-amazon-tarball.txt index 7b12495d3ba..c13d1c6efd0 100644 --- a/source/tutorial/install-mongodb-on-amazon-tarball.txt +++ b/source/tutorial/install-mongodb-on-amazon-tarball.txt @@ -4,8 +4,7 @@ Install MongoDB Community on Amazon Linux using .tgz Tarball .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/install-mongodb-on-os-x.txt b/source/tutorial/install-mongodb-on-os-x.txt index 086f37c5428..00313a21a2a 100644 --- a/source/tutorial/install-mongodb-on-os-x.txt +++ b/source/tutorial/install-mongodb-on-os-x.txt @@ -110,9 +110,9 @@ Follow these steps to install MongoDB |edition| Edition using Homebrew's #. To install MongoDB, run the following command in your macOS Terminal application: - .. code-block:: sh + brew install mongodb-community@{+version+} - brew install mongodb-community@{+version+} +.. tip:: Alternatively, you can specify a previous version of MongoDB if desired. You can also maintain multiple versions of MongoDB side by @@ -220,8 +220,7 @@ during the install. You can add your own MongoDB :doc:`configuration options ` to this file as well. -.. admonition:: macOS Prevents ``mongod`` From Opening - :class: note +.. note:: macOS Prevents ``mongod`` From Opening .. include:: /includes/extracts/macos-prevent-launch-mongod.rst diff --git a/source/tutorial/install-mongodb-on-red-hat-tarball.txt b/source/tutorial/install-mongodb-on-red-hat-tarball.txt index 2056115e778..c13b9517a78 100644 --- a/source/tutorial/install-mongodb-on-red-hat-tarball.txt +++ b/source/tutorial/install-mongodb-on-red-hat-tarball.txt @@ -81,9 +81,7 @@ Prerequisites ulimit `````` -.. container:: - - .. include:: /includes/fact-installation-ulimit.rst +.. include:: /includes/fact-installation-ulimit.rst Directory Paths ``````````````` @@ -91,63 +89,59 @@ Directory Paths To Use Default Directories ++++++++++++++++++++++++++ -.. container:: - - By default, MongoDB runs using the |mongod-user| user account and - uses the following default directories: +By default, MongoDB runs using the |mongod-user| user account and +uses the following default directories: - - |mongod-datadir| (the data directory) +- |mongod-datadir| (the data directory) - - ``/var/log/mongodb`` (the log directory) +- ``/var/log/mongodb`` (the log directory) - |arrow| If you installed via the package manager, - The default directories are created, and the owner and group for - these directories are set to |mongod-user|. +|arrow| If you installed via the package manager, + The default directories are created, and the owner and group for + these directories are set to |mongod-user|. - |arrow| If you installed by downloading the tarballs, - The default MongoDB directories are not created. To create the - MongoDB data and log directories: +|arrow| If you installed by downloading the tarballs, + The default MongoDB directories are not created. To create the + MongoDB data and log directories: - .. code-block:: sh + .. code-block:: sh - sudo mkdir -p /var/lib/mongo - sudo mkdir -p /var/log/mongodb + sudo mkdir -p /var/lib/mongo + sudo mkdir -p /var/log/mongodb - By default, MongoDB runs using the |mongod-user| user account. Once - created, set the owner and group of these directories to |mongod-user|: + By default, MongoDB runs using the |mongod-user| user account. Once + created, set the owner and group of these directories to |mongod-user|: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod To Use Non-Default Directories ++++++++++++++++++++++++++++++ -.. container:: +To use a data directory and/or log directory other than the default +directories: - To use a data directory and/or log directory other than the default - directories: +#. Create the new directory or directories. - #. Create the new directory or directories. +#. Edit the configuration file ``/etc/mongod.conf`` and modify the + following fields accordingly: - #. Edit the configuration file ``/etc/mongod.conf`` and modify the - following fields accordingly: + - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) - - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) + - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - #. Ensure that the user running MongoDB has access to the directory or - directories: +#. Ensure that the user running MongoDB has access to the directory or + directories: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod - If you change the user that runs the MongoDB process, you **must** - give the new user access to these directories. + If you change the user that runs the MongoDB process, you **must** + give the new user access to these directories. - #. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. +#. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. .. _install-tarball-selinux-data-directory: diff --git a/source/tutorial/install-mongodb-on-red-hat.txt b/source/tutorial/install-mongodb-on-red-hat.txt index e1a6844aeff..0f89336185f 100644 --- a/source/tutorial/install-mongodb-on-red-hat.txt +++ b/source/tutorial/install-mongodb-on-red-hat.txt @@ -65,9 +65,7 @@ Prerequisites ulimit `````` -.. container:: - - .. include:: /includes/fact-installation-ulimit.rst +.. include:: /includes/fact-installation-ulimit.rst Directory Paths ``````````````` @@ -75,63 +73,59 @@ Directory Paths To Use Default Directories ++++++++++++++++++++++++++ -.. container:: - - By default, MongoDB runs using the |mongod-user| user account and - uses the following default directories: +By default, MongoDB runs using the |mongod-user| user account and +uses the following default directories: - - |mongod-datadir| (the data directory) +- |mongod-datadir| (the data directory) - - ``/var/log/mongodb`` (the log directory) +- ``/var/log/mongodb`` (the log directory) - |arrow| If you installed via the package manager, - The default directories are created, and the owner and group for - these directories are set to |mongod-user|. +|arrow| If you installed via the package manager, + The default directories are created, and the owner and group for + these directories are set to |mongod-user|. - |arrow| If you installed by downloading the tarballs, - The default MongoDB directories are not created. To create the - MongoDB data and log directories: +|arrow| If you installed by downloading the tarballs, + The default MongoDB directories are not created. To create the + MongoDB data and log directories: - .. code-block:: sh + .. code-block:: sh - sudo mkdir -p /var/lib/mongo - sudo mkdir -p /var/log/mongodb + sudo mkdir -p /var/lib/mongo + sudo mkdir -p /var/log/mongodb - By default, MongoDB runs using the |mongod-user| user account. Once - created, set the owner and group of these directories to |mongod-user|: + By default, MongoDB runs using the |mongod-user| user account. Once + created, set the owner and group of these directories to |mongod-user|: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod To Use Non-Default Directories ++++++++++++++++++++++++++++++ -.. container:: +To use a data directory and/or log directory other than the default +directories: - To use a data directory and/or log directory other than the default - directories: +#. Create the new directory or directories. - #. Create the new directory or directories. +#. Edit the configuration file ``/etc/mongod.conf`` and modify the + following fields accordingly: - #. Edit the configuration file ``/etc/mongod.conf`` and modify the - following fields accordingly: + - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) - - :setting:`storage.dbPath` to specify a new data directory path (e.g. ``/some/data/directory``) + - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - :setting:`systemLog.path` to specify a new log file path (e.g. ``/some/log/directory/mongod.log``) - - #. Ensure that the user running MongoDB has access to the directory or - directories: +#. Ensure that the user running MongoDB has access to the directory or + directories: - .. code-block:: sh + .. code-block:: sh - sudo chown -R mongod:mongod + sudo chown -R mongod:mongod - If you change the user that runs the MongoDB process, you **must** - give the new user access to these directories. + If you change the user that runs the MongoDB process, you **must** + give the new user access to these directories. - #. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. +#. Configure SELinux if enforced. See :ref:`install-rhel-configure-selinux`. .. _install-selinux-data-directory: diff --git a/source/tutorial/install-mongodb-on-ubuntu-tarball.txt b/source/tutorial/install-mongodb-on-ubuntu-tarball.txt index 846885bd1e2..af54dee87dd 100644 --- a/source/tutorial/install-mongodb-on-ubuntu-tarball.txt +++ b/source/tutorial/install-mongodb-on-ubuntu-tarball.txt @@ -4,8 +4,7 @@ Install MongoDB Community on Ubuntu using .tgz Tarball .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/install-mongodb-on-ubuntu.txt b/source/tutorial/install-mongodb-on-ubuntu.txt index f11b13bac2f..71fb8af4097 100644 --- a/source/tutorial/install-mongodb-on-ubuntu.txt +++ b/source/tutorial/install-mongodb-on-ubuntu.txt @@ -4,8 +4,7 @@ Install MongoDB Community Edition on Ubuntu .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/iterate-a-cursor.txt b/source/tutorial/iterate-a-cursor.txt index 8b981f61ab3..666bec9deb8 100644 --- a/source/tutorial/iterate-a-cursor.txt +++ b/source/tutorial/iterate-a-cursor.txt @@ -72,7 +72,7 @@ example: myCursor.forEach(printjson); See :ref:`JavaScript cursor methods ` and your -:ecosystem:`driver ` documentation for more +:driver:`driver ` documentation for more information on cursor methods. .. include:: /includes/footnote-set-shell-batch-size.rst @@ -94,7 +94,7 @@ The :method:`~cursor.toArray()` method loads into RAM all documents returned by the cursor; the :method:`~cursor.toArray()` method exhausts the cursor. -Additionally, some :ecosystem:`drivers ` provide +Additionally, some :driver:`Drivers ` provide access to the documents by using an index on the cursor (i.e. ``cursor[index]``). This is a shortcut for first calling the :method:`~cursor.toArray()` method and then using an index @@ -133,7 +133,7 @@ the :method:`cursor.noCursorTimeout()` method: After setting the ``noCursorTimeout`` option, you must either close the cursor manually with :method:`cursor.close()` or by exhausting the cursor's results. -See your :ecosystem:`driver ` documentation for +See your :driver:`driver ` documentation for information on setting the ``noCursorTimeout`` option. .. _cursor-isolation: @@ -229,4 +229,7 @@ The result is the following document: } } -.. seealso:: :method:`db.serverStatus()` +.. seealso:: + + :method:`db.serverStatus()` + diff --git a/source/tutorial/limit-number-of-items-scanned-for-text-search.txt b/source/tutorial/limit-number-of-items-scanned-for-text-search.txt index 1029c7f39ed..1844c0312c3 100644 --- a/source/tutorial/limit-number-of-items-scanned-for-text-search.txt +++ b/source/tutorial/limit-number-of-items-scanned-for-text-search.txt @@ -58,4 +58,6 @@ query scans only those documents with ``dept`` equal to ``kitchen``: .. include:: /includes/fact-compound-index-with-text-restrictions.rst -.. seealso:: :doc:`/core/index-text` +.. seealso:: + + :doc:`/core/index-text` diff --git a/source/tutorial/manage-indexes.txt b/source/tutorial/manage-indexes.txt index 0a2cf7aa105..b6397510543 100644 --- a/source/tutorial/manage-indexes.txt +++ b/source/tutorial/manage-indexes.txt @@ -13,7 +13,7 @@ Manage Indexes This page shows how to manage existing indexes. For instructions on creating indexes, refer to the specific index type pages. -.. index:: index; list indexes + View Existing Indexes --------------------- @@ -22,7 +22,7 @@ View Existing Indexes .. include:: /includes/driver-view-existing-indexes-tabs.rst -.. index:: index; list indexes + .. |things| replace:: collections and indexes .. |method| replace:: :method:`db.getCollectionNames()` and :method:`db.collection.getIndexes()` diff --git a/source/tutorial/manage-sharded-cluster-balancer.txt b/source/tutorial/manage-sharded-cluster-balancer.txt index 62c4853949a..613d8857690 100644 --- a/source/tutorial/manage-sharded-cluster-balancer.txt +++ b/source/tutorial/manage-sharded-cluster-balancer.txt @@ -1,5 +1,5 @@ -.. index:: balancing; operations -.. index:: balancing; configure + + =============================== Manage Sharded Cluster Balancer @@ -313,8 +313,8 @@ You can also see if the balancer is enabled using :method:`sh.status()`. The :data:`~sh.status.balancer.currently-enabled` field indicates if the balancer is enabled. -.. index:: balancing; secondary throttle -.. index:: secondary throttle + + Change Replication Behavior for Chunk Migration ----------------------------------------------- diff --git a/source/tutorial/manage-the-database-profiler.txt b/source/tutorial/manage-the-database-profiler.txt index 625c0d024d1..c337fa7efc8 100644 --- a/source/tutorial/manage-the-database-profiler.txt +++ b/source/tutorial/manage-the-database-profiler.txt @@ -56,8 +56,8 @@ You can enable database profiling for :binary:`~bin.mongod` instances. This section uses the :binary:`~bin.mongo` shell helper :method:`db.setProfilingLevel()` helper to enable profiling. For -instructions using the driver, see your :ecosystem:`driver -documentation `. +instructions using the driver, see your :driver:`driver +documentation `. When you enable profiling for a :binary:`~bin.mongod` instance, you set the :ref:`profiling level ` to a value @@ -205,9 +205,8 @@ sampling rate for logging slow operations: db.setProfilingLevel(0, { sampleRate: 0.42 }) .. important:: - .. include:: /includes/fact-log-slow-queries.rst -.. |replace| binary:: :binary:`~bin.mongod` or :binary:`~bin.mongos` + .. include:: /includes/fact-log-slow-queries.rst .. [#mongos-systemlog] @@ -322,7 +321,7 @@ that last longer than ``15`` milliseconds, and specifies that only 50% of *slow* operations should be profiled. [#slow-oplogs]_ The ``slowms`` and ``slowOpSampleRate`` also affect which operations -are recorded to the diagnostic log when :setting:`~param.logLevel` is +are recorded to the diagnostic log when :parameter:`logLevel` is set to ``0``. The ``slowms`` and ``slowOpSampleRate`` are also available to configure diagnostic logging for :binary:`~bin.mongos`. [#slow-oplogs]_ diff --git a/source/tutorial/manage-users-and-roles.txt b/source/tutorial/manage-users-and-roles.txt index 97700237987..3c137d240be 100644 --- a/source/tutorial/manage-users-and-roles.txt +++ b/source/tutorial/manage-users-and-roles.txt @@ -150,7 +150,9 @@ Procedure .. include:: /includes/steps/change-user-password.rst -.. seealso:: :doc:`/tutorial/change-own-password-and-custom-data` +.. seealso:: + + :doc:`/tutorial/change-own-password-and-custom-data` View a User's Roles ------------------- diff --git a/source/tutorial/map-reduce-examples.txt b/source/tutorial/map-reduce-examples.txt index d68844c7c9c..2e302c476f1 100644 --- a/source/tutorial/map-reduce-examples.txt +++ b/source/tutorial/map-reduce-examples.txt @@ -33,7 +33,9 @@ following examples use the :method:`db.collection.mapReduce()` method. .. include:: /includes/examples-map-reduce.rst :start-after: map-reduce-document-prototype-begin -.. seealso:: +.. seealso:: + + - :doc:`/tutorial/perform-incremental-map-reduce` diff --git a/source/tutorial/measure-index-use.txt b/source/tutorial/measure-index-use.txt index 342d71bef84..5a9b0c0fbc3 100644 --- a/source/tutorial/measure-index-use.txt +++ b/source/tutorial/measure-index-use.txt @@ -1,4 +1,4 @@ -.. index:: index; measure use + .. _index-measure-index-use: .. _indexes-measuring-use: @@ -26,7 +26,9 @@ the ``orders`` collection: db.orders.aggregate( [ { $indexStats: { } } ] ) -.. seealso:: :pipeline:`$indexStats` +.. seealso:: + + :pipeline:`$indexStats` Return Query Plan with ``explain()`` ------------------------------------ @@ -42,7 +44,9 @@ method in :ref:`allPlansExecution ` mode to view partial execution statistics collected during plan selection. -.. seealso:: :ref:`plan-cache-key` +.. seealso:: + + :ref:`plan-cache-key` Control Index Use with ``hint()`` --------------------------------- diff --git a/source/tutorial/merge-chunks-in-sharded-cluster.txt b/source/tutorial/merge-chunks-in-sharded-cluster.txt index aedacfcf5f4..18a1c5d465c 100644 --- a/source/tutorial/merge-chunks-in-sharded-cluster.txt +++ b/source/tutorial/merge-chunks-in-sharded-cluster.txt @@ -202,35 +202,35 @@ The output of :method:`sh.status()` should resemble: Failed balancer rounds in last 5 attempts: 0 Migration Results for the last 24 hours: 519 : Success - databases: - { "_id" : "config", "primary" : "config", "partitioned" : true } - config.system.sessions - shard key: { "_id" : 1 } - unique: false - balancing: true - chunks: - shardA 512 - shardB 512 - too many chunks to print, use verbose if you want to force print - { "_id" : "test", "primary" : "shardA", "partitioned" : true, "version" : { "uuid" : UUID("22c042fc-7e3d-4c6d-992d-f3d714759781"), "lastMod" : 1 } } - test.members - shard key: { "username" : 1 } - unique: false - balancing: true - chunks: - shardA 5 - shardB 6 - { "username" : { "$minKey" : 1 } } -->> { "username" : "user16643" } on : shardA Timestamp(22, 0) - { "username" : "user16643" } -->> { "username" : "user2329" } on : shardB Timestamp(22, 1) - { "username" : "user2329" } -->> { "username" : "user29937" } on : shardB Timestamp(17, 0) - { "username" : "user29937" } -->> { "username" : "user36583" } on : shardB Timestamp(18, 0) - { "username" : "user36583" } -->> { "username" : "user43229" } on : shardB Timestamp(19, 0) - { "username" : "user43229" } -->> { "username" : "user49877" } on : shardB Timestamp(20, 0) - { "username" : "user49877" } -->> { "username" : "user56522" } on : shardB Timestamp(21, 0) - { "username" : "user56522" } -->> { "username" : "user63169" } on : shardA Timestamp(21, 1) - { "username" : "user63169" } -->> { "username" : "user69816" } on : shardA Timestamp(10, 1) - { "username" : "user69816" } -->> { "username" : "user96401" } on : shardA Timestamp(21, 2) - { "username" : "user96401" } -->> { "username" : { "$maxKey" : 1 } } on : shardA Timestamp(15, 2) + databases: + { "_id" : "config", "primary" : "config", "partitioned" : true } + config.system.sessions + shard key: { "_id" : 1 } + unique: false + balancing: true + chunks: + shardA 512 + shardB 512 + too many chunks to print, use verbose if you want to force print + { "_id" : "test", "primary" : "shardA", "partitioned" : true, "version" : { "uuid" : UUID("22c042fc-7e3d-4c6d-992d-f3d714759781"), "lastMod" : 1 } } + test.members + shard key: { "username" : 1 } + unique: false + balancing: true + chunks: + shardA 5 + shardB 6 + { "username" : { "$minKey" : 1 } } -->> { "username" : "user16643" } on : shardA Timestamp(22, 0) + { "username" : "user16643" } -->> { "username" : "user2329" } on : shardB Timestamp(22, 1) + { "username" : "user2329" } -->> { "username" : "user29937" } on : shardB Timestamp(17, 0) + { "username" : "user29937" } -->> { "username" : "user36583" } on : shardB Timestamp(18, 0) + { "username" : "user36583" } -->> { "username" : "user43229" } on : shardB Timestamp(19, 0) + { "username" : "user43229" } -->> { "username" : "user49877" } on : shardB Timestamp(20, 0) + { "username" : "user49877" } -->> { "username" : "user56522" } on : shardB Timestamp(21, 0) + { "username" : "user56522" } -->> { "username" : "user63169" } on : shardA Timestamp(21, 1) + { "username" : "user63169" } -->> { "username" : "user69816" } on : shardA Timestamp(10, 1) + { "username" : "user69816" } -->> { "username" : "user96401" } on : shardA Timestamp(21, 2) + { "username" : "user96401" } -->> { "username" : { "$maxKey" : 1 } } on : shardA Timestamp(15, 2) After the merge, the :ref:`balancer ` may migrate chunks across shards to ensure a more even distribution of chunks. diff --git a/source/tutorial/monitor-with-snmp-on-windows.txt b/source/tutorial/monitor-with-snmp-on-windows.txt index 622cf5cd9f7..efe7621a26c 100644 --- a/source/tutorial/monitor-with-snmp-on-windows.txt +++ b/source/tutorial/monitor-with-snmp-on-windows.txt @@ -10,7 +10,7 @@ Monitor MongoDB Windows with SNMP :depth: 1 :class: singlecol -.. admonition:: Enterprise Feature +.. note:: Enterprise Feature SNMP is only available in `MongoDB Enterprise `_. @@ -28,7 +28,9 @@ explains the setup and configuration of a |mongod-program| instance as an SNMP subagent, as well as initializing and testing of SNMP support with MongoDB Enterprise. -.. seealso:: :doc:`/tutorial/monitor-with-snmp` and +.. seealso:: + + :doc:`/tutorial/monitor-with-snmp` and :doc:`/tutorial/troubleshoot-snmp` for more information. Considerations @@ -57,8 +59,9 @@ Optional: Run MongoDB as SNMP Master copy mongod.conf.master C:\snmp\etc\config\mongod.conf -Additionally, start |mongod-program| with the :setting:`snmp-master` -option, as in the following: +Additionally, start |mongod-program| with the +:option:`snmp-master ` option, as in the +following: .. code-block:: powershell diff --git a/source/tutorial/monitor-with-snmp.txt b/source/tutorial/monitor-with-snmp.txt index bce6e69ec82..bbb46f6c016 100644 --- a/source/tutorial/monitor-with-snmp.txt +++ b/source/tutorial/monitor-with-snmp.txt @@ -10,7 +10,7 @@ Monitor MongoDB With SNMP on Linux :depth: 1 :class: singlecol -.. admonition:: Enterprise Feature +.. note:: Enterprise Feature SNMP is only available in `MongoDB Enterprise `_. @@ -26,7 +26,9 @@ explains the setup and configuration of a |mongod-program| instance as an SNMP subagent, as well as initializing and testing of SNMP support with MongoDB Enterprise. -.. seealso:: :doc:`/tutorial/troubleshoot-snmp` and +.. seealso:: + + :doc:`/tutorial/troubleshoot-snmp` and :doc:`/tutorial/monitor-with-snmp-on-windows` for complete instructions on using MongoDB with SNMP on Windows systems. @@ -66,8 +68,8 @@ Optional: Run MongoDB as SNMP Master range of 10.0.0.0/8 with a security name of "mynetwork" has been provided in the master configuration file as an example. -Then, start |mongod-program| with the :setting:`snmp-master` -option: +Then, start |mongod-program| with the +:option:`snmp-master ` option: .. code-block:: sh diff --git a/source/tutorial/perform-incremental-map-reduce.txt b/source/tutorial/perform-incremental-map-reduce.txt index 48f2d3586a7..29eaeae43ee 100644 --- a/source/tutorial/perform-incremental-map-reduce.txt +++ b/source/tutorial/perform-incremental-map-reduce.txt @@ -10,8 +10,8 @@ Perform Incremental Map-Reduce :depth: 1 :class: singlecol -.. admonition:: Aggregation Pipeline as Alternative to Map-Reduce - :class: note + +.. note:: Aggregation Pipeline as Alternative .. include:: /includes/fact-use-aggregation-not-map-reduce.rst @@ -245,9 +245,9 @@ map-reduce example without defining custom functions: #. The :pipeline:`$group` groups by the ``userid`` and calculates: - - The ``total_time`` using the :expression:`$sum` operator + - The ``total_time`` using the :group:`$sum` operator - - The ``count`` using the :expression:`$sum` operator + - The ``count`` using the :group:`$sum` operator - The ``avg_time`` using the :group:`$avg` operator @@ -375,7 +375,9 @@ map-reduce example without defining custom functions: updateSessionStats(ISODate('2020-03-05 00:00:00')) -.. seealso:: +.. seealso:: + + - :ref:`$merge Examples ` diff --git a/source/tutorial/project-fields-from-query-results.txt b/source/tutorial/project-fields-from-query-results.txt index 962a41931af..66823644e92 100644 --- a/source/tutorial/project-fields-from-query-results.txt +++ b/source/tutorial/project-fields-from-query-results.txt @@ -402,7 +402,9 @@ regards to projections. See :limit:`Projection Restrictions` for details. -.. seealso:: +.. seealso:: + + - :ref:`find-projection` diff --git a/source/tutorial/query-a-2d-index.txt b/source/tutorial/query-a-2d-index.txt index a1a4a7b37f8..7b087b2f4bc 100644 --- a/source/tutorial/query-a-2d-index.txt +++ b/source/tutorial/query-a-2d-index.txt @@ -109,8 +109,8 @@ The :query:`$near` operator uses the following syntax: For examples, see :query:`$near`. -.. index:: geospatial queries -.. index:: geospatial queries; exact + + .. _geospatial-indexes-exact-match: Exact Matches on a Flat Surface diff --git a/source/tutorial/query-a-2dsphere-index.txt b/source/tutorial/query-a-2dsphere-index.txt index fc217934ada..0ab83aa2bdf 100644 --- a/source/tutorial/query-a-2dsphere-index.txt +++ b/source/tutorial/query-a-2dsphere-index.txt @@ -108,7 +108,7 @@ The :query:`$near` uses the following syntax: For examples, see :query:`$near`. -See also the :query:`$nearSphere` operator and the:pipeline:`$geoNear` +See also the :query:`$nearSphere` operator and the :pipeline:`$geoNear` aggregation pipeline stage. Points within a Circle Defined on a Sphere diff --git a/source/tutorial/query-a-geohaystack-index.txt b/source/tutorial/query-a-geohaystack-index.txt index 74d6d52b8de..5d6024f72be 100644 --- a/source/tutorial/query-a-geohaystack-index.txt +++ b/source/tutorial/query-a-geohaystack-index.txt @@ -12,8 +12,8 @@ Query a Haystack Index :depth: 1 :class: singlecol -.. admonition:: Deprecation - :class: important +.. important:: Deprecation + .. include:: /includes/extracts/4.4-changes-geo-deprecation.rst diff --git a/source/tutorial/query-for-null-fields.txt b/source/tutorial/query-for-null-fields.txt index 8a508e69abc..2b899a53620 100644 --- a/source/tutorial/query-for-null-fields.txt +++ b/source/tutorial/query-for-null-fields.txt @@ -350,7 +350,9 @@ field. [#type0]_ The query only returns the document that does *not* contain the ``item`` field. -.. seealso:: Reference documentation for the :query:`$type` and +.. seealso:: + + Reference documentation for the :query:`$type` and :query:`$exists` operators. .. [#type0] diff --git a/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt b/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt index 5f46eb95cf0..7c6e4adbf67 100644 --- a/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt +++ b/source/tutorial/reconfigure-replica-set-with-unavailable-members.txt @@ -25,7 +25,7 @@ geographically distributed replica set, where *no* local group of members can reach a majority. See :ref:`replica-set-elections` for more information on this situation. -.. index:: replica set; reconfiguration + .. _replica-set-force-reconfiguration: Reconfigure by Forcing the Reconfiguration @@ -87,4 +87,6 @@ To force reconfiguration: #. If the failure or partition was only temporary, shut down or decommission the removed members as soon as possible. -.. seealso:: :doc:`/tutorial/resync-replica-set-member` +.. seealso:: + + :doc:`/tutorial/resync-replica-set-member` diff --git a/source/tutorial/remove-documents.txt b/source/tutorial/remove-documents.txt index f9107d18615..aebb9c437b2 100644 --- a/source/tutorial/remove-documents.txt +++ b/source/tutorial/remove-documents.txt @@ -168,9 +168,6 @@ This page provides examples in: tabs: - id: shell content: | - .. raw:: html - -
Delete All Documents -------------------- diff --git a/source/tutorial/restore-replica-set-from-backup.txt b/source/tutorial/restore-replica-set-from-backup.txt index c6a65ef80fd..c2e95cece71 100644 --- a/source/tutorial/restore-replica-set-from-backup.txt +++ b/source/tutorial/restore-replica-set-from-backup.txt @@ -4,8 +4,7 @@ Restore a Replica Set from MongoDB Backups .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/restore-sharded-cluster.txt b/source/tutorial/restore-sharded-cluster.txt index 25fcb5850bb..b4741ce5d85 100644 --- a/source/tutorial/restore-sharded-cluster.txt +++ b/source/tutorial/restore-sharded-cluster.txt @@ -4,8 +4,7 @@ Restore a Sharded Cluster .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: @@ -95,12 +94,12 @@ Shut Down Running MongoDB Processes run :method:`db.isMaster()`: * If :data:`~isMaster.ismaster` is false, the ``mongod`` is a - :term:`secondary ` member of a replica set. You + :term:`secondary` member of a replica set. You can shut it down by running :method:`db.shutdownServer()` from the ``admin`` database. * If :data:`~isMaster.ismaster` is true, the ``mongod`` is the - :term:`primary ` member of a replica set. Shut down + :term:`primary` member of a replica set. Shut down the secondary members of the replica set *first*. Use :method:`rs.status()` to identify the other members of the replica set. diff --git a/source/tutorial/resync-replica-set-member.txt b/source/tutorial/resync-replica-set-member.txt index 105d82d2e84..1a392559798 100644 --- a/source/tutorial/resync-replica-set-member.txt +++ b/source/tutorial/resync-replica-set-member.txt @@ -40,8 +40,8 @@ MongoDB provides two options for performing an initial sync: See :ref:`replica-set-resync-by-copying`. -.. index:: replica set; sync -.. index:: replica set; resync + + Procedures ---------- @@ -95,7 +95,7 @@ At this point, the :binary:`~bin.mongod` performs an initial sync. The length of the initial sync process depends on the size of the database and the network latency between members of the replica set. -.. index:: replica set; resync + .. _replica-set-resync-by-copying: Sync by Copying Data Files from Another Member diff --git a/source/tutorial/rotate-encryption-key.txt b/source/tutorial/rotate-encryption-key.txt index fb3eac1a598..fe20b6766be 100644 --- a/source/tutorial/rotate-encryption-key.txt +++ b/source/tutorial/rotate-encryption-key.txt @@ -16,7 +16,7 @@ Most regulatory requirements mandate that a managed key used to decrypt sensitive data must be rotated out and replaced with a new key once a year. -.. admonition:: Disambiguation +.. see:: Disambiguation To roll over database keys configured with AES256-GCM cipher afer a filesystem restore, see :option:`--eseDatabaseKeyRollover ` to authenticate each other as memers of the same deployment. @@ -64,74 +63,70 @@ sequence of keys. keyfile using any method you choose (e.g. ``openssl rand -base64 756``, etc.). -.. container:: - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: multiple-key-strings - name: Multiple Key Strings - content: | + - id: multiple-key-strings + name: Multiple Key Strings + content: | - You can specify multiple key strings where each key - string is **enclosed in quotes**. + You can specify multiple key strings where each key + string is **enclosed in quotes**. - .. figure:: /images/example-multiple-keys1.png - :alt: Image of multiple key strings. - :figwidth: 600px + .. figure:: /images/example-multiple-keys1.png + :alt: Image of multiple key strings. + :figwidth: 600px - - id: multiple-key-sequence - name: Multiple Key Sequence - content: | + - id: multiple-key-sequence + name: Multiple Key Sequence + content: | - You can specify multiple key strings as a sequence of key - strings (optionally enclosed in quotes). + You can specify multiple key strings as a sequence of key + strings (optionally enclosed in quotes). - .. figure:: /images/example-multiple-keys2.png - :alt: Image of multiple key string sequence. - :figwidth: 600px + .. figure:: /images/example-multiple-keys2.png + :alt: Image of multiple key string sequence. + :figwidth: 600px 2. Restart Each Member ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Once all the keyfiles contain both the old and new keys, restart each +member one at a time. - Once all the keyfiles contain both the old and new keys, restart each - member one at a time. +**For each secondary member**, connect a :binary:`~bin.mongo` shell to the +member and: - **For each secondary member**, connect a :binary:`~bin.mongo` shell to the - member and: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - a. Use the :method:`db.shutdownServer()` method to shut down the member: + .. code-block:: javascript - .. code-block:: javascript - - use admin - db.shutdownServer() + use admin + db.shutdownServer() - b. Restart the member. +b. Restart the member. - **For the primary**, connect a :binary:`~bin.mongo` shell to the member and +**For the primary**, connect a :binary:`~bin.mongo` shell to the member and - a. Use :method:`rs.stepDown()` to step down the member: +a. Use :method:`rs.stepDown()` to step down the member: - .. code-block:: javascript + .. code-block:: javascript - rs.stepDown() + rs.stepDown() - #. Use the :method:`db.shutdownServer()` method to shut down the member: +#. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - #. Restart the member. +#. Restart the member. - Since the keyfiles contains both the old and new keys, all members can - now accept either keys for membership authentication. +Since the keyfiles contains both the old and new keys, all members can +now accept either keys for membership authentication. 3. Update Keyfile Content to the New Key Only ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -143,51 +138,47 @@ sequence of keys. keyfile using any method you choose (e.g. ``openssl rand -base64 756``, etc.). -.. container:: - - Modify each member's keyfile to include only the new password. +Modify each member's keyfile to include only the new password. - .. figure:: /images/example-key2.png - :alt: Image of new key. - :figwidth: 558px +.. figure:: /images/example-key2.png + :alt: Image of new key. + :figwidth: 558px 4. Restart Each Member ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Once all the keyfiles contain the new key only, restart each member one +at a time. - Once all the keyfiles contain the new key only, restart each member one - at a time. +**For each secondary member**, connect a :binary:`~bin.mongo` shell to the +member and: - **For each secondary member**, connect a :binary:`~bin.mongo` shell to the - member and: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - a. Use the :method:`db.shutdownServer()` method to shut down the member: + .. code-block:: javascript - .. code-block:: javascript + use admin + db.shutdownServer() - use admin - db.shutdownServer() +b. Restart the member. - b. Restart the member. +**For the primary**, connect a :binary:`~bin.mongo` shell to the member and - **For the primary**, connect a :binary:`~bin.mongo` shell to the member and +a. Use :method:`rs.stepDown()` to step down the member: - a. Use :method:`rs.stepDown()` to step down the member: + .. code-block:: javascript - .. code-block:: javascript + rs.stepDown() - rs.stepDown() +#. Use the :method:`db.shutdownServer()` method to shut down the member: - #. Use the :method:`db.shutdownServer()` method to shut down the member: + .. code-block:: javascript - .. code-block:: javascript - - use admin - db.shutdownServer() + use admin + db.shutdownServer() - #. Restart the member. +#. Restart the member. - All members now accept only the new key for membership authentication. +All members now accept only the new key for membership authentication. diff --git a/source/tutorial/rotate-key-sharded-cluster.txt b/source/tutorial/rotate-key-sharded-cluster.txt index 94360e48985..f6b1c9e8a97 100644 --- a/source/tutorial/rotate-key-sharded-cluster.txt +++ b/source/tutorial/rotate-key-sharded-cluster.txt @@ -4,8 +4,7 @@ Rotate Keys for Sharded Clusters .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + Sharded cluster members can use :ref:`keyfiles ` to authenticate each other as memers of the same deployment. @@ -64,34 +63,32 @@ sequence of keys. keyfile using any method you choose (e.g. ``openssl rand -base64 756``, etc.). -.. container:: - - .. tabs:: +.. tabs:: - tabs: + tabs: - - id: multiple-key-strings - name: Multiple Key Strings - content: | + - id: multiple-key-strings + name: Multiple Key Strings + content: | - You can specify multiple key strings where each key - string is **enclosed in quotes** + You can specify multiple key strings where each key + string is **enclosed in quotes** - .. figure:: /images/example-multiple-keys1.png - :alt: Image of multiple key strings. - :figwidth: 600px + .. figure:: /images/example-multiple-keys1.png + :alt: Image of multiple key strings. + :figwidth: 600px - - id: multiple-key-sequence - name: Multiple Key Sequence - content: | + - id: multiple-key-sequence + name: Multiple Key Sequence + content: | - You can specify multiple key strings as a sequence of key - strings (optionally enclosed in quotes): + You can specify multiple key strings as a sequence of key + strings (optionally enclosed in quotes): - .. figure:: /images/example-multiple-keys2.png - :alt: Image of multiple key string sequence. - :figwidth: 600px + .. figure:: /images/example-multiple-keys2.png + :alt: Image of multiple key string sequence. + :figwidth: 600px 2. Restart Each Member ~~~~~~~~~~~~~~~~~~~~~~ @@ -102,91 +99,85 @@ member one at a time. Config Servers `````````````` -.. container:: - - **For each secondary of the config server replica set (CSRS)**, - connect a :binary:`~bin.mongo` shell to the member and: +**For each secondary of the config server replica set (CSRS)**, +connect a :binary:`~bin.mongo` shell to the member and: - a. Use the :method:`db.shutdownServer()` method to shut down the member: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - b. Restart the member. +b. Restart the member. - **For the primary**, connect a :binary:`~bin.mongo` shell to the member and +**For the primary**, connect a :binary:`~bin.mongo` shell to the member and - a. Use :method:`rs.stepDown()` to step down the member: +a. Use :method:`rs.stepDown()` to step down the member: - .. code-block:: javascript + .. code-block:: javascript - rs.stepDown() + rs.stepDown() - #. Use the :method:`db.shutdownServer()` method to shut down the member: +#. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - #. Restart the member. +#. Restart the member. Shard Replica Sets `````````````````` -.. container:: +**For each secondary member of the shard replica sets**, connect a +:binary:`~bin.mongo` shell to the member and: - **For each secondary member of the shard replica sets**, connect a - :binary:`~bin.mongo` shell to the member and: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - a. Use the :method:`db.shutdownServer()` method to shut down the member: + .. code-block:: javascript - .. code-block:: javascript + use admin + db.shutdownServer() - use admin - db.shutdownServer() +b. Restart the member. - b. Restart the member. +**For the primary of each shard replica set**, connect a +:binary:`~bin.mongo` shell to the member and - **For the primary of each shard replica set**, connect a - :binary:`~bin.mongo` shell to the member and +a. Use :method:`rs.stepDown()` to step down the member: - a. Use :method:`rs.stepDown()` to step down the member: + .. code-block:: javascript - .. code-block:: javascript + rs.stepDown() - rs.stepDown() +#. Use the :method:`db.shutdownServer()` method to shut down the member: - #. Use the :method:`db.shutdownServer()` method to shut down the member: + .. code-block:: javascript - .. code-block:: javascript + use admin + db.shutdownServer() - use admin - db.shutdownServer() - - #. Restart the member. +#. Restart the member. ``mongos`` Routers `````````````````` -.. container:: - - **For each mongos/router instance**, connect a - :binary:`~bin.mongo` shell to the :binary:`~bin.mongos` instance and: +**For each mongos/router instance**, connect a +:binary:`~bin.mongo` shell to the :binary:`~bin.mongos` instance and: - a. Use the :method:`db.shutdownServer()` method to shut down the member: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - b. Restart the member. +b. Restart the member. Once all members have been restarted, the members now accept either the old or new key for membership authentication. @@ -201,109 +192,99 @@ old or new key for membership authentication. keyfile using any method you choose (e.g. ``openssl rand -base64 756``, etc.). -.. container:: - - Modify each member's keyfile to include only the new password. +Modify each member's keyfile to include only the new password. - .. figure:: /images/example-key2.png - :alt: Image of new key. - :figwidth: 558px +.. figure:: /images/example-key2.png + :alt: Image of new key. + :figwidth: 558px 4. Restart Each Member ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - Once all the keyfiles contain the new key only, restart each member one - at a time. +Once all the keyfiles contain the new key only, restart each member one +at a time. Config Servers `````````````` -.. container:: +**For each secondary of the config server replica set (CSRS)**, +connect a :binary:`~bin.mongo` shell to the member and: - **For each secondary of the config server replica set (CSRS)**, - connect a :binary:`~bin.mongo` shell to the member and: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - a. Use the :method:`db.shutdownServer()` method to shut down the member: + .. code-block:: javascript - .. code-block:: javascript + use admin + db.shutdownServer() - use admin - db.shutdownServer() +b. Restart the member. - b. Restart the member. +**For the primary**, connect a :binary:`~bin.mongo` shell to the member and - **For the primary**, connect a :binary:`~bin.mongo` shell to the member and +a. Use :method:`rs.stepDown()` to step down the member: - a. Use :method:`rs.stepDown()` to step down the member: + .. code-block:: javascript - .. code-block:: javascript + rs.stepDown() - rs.stepDown() +#. Use the :method:`db.shutdownServer()` method to shut down the member: - #. Use the :method:`db.shutdownServer()` method to shut down the member: + .. code-block:: javascript - .. code-block:: javascript + use admin + db.shutdownServer() - use admin - db.shutdownServer() - - #. Restart the member. +#. Restart the member. Shard Replica Sets `````````````````` -.. container:: - - **For each secondary member of the shard replica sets**, connect a - :binary:`~bin.mongo` shell to the member and: +**For each secondary member of the shard replica sets**, connect a +:binary:`~bin.mongo` shell to the member and: - a. Use the :method:`db.shutdownServer()` method to shut down the member: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - b. Restart the member. +b. Restart the member. - **For the primary of each shard replica set**, connect a - :binary:`~bin.mongo` shell to the member and +**For the primary of each shard replica set**, connect a +:binary:`~bin.mongo` shell to the member and - a. Use :method:`rs.stepDown()` to step down the member: +a. Use :method:`rs.stepDown()` to step down the member: - .. code-block:: javascript + .. code-block:: javascript - rs.stepDown() + rs.stepDown() - #. Use the :method:`db.shutdownServer()` method to shut down the member: +#. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - #. Restart the member. +#. Restart the member. ``mongos`` Routers `````````````````` -.. container:: - - **For each mongos/router instance**, connect a - :binary:`~bin.mongo` shell to the :binary:`~bin.mongos` instance and: +**For each mongos/router instance**, connect a +:binary:`~bin.mongo` shell to the :binary:`~bin.mongos` instance and: - a. Use the :method:`db.shutdownServer()` method to shut down the member: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - b. Restart the member. +b. Restart the member. Once all members have been restarted, the members now accept only the new key for membership authentication. diff --git a/source/tutorial/rotate-log-files.txt b/source/tutorial/rotate-log-files.txt index 4d42e118661..4f9477ce12e 100644 --- a/source/tutorial/rotate-log-files.txt +++ b/source/tutorial/rotate-log-files.txt @@ -39,7 +39,9 @@ Finally, you can configure :binary:`~bin.mongod` to send log data to the ``syslog`` using the :option:`--syslog ` option. In this case, you can take advantage of alternate log rotation tools. -.. seealso:: For information on logging, see the +.. seealso:: + + For information on logging, see the :ref:`monitoring-standard-loggging` section. Default Log Rotation Behavior diff --git a/source/tutorial/rotate-x509-membership-certificates.txt b/source/tutorial/rotate-x509-membership-certificates.txt index b4826757e04..ede10fe5902 100644 --- a/source/tutorial/rotate-x509-membership-certificates.txt +++ b/source/tutorial/rotate-x509-membership-certificates.txt @@ -4,8 +4,7 @@ Rolling Update of x.509 Cluster Certificates that Contain New DN .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + Members of a replica set or a sharded cluster can use :ref:`x.509 certificates for membership authentication ` to @@ -60,119 +59,110 @@ Procedure 0. Optional. Set Override Parameter on Running Members ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: - - The procedure requires that all members of the deployment be - restarted. As the settings will not take into consideration until - you restart all members, your instances may log messages until the - procedure completes. +The procedure requires that all members of the deployment be +restarted. As the settings will not take into consideration until +you restart all members, your instances may log messages until the +procedure completes. - To avoid these messages, you can set the override parameter on - running members. +To avoid these messages, you can set the override parameter on +running members. - Connect a :binary:`~bin.mongo` shell directly to each member of the - deployment and set the :parameter:`tlsX509ClusterAuthDNOverride` - parameter to the new certificate ``DN``: +Connect a :binary:`~bin.mongo` shell directly to each member of the +deployment and set the :parameter:`tlsX509ClusterAuthDNOverride` +parameter to the new certificate ``DN``: - .. code-block:: javascript +.. code-block:: javascript - db.adminCommand( { setParameter: 1, tlsX509ClusterAuthDNOverride: "OU=MongoDB Server,O=MongoDB" } ) + db.adminCommand( { setParameter: 1, tlsX509ClusterAuthDNOverride: "OU=MongoDB Server,O=MongoDB" } ) 1. Modify the Configuration of ALL Members ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Modify each member's configuration: -.. container:: - - Modify each member's configuration: - - - Update :setting:`net.tls.certificateKeyFile` to the new certificate. +- Update :setting:`net.tls.certificateKeyFile` to the new certificate. - - Update :setting:`net.tls.clusterFile` to the new certificate. +- Update :setting:`net.tls.clusterFile` to the new certificate. - - Set :parameter:`tlsX509ClusterAuthDNOverride` parameter to the new - certificate ``DN``. +- Set :parameter:`tlsX509ClusterAuthDNOverride` parameter to the new + certificate ``DN``. - For example: +For example: - .. code-block:: yaml +.. code-block:: yaml - net.tls.mode: requireTLS - net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem" - net.tls.CAFile: "./mycerts/ca.pem" + net.tls.mode: requireTLS + net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem" + net.tls.CAFile: "./mycerts/ca.pem" - security.clusterAuthMode: x509 + security.clusterAuthMode: x509 - net.tls.clusterFile: "./mycerts/mongodb-cluster1.pem" - net.tls.clusterCAFile: "./mycerts/ca.pem" + net.tls.clusterFile: "./mycerts/mongodb-cluster1.pem" + net.tls.clusterCAFile: "./mycerts/ca.pem" - setParameter: - tlsX509ClusterAuthDNOverride: "OU=MongoDB Server,O=MongoDB" + setParameter: + tlsX509ClusterAuthDNOverride: "OU=MongoDB Server,O=MongoDB" - The settings will not take into consideration until you restart each - member (see next step). +The settings will not take into consideration until you restart each +member (see next step). 2. Restart Each Member ~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Once you have modified the configuration for all the members, +restart each secondaries and then the primary. - Once you have modified the configuration for all the members, - restart each secondaries and then the primary. +**For each secondary member**, connect a :binary:`~bin.mongo` shell to the +member and: - **For each secondary member**, connect a :binary:`~bin.mongo` shell to the - member and: +a. Use the :method:`db.shutdownServer()` method to shut down the member: - a. Use the :method:`db.shutdownServer()` method to shut down the member: - - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - b. Restart the member. +b. Restart the member. - Ensure the member has reached :replstate:`SECONDARY` state before - restarting the next secondary. + Ensure the member has reached :replstate:`SECONDARY` state before + restarting the next secondary. - **For the primary**, connect a :binary:`~bin.mongo` shell to the member and +**For the primary**, connect a :binary:`~bin.mongo` shell to the member and - a. Use :method:`rs.stepDown()` to step down the member: +a. Use :method:`rs.stepDown()` to step down the member: - .. code-block:: javascript + .. code-block:: javascript - rs.stepDown() + rs.stepDown() - #. Use the :method:`db.shutdownServer()` method to shut down the member: +#. Use the :method:`db.shutdownServer()` method to shut down the member: - .. code-block:: javascript + .. code-block:: javascript - use admin - db.shutdownServer() + use admin + db.shutdownServer() - #. Restart the member. +#. Restart the member. 3. Remove the ``tlsX509ClusterAuthDNOverride`` Setting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. container:: +Once all the members have been restarted with the new certificate, +you can remove the ``tlsX509ClusterAuthDNOverride`` parameter from +the configuration. - Once all the members have been restarted with the new certificate, - you can remove the ``tlsX509ClusterAuthDNOverride`` parameter from - the configuration. - - For example: +For example: - .. code-block:: yaml +.. code-block:: yaml - net.tls.mode: requireTLS - net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem" - net.tls.CAFile: "./mycerts/ca.pem" + net.tls.mode: requireTLS + net.tls.certificateKeyFile: "./mycerts/mongodb-server1.pem" + net.tls.CAFile: "./mycerts/ca.pem" - security.clusterAuthMode: x509 + security.clusterAuthMode: x509 - net.tls.clusterFile: "./mycerts/mongodb-cluster1.pem" - net.tls.clusterCAFile: "./mycerts/ca.pem" + net.tls.clusterFile: "./mycerts/mongodb-cluster1.pem" + net.tls.clusterCAFile: "./mycerts/ca.pem" - The settings will not take into consideration until you restart each - member. +The settings will not take into consideration until you restart each +member. diff --git a/source/tutorial/schedule-backup-window-for-sharded-clusters.txt b/source/tutorial/schedule-backup-window-for-sharded-clusters.txt index 6d32ccbd1b6..4e05960f57c 100644 --- a/source/tutorial/schedule-backup-window-for-sharded-clusters.txt +++ b/source/tutorial/schedule-backup-window-for-sharded-clusters.txt @@ -4,8 +4,7 @@ Schedule Backup Window for Sharded Clusters .. default-domain:: mongodb -.. role:: red(strong) - :class: text-danger + .. contents:: On this page :local: diff --git a/source/tutorial/sharding-high-availability-writes.txt b/source/tutorial/sharding-high-availability-writes.txt index 54b822b7931..a56d67f6e59 100644 --- a/source/tutorial/sharding-high-availability-writes.txt +++ b/source/tutorial/sharding-high-availability-writes.txt @@ -19,11 +19,9 @@ sharded cluster deployment and application-side logic to support distributed local writes, as well as high write availability in the event of a replica set election or datacenter failure. -.. tip:: +.. versionchanged:: 4.0.3 - .. versionchanged:: 4.0.3 - - .. include:: /includes/extracts/zoned-sharding-pre-define-zone.rst + .. include:: /includes/extracts/zoned-sharding-pre-define-zone.rst .. important:: @@ -79,8 +77,6 @@ Shard Key The collection uses the ``{ datacenter : 1, userid : 1 }`` compound index as the :term:`shard key`. -.. TODO:: actually discuss tag ranges in tag aware sharding page and link it here - The ``datacenter`` field in each document allows for creating a tag range on each distinct datacenter value. Without the ``datacenter`` field, it would not be possible to associate a document with a specific datacenter. diff --git a/source/tutorial/split-chunks-in-sharded-cluster.txt b/source/tutorial/split-chunks-in-sharded-cluster.txt index 56d5a15cb46..9584a49addf 100644 --- a/source/tutorial/split-chunks-in-sharded-cluster.txt +++ b/source/tutorial/split-chunks-in-sharded-cluster.txt @@ -80,4 +80,6 @@ document as the lower bound in the new chunk: the document matching the query, regardless of where that document is in the chunk. -.. seealso:: :ref:`initial-chunks-empty-collection` +.. seealso:: + + :ref:`initial-chunks-empty-collection` diff --git a/source/tutorial/text-search-with-rlp.txt b/source/tutorial/text-search-with-rlp.txt index 359a6d9b1b1..00ad04563a1 100644 --- a/source/tutorial/text-search-with-rlp.txt +++ b/source/tutorial/text-search-with-rlp.txt @@ -12,8 +12,7 @@ Text Search with Basis Technology Rosette Linguistics Platform :depth: 1 :class: singlecol -.. admonition:: Removal of Support for RLP - :class: admonition-example +.. deprecated:: MongoDB Enterprise no longer supports Text Search with Basis Technology Rosette Linguistics Platform. diff --git a/source/tutorial/troubleshoot-replica-sets.txt b/source/tutorial/troubleshoot-replica-sets.txt index 268f82f67ac..9f2e1405e4d 100644 --- a/source/tutorial/troubleshoot-replica-sets.txt +++ b/source/tutorial/troubleshoot-replica-sets.txt @@ -120,7 +120,7 @@ Possible causes of replication lag include: If you are performing a large data ingestion or bulk load operation that requires a large number of writes to the primary, particularly with :writeconcern:`unacknowledged write concern - <0>`, the secondaries will not be able to + `, the secondaries will not be able to read the oplog fast enough to keep up with changes. To prevent this, request :doc:`write acknowledgement diff --git a/source/tutorial/troubleshoot-snmp.txt b/source/tutorial/troubleshoot-snmp.txt index 0c7fd5d3cb3..0f2829521ee 100644 --- a/source/tutorial/troubleshoot-snmp.txt +++ b/source/tutorial/troubleshoot-snmp.txt @@ -10,7 +10,7 @@ Troubleshoot SNMP :depth: 1 :class: singlecol -.. admonition:: Enterprise Feature +.. note:: Enterprise Feature SNMP is only available in MongoDB Enterprise. @@ -94,9 +94,11 @@ Edition produce this error. :doc:`Install the Enterprise Edition ` and attempt to start :binary:`~bin.mongod` again. -Other MongoDB binaries, including :binary:`~bin.mongos` will produce this -error if you attempt to start them with :setting:`snmp-master` or -:setting:`snmp-subagent`. Only :binary:`~bin.mongod` supports SNMP. +Other MongoDB binaries, including :binary:`~bin.mongos` will produce +this error if you attempt to start them with +:option:`snmp-master ` or +:option:`snmp-subagent `. Only +:binary:`~bin.mongod` supports SNMP. .. include:: /includes/fact-macos-snmp.rst diff --git a/source/tutorial/update-documents-with-aggregation-pipeline.txt b/source/tutorial/update-documents-with-aggregation-pipeline.txt index b905b190d73..2f9b8c2265b 100644 --- a/source/tutorial/update-documents-with-aggregation-pipeline.txt +++ b/source/tutorial/update-documents-with-aggregation-pipeline.txt @@ -30,7 +30,7 @@ field values or updating one field using the value of another field(s). Example 1 ---------- -.. only:: website +.. tip:: You can try out the example in the provided shell. Click inside the shell to connect. Once connected, you can run the examples in the @@ -38,291 +38,282 @@ Example 1 .. include:: /includes/fact-mws.rst -.. container:: +Create an example ``students`` collection (if the collection does +not currently exist, insert operations will create the collection): - Create an example ``students`` collection (if the collection does - not currently exist, insert operations will create the collection): +.. code-block:: javascript - .. code-block:: javascript + db.students.insertMany([ + { _id: 1, test1: 95, test2: 92, test3: 90, modified: new Date("01/05/2020") }, + { _id: 2, test1: 98, test2: 100, test3: 102, modified: new Date("01/05/2020") }, + { _id: 3, test1: 95, test2: 110, modified: new Date("01/04/2020") } + ]) - db.students.insertMany([ - { _id: 1, test1: 95, test2: 92, test3: 90, modified: new Date("01/05/2020") }, - { _id: 2, test1: 98, test2: 100, test3: 102, modified: new Date("01/05/2020") }, - { _id: 3, test1: 95, test2: 110, modified: new Date("01/04/2020") } - ]) +To verify, query the collection: - To verify, query the collection: +.. code-block:: javascript - .. code-block:: javascript + db.students.find() - db.students.find() +The following :method:`db.collection.updateOne()` operation uses an +aggregation pipeline to update the document with ``_id: 3``: - The following :method:`db.collection.updateOne()` operation uses an - aggregation pipeline to update the document with ``_id: 3``: +.. code-block:: javascript - .. code-block:: javascript + db.students.updateOne( { _id: 3 }, [ { $set: { "test3": 98, modified: "$$NOW"} } ] ) - db.students.updateOne( { _id: 3 }, [ { $set: { "test3": 98, modified: "$$NOW"} } ] ) +Specifically, the pipeline consists of a :pipeline:`$set` stage +which adds the ``test3`` field (and sets its value to ``98``) to the +document and sets the ``modified`` field to the current datetime. +For the current datetime, the operation uses the aggregation +variable :variable:`NOW` for the (to access the variable, prefix with ``$$`` +and enclose in quotes). - Specifically, the pipeline consists of a :pipeline:`$set` stage - which adds the ``test3`` field (and sets its value to ``98``) to the - document and sets the ``modified`` field to the current datetime. - For the current datetime, the operation uses the aggregation - variable :variable:`NOW` for the (to access the variable, prefix with ``$$`` - and enclose in quotes). +To verify the update, you can query the collection: - To verify the update, you can query the collection: +.. code-block:: javascript - .. code-block:: javascript - - db.students.find().pretty() + db.students.find().pretty() Example 2 ---------- -.. only:: website +.. tip:: - You can try out the examples in the provided shell. Click inside the + You can try out the example in the provided shell. Click inside the shell to connect. Once connected, you can run the examples in the shell. .. include:: /includes/fact-mws.rst -.. container:: +Create an example ``students2`` collection (if the collection does not +currently exist, insert operations will create the collection): - Create an example ``students2`` collection (if the collection does not - currently exist, insert operations will create the collection): +.. code-block:: javascript - .. code-block:: javascript + db.students2.insertMany([ + { "_id" : 1, quiz1: 8, test2: 100, quiz2: 9, modified: new Date("01/05/2020") }, + { "_id" : 2, quiz2: 5, test1: 80, test2: 89, modified: new Date("01/05/2020") }, + ]) - db.students2.insertMany([ - { "_id" : 1, quiz1: 8, test2: 100, quiz2: 9, modified: new Date("01/05/2020") }, - { "_id" : 2, quiz2: 5, test1: 80, test2: 89, modified: new Date("01/05/2020") }, - ]) +To verify, query the collection: - To verify, query the collection: +.. code-block:: javascript - .. code-block:: javascript + db.students2.find() - db.students2.find() +The following +:method:`db.collection.updateMany()` operation uses an aggregation +pipeline to standardize the fields for the documents (i.e. documents +in the collection should have the same fields) and update the +``modified`` field: - The following - :method:`db.collection.updateMany()` operation uses an aggregation - pipeline to standardize the fields for the documents (i.e. documents - in the collection should have the same fields) and update the - ``modified`` field: - - .. code-block:: javascript +.. code-block:: javascript - db.students2.updateMany( {}, - [ - { $replaceRoot: { newRoot: - { $mergeObjects: [ { quiz1: 0, quiz2: 0, test1: 0, test2: 0 }, "$$ROOT" ] } - } }, - { $set: { modified: "$$NOW"} } - ] - ) + db.students2.updateMany( {}, + [ + { $replaceRoot: { newRoot: + { $mergeObjects: [ { quiz1: 0, quiz2: 0, test1: 0, test2: 0 }, "$$ROOT" ] } + } }, + { $set: { modified: "$$NOW"} } + ] + ) - Specifically, the pipeline consists of: +Specifically, the pipeline consists of: - - a :pipeline:`$replaceRoot` stage with an - :expression:`$mergeObjects` expression to set default values for - the ``quiz1``, ``quiz2``, ``test1`` and ``test2`` fields. The - aggregation variable :variable:`ROOT` refers to the current - document being modified (to access the variable, prefix with - ``$$`` and enclose in quotes). The current document fields will - override the default values. +- a :pipeline:`$replaceRoot` stage with a + :expression:`$mergeObjects` expression to set default values for + the ``quiz1``, ``quiz2``, ``test1`` and ``test2`` fields. The + aggregation variable :variable:`ROOT` refers to the current + document being modified (to access the variable, prefix with + ``$$`` and enclose in quotes). The current document fields will + override the default values. - - a :pipeline:`$set` stage to update the ``modified`` field to the - current datetime. For the current datetime, the operation uses the - aggregation variable :variable:`NOW` for the (to access the - variable, prefix with ``$$`` and enclose in quotes). +- a :pipeline:`$set` stage to update the ``modified`` field to the + current datetime. For the current datetime, the operation uses the + aggregation variable :variable:`NOW` for the (to access the + variable, prefix with ``$$`` and enclose in quotes). - To verify the update, you can query the collection: +To verify the update, you can query the collection: - .. code-block:: javascript +.. code-block:: javascript - db.students2.find() + db.students2.find() Example 3 --------- -.. only:: website +.. tip:: - You can try out the examples in the provided shell. Click inside the + You can try out the example in the provided shell. Click inside the shell to connect. Once connected, you can run the examples in the shell. .. include:: /includes/fact-mws.rst -.. container:: - Create an example ``students3`` collection (if the collection does not - currently exist, insert operations will create the collection): +Create an example ``students3`` collection (if the collection does not +currently exist, insert operations will create the collection): - .. code-block:: javascript +.. code-block:: javascript - db.students3.insert([ - { "_id" : 1, "tests" : [ 95, 92, 90 ], "modified" : ISODate("2019-01-01T00:00:00Z") }, - { "_id" : 2, "tests" : [ 94, 88, 90 ], "modified" : ISODate("2019-01-01T00:00:00Z") }, - { "_id" : 3, "tests" : [ 70, 75, 82 ], "modified" : ISODate("2019-01-01T00:00:00Z") } - ]); + db.students3.insert([ + { "_id" : 1, "tests" : [ 95, 92, 90 ], "modified" : ISODate("2019-01-01T00:00:00Z") }, + { "_id" : 2, "tests" : [ 94, 88, 90 ], "modified" : ISODate("2019-01-01T00:00:00Z") }, + { "_id" : 3, "tests" : [ 70, 75, 82 ], "modified" : ISODate("2019-01-01T00:00:00Z") } + ]); - To verify, query the collection: +To verify, query the collection: - .. code-block:: javascript +.. code-block:: javascript - db.students3.find() + db.students3.find() - The following :method:`db.collection.updateMany()` operation uses an - aggregation pipeline to update the documents with the calculated - grade average and letter grade. +The following :method:`db.collection.updateMany()` operation uses an +aggregation pipeline to update the documents with the calculated +grade average and letter grade. - .. code-block:: javascript +.. code-block:: javascript - db.students3.updateMany( - { }, - [ - { $set: { average : { $trunc: [ { $avg: "$tests" }, 0 ] }, modified: "$$NOW" } }, - { $set: { grade: { $switch: { - branches: [ - { case: { $gte: [ "$average", 90 ] }, then: "A" }, - { case: { $gte: [ "$average", 80 ] }, then: "B" }, - { case: { $gte: [ "$average", 70 ] }, then: "C" }, - { case: { $gte: [ "$average", 60 ] }, then: "D" } - ], - default: "F" - } } } } - ] - ) + db.students3.updateMany( + { }, + [ + { $set: { average : { $trunc: [ { $avg: "$tests" }, 0 ] }, modified: "$$NOW" } }, + { $set: { grade: { $switch: { + branches: [ + { case: { $gte: [ "$average", 90 ] }, then: "A" }, + { case: { $gte: [ "$average", 80 ] }, then: "B" }, + { case: { $gte: [ "$average", 70 ] }, then: "C" }, + { case: { $gte: [ "$average", 60 ] }, then: "D" } + ], + default: "F" + } } } } + ] + ) - Specifically, the pipeline consists of: +Specifically, the pipeline consists of: - - a :pipeline:`$set` stage to calculate the truncated average value - of the ``tests`` array elements and to update the ``modified`` - field to the current datetime. To calculate the truncated average, - the stage uses the :expression:`$avg` and :expression:`$trunc` - expressions. For the current datetime, the operation uses the - aggregation variable :variable:`NOW` for the (to access the - variable, prefix with ``$$`` and enclose in quotes) - - - a :pipeline:`$set` stage to add the ``grade`` field based on the - ``average`` using the :expression:`$switch` expression. +- a :pipeline:`$set` stage to calculate the truncated average value + of the ``tests`` array elements and to update the ``modified`` + field to the current datetime. To calculate the truncated average, + the stage uses the :group:`$avg` and :expression:`$trunc` + expressions. For the current datetime, the operation uses the + aggregation variable :variable:`NOW` for the (to access the + variable, prefix with ``$$`` and enclose in quotes) - To verify the update, you can query the collection: +- a :pipeline:`$set` stage to add the ``grade`` field based on the + ``average`` using the :expression:`$switch` expression. - .. code-block:: javascript +To verify the update, you can query the collection: - db.students3.find() +.. code-block:: javascript + + db.students3.find() Example 4 --------- -.. only:: website +.. tip:: - You can try out the examples in the provided shell. Click inside the + You can try out the example in the provided shell. Click inside the shell to connect. Once connected, you can run the examples in the shell. .. include:: /includes/fact-mws.rst -.. container:: - - Create an example ``students4`` collection (if the collection does - not currently exist, insert operations will create the collection): +Create an example ``students4`` collection (if the collection does +not currently exist, insert operations will create the collection): - .. code-block:: javascript +.. code-block:: javascript - db.students4.insertMany([ - { "_id" : 1, "quizzes" : [ 4, 6, 7 ] }, - { "_id" : 2, "quizzes" : [ 5 ] }, - { "_id" : 3, "quizzes" : [ 10, 10, 10 ] } - ]) + db.students4.insertMany([ + { "_id" : 1, "quizzes" : [ 4, 6, 7 ] }, + { "_id" : 2, "quizzes" : [ 5 ] }, + { "_id" : 3, "quizzes" : [ 10, 10, 10 ] } + ]) - To verify, query the collection: +To verify, query the collection: - .. code-block:: javascript +.. code-block:: javascript - db.students4.find() + db.students4.find() - The following :method:`db.collection.updateOne()` operation uses an - aggregation pipeline to add quiz scores to the document with ``_id: - 2``: +The following :method:`db.collection.updateOne()` operation uses an +aggregation pipeline to add quiz scores to the document with ``_id: +2``: - .. code-block:: javascript +.. code-block:: javascript - db.students4.updateOne( { _id: 2 }, - [ { $set: { quizzes: { $concatArrays: [ "$quizzes", [ 8, 6 ] ] } } } ] - ) + db.students4.updateOne( { _id: 2 }, + [ { $set: { quizzes: { $concatArrays: [ "$quizzes", [ 8, 6 ] ] } } } ] + ) - To verify the update, query the collection: +To verify the update, query the collection: - .. code-block:: javascript +.. code-block:: javascript - db.students4.find() + db.students4.find() Example 5 --------- -.. only:: website +.. tip:: - You can try out the examples in the provided shell. Click inside the + You can try out the example in the provided shell. Click inside the shell to connect. Once connected, you can run the examples in the shell. .. include:: /includes/fact-mws.rst -.. container:: +Create an example ``temperatures`` collection that contains +temperatures in Celsius (if the collection does not currently exist, +insert operations will create the collection): - Create an example ``temperatures`` collection that contains - temperatures in Celsius (if the collection does not currently exist, - insert operations will create the collection): +.. code-block:: javascript - .. code-block:: javascript + db.temperatures.insertMany([ + { "_id" : 1, "date" : ISODate("2019-06-23"), "tempsC" : [ 4, 12, 17 ] }, + { "_id" : 2, "date" : ISODate("2019-07-07"), "tempsC" : [ 14, 24, 11 ] }, + { "_id" : 3, "date" : ISODate("2019-10-30"), "tempsC" : [ 18, 6, 8 ] } + ]) - db.temperatures.insertMany([ - { "_id" : 1, "date" : ISODate("2019-06-23"), "tempsC" : [ 4, 12, 17 ] }, - { "_id" : 2, "date" : ISODate("2019-07-07"), "tempsC" : [ 14, 24, 11 ] }, - { "_id" : 3, "date" : ISODate("2019-10-30"), "tempsC" : [ 18, 6, 8 ] } - ]) - - To verify, query the collection: +To verify, query the collection: - .. code-block:: javascript +.. code-block:: javascript - db.temperatures.find() + db.temperatures.find() - The following :method:`db.collection.updateMany()` operation uses an - aggregation pipeline to update the documents with the corresponding - temperatures in Fahrenheit: +The following :method:`db.collection.updateMany()` operation uses an +aggregation pipeline to update the documents with the corresponding +temperatures in Fahrenheit: - .. code-block:: javascript +.. code-block:: javascript - db.temperatures.updateMany( { }, - [ - { $addFields: { "tempsF": { - $map: { - input: "$tempsC", - as: "celsius", - in: { $add: [ { $multiply: ["$$celsius", 9/5 ] }, 32 ] } - } - } } } - ] - ) + db.temperatures.updateMany( { }, + [ + { $addFields: { "tempsF": { + $map: { + input: "$tempsC", + as: "celsius", + in: { $add: [ { $multiply: ["$$celsius", 9/5 ] }, 32 ] } + } + } } } + ] + ) - Specifically, the pipeline consists of an :pipeline:`$addFields` - stage to add a new array field ``tempsF`` that contains the - temperatures in Fahrenheit. To convert each celsius temperature in - the ``tempsC`` array to Fahrenheit, the stage uses the - :expression:`$map` expression with :expression:`$add` and - :expression:`$multiply` expressions. +Specifically, the pipeline consists of an :pipeline:`$addFields` +stage to add a new array field ``tempsF`` that contains the +temperatures in Fahrenheit. To convert each celsius temperature in +the ``tempsC`` array to Fahrenheit, the stage uses the +:expression:`$map` expression with :expression:`$add` and +:expression:`$multiply` expressions. - To verify the update, you can query the collection: +To verify the update, you can query the collection: - .. code-block:: javascript +.. code-block:: javascript - db.temperatures.find() + db.temperatures.find() Additional Examples ------------------- diff --git a/source/tutorial/upgrade-cluster-to-ssl.txt b/source/tutorial/upgrade-cluster-to-ssl.txt index 488a3ab5830..9332e5f77ce 100644 --- a/source/tutorial/upgrade-cluster-to-ssl.txt +++ b/source/tutorial/upgrade-cluster-to-ssl.txt @@ -37,83 +37,81 @@ process. as the ``ssl`` options since MongoDB has always supported TLS 1.0 and later. -.. container:: - - #. For each node of a cluster, start the node with the command-line option - ``--tlsMode`` or the configuration file option :setting:`net.tls.mode` set to ``allowTLS``. - The ``allowTLS`` setting allows the node to accept both TLS/SSL - and non-TLS/non-SSL incoming connections. Its connections to other servers - do not use TLS/SSL. Include other :doc:`TLS/SSL options - ` [#systemstore]_ as well as any other options that are - required for your specific configuration. - - .. note:: +#. For each node of a cluster, start the node with the command-line option + ``--tlsMode`` or the configuration file option :setting:`net.tls.mode` set to ``allowTLS``. + The ``allowTLS`` setting allows the node to accept both TLS/SSL + and non-TLS/non-SSL incoming connections. Its connections to other servers + do not use TLS/SSL. Include other :doc:`TLS/SSL options + ` [#systemstore]_ as well as any other options that are + required for your specific configuration. + + .. note:: - .. include:: /includes/extracts/default-bind-ip-security.rst + .. include:: /includes/extracts/default-bind-ip-security.rst - For example: + For example: - .. tabs:: + .. tabs:: - tabs: + tabs: - - id: commandline - name: Command-Line Options - content: | + - id: commandline + name: Command-Line Options + content: | - .. code-block:: sh + .. code-block:: sh - mongod --replSet --tlsMode allowTLS --tlsCertificateKeyFile --sslCAFile + mongod --replSet --tlsMode allowTLS --tlsCertificateKeyFile --sslCAFile - - id: config - name: Configuration File Options - content: | + - id: config + name: Configuration File Options + content: | - To specify these options in the :doc:`configuration file - `, include the following - settings in the file: + To specify these options in the :doc:`configuration file + `, include the following + settings in the file: - .. code-block:: yaml + .. code-block:: yaml - net: - tls: - mode: allowTLS - PEMKeyFile: - CAFile: + net: + tls: + mode: allowTLS + PEMKeyFile: + CAFile: - Upgrade all nodes of the cluster to these settings. + Upgrade all nodes of the cluster to these settings. - #. Switch all clients to use TLS/SSL. See :ref:`ssl-clients`. +#. Switch all clients to use TLS/SSL. See :ref:`ssl-clients`. - #. For each node of a cluster, use the :dbcommand:`setParameter` - command to update the :parameter:`tlsMode` to ``preferTLS``. - [#update-mode-alternative]_ With ``preferTLS`` as its - :setting:`net.tls.mode`, the node accepts both TLS/SSL and non-TLS/non-SSL incoming - connections, and its connections to other servers use TLS/SSL. For - example: +#. For each node of a cluster, use the :dbcommand:`setParameter` + command to update the :parameter:`tlsMode` to ``preferTLS``. + [#update-mode-alternative]_ With ``preferTLS`` as its + :setting:`net.tls.mode`, the node accepts both TLS/SSL and non-TLS/non-SSL incoming + connections, and its connections to other servers use TLS/SSL. For + example: - .. code-block:: sh + .. code-block:: sh - db.adminCommand( { setParameter: 1, tlsMode: "preferTLS" } ) + db.adminCommand( { setParameter: 1, tlsMode: "preferTLS" } ) - Upgrade all nodes of the cluster to these settings. + Upgrade all nodes of the cluster to these settings. - At this point, all connections should be using TLS/SSL. + At this point, all connections should be using TLS/SSL. - #. For each node of the cluster, use the - :dbcommand:`setParameter` command to update the :parameter:`tlsMode` - to ``requireTLS``. [#update-mode-alternative]_ With ``requireTLS`` - as its :setting:`net.tls.mode`, the node will reject any non-TLS/non-SSL - connections. For example: +#. For each node of the cluster, use the + :dbcommand:`setParameter` command to update the :parameter:`tlsMode` + to ``requireTLS``. [#update-mode-alternative]_ With ``requireTLS`` + as its :setting:`net.tls.mode`, the node will reject any non-TLS/non-SSL + connections. For example: - .. code-block:: sh + .. code-block:: sh - db.adminCommand( { setParameter: 1, tlsMode: "requireTLS" } ) + db.adminCommand( { setParameter: 1, tlsMode: "requireTLS" } ) - #. After the upgrade of all nodes, edit the :doc:`configuration file - ` with the appropriate TLS/SSL - settings to ensure that upon subsequent restarts, the cluster uses - TLS/SSL. +#. After the upgrade of all nodes, edit the :doc:`configuration file + ` with the appropriate TLS/SSL + settings to ensure that upon subsequent restarts, the cluster uses + TLS/SSL. .. _upgrade-to-ssl: @@ -139,84 +137,81 @@ process. as the ``ssl`` options since MongoDB has always supported TLS 1.0 and later. +#. For each node of a cluster, start the node with the command-line option + ``--sslMode`` or the configuration file option :setting:`net.ssl.mode` set to ``allowSSL``. + The ``allowSSL`` setting allows the node to accept both TLS/SSL + and non-TLS/non-SSL incoming connections. Its connections to other servers + do not use TLS/SSL. Include other :doc:`TLS/SSL options + ` [#systemstore]_ as well as any other options that are + required for your specific configuration. -.. container:: - - #. For each node of a cluster, start the node with the command-line option - ``--sslMode`` or the configuration file option :setting:`net.ssl.mode` set to ``allowSSL``. - The ``allowSSL`` setting allows the node to accept both TLS/SSL - and non-TLS/non-SSL incoming connections. Its connections to other servers - do not use TLS/SSL. Include other :doc:`TLS/SSL options - ` [#systemstore]_ as well as any other options that are - required for your specific configuration. - - .. note:: + .. note:: - .. include:: /includes/extracts/default-bind-ip-security.rst + .. include:: /includes/extracts/default-bind-ip-security.rst - For example: + For example: - .. tabs:: + .. tabs:: - tabs: + tabs: - - id: commandline - name: Command-Line Options - content: | + - id: commandline + name: Command-Line Options + content: | - .. code-block:: sh + .. code-block:: sh - mongod --replSet --sslMode allowSSL --sslPEMKeyFile --sslCAFile + mongod --replSet --sslMode allowSSL --sslPEMKeyFile --sslCAFile - - id: config - name: Configuration File Options - content: | + - id: config + name: Configuration File Options + content: | - To specify these options in the :doc:`configuration file - `, include the following - settings in the file: + To specify these options in the :doc:`configuration file + `, include the following + settings in the file: - .. code-block:: yaml + .. code-block:: yaml - net: - ssl: - mode: - PEMKeyFile: - CAFile: + net: + ssl: + mode: + PEMKeyFile: + CAFile: - Upgrade all nodes of the cluster to these settings. + Upgrade all nodes of the cluster to these settings. - #. Switch all clients to use TLS/SSL. See :ref:`ssl-clients`. +#. Switch all clients to use TLS/SSL. See :ref:`ssl-clients`. - #. For each node of a cluster, use the :dbcommand:`setParameter` - command to update the :parameter:`sslMode` to ``preferSSL``. - [#update-mode-alternative]_ With ``preferSSL`` as its - :setting:`net.ssl.mode`, the node accepts both TLS/SSL and non-TLS/non-SSL incoming - connections, and its connections to other servers use TLS/SSL. For - example: +#. For each node of a cluster, use the :dbcommand:`setParameter` + command to update the :parameter:`sslMode` to ``preferSSL``. + [#update-mode-alternative]_ With ``preferSSL`` as its + :setting:`net.ssl.mode`, the node accepts both TLS/SSL and non-TLS/non-SSL incoming + connections, and its connections to other servers use TLS/SSL. For + example: - .. code-block:: sh + .. code-block:: sh - db.adminCommand( { setParameter: 1, sslMode: "preferSSL" } ) + db.adminCommand( { setParameter: 1, sslMode: "preferSSL" } ) - Upgrade all nodes of the cluster to these settings. + Upgrade all nodes of the cluster to these settings. - At this point, all connections should be using TLS/SSL. + At this point, all connections should be using TLS/SSL. - #. For each node of the cluster, use the - :dbcommand:`setParameter` command to update the :parameter:`sslMode` - to ``requireSSL``. [#update-mode-alternative]_ With ``requireSSL`` - as its :setting:`net.ssl.mode`, the node will reject any non-TLS/non-SSL - connections. For example: +#. For each node of the cluster, use the + :dbcommand:`setParameter` command to update the :parameter:`sslMode` + to ``requireSSL``. [#update-mode-alternative]_ With ``requireSSL`` + as its :setting:`net.ssl.mode`, the node will reject any non-TLS/non-SSL + connections. For example: - .. code-block:: sh + .. code-block:: sh - db.adminCommand( { setParameter: 1, sslMode: "requireSSL" } ) + db.adminCommand( { setParameter: 1, sslMode: "requireSSL" } ) - #. After the upgrade of all nodes, edit the :doc:`configuration file - ` with the appropriate TLS/SSL - settings to ensure that upon subsequent restarts, the cluster uses - TLS/SSL. +#. After the upgrade of all nodes, edit the :doc:`configuration file + ` with the appropriate TLS/SSL + settings to ensure that upon subsequent restarts, the cluster uses + TLS/SSL. .. [#update-mode-alternative] As an alternative to using the :dbcommand:`setParameter` command, you can also diff --git a/source/tutorial/upgrade-revision.txt b/source/tutorial/upgrade-revision.txt index a40cfa30537..942a46dc49f 100644 --- a/source/tutorial/upgrade-revision.txt +++ b/source/tutorial/upgrade-revision.txt @@ -37,8 +37,8 @@ Compatibility Considerations - The release notes, located at :doc:`/release-notes`. - - The documentation for your driver. See :ecosystem:`Drivers - ` and :ecosystem:`Driver Compatibility + - The documentation for your driver. See :driver:`Drivers + ` and :driver:`Driver Compatibility ` pages for more information. .. important:: @@ -110,8 +110,8 @@ use the procedure :ref:`upgrade-mongodb-instance`. Follow this upgrade procedure: 1. For deployments that use authentication, first upgrade all of your - MongoDB :ecosystem:`drivers `. To upgrade, see the - documentation for your driver as well as the :ecosystem:`Driver + MongoDB :driver:`Drivers `. To upgrade, see the + documentation for your driver as well as the :driver:`Driver Compatibility ` page. #. Upgrade sharded clusters, as described in diff --git a/source/tutorial/use-database-commands.txt b/source/tutorial/use-database-commands.txt index 10d22b89341..44e3322a895 100644 --- a/source/tutorial/use-database-commands.txt +++ b/source/tutorial/use-database-commands.txt @@ -45,7 +45,7 @@ commands called :method:`db.runCommand()`. The following operation in db.runCommand( { isMaster: 1 } ) -Many :ecosystem:`drivers ` provide an equivalent for +Many :driver:`Drivers ` provide an equivalent for the :method:`db.runCommand()` method. Internally, running commands with :method:`db.runCommand()` is equivalent to a special query against the :term:`$cmd` collection. diff --git a/source/tutorial/write-scripts-for-the-mongo-shell.txt b/source/tutorial/write-scripts-for-the-mongo-shell.txt index ff086b783db..6f796ba1acd 100644 --- a/source/tutorial/write-scripts-for-the-mongo-shell.txt +++ b/source/tutorial/write-scripts-for-the-mongo-shell.txt @@ -55,7 +55,9 @@ non-default port ``27020`` and set the global ``db`` variable: db = connect("localhost:27020/myDatabase"); -.. seealso:: :doc:`/reference/method/` +.. seealso:: + + :doc:`/reference/method/` Differences Between Interactive and Scripted ``mongo`` ------------------------------------------------------ diff --git a/worker.sh b/worker.sh index d2db2059765..c615eb5970c 100644 --- a/worker.sh +++ b/worker.sh @@ -1,2 +1 @@ -#!/bin/sh -make html +"build-and-stage-next-gen"