diff --git a/source/compatibility.txt b/source/compatibility.txt index b100d2f4..317aa962 100644 --- a/source/compatibility.txt +++ b/source/compatibility.txt @@ -1,4 +1,4 @@ -.. _cpp-compatibility-tables: +.. _cpp-compatibility: ============= Compatibility diff --git a/source/configuration.txt b/source/configuration.txt deleted file mode 100644 index e8ff3600..00000000 --- a/source/configuration.txt +++ /dev/null @@ -1,207 +0,0 @@ -.. _cpp-configuration: - -============= -Configuration -============= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: setup, set up, config - -In the mongocxx driver, most configuration is done via the `connection URI `__. Some -additional connection options are possible via the -`mongocxx::options::client <{+api+}/classmongocxx_1_1v__noabi_1_1options_1_1client>`__ class. - -Configuring TLS/SSL -------------------- - -To enable TLS (SSL), set ``tls=true`` in the URI: - -.. code-block:: cpp - - mongodb://mongodb.example.com/?tls=true - -By default, mongocxx will verify server certificates against the local -system CA list. You can override that either by specifying different settings in -the connection string, or by creating a -`mongocxx::options::tls <{+api+}/classmongocxx_1_1v__noabi_1_1options_1_1tls>`__ -object and passing it to ``tls_opts`` on ``mongocxx::options::client``. - -For example, to use a custom CA or to disable certificate validation, -see the following example: - -.. code-block:: cpp - - // 1) Using tls_options - mongocxx::options::client client_options; - mongocxx::options::tls tls_options; - - // If the server certificate is not signed by a well-known CA, - // you can set a custom CA file with the `ca_file` option. - tls_options.ca_file("/path/to/custom/cert.pem"); - - // If you want to disable certificate verification, you - // can set the `allow_invalid_certificates` option. - tls_options.allow_invalid_certificates(true); - - client_options.tls_opts(tls_options); - auto client1 = mongocxx::client{uri{"mongodb://host1/?tls=true"}, client_options}; - - // 2) Using the URI - auto client2 = mongocxx::client{uri{"mongodb://host1/?tls=true&tlsAllowInvalidCertificates=true&tlsCAFile=/path/to/custom/cert.pem"}}; - -Configuring Authentication --------------------------- - -Default Authentication Mechanism -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -MongoDB 3.0 changed the default authentication mechanism from ``MONGODB-CR`` -to ``SCRAM-SHA-1``. To create a credential that will authenticate properly -regardless of server version, use a connection string with the user and -password directly in the URI and with a parameter specifying the database -to authenticate from: - -.. _cpp-configuration-default-auth: - -.. code-block:: cpp - - #include - #include - - auto client = mongocxx::client{uri{"mongodb://user1:pwd1@host1/?authSource=db1"}}; - -``SCRAM-SHA-1`` -~~~~~~~~~~~~~~~ - -To explicitly create a credential of type ``SCRAM-SHA-1`` use a connection -string as above but with a parameter specifying the authentication -mechanism as ``"SCRAM-SHA-1"``: - -.. code-block:: cpp - - #include - #include - - auto client = mongocxx::client{ - uri{"mongodb://user1:pwd1@host1/?authSource=db1&authMechanism=SCRAM-SHA-1"} - }; - -``MONGODB-CR`` -~~~~~~~~~~~~~~ - -The ``MONGODB-CR`` authMechanism is deprecated and will no longer function in MongoDB 4.0. Instead, specify no authMechanism and the driver -will use an authentication mechanism compatible with your server. - -``X.509`` -~~~~~~~~~ - -The `X.509 `__ -mechanism authenticates a user whose name is derived from the distinguished -subject name of the X.509 certificate presented by the driver during TLS -negotiation. This authentication method requires the use of TLS -connections with certificate validation and is available in MongoDB 2.6 -and newer. To create a credential of this type, use a connection string with a -parameter that specifies the authentication mechanism as ``"MONGODB-X509"``, -that specifies the path to the PEM file containing the client private key -and certificate, and that has TLS enabled: - -.. code-block:: cpp - - #include - #include - - auto client = mongocxx::client{ - uri{"mongodb://host1/?authMechanism=MONGODB-X509&tlsCertificateKeyFile=client.pem&tls=true"} - }; - -See the MongoDB server :manual:`X.509 tutorial ` -for more information about determining the subject name from the certificate. - -The PEM file can also be specified using the `mongocxx::options::tls -<{+api+}/classmongocxx_1_1v__noabi_1_1options_1_1tls>`__ class, see the -:ref:`default TLS/SSL configuration ` example above. - -Kerberos (``GSSAPI``) -~~~~~~~~~~~~~~~~~~~~~ - -`MongoDB Enterprise `__ -supports proxy authentication through Kerberos service. To create a -credential of type `Kerberos (GSSAPI) `__ -use a connection string with the username and realm in the URI as well as -a parameter specifying the authentication mechanism as ``"GSSAPI"``: - -.. code-block:: cpp - - #include - #include - - auto client = mongocxx::client{ - uri{"mongodb://username%40REALM.COM@host1/?authMechanism=GSSAPI"} - }; - -.. note:: - - The ``@`` symbol in the URI string must be escaped to ``%40`` as shown in the example above. - -LDAP -~~~~ - -`MongoDB Enterprise `__ -supports proxy authentication through a Lightweight Directory Access -Protocol (LDAP) service. To create a credential of type LDAP use a -connection string specifying the user as well as parameters specifying -the authentication source as ``"$external"`` and the authentication mechanishm -as ``"PLAIN"``: - -.. code-block:: cpp - - #include - #include - - auto client = mongocxx::client{ - uri{"mongodb://user1:pwd1@host1/?authSource=$external&authMechanism=PLAIN"} - }; - -Configuring a connection pool ------------------------------ - -To configure a connection pool, first create a ``mongocxx::pool``, passing -the URI as an argument. The size of the pool can be configured in the URI. -Then, call ``mongocxx::pool::acquire`` to receive a client from the pool. -The client will automatically be returned to the pool when it goes out of -scope. - -.. code-block:: cpp - - #include - #include - - auto pool = mongocxx::pool{uri{"mongodb://host1/?minPoolSize=3&maxPoolSize=5"}}; - - { - // To get a client from the pool, call `acquire()`. - auto client = pool.acquire(); - - // The client is returned to the pool when it goes out of scope. - } - -See :ref:`connection pool documentation ` for more details. - -Compressing data to and from MongoDB ------------------------------------- - -MongoDB 3.4 added Snappy compression support, while zlib compression was added -in 3.6, and zstd compression in 4.2. - -You can enable data compression the appropriate URI options. Learn about these options -in the `MongoDB C driver API documentation `__. diff --git a/source/connect.txt b/source/connect.txt index f1e0c18c..d339ce14 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -29,6 +29,7 @@ Connect to MongoDB /connect/tls /connect/network-compression /connect/stable-api + /connect/connection-pools Overview -------- diff --git a/source/connection-pools.txt b/source/connect/connection-pools.txt similarity index 100% rename from source/connection-pools.txt rename to source/connect/connection-pools.txt diff --git a/source/data-formats.txt b/source/data-formats.txt index 5c562a38..3f06c14a 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -22,6 +22,7 @@ Specialized Data Formats :maxdepth: 1 /data-formats/time-series + /data-formats/working-with-bson Overview -------- @@ -32,4 +33,5 @@ sections: - Learn how to store and interact with time series data in the :ref:`cpp-time-series` guide. -.. TODO: link to BSON data guide \ No newline at end of file +- Learn how to use BSON types from the ``bsoncxx`` library in the :ref:`cpp-working-with-bson` + guide. diff --git a/source/working-with-bson.txt b/source/data-formats/working-with-bson.txt similarity index 100% rename from source/working-with-bson.txt rename to source/data-formats/working-with-bson.txt diff --git a/source/index.txt b/source/index.txt index 8effac5f..ec19e8f8 100644 --- a/source/index.txt +++ b/source/index.txt @@ -2,12 +2,6 @@ MongoDB C++ Driver =================== -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - .. facet:: :name: genre :values: reference @@ -17,8 +11,6 @@ MongoDB C++ Driver :maxdepth: 1 Get Started - /polyfill-selection - /advanced-installation /connect /read /write @@ -26,16 +18,12 @@ MongoDB C++ Driver /aggregation /security /data-formats - /configuration - /client-side-encryption - /tutorial + /polyfill-selection + /advanced-installation /thread-safety - /connection-pools - /working-with-bson /api-abi-versioning /whats-new /upgrade - /reporting-bugs /testing /compatibility /issues-and-help @@ -53,30 +41,12 @@ Get Started Learn how to install the driver, establish a connection to MongoDB, and begin working with data in the :ref:`cpp-get-started` tutorial. -Choose a C++17 Polyfill ------------------------ - -Learn how to a choose a polyfill library implementation for -pre-C++ 17 configurations in the :ref:`cpp-polyfill-selection` section. - -Advanced Installation Options ------------------------------ - -Learn about additional configuration and installation options -in the :ref:`cpp-installation-advanced` section. - Connect to MongoDB ------------------ Learn how to create and configure a connection to a MongoDB deployment in the :ref:`cpp-connect` section. -Databases and Collections -------------------------- - -Learn how to use the {+driver-short+} to work with MongoDB databases and collections -in the :ref:`cpp-databases-collections` section. - Read Data from MongoDB ---------------------- @@ -111,24 +81,30 @@ Specialized Data Formats Learn how to work with specialized data formats and custom types in the :ref:`cpp-data-formats` section. +Choose a C++17 Polyfill +----------------------- + +Learn how to a choose a polyfill library implementation for +pre-C++ 17 configurations in the :ref:`cpp-polyfill-selection` section. + +Advanced Installation Options +----------------------------- + +Learn about advanced configuration and installation options +in the :ref:`cpp-installation-advanced` section. + What's New ---------- For a list of new features and changes in each version, see the :ref:`cpp-whats-new` section. -Upgrade {+driver-short+} Versions ---------------------------- +Upgrade Driver Versions +----------------------- Learn what changes you might need to make to your application to upgrade driver versions in the :ref:`cpp-upgrade` section. -Previous Versions ------------------ - -For documentation on versions of the driver v3.9.x and earlier, see the -:ref:`cpp-previous-versions` section. - Issues & Help ------------- @@ -146,7 +122,7 @@ API Documentation ----------------- For detailed information about types and methods in the {+driver-short+}, see -the `{+driver-short+} API documentation <{+api-root+}>`__. +the `{+driver-short+} API documentation <{+api+}>`__. Driver Status by Family and Version diff --git a/source/read/retrieve.txt b/source/read/retrieve.txt index 3c85ca70..6ad04418 100644 --- a/source/read/retrieve.txt +++ b/source/read/retrieve.txt @@ -223,10 +223,8 @@ Additional Information To learn more about query filters, see :ref:`cpp-specify-query`. -For runnable code examples of retrieving documents with the {+driver-short+}, see :ref:`cpp-read`. - -For more examples that use the ``find()`` and ``find_one()`` methods, see the :ref:`cpp-tutorial-find` -section of the Tutorial page. +For runnable code examples of retrieving documents with the {+driver-short+}, +see :ref:`cpp-read`. API Documentation ~~~~~~~~~~~~~~~~~ diff --git a/source/reporting-bugs.txt b/source/reporting-bugs.txt deleted file mode 100644 index 76ed0358..00000000 --- a/source/reporting-bugs.txt +++ /dev/null @@ -1,34 +0,0 @@ -.. _cpp-reporting-bugs: - -============== -Reporting Bugs -============== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: errors, requests - -If you think you have found a bug or want to see a new feature in the -C++ driver, please open an issue in `JIRA `__: - -1. `Create a Jira account and login `__. - -2. Navigate to the `CXX project `__. - -3. Click **Create Issue**. Provide as much information as possible about - the issue and the steps to reproduce it. - -Be aware that bug reports in JIRA for the C++ driver are public. - -If you identify a security vulnerability in a driver or any other -MongoDB project, please report it according to the instructions found in -`Create a Vulnerability Report `__. diff --git a/source/security.txt b/source/security.txt index c6e14962..bec6d8aa 100644 --- a/source/security.txt +++ b/source/security.txt @@ -25,6 +25,7 @@ Secure Your Data /security/authentication /security/enterprise-authentication /security/in-use-encryption + /security/client-side-encryption Overview -------- diff --git a/source/client-side-encryption.txt b/source/security/client-side-encryption.txt similarity index 100% rename from source/client-side-encryption.txt rename to source/security/client-side-encryption.txt diff --git a/source/security/in-use-encryption.txt b/source/security/in-use-encryption.txt index 568c7e6d..a2fec898 100644 --- a/source/security/in-use-encryption.txt +++ b/source/security/in-use-encryption.txt @@ -97,5 +97,5 @@ low cardinality is susceptible to code breaking by frequency analysis. - :wikipedia:`Cardinality ` - :wikipedia:`Frequency Analysis ` -To learn more about CSFLE, see :manual:`CSFLE ` in the -Server manual. \ No newline at end of file +To learn more about CSFLE, see the :ref:`cpp-client-side-encryption` guide and +:manual:`CSFLE ` in the Server manual. \ No newline at end of file diff --git a/source/tutorial.txt b/source/tutorial.txt deleted file mode 100644 index 1566bf4c..00000000 --- a/source/tutorial.txt +++ /dev/null @@ -1,498 +0,0 @@ -.. _cpp-tutorial: - -========= -Tutorial -========= - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: tutorial - -.. meta:: - :keywords: tutorial, getting starting, hello world - -See the full code for this tutorial in -`tutorial.cpp `__. - -Prerequisites -------------- - -- A `mongod `__ - instance running on localhost on port 27017. - -- The mongocxx Driver. See :ref:`Installation `. - -- The following statements at the top of your source file: - -.. code-block:: cpp - - #include - #include - #include - - #include - #include - #include - #include - #include - #include - - using bsoncxx::builder::basic::kvp; - using bsoncxx::builder::basic::make_array; - using bsoncxx::builder::basic::make_document; - -Compiling ---------- - -The mongocxx driver's installation process will install a -``libmongocxx.pc`` file for use -with `pkg-config `__. - -To compile a program, run the following command: - -.. code-block:: bash - - c++ --std=c++11 .cpp $(pkg-config --cflags --libs libmongocxx) - -If you don't have pkg-config available, you will need to set include and -library flags manually on the command line or in your IDE. For example, if -libmongoc and mongocxx are installed in ``/usr/local``, then the compilation -line in above expands to this: - -.. code-block:: bash - - c++ --std=c++11 .cpp - -I/usr/local/include/mongocxx/v_noabi \ - -I/usr/local/include/bsoncxx/v_noabi \ - -L/usr/local/lib -lmongocxx -lbsoncxx - -Make a Connection ------------------ - -.. important:: - - Before making any connections, you need to create one and only one instance of `mongocxx::instance <{+api+}/classmongocxx_1_1v__noabi_1_1instance>`__. This instance must exist for the entirety of your program. - -To connect to a running MongoDB instance, use the -`mongocxx::instance <{+api+}/classmongocxx_1_1v__noabi_1_1instance>`__ -class. - -You must specify the host to connect to using a -`mongocxx::uri <{+api+}/classmongocxx_1_1v__noabi_1_1uri>`__ instance containing a -`MongoDB URI `__, -and pass that into the ``mongocxx::client`` constructor. For details regarding -supported URI options see the documentation for the version of libmongoc used -to build the C++ driver or for the `latest libmongoc release `__. - -The default ``mongocxx::uri`` constructor will connect to a -server running on localhost on port ``27017``: - -.. code-block:: cpp - - mongocxx::instance instance{}; // This should be done only once. - mongocxx::client client{mongocxx::uri{}}; - -This is equivalent to the following: - -.. code-block:: cpp - - mongocxx::instance instance{}; // This should be done only once. - mongocxx::uri uri("mongodb://localhost:27017"); - mongocxx::client client(uri); - -Access a Database ------------------ - -Once you have a `mongocxx::instance <{+api+}/classmongocxx_1_1v__noabi_1_1instance>`__ -instance connected to a MongoDB deployment, use either the -``database()`` method or ``operator[]`` to obtain a -`mongocxx::database <{+api+}/classmongocxx_1_1v__noabi_1_1database>`__ -instance. - -If the database you request does not exist, MongoDB creates it when you -first store data. - -The following example accesses the ``mydb`` database: - -.. code-block:: cpp - - auto db = client["mydb"]; - -Access a Collection -------------------- - -Once you have a -`mongocxx::database <{+api+}/classmongocxx_1_1v__noabi_1_1database>`__ -instance, use either the ``collection()`` method or ``operator[]`` to obtain a -`mongocxx::collection <{+api+}/classmongocxx_1_1v__noabi_1_1collection>`__ -instance. - -If the collection you request does not exist, MongoDB creates it when -you first store data. - -For example, using the ``db`` instance created in the previous section, -the following statement accesses the collection named ``test`` in the -``mydb`` database: - -.. code-block:: cpp - - auto collection = db["test"]; - -Create a Document ------------------ - -To create a ``document`` using the C++ driver, use one of the two -available builder interfaces: - -- Stream builder: ``bsoncxx::builder::stream`` - A document builder using the streaming operators that works well for literal document construction. - -- Basic builder: ``bsoncxx::builder::basic`` - A more conventional document builder that involves calling methods ona builder instance. - -This guide only briefly describes the basic builder. - -For example, consider the following JSON document: - -.. code-block:: json - - { - "name" : "MongoDB", - "type" : "database", - "count" : 1, - "versions": [ "v6.0", "v5.0", "v4.4", "v4.2", "v4.0", "v3.6" ], - "info" : { - "x" : 203, - "y" : 102 - } - } - -Using the basic builder interface, you can construct this document -as follows: - -.. code-block:: cpp - - auto doc_value = make_document( - kvp("name", "MongoDB"), - kvp("type", "database"), - kvp("count", 1), - kvp("versions", make_array("v6.0", "v5.0", "v4.4", "v4.2", "v4.0", "v3.6")), - kvp("info", make_document(kvp("x", 203), kvp("y", 102))) - ); - -This ``bsoncxx::document::value`` type is a read-only object owning its own -memory. To use it, you must obtain a `bsoncxx::document::view <{+api+}/classbsoncxx_1_1v__noabi_1_1document_1_1view>`__ using -the ``view()`` method: - -.. code-block:: cpp - - auto doc_view = doc_value.view(); - -You can access fields within this document view using ``operator[]``, -which will return a -`bsoncxx::document::element <{+api+}/classbsoncxx_1_1v__noabi_1_1document_1_1element>`__ -instance. For example, the following will extract the ``name`` field whose -value is a string: - -.. code-block:: cpp - - auto element = doc_view["name"]; - assert(element.type() == bsoncxx::type::k_string); - auto name = element.get_string().value; // For C++ driver version < 3.7.0, use get_utf8() - assert(0 == name.compare("MongoDB")); - -If the value in the name field is not a string and you do not -include a type guard as seen in the preceding example, this code will -throw an instance of `bsoncxx::exception <{+api+}/classbsoncxx_1_1v__noabi_1_1exception>`__. - -.. _cpp-tutorial-insert: - -Insert Documents ----------------- - -Insert One Document -~~~~~~~~~~~~~~~~~~~ - -To insert a single document into the collection, use a -`mongocxx::collection <{+api+}/classmongocxx_1_1v__noabi_1_1collection>`__ -instance's ``insert_one()`` method to insert ``{ "i": 0 }``: - -.. code-block:: cpp - - auto insert_one_result = collection.insert_one(make_document(kvp("i", 0))); - -``insert_one_result`` is an optional `mongocxx::result::insert_one -<{+api+}/classmongocxx_1_1v__noabi_1_1result_1_1insert__one>`__. In this -example, ``insert_one_result`` is expected to be set. The default behavior for -write operations is to wait for a reply from the server. This may be overridden by setting an unacknowledged -`mongocxx::write_concern <{+api+}/classmongocxx_1_1v__noabi_1_1write__concern>`__. - -.. code-block:: cpp - - assert(insert_one_result); // Acknowledged writes return results. - -If you do not specify a top-level ``_id`` field in the document, -MongoDB automatically adds an ``_id`` field to the inserted document. - -You can obtain this value using the ``inserted_id()`` method of the returned -`mongocxx::result::insert_one -<{+api+}/classmongocxx_1_1v__noabi_1_1result_1_1insert__one>`__ instance. - -.. code-block:: cpp - - auto doc_id = insert_one_result->inserted_id(); - assert(doc_id.type() == bsoncxx::type::k_oid); - -Insert Multiple Documents -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To insert multiple documents to the collection, use a -`mongocxx::collection <{+api+}/classmongocxx_1_1v__noabi_1_1collection>`__ instance's -``insert_many()`` method, which takes a list of documents to insert. - -The following example inserts the documents ``{ "i": 1 }`` and ``{ "i": 2 }``. -Create the documents and add to the documents list: - -.. code-block:: cpp - - std::vector documents; - documents.push_back(make_document(kvp("i", 1))); - documents.push_back(make_document(kvp("i", 2))); - -To insert these documents to the collection, pass the list of documents to the ``insert_many()`` method. - -.. code-block:: cpp - - auto insert_many_result = collection.insert_many(documents); - assert(insert_many_result); // Acknowledged writes return results. - -If you do not specify a top-level ``_id`` field in each document, -MongoDB automatically adds a ``_id`` field to the inserted documents. - -You can obtain this value using the ``inserted_ids()`` method of the -returned `mongocxx::result::insert_many <{+api+}/classmongocxx_1_1v__noabi_1_1result_1_1insert__many>`__ -instance. - -.. code-block:: cpp - - auto doc0_id = insert_many_result->inserted_ids().at(0); - auto doc1_id = insert_many_result->inserted_ids().at(1); - assert(doc0_id.type() == bsoncxx::type::k_oid); - assert(doc1_id.type() == bsoncxx::type::k_oid); - -.. _cpp-tutorial-find: - -Query the Collection ---------------------- - -To query the collection, use the collection's ``find()`` and ``find_one()`` methods. - -``find()`` will return an instance of -`mongocxx::cursor <{+api+}/classmongocxx_1_1v__noabi_1_1cursor>`__, -while ``find_one()`` will return an instance of -``std::optional< bsoncxx::document::value >``. For more information, see -`bsoncxx::document::value <{+api+}/classbsoncxx_1_1v__noabi_1_1document_1_1value>`__. - -You can call either method with an empty document to query all documents -in a collection, or pass a filter to query for documents that match the -filter criteria. - -Find a Single Document in a Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To return a single document in the collection, use the ``find_one()`` -method without any parameters. - -.. code-block:: cpp - - auto find_one_result = collection.find_one({}); - if (find_one_result) { - // Do something with *find_one_result - } - assert(find_one_result); - -Find All Documents in a Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: cpp - - auto cursor_all = collection.find({}); - for (auto doc : cursor_all) { - // Do something with doc - assert(doc["_id"].type() == bsoncxx::type::k_oid); - } - -Print All Documents in a Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `bsoncxx::to_json <{+api+}/namespacebsoncxx>`__ function converts a BSON document to a JSON string. - -.. code-block:: cpp - - auto cursor_all = collection.find({}); - std::cout << "collection " << collection.name() - << " contains these documents:" << std::endl; - for (auto doc : cursor_all) { - std::cout << bsoncxx::to_json(doc, bsoncxx::ExtendedJsonMode::k_relaxed) << std::endl; - } - std::cout << std::endl; - -The above example prints output resembling the following: - -.. code-block:: none - - collection test contains these documents: - { "_id" : { "$oid" : "6409edb48c37f371c70f03a1" }, "i" : 0 } - { "_id" : { "$oid" : "6409edb48c37f371c70f03a2" }, "i" : 1 } - { "_id" : { "$oid" : "6409edb48c37f371c70f03a3" }, "i" : 2 } - -The ``_id`` element has been added automatically by MongoDB to your -document and your value will differ from that shown. MongoDB reserves -field names that start with an underscore (``_``) and the dollar sign -(``$``) for internal use. - -Specify a Query Filter -~~~~~~~~~~~~~~~~~~~~~~ - -Get A Single Document That Matches a Filter -``````````````````````````````````````````` - -To find the first document where the field ``i`` has the value ``0``, -pass the document ``{"i": 0}`` to specify the equality condition: - -.. code-block:: cpp - - auto find_one_filtered_result = collection.find_one(make_document(kvp("i", 0))); - if (find_one_filtered_result) { - // Do something with *find_one_filtered_result - } - -Get All Documents That Match a Filter -````````````````````````````````````` - -The following example gets all documents where ``0 < "i" <= 2``: - -.. code-block:: cpp - - auto cursor_filtered = - collection.find(make_document(kvp("i", make_document(kvp("$gt", 0), kvp("$lte", 2))))); - for (auto doc : cursor_filtered) { - // Do something with doc - assert(doc["_id"].type() == bsoncxx::type::k_oid); - } - -Update Documents ----------------- - -To update documents in a collection, you can use the collection's -``update_one()`` and ``update_many()`` methods. - -The update methods return an instance of ``std::optional< -mongocxx::result::update >``, which provides information about the operation -including the number of documents modified by the update. For more information, -see `mongocxx::result::update -<{+api+}/classmongocxx_1_1v__noabi_1_1result_1_1update>`__. - -Update a Single Document -~~~~~~~~~~~~~~~~~~~~~~~~ - -To update at most one document, use the ``update_one()`` method. - -The following example updates the first document that matches the filter -``{ "i": 0 }`` and sets the value of ``foo`` to ``bar``: - -.. code-block:: cpp - - auto update_one_result = - collection.update_one(make_document(kvp("i", 0)), - make_document(kvp("$set", make_document(kvp("foo", "bar"))))); - assert(update_one_result); // Acknowledged writes return results. - assert(update_one_result->modified_count() == 1); - -Update Multiple Documents -~~~~~~~~~~~~~~~~~~~~~~~~~ - -To update all documents matching a filter, use the ``update_many()`` -method. - -The following example sets the value of ``foo`` to ``buzz`` where -``i`` is greater than ``0``: - -.. code-block:: cpp - - auto update_many_result = - collection.update_many(make_document(kvp("i", make_document(kvp("$gt", 0)))), - make_document(kvp("$set", make_document(kvp("foo", "buzz"))))); - assert(update_many_result); // Acknowledged writes return results. - assert(update_many_result->modified_count() == 2); - -Delete Documents ----------------- - -To delete documents from a collection, you can use a collection's -``delete_one()`` and ``delete_many()`` methods. - -The delete methods return an instance of ``std::optional< -mongocxx::result::delete >``, which contains the number of documents deleted. -For more information, see `mongocxx::result::delete -<{+api+}/classmongocxx_1_1v__noabi_1_1result_1_1delete__result>`__. - -Delete a Single Document -~~~~~~~~~~~~~~~~~~~~~~~~ - -To delete at most a single document that matches a filter, use the -``delete_one()`` method. - -For example, to delete a document that matches the filter -``{ "i": 0 }``: - -.. code-block:: cpp - - auto delete_one_result = collection.delete_one(make_document(kvp("i", 0))); - assert(delete_one_result); // Acknowledged writes return results. - assert(delete_one_result->deleted_count() == 1); - -Delete All Documents That Match a Filter -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To delete all documents matching a filter, use a collection's -``delete_many()`` method. - -The following example deletes all documents where ``i`` is greater than ``0``: - -.. code-block:: cpp - - auto delete_many_result = - collection.delete_many(make_document(kvp("i", make_document(kvp("$gt", 0))))); - assert(delete_many_result); // Acknowledged writes return results. - assert(delete_many_result->deleted_count() == 2); - -Create Indexes --------------- - -To create an `index `__ on a -field or set of fields, pass an index specification document to the -``create_index()`` method of a -`mongocxx::collection <{+api+}/classmongocxx_1_1v__noabi_1_1collection>`__ instance. An -index key specification document contains the fields to index and the -index type for each field: - -.. code-block:: json - - { "index1": "", "index2": "" } - -- For an ascending index type, specify 1 for ````. -- For a descending index type, specify -1 for ````. - -The following example creates an ascending index on the ``i`` field: - -.. code-block:: cpp - - auto index_specification = make_document(kvp("i", 1)); - collection.create_index(std::move(index_specification)); diff --git a/source/upgrade.txt b/source/upgrade.txt index 223bb5c1..374fff96 100644 --- a/source/upgrade.txt +++ b/source/upgrade.txt @@ -28,7 +28,7 @@ Before you upgrade, perform the following actions: - Ensure the new {+driver-short+} version is compatible with the {+mdb-server+} versions your application connects to and the C++ standard version your application compiles with. For version compatibility information, see the - :ref:`{+driver-short+} Compatibility ` + :ref:`{+driver-short+} Compatibility ` page. - Address any breaking changes between the driver version your application is using and your planned upgrade version in the diff --git a/source/write/insert.txt b/source/write/insert.txt index 3f6a19a6..8d921b19 100644 --- a/source/write/insert.txt +++ b/source/write/insert.txt @@ -42,8 +42,8 @@ and assign the following values to your ``db`` and ``collection`` variables: :start-after: start-db-coll :end-before: end-db-coll -To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see -the :ref:`` tutorial. +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the +:atlas:`Get Started with Atlas ` guide. The ``_id`` Field ----------------- @@ -160,9 +160,6 @@ Additional Information For runnable code examples of inserting documents with the {+driver-short+}, see :ref:`cpp-write`. -For more examples that use the ``insert_one()`` and ``insert_many()`` methods, see the -:ref:`cpp-tutorial-insert` section of the Tutorial page. - API Documentation ~~~~~~~~~~~~~~~~~