From 9a540f7091f7b5bae149a00af65e6e29ff246394 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 2 Apr 2025 16:42:56 -0500 Subject: [PATCH 01/10] wip --- snooty.toml | 2 +- source/{fundamentals => }/aggregation.txt | 0 source/{fundamentals => }/atlas-search.txt | 0 source/{fundamentals => }/bson.txt | 0 source/{fundamentals => }/builders.txt | 0 .../{fundamentals/connection => }/connect.txt | 0 .../connection-options.txt | 0 .../connection-options}/connection-pools.txt | 0 .../network-compression.txt | 0 .../connection-options}/server-selection.txt | 0 .../connection-options}/tls.txt | 0 .../connection-troubleshooting.txt | 0 source/{fundamentals => }/connection.txt | 0 source/{fundamentals => }/crud.txt | 0 .../crud/read-operations.txt | 0 .../crud/read-operations/change-streams.txt | 0 .../crud/read-operations/count.txt | 0 .../crud/read-operations/distinct.txt | 0 .../crud/read-operations/project.txt | 0 .../crud/read-operations/retrieve.txt | 0 .../specify-documents-to-return.txt | 0 .../crud/write-operations.txt | 0 .../crud/write-operations/bulk-write.txt | 0 .../crud/write-operations/delete.txt | 0 .../crud/write-operations/insert.txt | 0 .../crud/write-operations/replace.txt | 0 .../crud/write-operations/update-many.txt | 0 .../write-operations/update-many/arrays.txt | 0 .../write-operations/update-many/fields.txt | 0 .../crud/write-operations/update-one.txt | 0 .../write-operations/update-one/arrays.txt | 0 .../write-operations/update-one/fields.txt | 0 .../database-collection.txt | 0 source/{fundamentals => }/encrypt-fields.txt | 0 source/{fundamentals => }/geo.txt | 0 source/get-started.txt | 217 +++++++++++++++++- .../get-started/create-connection-string.txt | 86 ------- source/get-started/deploy-cluster.txt | 29 --- source/get-started/download-driver.txt | 34 --- source/get-started/run-sample-query.txt | 49 ---- source/{fundamentals => }/gridfs.txt | 0 source/{fundamentals => }/indexes.txt | 0 source/{fundamentals => }/linq.txt | 0 source/{fundamentals => }/logging.txt | 0 source/{fundamentals => }/monitoring.txt | 0 source/{fundamentals => }/odata.txt | 0 .../read-write-configuration.txt | 0 source/reference.txt | 0 .../run-command.txt | 0 source/security.txt | 0 .../authentication.txt | 0 .../authentication/aws-iam.txt | 0 .../authentication/kerberos.txt | 0 .../authentication/ldap.txt | 0 .../authentication/oidc.txt | 0 .../authentication/scram.txt | 0 .../authentication/x509.txt | 0 source/{fundamentals => }/serialization.txt | 0 .../serialization/class-mapping.txt | 0 .../serialization/guid-serialization.txt | 0 .../{fundamentals => }/serialization/poco.txt | 0 .../serialization/polymorphic-objects.txt | 0 source/{fundamentals => }/specify-query.txt | 0 source/{fundamentals => }/stable-api.txt | 0 source/{fundamentals => }/time-series.txt | 0 source/{fundamentals => }/transactions.txt | 0 66 files changed, 211 insertions(+), 206 deletions(-) rename source/{fundamentals => }/aggregation.txt (100%) rename source/{fundamentals => }/atlas-search.txt (100%) rename source/{fundamentals => }/bson.txt (100%) rename source/{fundamentals => }/builders.txt (100%) rename source/{fundamentals/connection => }/connect.txt (100%) rename source/{fundamentals/connection => connect}/connection-options.txt (100%) rename source/{fundamentals/connection => connect/connection-options}/connection-pools.txt (100%) rename source/{fundamentals/connection => connect/connection-options}/network-compression.txt (100%) rename source/{fundamentals/connection => connect/connection-options}/server-selection.txt (100%) rename source/{fundamentals/connection => connect/connection-options}/tls.txt (100%) rename source/{ => connect}/connection-troubleshooting.txt (100%) rename source/{fundamentals => }/connection.txt (100%) rename source/{fundamentals => }/crud.txt (100%) rename source/{fundamentals => }/crud/read-operations.txt (100%) rename source/{fundamentals => }/crud/read-operations/change-streams.txt (100%) rename source/{fundamentals => }/crud/read-operations/count.txt (100%) rename source/{fundamentals => }/crud/read-operations/distinct.txt (100%) rename source/{fundamentals => }/crud/read-operations/project.txt (100%) rename source/{fundamentals => }/crud/read-operations/retrieve.txt (100%) rename source/{fundamentals => }/crud/read-operations/specify-documents-to-return.txt (100%) rename source/{fundamentals => }/crud/write-operations.txt (100%) rename source/{fundamentals => }/crud/write-operations/bulk-write.txt (100%) rename source/{fundamentals => }/crud/write-operations/delete.txt (100%) rename source/{fundamentals => }/crud/write-operations/insert.txt (100%) rename source/{fundamentals => }/crud/write-operations/replace.txt (100%) rename source/{fundamentals => }/crud/write-operations/update-many.txt (100%) rename source/{fundamentals => }/crud/write-operations/update-many/arrays.txt (100%) rename source/{fundamentals => }/crud/write-operations/update-many/fields.txt (100%) rename source/{fundamentals => }/crud/write-operations/update-one.txt (100%) rename source/{fundamentals => }/crud/write-operations/update-one/arrays.txt (100%) rename source/{fundamentals => }/crud/write-operations/update-one/fields.txt (100%) rename source/{fundamentals => }/database-collection.txt (100%) rename source/{fundamentals => }/encrypt-fields.txt (100%) rename source/{fundamentals => }/geo.txt (100%) delete mode 100644 source/get-started/create-connection-string.txt delete mode 100644 source/get-started/deploy-cluster.txt delete mode 100644 source/get-started/download-driver.txt delete mode 100644 source/get-started/run-sample-query.txt rename source/{fundamentals => }/gridfs.txt (100%) rename source/{fundamentals => }/indexes.txt (100%) rename source/{fundamentals => }/linq.txt (100%) rename source/{fundamentals => }/logging.txt (100%) rename source/{fundamentals => }/monitoring.txt (100%) rename source/{fundamentals => }/odata.txt (100%) rename source/{fundamentals => }/read-write-configuration.txt (100%) create mode 100644 source/reference.txt rename source/{fundamentals/databases-collections => }/run-command.txt (100%) create mode 100644 source/security.txt rename source/{fundamentals => security}/authentication.txt (100%) rename source/{fundamentals => security}/authentication/aws-iam.txt (100%) rename source/{fundamentals => security}/authentication/kerberos.txt (100%) rename source/{fundamentals => security}/authentication/ldap.txt (100%) rename source/{fundamentals => security}/authentication/oidc.txt (100%) rename source/{fundamentals => security}/authentication/scram.txt (100%) rename source/{fundamentals => security}/authentication/x509.txt (100%) rename source/{fundamentals => }/serialization.txt (100%) rename source/{fundamentals => }/serialization/class-mapping.txt (100%) rename source/{fundamentals => }/serialization/guid-serialization.txt (100%) rename source/{fundamentals => }/serialization/poco.txt (100%) rename source/{fundamentals => }/serialization/polymorphic-objects.txt (100%) rename source/{fundamentals => }/specify-query.txt (100%) rename source/{fundamentals => }/stable-api.txt (100%) rename source/{fundamentals => }/time-series.txt (100%) rename source/{fundamentals => }/transactions.txt (100%) diff --git a/snooty.toml b/snooty.toml index 085ef4b7..a29f100f 100644 --- a/snooty.toml +++ b/snooty.toml @@ -47,5 +47,5 @@ string-data-type = "``string``" int-data-type = "``integer``" not-available = "N/A" analyzer = "MongoDB C# Analyzer" -analyzer-short = "C# Analzyer" +analyzer-short = "C# Analyzer" query-api = "MongoDB Query API" diff --git a/source/fundamentals/aggregation.txt b/source/aggregation.txt similarity index 100% rename from source/fundamentals/aggregation.txt rename to source/aggregation.txt diff --git a/source/fundamentals/atlas-search.txt b/source/atlas-search.txt similarity index 100% rename from source/fundamentals/atlas-search.txt rename to source/atlas-search.txt diff --git a/source/fundamentals/bson.txt b/source/bson.txt similarity index 100% rename from source/fundamentals/bson.txt rename to source/bson.txt diff --git a/source/fundamentals/builders.txt b/source/builders.txt similarity index 100% rename from source/fundamentals/builders.txt rename to source/builders.txt diff --git a/source/fundamentals/connection/connect.txt b/source/connect.txt similarity index 100% rename from source/fundamentals/connection/connect.txt rename to source/connect.txt diff --git a/source/fundamentals/connection/connection-options.txt b/source/connect/connection-options.txt similarity index 100% rename from source/fundamentals/connection/connection-options.txt rename to source/connect/connection-options.txt diff --git a/source/fundamentals/connection/connection-pools.txt b/source/connect/connection-options/connection-pools.txt similarity index 100% rename from source/fundamentals/connection/connection-pools.txt rename to source/connect/connection-options/connection-pools.txt diff --git a/source/fundamentals/connection/network-compression.txt b/source/connect/connection-options/network-compression.txt similarity index 100% rename from source/fundamentals/connection/network-compression.txt rename to source/connect/connection-options/network-compression.txt diff --git a/source/fundamentals/connection/server-selection.txt b/source/connect/connection-options/server-selection.txt similarity index 100% rename from source/fundamentals/connection/server-selection.txt rename to source/connect/connection-options/server-selection.txt diff --git a/source/fundamentals/connection/tls.txt b/source/connect/connection-options/tls.txt similarity index 100% rename from source/fundamentals/connection/tls.txt rename to source/connect/connection-options/tls.txt diff --git a/source/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt similarity index 100% rename from source/connection-troubleshooting.txt rename to source/connect/connection-troubleshooting.txt diff --git a/source/fundamentals/connection.txt b/source/connection.txt similarity index 100% rename from source/fundamentals/connection.txt rename to source/connection.txt diff --git a/source/fundamentals/crud.txt b/source/crud.txt similarity index 100% rename from source/fundamentals/crud.txt rename to source/crud.txt diff --git a/source/fundamentals/crud/read-operations.txt b/source/crud/read-operations.txt similarity index 100% rename from source/fundamentals/crud/read-operations.txt rename to source/crud/read-operations.txt diff --git a/source/fundamentals/crud/read-operations/change-streams.txt b/source/crud/read-operations/change-streams.txt similarity index 100% rename from source/fundamentals/crud/read-operations/change-streams.txt rename to source/crud/read-operations/change-streams.txt diff --git a/source/fundamentals/crud/read-operations/count.txt b/source/crud/read-operations/count.txt similarity index 100% rename from source/fundamentals/crud/read-operations/count.txt rename to source/crud/read-operations/count.txt diff --git a/source/fundamentals/crud/read-operations/distinct.txt b/source/crud/read-operations/distinct.txt similarity index 100% rename from source/fundamentals/crud/read-operations/distinct.txt rename to source/crud/read-operations/distinct.txt diff --git a/source/fundamentals/crud/read-operations/project.txt b/source/crud/read-operations/project.txt similarity index 100% rename from source/fundamentals/crud/read-operations/project.txt rename to source/crud/read-operations/project.txt diff --git a/source/fundamentals/crud/read-operations/retrieve.txt b/source/crud/read-operations/retrieve.txt similarity index 100% rename from source/fundamentals/crud/read-operations/retrieve.txt rename to source/crud/read-operations/retrieve.txt diff --git a/source/fundamentals/crud/read-operations/specify-documents-to-return.txt b/source/crud/read-operations/specify-documents-to-return.txt similarity index 100% rename from source/fundamentals/crud/read-operations/specify-documents-to-return.txt rename to source/crud/read-operations/specify-documents-to-return.txt diff --git a/source/fundamentals/crud/write-operations.txt b/source/crud/write-operations.txt similarity index 100% rename from source/fundamentals/crud/write-operations.txt rename to source/crud/write-operations.txt diff --git a/source/fundamentals/crud/write-operations/bulk-write.txt b/source/crud/write-operations/bulk-write.txt similarity index 100% rename from source/fundamentals/crud/write-operations/bulk-write.txt rename to source/crud/write-operations/bulk-write.txt diff --git a/source/fundamentals/crud/write-operations/delete.txt b/source/crud/write-operations/delete.txt similarity index 100% rename from source/fundamentals/crud/write-operations/delete.txt rename to source/crud/write-operations/delete.txt diff --git a/source/fundamentals/crud/write-operations/insert.txt b/source/crud/write-operations/insert.txt similarity index 100% rename from source/fundamentals/crud/write-operations/insert.txt rename to source/crud/write-operations/insert.txt diff --git a/source/fundamentals/crud/write-operations/replace.txt b/source/crud/write-operations/replace.txt similarity index 100% rename from source/fundamentals/crud/write-operations/replace.txt rename to source/crud/write-operations/replace.txt diff --git a/source/fundamentals/crud/write-operations/update-many.txt b/source/crud/write-operations/update-many.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-many.txt rename to source/crud/write-operations/update-many.txt diff --git a/source/fundamentals/crud/write-operations/update-many/arrays.txt b/source/crud/write-operations/update-many/arrays.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-many/arrays.txt rename to source/crud/write-operations/update-many/arrays.txt diff --git a/source/fundamentals/crud/write-operations/update-many/fields.txt b/source/crud/write-operations/update-many/fields.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-many/fields.txt rename to source/crud/write-operations/update-many/fields.txt diff --git a/source/fundamentals/crud/write-operations/update-one.txt b/source/crud/write-operations/update-one.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-one.txt rename to source/crud/write-operations/update-one.txt diff --git a/source/fundamentals/crud/write-operations/update-one/arrays.txt b/source/crud/write-operations/update-one/arrays.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-one/arrays.txt rename to source/crud/write-operations/update-one/arrays.txt diff --git a/source/fundamentals/crud/write-operations/update-one/fields.txt b/source/crud/write-operations/update-one/fields.txt similarity index 100% rename from source/fundamentals/crud/write-operations/update-one/fields.txt rename to source/crud/write-operations/update-one/fields.txt diff --git a/source/fundamentals/database-collection.txt b/source/database-collection.txt similarity index 100% rename from source/fundamentals/database-collection.txt rename to source/database-collection.txt diff --git a/source/fundamentals/encrypt-fields.txt b/source/encrypt-fields.txt similarity index 100% rename from source/fundamentals/encrypt-fields.txt rename to source/encrypt-fields.txt diff --git a/source/fundamentals/geo.txt b/source/geo.txt similarity index 100% rename from source/fundamentals/geo.txt rename to source/geo.txt diff --git a/source/get-started.txt b/source/get-started.txt index bab7ee64..0bd5be2b 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -18,13 +18,6 @@ Get Started with the {+driver-short+} :description: Learn how to create an app to connect to MongoDB deployment by using the .NET/C# driver. :keywords: quick start, tutorial, basics -.. toctree:: - - Download the Driver - Deploy a Cluster - Create a Connection String - Run a Sample Query - Overview -------- @@ -42,3 +35,213 @@ MongoDB Atlas. Follow this guide to connect a sample {+language+} application to a MongoDB Atlas deployment. If you prefer to connect to MongoDB using a different driver or programming language, see our :driver:`list of official drivers <>`. + +.. _csharp-get-started-download-driver: + +Download the {+driver-short+} +---------------------------- + +.. procedure:: + :style: connected + + .. step:: Create a Project Directory + + In your shell, run the following commands to create a + directory called ``csharp-quickstart`` and initialize a {+framework+} project for + a new console application: + + .. code-block:: bash + + mkdir csharp-quickstart + cd csharp-quickstart + dotnet new console + + .. step:: Install the {+driver-short+} + + Run the following command to install the current version of the {+driver-short+} + as a dependency of your project: + + .. code-block:: bash + + dotnet add package MongoDB.Driver + +After you complete these steps, you have a new {+framework+} project +and the {+driver-short+} installed. + +.. _csharp-get-started-deploy-cluster: + +Deploy a MongoDB Atlas Cluster +------------------------------ + +You can create a free tier MongoDB deployment on MongoDB Atlas +to store and manage your data. MongoDB Atlas hosts and manages +your MongoDB database in the cloud. + +.. procedure:: + :style: connected + + .. step:: Create a Free MongoDB Deployment on Atlas + + Complete the :atlas:`Get Started with Atlas ` + guide to set up a new Atlas account and load sample data into a new free + tier MongoDB deployment. + + .. step:: Save your Credentials + + After you create your database user, save that user's + username and password to a safe location for use in an upcoming step. + +After you complete these steps, you have a new free tier MongoDB +deployment on Atlas, database user credentials, and sample data loaded +in your database. + +.. _csharp-get-started-connection-string: + +Create a Connection String +-------------------------- + +You can connect to your MongoDB deployment by providing a +**connection URI**, also called a *connection string*, which +instructs the driver on how to connect to a MongoDB deployment +and how to behave while connected. + +The connection string includes the hostname or IP address and +port of your deployment, the authentication mechanism, user credentials +when applicable, and connection options. + +.. tip:: + + To connect to a self-managed (non-Atlas) deployment, see + :ref:`csharp-connect-to-mongodb`. + +.. procedure:: + :style: connected + + .. step:: Find your MongoDB Atlas Connection String + + To retrieve your connection string for the deployment that + you created in the :ref:`previous step `, + log into your Atlas account and navigate to the + :guilabel:`Database` section and click the :guilabel:`Connect` button + for your new deployment. + + .. figure:: /includes/figures/atlas_connection_select_cluster.png + :alt: The connect button in the clusters section of the Atlas UI + + Proceed to the :guilabel:`Connect your application` section and select + "C# / .NET" from the :guilabel:`Driver` selection menu and the version + that best matches the version you installed from the :guilabel:`Version` + selection menu. + + Select the :guilabel:`Password (SCRAM)` authentication mechanism. + + Deselect the :guilabel:`Include full driver code example` option to view + the connection string. + + .. step:: Copy your Connection String + + Click the button on the right of the connection string to copy it to + your clipboard as shown in the following screenshot: + + .. figure:: /includes/figures/atlas_connection_copy_string.png + :alt: The connection string copy button in the Atlas UI + + .. step:: Update the Placeholders + + Paste this connection string into a file in your preferred text editor + and replace the ```` and ```` placeholders with + your database user's username and password. + + Save this file to a safe location for use in the next step. + + .. step:: Set an Environment Variable + + In your shell, run the following code to save your MongoDB + :ref:`connection string ` to an + environment variable. Replace ```` with the connection + string that you saved to a file in the previous step. + + .. code-block:: bash + + export MONGODB_URI="" + + .. note:: PowerShell + + If you're using Microsoft PowerShell, run the following command instead: + + .. code-block:: bash + + set MONGODB_URI="" + + Storing your credentials in an environment variable is safer than hardcoding them + in your source code. + +After completing these steps, you have a connection string that +contains your database username and password. + +.. _csharp-get-started-run-sample-query: + +Run a Sample Query +------------------ + +.. procedure:: + :style: connected + + .. step:: Create your {+lang-framework+} Application + + Copy and paste the following code into the ``Program.cs`` file in your application: + + .. literalinclude:: /includes/quick-start/Program.cs + :language: csharp + :dedent: + + .. step:: Run your Application + + In your shell, run the following command to start this application: + + .. code-block:: sh + + dotnet run csharp-quickstart.csproj + + The output includes details of the retrieved movie document: + + .. code-block:: none + + { + _id: ..., + plot: 'A young man is accidentally sent 30 years into the past...', + genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], + ... + title: 'Back to the Future', + ... + } + + .. tip:: + + If you encounter an error or see no output, ensure that you specified the + proper connection string, and that you loaded the + sample data. + +After you complete these steps, you have a working application that +uses the driver to connect to your MongoDB deployment, runs a query on +the sample data, and prints out the result. + +.. _csharp-get-started-next-steps: + +Next Steps +---------- + +Congratulations on completing the tutorial! + +In this tutorial, you created a {+language+} application that +connects to a MongoDB deployment hosted on MongoDB Atlas +and retrieves a document that matches a query. + +Learn more about the {+driver-short+} from the following resources: + +- Learn how to insert documents in the :ref:`` section. +- Learn how to find documents in the :ref:`` section. +- Learn how to update documents in the :ref:`` section. +- Learn how to delete documents in the :ref:`` section. + +.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/create-connection-string.txt b/source/get-started/create-connection-string.txt deleted file mode 100644 index 1a3524c5..00000000 --- a/source/get-started/create-connection-string.txt +++ /dev/null @@ -1,86 +0,0 @@ -.. _csharp-get-started-connection-string: - -========================== -Create a Connection String -========================== - -You can connect to your MongoDB deployment by providing a -**connection URI**, also called a *connection string*, which -instructs the driver on how to connect to a MongoDB deployment -and how to behave while connected. - -The connection string includes the hostname or IP address and -port of your deployment, the authentication mechanism, user credentials -when applicable, and connection options. - -.. tip:: - - To connect to a self-managed (non-Atlas) deployment, see - :ref:`csharp-connect-to-mongodb`. - -.. procedure:: - :style: connected - - .. step:: Find your MongoDB Atlas Connection String - - To retrieve your connection string for the deployment that - you created in the :ref:`previous step `, - log into your Atlas account and navigate to the - :guilabel:`Database` section and click the :guilabel:`Connect` button - for your new deployment. - - .. figure:: /includes/figures/atlas_connection_select_cluster.png - :alt: The connect button in the clusters section of the Atlas UI - - Proceed to the :guilabel:`Connect your application` section and select - "C# / .NET" from the :guilabel:`Driver` selection menu and the version - that best matches the version you installed from the :guilabel:`Version` - selection menu. - - Select the :guilabel:`Password (SCRAM)` authentication mechanism. - - Deselect the :guilabel:`Include full driver code example` option to view - the connection string. - - .. step:: Copy your Connection String - - Click the button on the right of the connection string to copy it to - your clipboard as shown in the following screenshot: - - .. figure:: /includes/figures/atlas_connection_copy_string.png - :alt: The connection string copy button in the Atlas UI - - .. step:: Update the Placeholders - - Paste this connection string into a file in your preferred text editor - and replace the ```` and ```` placeholders with - your database user's username and password. - - Save this file to a safe location for use in the next step. - - .. step:: Set an Environment Variable - - In your shell, run the following code to save your MongoDB - :ref:`connection string ` to an - environment variable. Replace ```` with the connection - string that you saved to a file in the previous step. - - .. code-block:: bash - - export MONGODB_URI="" - - .. note:: PowerShell - - If you're using Microsoft PowerShell, run the following command instead: - - .. code-block:: bash - - set MONGODB_URI="" - - Storing your credentials in an environment variable is safer than hardcoding them - in your source code. - -After completing these steps, you have a connection string that -contains your database username and password. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/deploy-cluster.txt b/source/get-started/deploy-cluster.txt deleted file mode 100644 index f3849975..00000000 --- a/source/get-started/deploy-cluster.txt +++ /dev/null @@ -1,29 +0,0 @@ -.. _csharp-get-started-deploy-cluster: - -============================== -Deploy a MongoDB Atlas Cluster -============================== - -You can create a free tier MongoDB deployment on MongoDB Atlas -to store and manage your data. MongoDB Atlas hosts and manages -your MongoDB database in the cloud. - -.. procedure:: - :style: connected - - .. step:: Create a Free MongoDB Deployment on Atlas - - Complete the :atlas:`Get Started with Atlas ` - guide to set up a new Atlas account and load sample data into a new free - tier MongoDB deployment. - - .. step:: Save your Credentials - - After you create your database user, save that user's - username and password to a safe location for use in an upcoming step. - -After you complete these steps, you have a new free tier MongoDB -deployment on Atlas, database user credentials, and sample data loaded -in your database. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/download-driver.txt b/source/get-started/download-driver.txt deleted file mode 100644 index 66aebe51..00000000 --- a/source/get-started/download-driver.txt +++ /dev/null @@ -1,34 +0,0 @@ -.. _csharp-get-started-download-driver: - -=========================== -Download the {+driver-short+} -=========================== - -.. procedure:: - :style: connected - - .. step:: Create a Project Directory - - In your shell, run the following commands to create a - directory called ``csharp-quickstart`` and initialize a {+framework+} project for - a new console application: - - .. code-block:: bash - - mkdir csharp-quickstart - cd csharp-quickstart - dotnet new console - - .. step:: Install the {+driver-short+} - - Run the following command to install the current version of the {+driver-short+} - as a dependency of your project: - - .. code-block:: bash - - dotnet add package MongoDB.Driver - -After you complete these steps, you have a new {+framework+} project -and the {+driver-short+} installed. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/get-started/run-sample-query.txt b/source/get-started/run-sample-query.txt deleted file mode 100644 index 0a79e9d3..00000000 --- a/source/get-started/run-sample-query.txt +++ /dev/null @@ -1,49 +0,0 @@ -.. _csharp-get-started-run-sample-query: - -================== -Run a Sample Query -================== - -.. procedure:: - :style: connected - - .. step:: Create your {+lang-framework+} Application - - Copy and paste the following code into the ``Program.cs`` file in your application: - - .. literalinclude:: /includes/quick-start/Program.cs - :language: csharp - :dedent: - - .. step:: Run your Application - - In your shell, run the following command to start this application: - - .. code-block:: sh - - dotnet run csharp-quickstart.csproj - - The output includes details of the retrieved movie document: - - .. code-block:: none - - { - _id: ..., - plot: 'A young man is accidentally sent 30 years into the past...', - genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ], - ... - title: 'Back to the Future', - ... - } - - .. tip:: - - If you encounter an error or see no output, ensure that you specified the - proper connection string, and that you loaded the - sample data. - -After you complete these steps, you have a working application that -uses the driver to connect to your MongoDB deployment, runs a query on -the sample data, and prints out the result. - -.. include:: /includes/get-started/quickstart-troubleshoot.rst diff --git a/source/fundamentals/gridfs.txt b/source/gridfs.txt similarity index 100% rename from source/fundamentals/gridfs.txt rename to source/gridfs.txt diff --git a/source/fundamentals/indexes.txt b/source/indexes.txt similarity index 100% rename from source/fundamentals/indexes.txt rename to source/indexes.txt diff --git a/source/fundamentals/linq.txt b/source/linq.txt similarity index 100% rename from source/fundamentals/linq.txt rename to source/linq.txt diff --git a/source/fundamentals/logging.txt b/source/logging.txt similarity index 100% rename from source/fundamentals/logging.txt rename to source/logging.txt diff --git a/source/fundamentals/monitoring.txt b/source/monitoring.txt similarity index 100% rename from source/fundamentals/monitoring.txt rename to source/monitoring.txt diff --git a/source/fundamentals/odata.txt b/source/odata.txt similarity index 100% rename from source/fundamentals/odata.txt rename to source/odata.txt diff --git a/source/fundamentals/read-write-configuration.txt b/source/read-write-configuration.txt similarity index 100% rename from source/fundamentals/read-write-configuration.txt rename to source/read-write-configuration.txt diff --git a/source/reference.txt b/source/reference.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/fundamentals/databases-collections/run-command.txt b/source/run-command.txt similarity index 100% rename from source/fundamentals/databases-collections/run-command.txt rename to source/run-command.txt diff --git a/source/security.txt b/source/security.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/fundamentals/authentication.txt b/source/security/authentication.txt similarity index 100% rename from source/fundamentals/authentication.txt rename to source/security/authentication.txt diff --git a/source/fundamentals/authentication/aws-iam.txt b/source/security/authentication/aws-iam.txt similarity index 100% rename from source/fundamentals/authentication/aws-iam.txt rename to source/security/authentication/aws-iam.txt diff --git a/source/fundamentals/authentication/kerberos.txt b/source/security/authentication/kerberos.txt similarity index 100% rename from source/fundamentals/authentication/kerberos.txt rename to source/security/authentication/kerberos.txt diff --git a/source/fundamentals/authentication/ldap.txt b/source/security/authentication/ldap.txt similarity index 100% rename from source/fundamentals/authentication/ldap.txt rename to source/security/authentication/ldap.txt diff --git a/source/fundamentals/authentication/oidc.txt b/source/security/authentication/oidc.txt similarity index 100% rename from source/fundamentals/authentication/oidc.txt rename to source/security/authentication/oidc.txt diff --git a/source/fundamentals/authentication/scram.txt b/source/security/authentication/scram.txt similarity index 100% rename from source/fundamentals/authentication/scram.txt rename to source/security/authentication/scram.txt diff --git a/source/fundamentals/authentication/x509.txt b/source/security/authentication/x509.txt similarity index 100% rename from source/fundamentals/authentication/x509.txt rename to source/security/authentication/x509.txt diff --git a/source/fundamentals/serialization.txt b/source/serialization.txt similarity index 100% rename from source/fundamentals/serialization.txt rename to source/serialization.txt diff --git a/source/fundamentals/serialization/class-mapping.txt b/source/serialization/class-mapping.txt similarity index 100% rename from source/fundamentals/serialization/class-mapping.txt rename to source/serialization/class-mapping.txt diff --git a/source/fundamentals/serialization/guid-serialization.txt b/source/serialization/guid-serialization.txt similarity index 100% rename from source/fundamentals/serialization/guid-serialization.txt rename to source/serialization/guid-serialization.txt diff --git a/source/fundamentals/serialization/poco.txt b/source/serialization/poco.txt similarity index 100% rename from source/fundamentals/serialization/poco.txt rename to source/serialization/poco.txt diff --git a/source/fundamentals/serialization/polymorphic-objects.txt b/source/serialization/polymorphic-objects.txt similarity index 100% rename from source/fundamentals/serialization/polymorphic-objects.txt rename to source/serialization/polymorphic-objects.txt diff --git a/source/fundamentals/specify-query.txt b/source/specify-query.txt similarity index 100% rename from source/fundamentals/specify-query.txt rename to source/specify-query.txt diff --git a/source/fundamentals/stable-api.txt b/source/stable-api.txt similarity index 100% rename from source/fundamentals/stable-api.txt rename to source/stable-api.txt diff --git a/source/fundamentals/time-series.txt b/source/time-series.txt similarity index 100% rename from source/fundamentals/time-series.txt rename to source/time-series.txt diff --git a/source/fundamentals/transactions.txt b/source/transactions.txt similarity index 100% rename from source/fundamentals/transactions.txt rename to source/transactions.txt From bddfbe6147587b4b4f979004ac7c52ac5a5d1d49 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 3 Apr 2025 10:24:17 -0500 Subject: [PATCH 02/10] wip --- source/connect.txt | 164 ++---------------- .../connection-options}/stable-api.txt | 0 source/connect/mongoclient.txt | 157 +++++++++++++++++ source/connection.txt | 31 ---- source/{ => crud}/builders.txt | 0 .../{write-operations => }/bulk-write.txt | 0 .../configure.txt} | 0 source/crud/{write-operations => }/delete.txt | 0 source/{ => crud}/geo.txt | 0 source/{ => crud}/gridfs.txt | 0 source/crud/{write-operations => }/insert.txt | 0 source/{ => crud}/linq.txt | 0 .../crud/{read-operations.txt => query.txt} | 0 .../change-streams.txt | 0 .../crud/{read-operations => query}/count.txt | 0 source/crud/query/cursors.txt | 0 .../{read-operations => query}/distinct.txt | 0 .../retrieve.txt => query/find.txt} | 0 .../{read-operations => query}/project.txt | 0 .../specify-documents-to-return.txt | 0 source/{ => crud/query}/specify-query.txt | 0 .../crud/{write-operations => }/replace.txt | 0 source/{ => crud}/transactions.txt | 0 .../{write-operations => }/update-many.txt | 0 .../update-many/arrays.txt | 0 .../update-many/fields.txt | 0 .../{write-operations => }/update-one.txt | 0 .../update-one/arrays.txt | 0 .../update-one/fields.txt | 0 source/crud/write-operations.txt | 25 --- source/data-formats.txt | 0 source/{ => data-formats}/bson.txt | 0 source/data-formats/custom-types.txt | 0 .../custom-types}/class-mapping.txt | 0 .../custom-types}/poco.txt | 0 .../custom-types}/polymorphic-objects.txt | 0 .../custom-types}/serialization.txt | 0 source/data-formats/extended-json.txt | 0 .../guid-serialization.txt | 0 source/{ => data-formats}/time-series.txt | 0 ...llection.txt => databases-collections.txt} | 0 source/fundamentals.txt | 58 ------- source/integrations.txt | 0 source/{ => integrations}/odata.txt | 0 source/logging-and-monitoring.txt | 0 .../{ => logging-and-monitoring}/logging.txt | 0 .../monitoring.txt | 0 source/{ => reference}/compatibility.txt | 0 source/{ => reference}/issues-and-help.txt | 0 source/{ => reference}/previous-versions.txt | 0 source/{ => reference}/quick-reference.txt | 0 .../release-notes.txt} | 0 source/{ => reference}/upgrade.txt | 0 source/{ => reference}/upgrade/v2.txt | 0 source/{ => reference}/upgrade/v3.txt | 0 source/{ => security}/encrypt-fields.txt | 0 source/usage-examples.txt | 105 ----------- 57 files changed, 175 insertions(+), 365 deletions(-) rename source/{ => connect/connection-options}/stable-api.txt (100%) create mode 100644 source/connect/mongoclient.txt delete mode 100644 source/connection.txt rename source/{ => crud}/builders.txt (100%) rename source/crud/{write-operations => }/bulk-write.txt (100%) rename source/{read-write-configuration.txt => crud/configure.txt} (100%) rename source/crud/{write-operations => }/delete.txt (100%) rename source/{ => crud}/geo.txt (100%) rename source/{ => crud}/gridfs.txt (100%) rename source/crud/{write-operations => }/insert.txt (100%) rename source/{ => crud}/linq.txt (100%) rename source/crud/{read-operations.txt => query.txt} (100%) rename source/crud/{read-operations => query}/change-streams.txt (100%) rename source/crud/{read-operations => query}/count.txt (100%) create mode 100644 source/crud/query/cursors.txt rename source/crud/{read-operations => query}/distinct.txt (100%) rename source/crud/{read-operations/retrieve.txt => query/find.txt} (100%) rename source/crud/{read-operations => query}/project.txt (100%) rename source/crud/{read-operations => query}/specify-documents-to-return.txt (100%) rename source/{ => crud/query}/specify-query.txt (100%) rename source/crud/{write-operations => }/replace.txt (100%) rename source/{ => crud}/transactions.txt (100%) rename source/crud/{write-operations => }/update-many.txt (100%) rename source/crud/{write-operations => }/update-many/arrays.txt (100%) rename source/crud/{write-operations => }/update-many/fields.txt (100%) rename source/crud/{write-operations => }/update-one.txt (100%) rename source/crud/{write-operations => }/update-one/arrays.txt (100%) rename source/crud/{write-operations => }/update-one/fields.txt (100%) delete mode 100644 source/crud/write-operations.txt create mode 100644 source/data-formats.txt rename source/{ => data-formats}/bson.txt (100%) create mode 100644 source/data-formats/custom-types.txt rename source/{serialization => data-formats/custom-types}/class-mapping.txt (100%) rename source/{serialization => data-formats/custom-types}/poco.txt (100%) rename source/{serialization => data-formats/custom-types}/polymorphic-objects.txt (100%) rename source/{ => data-formats/custom-types}/serialization.txt (100%) create mode 100644 source/data-formats/extended-json.txt rename source/{serialization => data-formats}/guid-serialization.txt (100%) rename source/{ => data-formats}/time-series.txt (100%) rename source/{database-collection.txt => databases-collections.txt} (100%) delete mode 100644 source/fundamentals.txt create mode 100644 source/integrations.txt rename source/{ => integrations}/odata.txt (100%) create mode 100644 source/logging-and-monitoring.txt rename source/{ => logging-and-monitoring}/logging.txt (100%) rename source/{ => logging-and-monitoring}/monitoring.txt (100%) rename source/{ => reference}/compatibility.txt (100%) rename source/{ => reference}/issues-and-help.txt (100%) rename source/{ => reference}/previous-versions.txt (100%) rename source/{ => reference}/quick-reference.txt (100%) rename source/{whats-new.txt => reference/release-notes.txt} (100%) rename source/{ => reference}/upgrade.txt (100%) rename source/{ => reference}/upgrade/v2.txt (100%) rename source/{ => reference}/upgrade/v3.txt (100%) rename source/{ => security}/encrypt-fields.txt (100%) delete mode 100644 source/usage-examples.txt diff --git a/source/connect.txt b/source/connect.txt index 2e8b8625..5e688438 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -1,15 +1,8 @@ -.. _csharp-connect-to-mongodb: +.. _csharp-connect: -================ -Connection Guide -================ - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: connection string, URI, server, Atlas, settings +================== +Connect to MongoDB +================== .. contents:: On this page :local: @@ -17,140 +10,19 @@ Connection Guide :depth: 2 :class: singlecol -This guide shows you how to connect to a MongoDB instance or replica set -deployment using the {+driver-short+}. - -.. _csharp_connection_uri: - -Connection URI --------------- - -A **connection URI**, also known as a *connection string*, tells the driver how to connect to a MongoDB deployment and how to behave while connected. - -A standard connection string includes the following pieces: - -.. list-table:: - :widths: 20 80 - :header-rows: 1 - - * - Piece - - Description - - * - ``mongodb://`` - - - Required. A prefix that identifies this as a string in the - standard connection format. - - * - ``username:password@`` - - - Optional. Authentication credentials. If you include these, the client will authenticate the user against the database specified in ``authSource``. - - * - ``host[:port]`` - - - Required. The host and optional port number where MongoDB is running. If you don't include the port number, the driver will use the default port, ``27017``. - - * - ``/defaultauthdb`` - - - Optional. The authentication database to use if the - connection string includes ``username:password@`` - authentication credentials but not the ``authSource`` option. If you don't include - this piece, the client will authenticate the user against the ``admin`` database. - - * - ``?`` - - - Optional. A query string that specifies connection-specific - options as ``=`` pairs. See - :ref:`csharp-connection-options` for a full description of - these options. - -To use a connection URI, pass it as a string to the ``MongoClient`` constructor. In the -following example, the driver uses a sample connection URI to connect to a MongoDB -instance on port ``27017`` of ``localhost``: - -.. literalinclude:: /includes/fundamentals/code-examples/connection/LocalConnection.cs - :language: csharp - :start-after: // start local connection - :end-before: // end local connection - -.. tip:: Reuse Your Client - - Because each ``MongoClient`` represents a pool of connections to the - database, most applications require only a single instance of - ``MongoClient``, even across multiple requests. To learn more about - how connection pools work in the driver, see the :ref:`FAQ page - `. - -See :manual:`the MongoDB Manual ` for more information about creating a connection string. - -MongoClientSettings -------------------- - -You can use a ``MongoClientSettings`` object to configure the connection in code -rather than in a connection URI. To use a ``MongoClientSettings`` object, create an -instance of the class and pass it as an argument to the ``MongoClient`` constructor. - -In the following example, the driver uses a ``MongoClientSettings`` object to connect to a -MongoDB instance on port ``27017`` of ``localhost``: - -.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettings.cs - :language: csharp - :dedent: - :start-after: // start mongo client settings - :end-before: // end mongo client settings - -Other Connection Targets ------------------------- - -Connect to Atlas -~~~~~~~~~~~~~~~~ - -To connect to a MongoDB deployment on Atlas, create a client. You can -create a client that uses your connection string and other -client options by passing a ``MongoClientSettings`` object to the ``MongoClient`` -constructor. - -To specify your connection URI, pass it to the ``FromConnectionString()`` -method, which returns a new ``MongoClientSettings`` instance. To specify any other -client options, set the relevant fields of the ``MongoClientSettings`` object. - -You can set the {+stable-api+} version as a client option to avoid -breaking changes when you upgrade to a new server version. To -learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page -`. - -The following code shows how you can specify the connection string and -the {+stable-api+} client option when connecting to a MongoDB -deployment and verify that the connection is successful: - -.. literalinclude:: /includes/fundamentals/code-examples/connection/AtlasConnection.cs - :language: csharp - :start-after: // start atlas connection - :end-before: // end atlas connection - -.. tip:: - - Follow the :atlas:`Atlas driver connection guide ` - to retrieve your connection string. - -Connect to a Replica Set -~~~~~~~~~~~~~~~~~~~~~~~~ - -To connect to a replica set deployment, specify the hostnames (or IP addresses) and -port numbers of the members of the replica set. - -If you aren't able to provide a full list of hosts in the replica set, you can -specify one or more of the hosts in the replica set and instruct the driver to -perform automatic discovery in one of the following ways: - -- Specify the name of the replica set as the value of the ``replicaSet`` parameter. -- Specify ``false`` as the value of the ``directConnection`` parameter. -- Specify more than one host in the replica set. +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use the {+driver-short+} to connect to MongoDB. + :keywords: client, ssl -In the following example, the driver uses a sample connection URI to connect to the -MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different -hosts, including ``sample.host1``: +.. toctree:: + :titlesonly: + :maxdepth: 1 -.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs - :language: csharp - :start-after: // start replica set connection - :end-before: // end replica set connection + Create a MongoClient + Choose a Connection Target + Specify Connection Options + Connect with AWS Lambda \ No newline at end of file diff --git a/source/stable-api.txt b/source/connect/connection-options/stable-api.txt similarity index 100% rename from source/stable-api.txt rename to source/connect/connection-options/stable-api.txt diff --git a/source/connect/mongoclient.txt b/source/connect/mongoclient.txt new file mode 100644 index 00000000..99dbfde5 --- /dev/null +++ b/source/connect/mongoclient.txt @@ -0,0 +1,157 @@ +.. _csharp-connect-to-mongodb: +.. _csharp-create-mongoclient: + +==================== +Create a MongoClient +==================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: connection string, URI, server, Atlas, settings + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This guide shows you how to connect to a MongoDB instance or replica set +deployment by using the {+driver-short+}. + +.. _csharp_connection_uri: + +Connection URI +-------------- + +A **connection URI**, also known as a *connection string*, tells the driver how to connect to a MongoDB deployment and how to behave while connected. + +A standard connection string includes the following pieces: + +.. list-table:: + :widths: 20 80 + :header-rows: 1 + + * - Piece + - Description + + * - ``mongodb://`` + + - Required. A prefix that identifies this as a string in the + standard connection format. + + * - ``username:password@`` + + - Optional. Authentication credentials. If you include these, the client will authenticate the user against the database specified in ``authSource``. + + * - ``host[:port]`` + + - Required. The host and optional port number where MongoDB is running. If you don't include the port number, the driver will use the default port, ``27017``. + + * - ``/defaultauthdb`` + + - Optional. The authentication database to use if the + connection string includes ``username:password@`` + authentication credentials but not the ``authSource`` option. If you don't include + this piece, the client will authenticate the user against the ``admin`` database. + + * - ``?`` + + - Optional. A query string that specifies connection-specific + options as ``=`` pairs. See + :ref:`csharp-connection-options` for a full description of + these options. + +To use a connection URI, pass it as a string to the ``MongoClient`` constructor. In the +following example, the driver uses a sample connection URI to connect to a MongoDB +instance on port ``27017`` of ``localhost``: + +.. literalinclude:: /includes/fundamentals/code-examples/connection/LocalConnection.cs + :language: csharp + :start-after: // start local connection + :end-before: // end local connection + +.. tip:: Reuse Your Client + + Because each ``MongoClient`` represents a pool of connections to the + database, most applications require only a single instance of + ``MongoClient``, even across multiple requests. To learn more about + how connection pools work in the driver, see the :ref:`FAQ page + `. + +See :manual:`the MongoDB Manual ` for more information about creating a connection string. + +MongoClientSettings +------------------- + +You can use a ``MongoClientSettings`` object to configure the connection in code +rather than in a connection URI. To use a ``MongoClientSettings`` object, create an +instance of the class and pass it as an argument to the ``MongoClient`` constructor. + +In the following example, the driver uses a ``MongoClientSettings`` object to connect to a +MongoDB instance on port ``27017`` of ``localhost``: + +.. literalinclude:: /includes/fundamentals/code-examples/connection/MongoClientSettings.cs + :language: csharp + :dedent: + :start-after: // start mongo client settings + :end-before: // end mongo client settings + +Other Connection Targets +------------------------ + +Connect to Atlas +~~~~~~~~~~~~~~~~ + +To connect to a MongoDB deployment on Atlas, create a client. You can +create a client that uses your connection string and other +client options by passing a ``MongoClientSettings`` object to the ``MongoClient`` +constructor. + +To specify your connection URI, pass it to the ``FromConnectionString()`` +method, which returns a new ``MongoClientSettings`` instance. To specify any other +client options, set the relevant fields of the ``MongoClientSettings`` object. + +You can set the {+stable-api+} version as a client option to avoid +breaking changes when you upgrade to a new server version. To +learn more about the {+stable-api+} feature, see the :ref:`{+stable-api+} page +`. + +The following code shows how you can specify the connection string and +the {+stable-api+} client option when connecting to a MongoDB +deployment and verify that the connection is successful: + +.. literalinclude:: /includes/fundamentals/code-examples/connection/AtlasConnection.cs + :language: csharp + :start-after: // start atlas connection + :end-before: // end atlas connection + +.. tip:: + + Follow the :atlas:`Atlas driver connection guide ` + to retrieve your connection string. + +Connect to a Replica Set +~~~~~~~~~~~~~~~~~~~~~~~~ + +To connect to a replica set deployment, specify the hostnames (or IP addresses) and +port numbers of the members of the replica set. + +If you aren't able to provide a full list of hosts in the replica set, you can +specify one or more of the hosts in the replica set and instruct the driver to +perform automatic discovery in one of the following ways: + +- Specify the name of the replica set as the value of the ``replicaSet`` parameter. +- Specify ``false`` as the value of the ``directConnection`` parameter. +- Specify more than one host in the replica set. + +In the following example, the driver uses a sample connection URI to connect to the +MongoDB replica set ``sampleRS``, which is running on port ``27017`` of three different +hosts, including ``sample.host1``: + +.. literalinclude:: /includes/fundamentals/code-examples/connection/ReplicaSetConnection.cs + :language: csharp + :start-after: // start replica set connection + :end-before: // end replica set connection diff --git a/source/connection.txt b/source/connection.txt deleted file mode 100644 index 3b0ec89a..00000000 --- a/source/connection.txt +++ /dev/null @@ -1,31 +0,0 @@ -.. _csharp-connection: - -========== -Connection -========== - -.. default-domain:: mongodb - -.. toctree:: - - Connection Guide - Connection Options - Configure TLS - Network Compression - Connect with AWS Lambda - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -Overview --------- - -In this section, you'll learn how to use the {+driver-short+} to connect your application to a MongoDB deployment. Click a link in the following list to jump to a topic: - -- :ref:`How to Connect to MongoDB ` -- :ref:`Connection Options ` -- :ref:`Enable TLS on a Connection ` -- :atlas:`Connect to MongoDB Atlas from AWS Lambda ` \ No newline at end of file diff --git a/source/builders.txt b/source/crud/builders.txt similarity index 100% rename from source/builders.txt rename to source/crud/builders.txt diff --git a/source/crud/write-operations/bulk-write.txt b/source/crud/bulk-write.txt similarity index 100% rename from source/crud/write-operations/bulk-write.txt rename to source/crud/bulk-write.txt diff --git a/source/read-write-configuration.txt b/source/crud/configure.txt similarity index 100% rename from source/read-write-configuration.txt rename to source/crud/configure.txt diff --git a/source/crud/write-operations/delete.txt b/source/crud/delete.txt similarity index 100% rename from source/crud/write-operations/delete.txt rename to source/crud/delete.txt diff --git a/source/geo.txt b/source/crud/geo.txt similarity index 100% rename from source/geo.txt rename to source/crud/geo.txt diff --git a/source/gridfs.txt b/source/crud/gridfs.txt similarity index 100% rename from source/gridfs.txt rename to source/crud/gridfs.txt diff --git a/source/crud/write-operations/insert.txt b/source/crud/insert.txt similarity index 100% rename from source/crud/write-operations/insert.txt rename to source/crud/insert.txt diff --git a/source/linq.txt b/source/crud/linq.txt similarity index 100% rename from source/linq.txt rename to source/crud/linq.txt diff --git a/source/crud/read-operations.txt b/source/crud/query.txt similarity index 100% rename from source/crud/read-operations.txt rename to source/crud/query.txt diff --git a/source/crud/read-operations/change-streams.txt b/source/crud/query/change-streams.txt similarity index 100% rename from source/crud/read-operations/change-streams.txt rename to source/crud/query/change-streams.txt diff --git a/source/crud/read-operations/count.txt b/source/crud/query/count.txt similarity index 100% rename from source/crud/read-operations/count.txt rename to source/crud/query/count.txt diff --git a/source/crud/query/cursors.txt b/source/crud/query/cursors.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/crud/read-operations/distinct.txt b/source/crud/query/distinct.txt similarity index 100% rename from source/crud/read-operations/distinct.txt rename to source/crud/query/distinct.txt diff --git a/source/crud/read-operations/retrieve.txt b/source/crud/query/find.txt similarity index 100% rename from source/crud/read-operations/retrieve.txt rename to source/crud/query/find.txt diff --git a/source/crud/read-operations/project.txt b/source/crud/query/project.txt similarity index 100% rename from source/crud/read-operations/project.txt rename to source/crud/query/project.txt diff --git a/source/crud/read-operations/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt similarity index 100% rename from source/crud/read-operations/specify-documents-to-return.txt rename to source/crud/query/specify-documents-to-return.txt diff --git a/source/specify-query.txt b/source/crud/query/specify-query.txt similarity index 100% rename from source/specify-query.txt rename to source/crud/query/specify-query.txt diff --git a/source/crud/write-operations/replace.txt b/source/crud/replace.txt similarity index 100% rename from source/crud/write-operations/replace.txt rename to source/crud/replace.txt diff --git a/source/transactions.txt b/source/crud/transactions.txt similarity index 100% rename from source/transactions.txt rename to source/crud/transactions.txt diff --git a/source/crud/write-operations/update-many.txt b/source/crud/update-many.txt similarity index 100% rename from source/crud/write-operations/update-many.txt rename to source/crud/update-many.txt diff --git a/source/crud/write-operations/update-many/arrays.txt b/source/crud/update-many/arrays.txt similarity index 100% rename from source/crud/write-operations/update-many/arrays.txt rename to source/crud/update-many/arrays.txt diff --git a/source/crud/write-operations/update-many/fields.txt b/source/crud/update-many/fields.txt similarity index 100% rename from source/crud/write-operations/update-many/fields.txt rename to source/crud/update-many/fields.txt diff --git a/source/crud/write-operations/update-one.txt b/source/crud/update-one.txt similarity index 100% rename from source/crud/write-operations/update-one.txt rename to source/crud/update-one.txt diff --git a/source/crud/write-operations/update-one/arrays.txt b/source/crud/update-one/arrays.txt similarity index 100% rename from source/crud/write-operations/update-one/arrays.txt rename to source/crud/update-one/arrays.txt diff --git a/source/crud/write-operations/update-one/fields.txt b/source/crud/update-one/fields.txt similarity index 100% rename from source/crud/write-operations/update-one/fields.txt rename to source/crud/update-one/fields.txt diff --git a/source/crud/write-operations.txt b/source/crud/write-operations.txt deleted file mode 100644 index bb946729..00000000 --- a/source/crud/write-operations.txt +++ /dev/null @@ -1,25 +0,0 @@ -.. _csharp-crud-write-operations: - -================ -Write Operations -================ - -.. meta:: - :description: Learn about the commands for running MongoDB write operations by using the {+driver-long+}. - -.. toctree:: - :caption: Write Operations - - Insert - Update One - Update Many - Replace - Delete - Bulk Write Operations - -- :ref:`csharp-insert-guide` -- :ref:`csharp-update-one` -- :ref:`csharp-update-many` -- :ref:`csharp-replace-documents` -- :ref:`csharp-delete-guide` -- :ref:`csharp-bulk-write` diff --git a/source/data-formats.txt b/source/data-formats.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/bson.txt b/source/data-formats/bson.txt similarity index 100% rename from source/bson.txt rename to source/data-formats/bson.txt diff --git a/source/data-formats/custom-types.txt b/source/data-formats/custom-types.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/serialization/class-mapping.txt b/source/data-formats/custom-types/class-mapping.txt similarity index 100% rename from source/serialization/class-mapping.txt rename to source/data-formats/custom-types/class-mapping.txt diff --git a/source/serialization/poco.txt b/source/data-formats/custom-types/poco.txt similarity index 100% rename from source/serialization/poco.txt rename to source/data-formats/custom-types/poco.txt diff --git a/source/serialization/polymorphic-objects.txt b/source/data-formats/custom-types/polymorphic-objects.txt similarity index 100% rename from source/serialization/polymorphic-objects.txt rename to source/data-formats/custom-types/polymorphic-objects.txt diff --git a/source/serialization.txt b/source/data-formats/custom-types/serialization.txt similarity index 100% rename from source/serialization.txt rename to source/data-formats/custom-types/serialization.txt diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/serialization/guid-serialization.txt b/source/data-formats/guid-serialization.txt similarity index 100% rename from source/serialization/guid-serialization.txt rename to source/data-formats/guid-serialization.txt diff --git a/source/time-series.txt b/source/data-formats/time-series.txt similarity index 100% rename from source/time-series.txt rename to source/data-formats/time-series.txt diff --git a/source/database-collection.txt b/source/databases-collections.txt similarity index 100% rename from source/database-collection.txt rename to source/databases-collections.txt diff --git a/source/fundamentals.txt b/source/fundamentals.txt deleted file mode 100644 index fe326063..00000000 --- a/source/fundamentals.txt +++ /dev/null @@ -1,58 +0,0 @@ -.. _csharp-fundamentals: - -============ -Fundamentals -============ - -.. meta:: - :description: Learn how to use the (+driver-long+} to run commands on MongoDB. - -.. toctree:: - :titlesonly: - :maxdepth: 1 - - Connection - Databases & Collections - CRUD Operations - Operations with Builders - Atlas Search - Stable API - Authentication - Aggregation - LINQ - BSON Operations - Query - Serialization - Transactions - Indexes - Logging - Time Series Collections - In-Use Encryption - Search Geospatially - Store Large Files - Replica Set Operations - OData - Monitoring - -- :ref:`Connecting to MongoDB ` -- :ref:`csharp-db-coll` -- :ref:`csharp-crud` -- :ref:`csharp-builders` -- :ref:`csharp-atlas-search` -- :ref:`csharp-stable-api` -- :ref:`csharp-authentication-mechanisms` -- :ref:`csharp-aggregation` -- :ref:`csharp-linq` -- :ref:`csharp-bson` -- :ref:`csharp-specify-query` -- :ref:`csharp-serialization` -- :ref:`csharp-transactions` -- :ref:`csharp-indexes` -- :ref:`csharp-logging` -- :ref:`csharp-time-series` -- :ref:`Encrypt Fields ` -- :ref:`csharp-geo` -- :ref:`csharp-gridfs` -- :ref:`csharp-read-write-config` -- :ref:`csharp-odata` -- :ref:`csharp-monitoring` \ No newline at end of file diff --git a/source/integrations.txt b/source/integrations.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/odata.txt b/source/integrations/odata.txt similarity index 100% rename from source/odata.txt rename to source/integrations/odata.txt diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/logging.txt b/source/logging-and-monitoring/logging.txt similarity index 100% rename from source/logging.txt rename to source/logging-and-monitoring/logging.txt diff --git a/source/monitoring.txt b/source/logging-and-monitoring/monitoring.txt similarity index 100% rename from source/monitoring.txt rename to source/logging-and-monitoring/monitoring.txt diff --git a/source/compatibility.txt b/source/reference/compatibility.txt similarity index 100% rename from source/compatibility.txt rename to source/reference/compatibility.txt diff --git a/source/issues-and-help.txt b/source/reference/issues-and-help.txt similarity index 100% rename from source/issues-and-help.txt rename to source/reference/issues-and-help.txt diff --git a/source/previous-versions.txt b/source/reference/previous-versions.txt similarity index 100% rename from source/previous-versions.txt rename to source/reference/previous-versions.txt diff --git a/source/quick-reference.txt b/source/reference/quick-reference.txt similarity index 100% rename from source/quick-reference.txt rename to source/reference/quick-reference.txt diff --git a/source/whats-new.txt b/source/reference/release-notes.txt similarity index 100% rename from source/whats-new.txt rename to source/reference/release-notes.txt diff --git a/source/upgrade.txt b/source/reference/upgrade.txt similarity index 100% rename from source/upgrade.txt rename to source/reference/upgrade.txt diff --git a/source/upgrade/v2.txt b/source/reference/upgrade/v2.txt similarity index 100% rename from source/upgrade/v2.txt rename to source/reference/upgrade/v2.txt diff --git a/source/upgrade/v3.txt b/source/reference/upgrade/v3.txt similarity index 100% rename from source/upgrade/v3.txt rename to source/reference/upgrade/v3.txt diff --git a/source/encrypt-fields.txt b/source/security/encrypt-fields.txt similarity index 100% rename from source/encrypt-fields.txt rename to source/security/encrypt-fields.txt diff --git a/source/usage-examples.txt b/source/usage-examples.txt deleted file mode 100644 index 1096d1e9..00000000 --- a/source/usage-examples.txt +++ /dev/null @@ -1,105 +0,0 @@ -.. _csharp-usage-examples: - -============== -Usage Examples -============== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code, .NET, operation - -.. contents:: On this page - :local: - :backlinks: none - :depth: 1 - :class: singlecol - -.. toctree:: - - Find a Document - Find Multiple Documents - Insert a Document - Insert Multiple Documents - Update a Document - Update Many Documents - Replace a Document - Delete a Document - Delete Many Documents - -Overview --------- - -Usage examples provide convenient starting points for popular MongoDB -operations. Each example provides the following information: - -- A code snippet that shows how to perform the operation in synchronous and - asynchronous frameworks - -- A link to a fully runnable console application using the operation - -- The expected result after running the example - -.. tip:: - - Whether you use a synchronous or asynchronous framework in your application depends - on your use case. Synchronous calls are more suitable for simple query workflows or - when you must implement sequential logic. Consider using asynchronous calls if - your application relies on multiple concurrent database requests or if your - program doesn't require an immediate response from the database to continue - executing. - - We encourage experimenting with both approaches to determine the most - suitable framework for your purposes. - -How to Use the Usage Examples ------------------------------ - -These examples use the :atlas:`sample datasets ` -provided by Atlas. You can load them into your database on the free tier of -MongoDB Atlas by following the -:atlas:`Get Started with Atlas Guide ` -or you can -:guides:`import the sample dataset into a local MongoDB instance -`. - -Once you have imported the dataset, you can copy and paste a usage -example into your development environment of choice. You can follow the -:ref:`csharp-get-started` to learn more about getting -started with the {+driver-long+}. Once you've copied a usage example, -you'll need to edit the connection URI to get the example connected to -your MongoDB instance: - -.. code-block:: csharp - - // Replace the following with your MongoDB deployment's connection string. - private static string _mongoConnectionString = ""; - -For more information about connecting to your MongoDB instance, see the -:ref:`Connection Guide `. - -Example Classes ---------------- - -The usage examples in this section show how to perform operations on documents -in the ``restaurants`` collection. The examples use the following ``Restaurant``, -``Address``, and ``GradeEntry`` classes to model the data in this collection: - -.. literalinclude:: /includes/code-examples/Restaurant.cs - :language: csharp - :copyable: - :dedent: - -.. literalinclude:: /includes/code-examples/Address.cs - :language: csharp - :copyable: - :dedent: - -.. literalinclude:: /includes/code-examples/GradeEntry.cs - :language: csharp - :copyable: - :dedent: - -.. include:: /includes/convention-pack-note.rst From cea42289ffd83476d1b18621d78c02ee3a613b5a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 3 Apr 2025 10:53:29 -0500 Subject: [PATCH 03/10] edit index --- source/data-formats.txt | 1 + source/databases-collections.txt | 1 + source/index.txt | 179 +++++++++++++----------------- source/integrations.txt | 51 +++++++++ source/logging-and-monitoring.txt | 1 + source/reference.txt | 24 ++++ source/security.txt | 1 + 7 files changed, 156 insertions(+), 102 deletions(-) diff --git a/source/data-formats.txt b/source/data-formats.txt index e69de29b..77eaca0d 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -0,0 +1 @@ +.. _csharp-data-formats: \ No newline at end of file diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 919d9e03..73da433d 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -1,4 +1,5 @@ .. _csharp-db-coll: +.. _csharp-databases-collections: ========================= Databases and Collections diff --git a/source/index.txt b/source/index.txt index 0730ca4c..b764a51f 100644 --- a/source/index.txt +++ b/source/index.txt @@ -1,3 +1,5 @@ +.. _csharp-index: + ================= MongoDB C# Driver ================= @@ -11,143 +13,116 @@ MongoDB C# Driver .. toctree:: - Previous Versions Get Started - Quick Reference - What's New - Usage Examples - Fundamentals - API Documentation <{+new-api-root+}/index.html> - FAQ - Connection Troubleshooting + Connect + Databases & Collections + CRUD Operations + Aggregation + Data Formats + Indexes + Run a Database Command + Atlas Search + Atlas Vector Search + Logging and Monitoring + Security + Integrations + Reference + API Documentation <{+api-root+}> Issues & Help - Compatibility - Upgrade - Entity Framework Provider - {+analyzer-short+} -Introduction ------------- +Overview +-------- Welcome to the documentation site for the official {+driver-long+}. You can add the driver to your application to work with MongoDB in {+language+}. -Download the driver using `NuGet `__, or set up a runnable -project by following our :ref:`Get Started ` guide. - -Previous Versions ------------------ - -For documentation on versions of the driver v2.18 and earlier, see the :ref:`csharp-previous-versions` section. - -Connect to a Compatible MongoDB Deployment ------------------------------------------- - -You can use the {+driver-short+} to connect to MongoDB -deployments running on one of the following hosted services or editions: - -.. include:: /includes/fact-environments.rst Get Started ----------- -Learn how to establish a connection to MongoDB Atlas and begin -working with data in the :ref:`csharp-get-started` section. - -Quick Reference ---------------- - -See driver syntax examples for common MongoDB commands in the -:ref:`Quick Reference ` section. +Learn how to install the driver, establish a connection to MongoDB, and begin +working with data in the :ref:`csharp-get-started` tutorial. -What's New ----------- +Connect to MongoDB +------------------ -For a list of new features and changes in each version, see the :ref:`What's New ` -section. - -Usage Examples --------------- - -For fully runnable code snippets and explanations for common -methods, see :ref:`csharp-usage-examples`. - -Fundamentals ------------- +Learn how to create and configure a connection to a MongoDB deployment +in the :ref:`csharp-connect` section. -For detailed information on key concepts of using the {+driver-short+}, see -:ref:`csharp-fundamentals`. +Databases and Collections +------------------------- -API Documentation ------------------ +Learn how to use the {+driver-short+} to work with MongoDB databases and collections +in the :ref:`csharp-databases-collections` section. -For detailed information about types and methods in the {+driver-short+}, see -the `{+driver-long+} API documentation -<{+new-api-root+}/index.html>`__. +Read and Write Data +------------------- -Take the Free Online Course Taught by MongoDB ---------------------------------------------- +Learn how to find, update, and delete data in the :ref:`csharp-crud` section. -.. list-table:: +Transform Your Data with Aggregation +------------------------------------ - * - .. figure:: /includes/figures/M220N.png - :alt: Banner for the C# MongoDB University Course +Learn how to use the {+driver-short+} to perform aggregation operations in the +:ref:`csharp-aggregation` section. - - `Using MongoDB with C# `__ +Data Formats +------------ - Learn the essentials of C# & ASP.NET application development with MongoDB. +Learn how to work with specialized data formats and custom types in the +:ref:`csharp-data-formats` section. -FAQ ---- +Optimize Queries with Indexes +----------------------------- -For answers to commonly asked questions about the {+driver-long+}, see the :ref:`csharp-faq` +Learn how to work with common types of indexes in the :ref:`csharp-indexes` section. -Connection Troubleshooting --------------------------- +Run a Database Command +---------------------- -For solutions to issues you might encounter when using the driver to connect to -a MongoDB deployment, see the :ref:`csharp-connection-troubleshooting` section. +Learn how to run a database command in the :ref:`csharp-run-command` section. -Issues & Help -------------- +Atlas Search +------------ -Learn how to report bugs, contribute to the driver, and find -additional resources for asking questions in the :ref:`csharp-issues-help` section. +Learn how to use Atlas Search to build full-text search capabilities in the +:ref:`csharp-atlas-search` section. -Compatibility -------------- +Atlas Vector Search +------------------- -For the compatibility charts that show the recommended {+driver-short+} version -for each {+mdb-server+} version, see :ref:`csharp-compatibility-tables`. +Learn how to use Atlas Vector Search to query your Atlas data based on semantic meaning +rather than keyword matches in the +`Atlas Vector Search `__ +documentation. -Upgrade Driver Versions ------------------------ +Logging and Monitoring +---------------------- -Learn what changes you may need to make to your application to upgrade -driver versions in the :ref:`Upgrade Driver Versions ` -section. +Learn how to monitor changes to your application and write them to logs in the +:ref:`csharp-logging-monitoring` section. -Entity Framework Provider -------------------------- +Secure Your Data +---------------- -The MongoDB Entity Framework Provider is an object-relational mapper (ORM) that lets you -use Microsoft's Entity Framework to work with MongoDB data. ORMs provide an -object-oriented interface for data management. +Learn about ways you can authenticate your application and encrypt your data in +the :ref:`csharp-security` section. -The provider includes features such as the following: +Reference +--------- -- Intelligent object tracking -- Entity-based LINQ operations -- Entity Framework modeling and mapping with the fluent API -- Automatic database updates through change tracking +Find more information about {+driver-short+} versions, compatibility, and upgrading driver +versions in the :ref:`csharp-reference` section. -To learn more, see the -`MongoDB Entity Framework Provider documentation `__. +API Documentation +----------------- -{+analyzer+} -------------------- +For detailed information about types and methods in the {+driver-short+}, see +the `{+driver-long+} API documentation +<{+new-api-root+}/index.html>`__. + +Issues & Help +------------- -The {+analyzer-short+} is a tool that helps you understand how your -{+driver-short+} code translates into the {+query-api+} and if your code -includes any unsupported LINQ or builder expressions. To learn more, see the -`{+analyzer-short+} documentation `__. \ No newline at end of file +Learn how to report bugs, contribute to the driver, and find help in the +:ref:`` section. \ No newline at end of file diff --git a/source/integrations.txt b/source/integrations.txt index e69de29b..a4457ea2 100644 --- a/source/integrations.txt +++ b/source/integrations.txt @@ -0,0 +1,51 @@ +.. _csharp-integrations:: + +====================== +Integrations and Tools +====================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn about {+driver-short+} integrations and tools. + :keywords: third-party + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + Entity Framework Provider + {+analyzer-short+} + +Entity Framework Provider +------------------------- + +The MongoDB Entity Framework Provider is an object-relational mapper (ORM) that lets you +use Microsoft's Entity Framework to work with MongoDB data. ORMs provide an +object-oriented interface for data management. + +The provider includes features such as the following: + +- Intelligent object tracking +- Entity-based LINQ operations +- Entity Framework modeling and mapping with the fluent API +- Automatic database updates through change tracking + +To learn more, see the +`MongoDB Entity Framework Provider documentation `__. + +{+analyzer+} +------------------- + +The {+analyzer-short+} is a tool that helps you understand how your +{+driver-short+} code translates into the {+query-api+} and if your code +includes any unsupported LINQ or builder expressions. To learn more, see the +`{+analyzer-short+} documentation `__. \ No newline at end of file diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt index e69de29b..d18df391 100644 --- a/source/logging-and-monitoring.txt +++ b/source/logging-and-monitoring.txt @@ -0,0 +1 @@ +.. _csharp-logging-monitoring: \ No newline at end of file diff --git a/source/reference.txt b/source/reference.txt index e69de29b..06e103ca 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -0,0 +1,24 @@ +.. _csharp-reference: + +========= +Reference +========= + +.. facet:: + :name: programming_language + :values: csharp + +.. meta:: + :keywords: dotnet + +.. toctree:: + + Previous Versions + Quick Reference + Compatibility + Upgrade + +Previous Versions +----------------- + +For documentation on versions of the driver v2.18 and earlier, see the :ref:`csharp-previous-versions` section. \ No newline at end of file diff --git a/source/security.txt b/source/security.txt index e69de29b..5927bd31 100644 --- a/source/security.txt +++ b/source/security.txt @@ -0,0 +1 @@ +.. _csharp-security: \ No newline at end of file From 218886a55ea1c9aa8f62299046f1967f218da134 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 3 Apr 2025 13:59:02 -0500 Subject: [PATCH 04/10] wip --- snooty.toml | 14 +++----------- source/connect/connection-options.txt | 10 ++++++++++ source/crud.txt | 18 ++++++++++++------ source/crud/query.txt | 24 ++++++++++-------------- source/integrations.txt | 14 +++++++++++++- 5 files changed, 48 insertions(+), 32 deletions(-) diff --git a/snooty.toml b/snooty.toml index a29f100f..d3f802ad 100644 --- a/snooty.toml +++ b/snooty.toml @@ -1,15 +1,7 @@ toc_landing_pages = [ - "/fundamentals/connection", - "/fundamentals/crud", - "/usage-examples", - "/fundamentals", - "/fundamentals/serialization", - "/fundamentals/crud/write-operations/update-one", - "/fundamentals/crud/write-operations/update-many", - "/fundamentals/authentication", - "/upgrade", - "/fundamentals/database-collection", - "/get-started" + "/get-started", + "/connect/connection-options", + "/crud" ] name = "csharp" title = "C#/.NET" diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 21c26c7f..2d4198e0 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -17,6 +17,16 @@ Connection Options :depth: 2 :class: singlecol +.. toctree:: + :caption: Specify Connection Options + + Compress Network Traffic + Customize Server Selection + Stable API + Limit Server Execution Time + Connection Pools + Connect from AWS Lambda + This section describes the MongoDB connection and authentication options available in the {+driver-short+}. You can configure your connection using either the connection URI or a ``MongoClientSettings`` object. diff --git a/source/crud.txt b/source/crud.txt index 9e3275dc..2292d8e8 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -8,10 +8,16 @@ CRUD Operations :description: Learn how to run create, read, update, delete (CRUD) MongoDB operations by using the {+driver-long+}. .. toctree:: - :caption: CRUD Operations + :titlesonly: + :maxdepth: 1 - Write - Read - -- :ref:`csharp-crud-read-operations` -- :ref:`csharp-crud-write-operations` + Insert Documents + Query Documents + Update Documents + Replace Documents + Delete Documents + Bulk Write Operations + Transactions + Store Large Files + Configure CRUD Operations + Geospatial Queries diff --git a/source/crud/query.txt b/source/crud/query.txt index 6938a56a..93468c74 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -1,4 +1,5 @@ .. _csharp-crud-read-operations: +.. _csharp-crud-query: =============== Read Operations @@ -8,18 +9,13 @@ Read Operations :description: Learn about the commands for running MongoDB read operations by using the {+driver-long+}. .. toctree:: - :caption: Read Operations + :titlesonly: + :maxdepth: 1 - Retrieve Data - Specify Fields to Return - Count Documents - List Distinct Values - Monitor Data Changes - Specify Query Results - -- :ref:`csharp-retrieve` -- :ref:`csharp-project` -- :ref:`csharp-count-documents` -- :ref:`csharp-distinct` -- :ref:`csharp-change-streams` -- :ref:`csharp-specify-documents-to-return` + Specify a Query + Find Documents + Specify Documents to Return + Specify Fields to Return + Count Documents + Distinct Field Values + Access Data from a Cursor \ No newline at end of file diff --git a/source/integrations.txt b/source/integrations.txt index a4457ea2..61bcb16d 100644 --- a/source/integrations.txt +++ b/source/integrations.txt @@ -1,4 +1,4 @@ -.. _csharp-integrations:: +.. _csharp-integrations: ====================== Integrations and Tools @@ -22,9 +22,21 @@ Integrations and Tools :titlesonly: :maxdepth: 1 + :ref:`OData ` Entity Framework Provider {+analyzer-short+} +OData +----- + +OData (Open Data Protocol) is a standardized protocol for building and consuming +RESTful APIs that allows for the querying and manipulation of data by using +HTTP requests. It provides a uniform way to expose and interact +with data from multiple sources. + +To learn how to integrate OData with your MongoDB application, see the +:ref:`OData ` tutorial. + Entity Framework Provider ------------------------- From 870fc354f75fad94061d3acdb7da2a8433f32554 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:19:45 -0500 Subject: [PATCH 05/10] wip --- snooty.toml | 3 +- source/connect.txt | 1 - source/data-formats.txt | 42 ++++++++++++++++++- .../{guid-serialization.txt => guids.txt} | 0 source/logging-and-monitoring.txt | 19 ++++++++- .../change-streams.txt | 0 source/security.txt | 19 ++++++++- ...crypt-fields.txt => in-use-encryption.txt} | 1 + .../tls.txt => security/tls-ssl.txt} | 0 9 files changed, 80 insertions(+), 5 deletions(-) rename source/data-formats/{guid-serialization.txt => guids.txt} (100%) rename source/{crud/query => logging-and-monitoring}/change-streams.txt (100%) rename source/security/{encrypt-fields.txt => in-use-encryption.txt} (77%) rename source/{connect/connection-options/tls.txt => security/tls-ssl.txt} (100%) diff --git a/snooty.toml b/snooty.toml index d3f802ad..5c6fc2da 100644 --- a/snooty.toml +++ b/snooty.toml @@ -1,7 +1,8 @@ toc_landing_pages = [ "/get-started", "/connect/connection-options", - "/crud" + "/crud", + "/security/authentication" ] name = "csharp" title = "C#/.NET" diff --git a/source/connect.txt b/source/connect.txt index 5e688438..e65a58a1 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,4 +25,3 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target Specify Connection Options - Connect with AWS Lambda \ No newline at end of file diff --git a/source/data-formats.txt b/source/data-formats.txt index 77eaca0d..7bd3b913 100644 --- a/source/data-formats.txt +++ b/source/data-formats.txt @@ -1 +1,41 @@ -.. _csharp-data-formats: \ No newline at end of file +.. _csharp-data-formats: + +======================== +Specialized Data Formats +======================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: bson, guid, serialization, extended json, custom types, time series + +.. toctree:: + :titlesonly: + :maxdepth: 1 + + BSON + Extended JSON + Custom Types + GUIDs + Time Series Data + +Overview +-------- + +You can use several types of specialized data formats in your {+driver-short+} +application. To learn how to work with these data formats, see the following +sections: + +- Learn how to work with BSON documents in the :ref:`csharp-bson` guide. +- Learn how to translate BSON to Extended JSON in the :ref:`csharp-extended-json` guide. +- Learn how to serialize custom types in the :ref:`csharp-custom-types` guide. +- Learn about globally unique identifiers (GUIDs) and how to maintain cross-language + compatibility while working with them in the :ref:`csharp-guids` guide. \ No newline at end of file diff --git a/source/data-formats/guid-serialization.txt b/source/data-formats/guids.txt similarity index 100% rename from source/data-formats/guid-serialization.txt rename to source/data-formats/guids.txt diff --git a/source/logging-and-monitoring.txt b/source/logging-and-monitoring.txt index d18df391..f459fe79 100644 --- a/source/logging-and-monitoring.txt +++ b/source/logging-and-monitoring.txt @@ -1 +1,18 @@ -.. _csharp-logging-monitoring: \ No newline at end of file +.. _csharp-logging-monitoring: + +====================== +Logging and Monitoring +====================== + +.. facet:: + :name: programming_language + :values: csharp + +.. meta:: + :keywords: dotnet + +.. toctree:: + + Logging + Monitoring + Change Streams \ No newline at end of file diff --git a/source/crud/query/change-streams.txt b/source/logging-and-monitoring/change-streams.txt similarity index 100% rename from source/crud/query/change-streams.txt rename to source/logging-and-monitoring/change-streams.txt diff --git a/source/security.txt b/source/security.txt index 5927bd31..82b6bbe4 100644 --- a/source/security.txt +++ b/source/security.txt @@ -1 +1,18 @@ -.. _csharp-security: \ No newline at end of file +.. _csharp-security: + +======== +Security +======== + +.. facet:: + :name: programming_language + :values: csharp + +.. meta:: + :keywords: dotnet + +.. toctree:: + + Authentication + In-Use Encryption + TLS/SSL \ No newline at end of file diff --git a/source/security/encrypt-fields.txt b/source/security/in-use-encryption.txt similarity index 77% rename from source/security/encrypt-fields.txt rename to source/security/in-use-encryption.txt index f519dca0..1939074c 100644 --- a/source/security/encrypt-fields.txt +++ b/source/security/in-use-encryption.txt @@ -1,4 +1,5 @@ .. _csharp-fle: +.. _csharp-in-use-encryption: .. sharedinclude:: dbx/encrypt-fields.rst diff --git a/source/connect/connection-options/tls.txt b/source/security/tls-ssl.txt similarity index 100% rename from source/connect/connection-options/tls.txt rename to source/security/tls-ssl.txt From a5b4b504a2fd5589c0c6e071a052e65c1c1f1b4c Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:22:43 -0500 Subject: [PATCH 06/10] ref drawer --- source/reference.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/reference.txt b/source/reference.txt index 06e103ca..7c6da5cc 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -13,10 +13,10 @@ Reference .. toctree:: - Previous Versions - Quick Reference - Compatibility - Upgrade + Quick Reference + Compatibility + Upgrade + Previous Versions Previous Versions ----------------- From f69db2804823403a14ec1bcf9eedda5a09f8aefc Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:48:26 -0500 Subject: [PATCH 07/10] wip --- snooty.toml | 1 - source/aggregation.txt | 136 ++++++ source/{crud => aggregation}/linq.txt | 0 source/atlas-search.txt | 30 ++ .../builders.txt => atlas-vector-search.txt} | 437 +----------------- source/connect.txt | 1 + source/crud/query/project.txt | 88 +++- .../query/specify-documents-to-return.txt | 24 +- source/crud/query/specify-query.txt | 91 ++++ source/crud/update-many.txt | 46 ++ source/crud/update-one.txt | 50 +- source/indexes.txt | 79 ++++ source/integrations.txt | 1 - 13 files changed, 544 insertions(+), 440 deletions(-) rename source/{crud => aggregation}/linq.txt (100%) rename source/{crud/builders.txt => atlas-vector-search.txt} (62%) diff --git a/snooty.toml b/snooty.toml index 5c6fc2da..61696522 100644 --- a/snooty.toml +++ b/snooty.toml @@ -1,7 +1,6 @@ toc_landing_pages = [ "/get-started", "/connect/connection-options", - "/crud", "/security/authentication" ] name = "csharp" diff --git a/source/aggregation.txt b/source/aggregation.txt index 96169dd5..c5fdbe4b 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -219,3 +219,139 @@ following API documentation: - `Where() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Where.html>`__ - `GroupBy() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.GroupBy.html>`__ - `Select() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Linq.MongoQueryable.Select.html>`__ + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +.. _csharp-builders-aggregation: + +Build an Aggregation Pipeline +----------------------------- + +The ``PipelineDefinitionBuilder`` class provides a type-safe interface for +defining an **aggregation pipeline**. An aggregation pipeline is a series of +stages that are used to transform a document. Suppose you want to create a +pipeline that performs the following operations: + +- Matches all documents with "spring" in the ``Season`` field +- Sorts the results by the ``Category`` field +- Groups the documents by category and shows the average price and total + available for all documents in that category + +Use ``PipelineDefinitionBuilder`` classes to build the pipeline: + +.. code-block:: csharp + + var sortBuilder = Builders.Sort.Ascending(f => f.Category); + var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); + + var pipeline = new EmptyPipelineDefinition() + .Match(matchFilter) + .Sort(sortBuilder) + .Group(f => f.Category, + g => new + { + name = g.Key, + avgPrice = g.Average(f => f.Price), + totalAvailable = g.Sum(f => f.Stock) + } + ); + +The preceding example creates the following pipeline: + +.. code-block:: json + + [{ "$match" : { "season" : "spring" } }, { "$sort" : { "category" : 1 } }, { "$group" : { "_id" : "$category", "avgPrice" : { "$avg" : "$price" }, "totalAvailable" : { "$sum" : "$stock" } } }] + +You can add stages to your pipeline that don't have corresponding type-safe +methods in the ``PipelineDefinitionBuilder`` interface by providing your query +as a ``BsonDocument`` to the `AppendStage() method +<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.AppendStage.html>`__. + +.. code-block:: csharp + + var pipeline = new EmptyPipelineDefinition().AppendStage("{ $set: { field1: '$field2' } }"); + +.. note:: + + When using a ``BsonDocument`` to define your pipeline stage, the driver does + not take into account any ``BsonClassMap``, serialization attributes or + serialization conventions. The field names used in the ``BsonDocument`` must + match those stored on the server. + + For more information on providing a query as a ``BsonDocument``, see our + :ref:`FAQ page `. + +To learn more about the Aggregation Pipeline, see the +:manual:`Aggregation Pipeline ` server manual page. + +.. _csharp-builders-out: + +Write Pipeline Results to a Collection +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can write the documents returned from an aggregation pipeline to a +collection by creating an ``$out`` stage at the end of your aggregation +pipeline. To create an ``$out`` stage, call the ``Out()`` method on a +``PipelineStageDefinitionBuilder``. The ``Out()`` method requires the name of +the collection you want to write the documents to. + +The following example builds an aggregation pipeline that matches all documents +with a ``season`` field value of ``"Spring"`` and outputs them to +a ``springFlowers`` collection: + +.. code-block:: csharp + + var outputCollection = database.GetCollection("springFlowers"); + var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); + + // Creates an aggregation pipeline and outputs resulting documents to a new collection. + var pipeline = new EmptyPipelineDefinition() + .Match(matchFilter) + .Out(outputCollection); + +You can write the results of an aggregation pipeline to a time series collection +by specifying a ``TimeSeriesOption`` object and passing it as the second +parameter to the ``Out()`` method. + +Imagine that the documents in the ``plants.flowers`` collection contain a ``datePlanted`` field that +holds BSON date values. You can store the documents in this collection in a time +series collection by using the ``datePlanted`` field as the time field. + +The following example creates a ``TimeSeriesOptions`` object and specifies +``datePlanted`` as the ``timeField``. It then builds an aggregation pipeline that matches all documents +with a ``season`` field value of ``"Spring"`` and outputs them to a +time series collection called ``springFlowerTimes``. + +.. code-block:: csharp + + var timeSeriesOptions = new TimeSeriesOptions("datePlanted"); + var collectionName = "springFlowerTimes" + var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); + + // Creates an aggregation pipeline and outputs resulting documents to a time series collection. + var pipeline = new EmptyPipelineDefinition() + .Match(matchFilter) + .Out(collectionName, timeSeriesOptions); + +To learn more about time series collections, see :ref:`csharp-time-series`. + + +- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__ \ No newline at end of file diff --git a/source/crud/linq.txt b/source/aggregation/linq.txt similarity index 100% rename from source/crud/linq.txt rename to source/aggregation/linq.txt diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 4dae38c5..770674ef 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -683,3 +683,33 @@ The search returns the following document: To learn more about the ``wildcard`` operator, see the :atlas:`wildcard ` Atlas guide. + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Build an Atlas Search Query +--------------------------- + +The ``Search`` class provides a type-safe interface for creating a +:manual:`$search ` +pipeline stage. + +To learn how to construct search queries with the ``Search`` class, see +:ref:`csharp-atlas-search`. diff --git a/source/crud/builders.txt b/source/atlas-vector-search.txt similarity index 62% rename from source/crud/builders.txt rename to source/atlas-vector-search.txt index 4ccf6189..4a92f822 100644 --- a/source/crud/builders.txt +++ b/source/atlas-vector-search.txt @@ -1,48 +1,4 @@ -.. _csharp-builders: - -======================== -Operations with Builders -======================== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: aggregation, query, code example - -Overview --------- - -.. include:: /includes/linq-vs-builders.rst - -In this guide, you can learn about the helper classes, or **builders**, that -the {+driver-short+} provides to create types used in your operations. -Using builders helps you identify errors at compile time and avoid them -at runtime. This guide provides information on builder classes that you -can use for the following tasks: - -- Creating a filter definition -- Creating a projection -- Defining a sort order -- Defining an update operation -- Selecting index keys - -.. tip:: {+analyzer+} - - The {+analyzer-short+} is a tool that helps you analyze your - builders definitions and understand how your {+lang-framework+} code - translates into the {+query-api+}. For more information and - installation instructions, see the `{+analyzer-short+} reference page `__. - -You should read this guide if you want to learn more about how to -construct definitions and build up syntax using builders. +.. TODO: integrate into existing page Sample Class ------------ @@ -62,371 +18,6 @@ Each builder class takes a generic type parameter with. In this guide, the ``Flower`` class is the document type used in each builder class example. -Construct a Filter ------------------- - -The ``FilterDefinitionBuilder`` class provides a type-safe interface for -building up queries. Suppose you want to query your collection for -documents matching the following criteria: - -- ``Price`` field value less than 20 -- ``Category`` field value is "Perennial" - -Use builders to create the filter definition with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt(f => f.Price, 20) & builder.Eq(f => f.Category, "Perennial"); - -Using the typed variant form provides compile-time safety. Additionally, -your IDE can provide refactoring support. - -Alternatively, you can use string-based field names to contruct the filter: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); - -If you are using LINQ, you can also use the ``Inject()`` method to apply the filter -to a LINQ query: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); - var query = collection.AsQueryable().Where(f => filter.Inject()); - -Array Operators -~~~~~~~~~~~~~~~ - -If your document has properties or fields that serialize to arrays, -you can use the methods beginning with ``Any``, such as ``AnyEq()`` or -``AnyLt()``, to compare the entire array against a single item. - -Use builders to check which documents in the collection have a -``Season`` array that includes "winter": - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.AnyEq(f => f.Season, "winter"); - -You can also call the ``ElemMatch()`` method to find documents that have an -array field that contains at least one element that matches a specified search -criteria. The following example returns documents that contain the value -``"Summer"`` in their ``Season`` array: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.ElemMatch(f => f.Season, s => s == "Summer"); - -To learn more about array operators, see the :manual:`Array Query Operators -` guide in the {+mdb-server+} manual. - -.. _csharp-builders-projection: - -Create a Projection -------------------- - -The ``ProjectionDefinitionBuilder`` class provides a type-safe interface for -defining a projection. Suppose you want to create a projection on the -``Name`` and ``Price`` fields, but exclude the ``Id`` field. - -Use builders to create the projection definition with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Include(f => f.Name).Include(f => f.Price).Exclude(f => f.Id); - -You can also use string-based field names to define the projection: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Include("Name").Include("Price").Exclude("Id"); - -Finally, you can use the ``Expression()`` method to define the -projection: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Expression(f => new { Name = f.Name, Price = f.Price }); - -This definition has a return type of ``ProjectionDefinition`` whereas the others return a -``ProjectionDefinition``. - -Lambda Expressions -~~~~~~~~~~~~~~~~~~ - -The driver supports using lambda expressions to render projections. When -you define a ``Find()`` projection with the ``Expression()`` method to -create a lambda expression, the driver inspects the expression -to determine which fields are referenced and automatically constructs a -server-side projection to return only those fields. - -You can also use lambda expressions to create new fields by performing -operations on values in your documents. The following example shows how -you can use a lambda expression to project a new ``Profit`` field -using the ``Price`` and ``Stock`` fields: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Projection; - var projection = builder.Expression(f => new { Profit = f.Price * f.Stock }); - -.. note:: ``Id`` Field Exclusion - - When you create a projection using a lambda expression, the output - automatically excludes the ``Id`` field unless you explicitly include - is as a projection field. - -Define a Sort -------------- - -The ``SortDefinitionBuilder`` class provides a type-safe interface for -building up sort syntax. Suppose you want to define a sort with the -following order: - -- Ascending on ``Price`` -- Descending on ``Category`` - -Use builders to create the sort definition with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Sort; - var sort = builder.Ascending(f => f.Price).Descending(f => f.Category); - -Alternatively, you can use string-based field names to define the sort: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Sort; - var sort = builder.Ascending("Price").Descending("Category"); - -Define an Update ----------------- - -The ``UpdateDefinitionBuilder`` class provides a type-safe interface for -building up an update specification. Suppose you want to create an -update specification with the following criteria: - -- Create the new field ``SunRequirement`` -- Multiply the ``Price`` field value by 0.9 - -Use builders to create the update specification with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Update; - var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9); - -Alternatively, you can use string-based field names to define the update: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Update; - var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9); - -.. _csharp-builders-indexes: - -Define Index Keys ------------------ - -The ``IndexKeysDefinitionBuilder`` class provides a type-safe interface for -defining index keys. Suppose you want to select ``Category`` as an -ascending index key. - -Use builders to select the index key with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - var keys = builder.Ascending(f => f.Category); - -Alternatively, you can use string-based field names to select the index key: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - var keys = builder.Ascending("Category"); - -The ``IndexKeysDefinitionBuilder`` class also provides methods to build -a wildcard index. You can create a wildcard index using ``All field paths`` or ``A -single field path``, in this case using ``Category``: - -.. tabs:: - - .. tab:: ``All field paths`` - :tabid: all-wildcard-index - - .. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - var keys = builder.Wildcard(); - - .. tab:: ``A single field path`` - :tabid: single-wildcard-index - - .. code-block:: csharp - :copyable: true - - var builder = Builders.IndexKeys; - - // Using the typed variant - var keys = builder.Wildcard(f => f.Category); - - // Using string-based field names - var keys = builder.Wildcard("Category"); - -For more information about how to use wildcard indexes, see -:manual:`Wildcard Indexes `. - -.. _csharp-builders-aggregation: - -Build an Aggregation Pipeline ------------------------------ - -The ``PipelineDefinitionBuilder`` class provides a type-safe interface for -defining an **aggregation pipeline**. An aggregation pipeline is a series of -stages that are used to transform a document. Suppose you want to create a -pipeline that performs the following operations: - -- Matches all documents with "spring" in the ``Season`` field -- Sorts the results by the ``Category`` field -- Groups the documents by category and shows the average price and total - available for all documents in that category - -Use ``PipelineDefinitionBuilder`` classes to build the pipeline: - -.. code-block:: csharp - - var sortBuilder = Builders.Sort.Ascending(f => f.Category); - var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); - - var pipeline = new EmptyPipelineDefinition() - .Match(matchFilter) - .Sort(sortBuilder) - .Group(f => f.Category, - g => new - { - name = g.Key, - avgPrice = g.Average(f => f.Price), - totalAvailable = g.Sum(f => f.Stock) - } - ); - -The preceding example creates the following pipeline: - -.. code-block:: json - - [{ "$match" : { "season" : "spring" } }, { "$sort" : { "category" : 1 } }, { "$group" : { "_id" : "$category", "avgPrice" : { "$avg" : "$price" }, "totalAvailable" : { "$sum" : "$stock" } } }] - -You can add stages to your pipeline that don't have corresponding type-safe -methods in the ``PipelineDefinitionBuilder`` interface by providing your query -as a ``BsonDocument`` to the `AppendStage() method -<{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.AppendStage.html>`__. - -.. code-block:: csharp - - var pipeline = new EmptyPipelineDefinition().AppendStage("{ $set: { field1: '$field2' } }"); - -.. note:: - - When using a ``BsonDocument`` to define your pipeline stage, the driver does - not take into account any ``BsonClassMap``, serialization attributes or - serialization conventions. The field names used in the ``BsonDocument`` must - match those stored on the server. - - For more information on providing a query as a ``BsonDocument``, see our - :ref:`FAQ page `. - -To learn more about the Aggregation Pipeline, see the -:manual:`Aggregation Pipeline ` server manual page. - -.. _csharp-builders-out: - -Write Pipeline Results to a Collection -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can write the documents returned from an aggregation pipeline to a -collection by creating an ``$out`` stage at the end of your aggregation -pipeline. To create an ``$out`` stage, call the ``Out()`` method on a -``PipelineStageDefinitionBuilder``. The ``Out()`` method requires the name of -the collection you want to write the documents to. - -The following example builds an aggregation pipeline that matches all documents -with a ``season`` field value of ``"Spring"`` and outputs them to -a ``springFlowers`` collection: - -.. code-block:: csharp - - var outputCollection = database.GetCollection("springFlowers"); - var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); - - // Creates an aggregation pipeline and outputs resulting documents to a new collection. - var pipeline = new EmptyPipelineDefinition() - .Match(matchFilter) - .Out(outputCollection); - -You can write the results of an aggregation pipeline to a time series collection -by specifying a ``TimeSeriesOption`` object and passing it as the second -parameter to the ``Out()`` method. - -Imagine that the documents in the ``plants.flowers`` collection contain a ``datePlanted`` field that -holds BSON date values. You can store the documents in this collection in a time -series collection by using the ``datePlanted`` field as the time field. - -The following example creates a ``TimeSeriesOptions`` object and specifies -``datePlanted`` as the ``timeField``. It then builds an aggregation pipeline that matches all documents -with a ``season`` field value of ``"Spring"`` and outputs them to a -time series collection called ``springFlowerTimes``. - -.. code-block:: csharp - - var timeSeriesOptions = new TimeSeriesOptions("datePlanted"); - var collectionName = "springFlowerTimes" - var matchFilter = Builders.Filter.AnyEq(f => f.Season, "spring"); - - // Creates an aggregation pipeline and outputs resulting documents to a time series collection. - var pipeline = new EmptyPipelineDefinition() - .Match(matchFilter) - .Out(collectionName, timeSeriesOptions); - -To learn more about time series collections, see :ref:`csharp-time-series`. - -Build an Atlas Search Query ---------------------------- - -The ``Search`` class provides a type-safe interface for creating a -:manual:`$search ` -pipeline stage. - -To learn how to construct search queries with the ``Search`` class, see -:ref:`csharp-atlas-search`. - Perform an Atlas Vector Search ------------------------------ @@ -488,28 +79,4 @@ The results of the preceding example contain the following documents: { "_id" : ObjectId("573a13e5f29313caabdc40c9"), "plot" : "A dimension-traveling wizard gets stuck in the 21st century because cell-phone radiation interferes with his magic. With his home world on the brink of war, he seeks help from a jaded ...", "title" : "The Portal" } To learn more about Atlas Vector Search, see :atlas:`Atlas Vector Search Overview ` -in the Atlas manual. - -Troubleshooting ---------------- - -.. include:: /includes/troubleshooting/unsupported-filter-expression.rst - -Additional Information ----------------------- - -Find runnable examples using builders for various operations under -:ref:`Usage Examples `. - -API Documentation -~~~~~~~~~~~~~~~~~ - -To learn more about any of the methods or types discussed in this -guide, see the following API Documentation: - -- `FilterDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinitionBuilder-1.html>`__ -- `ProjectionDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.html>`__ -- `SortDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinitionBuilder-1.html>`__ -- `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__ -- `IndexKeysDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IndexKeysDefinitionBuilder-1.html>`__ -- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__ \ No newline at end of file +in the Atlas manual. \ No newline at end of file diff --git a/source/connect.txt b/source/connect.txt index e65a58a1..6f15db31 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -25,3 +25,4 @@ Connect to MongoDB Create a MongoClient Choose a Connection Target Specify Connection Options + Connection Troubleshooting \ No newline at end of file diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index 6ad03656..cd24ad2d 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -142,4 +142,90 @@ guide, see the following API Documentation: - `Find() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`_ - `Projection <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Builders-1.Projection.html>`_ - `Include() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Include.html>`_ -- `Exclude() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Exclude.html>`_ \ No newline at end of file +- `Exclude() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Exclude.html>`_ + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +.. _csharp-builders-projection: + +Create a Projection +------------------- + +The ``ProjectionDefinitionBuilder`` class provides a type-safe interface for +defining a projection. Suppose you want to create a projection on the +``Name`` and ``Price`` fields, but exclude the ``Id`` field. + +Use builders to create the projection definition with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Include(f => f.Name).Include(f => f.Price).Exclude(f => f.Id); + +You can also use string-based field names to define the projection: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Include("Name").Include("Price").Exclude("Id"); + +Finally, you can use the ``Expression()`` method to define the +projection: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Expression(f => new { Name = f.Name, Price = f.Price }); + +This definition has a return type of ``ProjectionDefinition`` whereas the others return a +``ProjectionDefinition``. + +Lambda Expressions +~~~~~~~~~~~~~~~~~~ + +The driver supports using lambda expressions to render projections. When +you define a ``Find()`` projection with the ``Expression()`` method to +create a lambda expression, the driver inspects the expression +to determine which fields are referenced and automatically constructs a +server-side projection to return only those fields. + +You can also use lambda expressions to create new fields by performing +operations on values in your documents. The following example shows how +you can use a lambda expression to project a new ``Profit`` field +using the ``Price`` and ``Stock`` fields: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Projection; + var projection = builder.Expression(f => new { Profit = f.Price * f.Stock }); + +.. note:: ``Id`` Field Exclusion + + When you create a projection using a lambda expression, the output + automatically excludes the ``Id`` field unless you explicitly include + is as a projection field. + +- `ProjectionDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 99e7d85f..8f99716e 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -217,4 +217,26 @@ guide, see the following API documentation: - `IFindFluent <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.html>`_ - `Limit() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Limit.html>`_ - `Sort() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Sort.html>`_ -- `Skip() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Skip.html>`_ \ No newline at end of file +- `Skip() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IFindFluent-2.Skip.html>`_ + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +- `SortDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.SortDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/crud/query/specify-query.txt b/source/crud/query/specify-query.txt index 22bfa38b..a45d2bb6 100644 --- a/source/crud/query/specify-query.txt +++ b/source/crud/query/specify-query.txt @@ -358,3 +358,94 @@ following Server Manual Entries: To learn more about using Builders, see :ref:`csharp-builders`. To learn how to specify queries using LINQ, see :ref:`csharp-linq`. + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Construct a Filter +------------------ + +The ``FilterDefinitionBuilder`` class provides a type-safe interface for +building up queries. Suppose you want to query your collection for +documents matching the following criteria: + +- ``Price`` field value less than 20 +- ``Category`` field value is "Perennial" + +Use builders to create the filter definition with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.Lt(f => f.Price, 20) & builder.Eq(f => f.Category, "Perennial"); + +Using the typed variant form provides compile-time safety. Additionally, +your IDE can provide refactoring support. + +Alternatively, you can use string-based field names to contruct the filter: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); + +If you are using LINQ, you can also use the ``Inject()`` method to apply the filter +to a LINQ query: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); + var query = collection.AsQueryable().Where(f => filter.Inject()); + +Array Operators +~~~~~~~~~~~~~~~ + +If your document has properties or fields that serialize to arrays, +you can use the methods beginning with ``Any``, such as ``AnyEq()`` or +``AnyLt()``, to compare the entire array against a single item. + +Use builders to check which documents in the collection have a +``Season`` array that includes "winter": + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.AnyEq(f => f.Season, "winter"); + +You can also call the ``ElemMatch()`` method to find documents that have an +array field that contains at least one element that matches a specified search +criteria. The following example returns documents that contain the value +``"Summer"`` in their ``Season`` array: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Filter; + var filter = builder.ElemMatch(f => f.Season, s => s == "Summer"); + +To learn more about array operators, see the :manual:`Array Query Operators +` guide in the {+mdb-server+} manual. + +- `FilterDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/crud/update-many.txt b/source/crud/update-many.txt index 7d46dfce..fcb15029 100644 --- a/source/crud/update-many.txt +++ b/source/crud/update-many.txt @@ -126,4 +126,50 @@ Update Many :start-after: // start-pipeline-async :end-before: // end-pipeline-async +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Define an Update +---------------- + +The ``UpdateDefinitionBuilder`` class provides a type-safe interface for +building up an update specification. Suppose you want to create an +update specification with the following criteria: + +- Create the new field ``SunRequirement`` +- Multiply the ``Price`` field value by 0.9 + +Use builders to create the update specification with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9); + +Alternatively, you can use string-based field names to define the update: +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9); + +- `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/crud/update-one.txt b/source/crud/update-one.txt index 9afb9fd3..ab07f9f9 100644 --- a/source/crud/update-one.txt +++ b/source/crud/update-one.txt @@ -112,4 +112,52 @@ Update One :copyable: true :dedent: :start-after: // start-pipeline-async - :end-before: // end-pipeline-async \ No newline at end of file + :end-before: // end-pipeline-async + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +Define an Update +---------------- + +The ``UpdateDefinitionBuilder`` class provides a type-safe interface for +building up an update specification. Suppose you want to create an +update specification with the following criteria: + +- Create the new field ``SunRequirement`` +- Multiply the ``Price`` field value by 0.9 + +Use builders to create the update specification with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set(f => f.SunRequirement, "Full sun").Mul(f => f.Price, 0.9); + +Alternatively, you can use string-based field names to define the update: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.Update; + var update = builder.Set("SunRequirement", "Full sun").Mul("Price", 0.9); + +- `UpdateDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.UpdateDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/indexes.txt b/source/indexes.txt index 01643254..62c52fe1 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -432,3 +432,82 @@ all indexes in a collection: :start-after: begin-list-indexes :end-before: end-list-indexes :dedent: + +.. TODO: integrate into existing page + +Sample Class +------------ + +The code examples in this guide demonstrate how you can use builders to +create types to interact with documents in the sample collection ``plants.flowers``. +Documents in this collection are modeled by the following ``Flower`` class: + +.. literalinclude:: /includes/fundamentals/code-examples/builders.cs + :language: csharp + :dedent: + :start-after: start-model + :end-before: end-model + +Each builder class takes a generic type parameter +``TDocument`` which represents the type of document that you are working +with. In this guide, the ``Flower`` class is the document type used in +each builder class example. + +.. _csharp-builders-indexes: + +Define Index Keys +----------------- + +The ``IndexKeysDefinitionBuilder`` class provides a type-safe interface for +defining index keys. Suppose you want to select ``Category`` as an +ascending index key. + +Use builders to select the index key with the typed variant: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + var keys = builder.Ascending(f => f.Category); + +Alternatively, you can use string-based field names to select the index key: + +.. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + var keys = builder.Ascending("Category"); + +The ``IndexKeysDefinitionBuilder`` class also provides methods to build +a wildcard index. You can create a wildcard index using ``All field paths`` or ``A +single field path``, in this case using ``Category``: + +.. tabs:: + + .. tab:: ``All field paths`` + :tabid: all-wildcard-index + + .. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + var keys = builder.Wildcard(); + + .. tab:: ``A single field path`` + :tabid: single-wildcard-index + + .. code-block:: csharp + :copyable: true + + var builder = Builders.IndexKeys; + + // Using the typed variant + var keys = builder.Wildcard(f => f.Category); + + // Using string-based field names + var keys = builder.Wildcard("Category"); + +For more information about how to use wildcard indexes, see +:manual:`Wildcard Indexes `. + +- `IndexKeysDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IndexKeysDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/integrations.txt b/source/integrations.txt index 61bcb16d..f17bf8e7 100644 --- a/source/integrations.txt +++ b/source/integrations.txt @@ -19,7 +19,6 @@ Integrations and Tools :keywords: third-party .. toctree:: - :titlesonly: :maxdepth: 1 :ref:`OData ` From c27d872b90b26a0b45033810b38b19924f72f7d1 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Thu, 3 Apr 2025 15:59:33 -0500 Subject: [PATCH 08/10] small changes --- source/reference.txt | 2 +- source/reference/previous-versions.txt | 6 +++--- source/reference/upgrade.txt | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/source/reference.txt b/source/reference.txt index 7c6da5cc..780ca790 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -16,7 +16,7 @@ Reference Quick Reference Compatibility Upgrade - Previous Versions + Versions 2.0 to 2.18 Previous Versions ----------------- diff --git a/source/reference/previous-versions.txt b/source/reference/previous-versions.txt index 1fdfc547..a1b74602 100644 --- a/source/reference/previous-versions.txt +++ b/source/reference/previous-versions.txt @@ -1,8 +1,8 @@ .. _csharp-previous-versions: -================= -Previous Versions -================= +==================== +Versions 2.0 to 2.18 +==================== The following links direct you to documentation for previous versions of the driver. diff --git a/source/reference/upgrade.txt b/source/reference/upgrade.txt index fd55892c..d4d41064 100644 --- a/source/reference/upgrade.txt +++ b/source/reference/upgrade.txt @@ -21,8 +21,8 @@ Upgrade Driver Versions :titlesonly: :maxdepth: 1 - Version 2.x - Version 3.0 + Version 2.x + Version 3.0 Overview -------- From 9042203113d8724c2f604d3bcd7e4de9282b042f Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 4 Apr 2025 10:12:41 -0500 Subject: [PATCH 09/10] wip --- source/aggregation.txt | 1068 +++++++++++++++- source/aggregation/linq.txt | 1069 ----------------- source/atlas-vector-search.txt | 19 +- source/connect/connection-options/csot.txt | 0 source/connect/connection-targets.txt | 0 source/connect/connection-troubleshooting.txt | 2 - source/crud.txt | 3 +- source/crud/insert.txt | 4 +- source/crud/query/count.txt | 1 - source/crud/query/find.txt | 2 +- .../query/specify-documents-to-return.txt | 2 +- source/crud/query/specify-query.txt | 17 +- source/crud/update-many.txt | 4 +- source/crud/update-one.txt | 4 +- source/data-formats/custom-types.txt | 26 + source/data-formats/custom-types/poco.txt | 3 - .../custom-types/serialization.txt | 8 - source/data-formats/extended-json.txt | 11 + source/data-formats/time-series.txt | 2 +- source/databases-collections.txt | 2 +- source/get-started.txt | 9 +- source/index.txt | 2 +- source/integrations.txt | 2 +- source/{reference => }/issues-and-help.txt | 0 source/reference.txt | 1 + source/reference/quick-reference.txt | 18 - source/reference/release-notes.txt | 10 +- source/security.txt | 2 +- source/security/authentication.txt | 12 +- 29 files changed, 1156 insertions(+), 1147 deletions(-) delete mode 100644 source/aggregation/linq.txt create mode 100644 source/connect/connection-options/csot.txt create mode 100644 source/connect/connection-targets.txt rename source/{reference => }/issues-and-help.txt (100%) diff --git a/source/aggregation.txt b/source/aggregation.txt index c5fdbe4b..404bf1ea 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -354,4 +354,1070 @@ time series collection called ``springFlowerTimes``. To learn more about time series collections, see :ref:`csharp-time-series`. -- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__ \ No newline at end of file +- `PipelineDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.PipelineDefinitionBuilder.html>`__ + +.. TODO: integrate into existing page + +.. _csharp-linq: + +==== +LINQ +==== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, query, aggregation + + +Overview +-------- + +.. include:: /includes/linq-vs-builders.rst + +In this guide you can learn how to use +`LINQ `__ +with the {+driver-long+}. LINQ allows you to construct queries against +strongly typed collections of objects by using language keywords and operators. +The {+driver-short+} automatically translates LINQ queries into +:manual:`aggregation operations `. + +.. important:: + + LINQ3 is the only LINQ provider available in the {+driver-long+}. If you have + manually configured your project to use LINQ2, it will not compile. + +The examples in this guide use the ``restaurants`` collection +in the ``sample_restaurants`` database provided in the :atlas:`Atlas sample datasets `. +To learn how to create a free MongoDB Atlas cluster and load the sample datasets, +see the :ref:``. + +The following ``Restaurant``, ``Address`` and ``GradeEntry`` classes model the +documents in this collection: + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-restaurant-model + :end-before: end-restaurant-model + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-address-model + :end-before: end-address-model + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-grade-model + :end-before: end-grade-model + +.. include:: /includes/convention-pack-note.rst + +.. _csharp-linq-queryable: + +Make A Collection Queryable +--------------------------- + +To use LINQ to query your collection, you must first create an +an `IQueryable +`__ +object that links to the collection. To create the object, use the ``AsQueryable()`` method +as follows: + +.. code-block:: csharp + :emphasize-lines: 3 + + var restaurantsDatabase = client.GetDatabase("sample_restaurants"); + var restaurantsCollection = restaurantsDatabase.GetCollection("restaurants"); + var queryableCollection = restaurantsCollection.AsQueryable(); + +Once you have the queryable object, you can compose a query using +**method syntax**. Some pipeline stages also support **query comprehension syntax**, +which resembles SQL query syntax. + +Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see +how to compose a query using LINQ: + +.. tabs:: + + .. tab:: Method Syntax + :tabid: method-syntax + + .. code-block:: csharp + + var query = queryableCollection + .Where(r => r.Name == "The Movable Feast") + .Select(r => new { r.Name, r.Address }); + + .. tab:: Query Syntax + :tabid: query-syntax + + .. code-block:: csharp + + var query = from r in queryableCollection + where r.Name == "The Movable Feast" + select new { r.Name, r.Address }; + +You can print the results of the preceding example as follows: + +.. io-code-block:: + + .. input:: + :language: csharp + + foreach (var restaurant in query) + { + Console.WriteLine(restaurant.ToJson()); + } + + .. output:: + + { "name" : "The Movable Feast", "address" : { "building" : "284", "coord" : [-73.982923900000003, 40.6580753], "street" : "Prospect Park West", "zipcode" : "11215" } } + +.. tip:: Accessing Query Results + + You can also access the results of your query by using the ``ToList()`` or + ``ToCursor()`` methods: + + .. code-block:: csharp + + var results = query.ToList(); + + .. code-block:: csharp + + var results = query.ToCursor(); + + +Supported Aggregation Stages +---------------------------- + +You can use LINQ to create an :ref:`aggregation pipeline `. +The {+driver-short+} automatically translates each LINQ statement into the corresponding +aggregation pipeline stages. In this section you can learn which +aggregation pipeline stages are supported. + +To learn more about the aggregation pipeline stages, see the +:ref:`aggregation-pipeline-operator-reference` page in the server manual. + +$project +~~~~~~~~ + +The ``$project`` aggregation stage returns a document containing only the specified +fields. + +Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how +to generate a ``$project`` stage using LINQ: + +.. tabs:: + + .. tab:: Method Syntax + :tabid: method-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = queryableCollection + .Select(r => new { r.Name, r.Address }); + + .. tab:: Query Syntax + :tabid: query-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = from r in queryableCollection + select new { r.Name, r.Address }; + +The result of the preceding example contains the following document: + +.. code-block:: json + + { "name" : "The Movable Feast", "address" : { "building" : "284", "coord" : [-73.982923900000003, 40.6580753], "street" : "Prospect Park West", "zipcode" : "11215" } } + +.. note:: Excluding the ``_id`` Field + + If you don't include the ``_id`` field in your LINQ projection, the {+driver-short+} + automatically excludes it from the results. + +$match +~~~~~~ + +The ``$match`` aggregation stage returns the documents that match a specified +criteria. + +Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how +to generate a ``$match`` stage using LINQ: + +.. tabs:: + + .. tab:: Method Syntax + :tabid: method-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = queryableCollection + .Where(r => r.Name == "The Movable Feast"); + + .. tab:: Query Syntax + :tabid: query-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = from r in queryableCollection + where r.Name == "The Movable Feast" + select r; + +The result of the preceding example contains the following document: + +.. code-block:: json + + // Results Truncated + + { "_id" : ObjectId(...), "name" : "The Movable Feast", "restaurant_id" : "40361606", "cuisine" : "American", "address" : {...}, "borough" : "Brooklyn", "grades" : [...] } + +$limit +~~~~~~ + +The ``$limit`` aggregation stage limits the number of documents returned by the +query. The following example shows how to generate a ``$limit`` stage using LINQ: + +.. code-block:: csharp + :emphasize-lines: 4 + + var query = queryableCollection + .Where(r => r.Cuisine == "Italian") + .Select(r => new {r.Name, r.Cuisine}) + .Take(5); + +The result of the preceding example contains the following documents: + +.. code-block:: json + + { "name" : "Philadelhia Grille Express", "cuisine" : "Italian" } + { "name" : "Isle Of Capri Resturant", "cuisine" : "Italian" } + { "name" : "Marchis Restaurant", "cuisine" : "Italian" } + { "name" : "Crystal Room", "cuisine" : "Italian" } + { "name" : "Forlinis Restaurant", "cuisine" : "Italian" } + +$sample +~~~~~~~ + +The ``$sample`` aggregation stage returns a random sample of documents from a +collection. The following example shows how to generate a ``$sample`` stage by using +LINQ: + +.. code-block:: csharp + :emphasize-lines: 4 + + var query = queryableCollection + .Aggregate() + .Sample(4) + .ToList(); + +The result of the preceding example contains the following documents: + +.. code-block:: json + + // Results Truncated + + { "name" : "Von Dolhens", "cuisine" : "Ice Cream, Gelato, Yogurt, Ices" } + { "name" : "New York Mercantile Exchange", "cuisine" : "American" } + { "name" : "Michaelangelo's Restaurant", "cuisine" : "Italian" } + { "name" : "Charlie Palmer Steak", "cuisine" : "American" } + +$skip +~~~~~ + +The ``$skip`` aggregation stage skips over a specified number of documents returned +by a query, then returns the rest of the results. The following example shows how to generate +a ``$skip`` stage using LINQ: + +.. code-block:: csharp + :emphasize-lines: 4 + + var query = queryableCollection + .Where(r => r.Cuisine == "Italian") + .Select(r => new {r.Name, r.Cuisine}) + .Skip(2); + +The preceding example skips the first two restaurants that match the criteria, and +returns the rest. The result contains the following documents: + +.. code-block:: json + + // Results Truncated + + { "name" : "Marchis Restaurant", "cuisine" : "Italian" } + { "name" : "Crystal Room", "cuisine" : "Italian" } + { "name" : "Forlinis Restaurant", "cuisine" : "Italian" } + ... + +$unwind +~~~~~~~ + +The ``$unwind`` aggregation stage deconstructs a specified array field and returns +a document for each element in that array. + +Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how +to generate an ``$unwind`` stage using LINQ: + +.. tabs:: + + .. tab:: Method Syntax + :tabid: method-syntax + + .. code-block:: csharp + :emphasize-lines: 3 + + var query = queryableCollection + .Where(r => r.Name == "The Movable Feast") + .SelectMany(r => r.Grades); + + .. tab:: Query Syntax + :tabid: query-syntax + + .. code-block:: csharp + :emphasize-lines: 3 + + var query = from r in queryableCollection + where r.Name == "The Movable Feast" + from grade in r.Grades + select grade; + +The query in the preceding example finds the document where the ``Name`` field +has the value "The Movable Feast." Then, for each element in this document's +``Grades`` array, the query returns a new document. The result contains the +following documents: + +.. code-block:: json + + { "date" : ISODate("2014-11-19T00:00:00Z"), "grade" : "A", "score" : 11 } + { "date" : ISODate("2013-11-14T00:00:00Z"), "grade" : "A", "score" : 2 } + { "date" : ISODate("2012-12-05T00:00:00Z"), "grade" : "A", "score" : 13 } + { "date" : ISODate("2012-05-17T00:00:00Z"), "grade" : "A", "score" : 11 } + +Nested Statements ++++++++++++++++++ + +You can chain or nest ``Select`` and ``SelectMany`` statements to unwind nested +arrays. Consider a collection that contains documents with a **new** schema. These +documents contain a ``restaurants`` field, which holds an array of documents +represented by the ``Restaurant`` class. The documents within the array each have +a ``grades`` field that holds an array of documents represented by +the ``Grade`` class. The following code is an example of a single document in +this collection: + +.. code-block:: json + + { + "_id": { "$oid": ... }, + "restaurants": [ + { + "_id": { ... } , + "address": { ... }, + "name": "Tov Kosher Kitchen", + "grades": [ + { + "date" : ISODate("2014-11-24T00:00:00Z"), + "grade" : "Z", + "score" : 20.0 + }, + { + "date" : ISODate("2013-01-17T00:00:00Z"), + "grade" : "A", + "score" : 13.0 + } + ] + ... + }, + { + "_id": { ... } , + "address": { ... }, + "name": "Harriet's Kitchen", + "grades": [ + { + "date" : ISODate("2014-04-19T00:00:00Z"), + "grade" : "B", + "score" : 12.0 + } + ], + ... + }, + ... + ] + } + +You can nest ``SelectMany`` statements within ``SelectMany`` or ``Select`` +statements. The following example nests a ``SelectMany`` statement within a +``Select`` statement to retrieve an array from each document in the collection. +Each array holds all grade objects from all restaurants in each document. + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :start-after: start-nested-SelectMany + :end-before: end-nested-SelectMany + + .. output:: + :visible: false + :language: json + + // output for first document in collection + [ + { "date" : ISODate("2014-11-24T00:00:00Z"), + "grade" : "Z", + "score" : 20.0 + }, + { "date" : ISODate("2013-01-17T00:00:00Z"), + "grade" : "A", + "score" : 13.0 + }, + { + "date" : ISODate("2014-04-19T00:00:00Z"), + "grade" : "B", + "score" : 12.0 + }, + ... + ], + // output for second document in collection + [ + ... + ] + +$group +~~~~~~ + +The ``$group`` aggregation stage separates documents into groups according to +the criteria you specify. + +Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how +to generate an ``$group`` stage using LINQ: + +.. tabs:: + + .. tab:: Method Syntax + :tabid: method-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = queryableCollection + .GroupBy(r => r.Cuisine) + .Select(g => new { Cuisine = g.Key, Count = g.Count() }); + + .. tab:: Query Syntax + :tabid: query-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = from r in queryableCollection + group r by r.Cuisine into g + select new {Cuisine = g.Key, Count = g.Count()}; + +The preceding example groups each document by the value in its ``Cuisine`` field, +then counts how many documents have each ``Cuisine`` value. The result contains +the following documents: + +.. code-block:: json + + // Results Truncated + + { "cuisine" : "Caribbean", "count" : 657 } + { "cuisine" : "Café/Coffee/Tea", "count" : 1214 } + { "cuisine" : "Iranian", "count" : 2 } + { "cuisine" : "Nuts/Confectionary", "count" : 6 } + { "cuisine" : "Middle Eastern", "count" : 168 } + ... + +.. note:: Result Order + + The preceding queries don't always return results in the same order. Running + this example may return the results in a different order than shown above. + +$sort +~~~~~ + +The ``$sort`` aggregation stage returns the results of your query in the order +that you specify. + +Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how +to generate an ``$sort`` stage using LINQ: + +.. tabs:: + + .. tab:: Method Syntax + :tabid: method-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = queryableCollection + .OrderBy(r => r.Name) + .ThenByDescending(r => r.RestaurantId); + + .. tab:: Query Syntax + :tabid: query-syntax + + .. code-block:: csharp + :emphasize-lines: 2 + + var query = from r in queryableCollection + orderby r.Name, r.RestaurantId descending + select r; + +The preceding example returns the query results sorted alphabetically by the +``Name`` field, with a secondary descending sort on the ``RestaurantId`` field. +The following is a subset of the documents contained in the returned results: + +.. code-block:: json + + // Results Truncated + + ... + { "_id" : ObjectId(...), "name" : "Aba Turkish Restaurant", "restaurant_id" : "41548686", "cuisine" : "Turkish", "address" : {...}, "borough" : "Manhattan", "grades" : [...] } + { "_id" : ObjectId(...), "name" : "Abace Sushi", "restaurant_id" : "50006214", "cuisine" : "Japanese", "address" : { ... }, "borough" : "Manhattan", "grades" : [...] } + { "_id" : ObjectId(...), "name" : "Abacky Potluck", "restaurant_id" : "50011222", "cuisine" : "Asian", "address" : { ... }, "borough" : "Manhattan", "grades" : [...] } + { "_id" : ObjectId(...), "name" : "Abaleh", "restaurant_id" : "50009096", "cuisine" : "Mediterranean", "address" : { ... }, "borough" : "Manhattan", "grades" : [...] } + ... + +$lookup +~~~~~~~ + +The ``$lookup`` aggregation stage joins documents from one collection to documents +from another collection in the same database. The ``$lookup`` stage adds a new +array field to each input document. The new array field contains the matching +documents from the "joined" collection. + +.. note:: + + To perform a lookup, you must make both collections queryable by using the + ``AsQueryable()`` method. + + To learn how to make a collection queryable, see :ref:`csharp-linq-queryable`. + +Consider a second collection in the ``sample_restaurants`` database called +``reviews`` that has restaurant reviews. You can join documents from that collection +to documents with the same ``name`` value in the ``restaurants`` collection using +the ``$lookup`` stage. + +The following ``Review`` class models the documents in the ``reviews`` collection: + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-review-model + :end-before: end-review-model + +Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how +to generate a ``$lookup`` stage by using LINQ: + +.. tabs:: + + .. tab:: Method Syntax + :tabid: method-syntax + + .. code-block:: csharp + + var query = queryableCollection + .GroupJoin(reviewCollection, + restaurant => restaurant.Name, + review => review.RestaurantName, + (restaurant, reviews) => + new { Restaurant = restaurant, Reviews = reviews } + ); + + .. tab:: Query Syntax + :tabid: query-syntax + + .. code-block:: csharp + + var query = from restaurant in queryableCollection + join rv in reviewCollection on restaurant.Name equals rv.RestaurantName into reviews + select new { restaurant, reviews }; + +The preceding example returns all documents from the ``restaurants`` collection. Each +restaurant document has an added field called ``reviews``, which contains all +reviews for that restaurant. A review matches a restaurant if the value of the +``name`` field in the review document matches the ``name`` field of the restaurant +document. + +The following shows a subset of the returned results: + +.. code-block:: json + + // Results Truncated + + { + "restaurant": { + "_id": ObjectId("..."), + "name": "The Movable Feast", + "restaurant_id": "40361606", + "cuisine": "American", + "address": { ... }, + "borough": "Brooklyn", + "grades": [ ... ] + }, + "reviews": [ + { + "_id": ObjectId("..."), + "restaurant_name": "The Movable Feast", + "reviewer": "Lazlo Cravensworth", + "review_text": "Great restaurant! 12/10 stars!" + }, + { + "_id": ObjectId("..."), + "restaurant_name": "The Movable Feast", + "reviewer": "Michael Scarn", + "review_text": "It really was a feast" + } + ] + } + +$vectorSearch +~~~~~~~~~~~~~ + +The ``$vectorSearch`` aggregation stage performs an *approximate nearest neighbor* search +on a vector in the specified field. Your collection *must* have a +defined Atlas Vector Search index before you can perform a vector search on your data. + +.. tip:: + + To obtain the sample dataset used in the following example, see :ref:`csharp-get-started`. + To create the sample Atlas Vector Search index used in the following example, see + :atlas:`Create an Atlas Vector Search Index ` in the + Atlas manual. + +Consider the ``embedded_movies`` collection in the ``sample_mflix`` database. You +can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding`` +field of the documents in the collection. + +The following ``EmbeddedMovie`` class models the documents in the ``embedded_movies`` +collection: + +.. code-block:: csharp + + [BsonIgnoreExtraElements] + public class EmbeddedMovie + { + [BsonIgnoreIfDefault] + public string Title { get; set; } + + public string Plot { get; set; } + + [BsonElement("plot_embedding")] + public double[] Embedding { get; set; } + } + +The following example shows how to generate a ``$vectorSearch`` stage to search +the ``plot_embedding`` field using vector embeddings for the string ``"time travel"``: + +.. code-block:: csharp + + // Defines vector embeddings for the string "time travel" + var vector = new[] {-0.0016261312,-0.028070757,-0.011342932,-0.012775794,-0.0027440966,0.008683807,-0.02575152,-0.02020668,-0.010283281,-0.0041719596,0.021392956,0.028657231,-0.006634482,0.007490867,0.018593878,0.0038187427,0.029590257,-0.01451522,0.016061379,0.00008528442,-0.008943722,0.01627464,0.024311995,-0.025911469,0.00022596726,-0.008863748,0.008823762,-0.034921836,0.007910728,-0.01515501,0.035801545,-0.0035688248,-0.020299982,-0.03145631,-0.032256044,-0.028763862,-0.0071576433,-0.012769129,0.012322609,-0.006621153,0.010583182,0.024085402,-0.001623632,0.007864078,-0.021406285,0.002554159,0.012229307,-0.011762793,0.0051682983,0.0048484034,0.018087378,0.024325324,-0.037694257,-0.026537929,-0.008803768,-0.017767483,-0.012642504,-0.0062712682,0.0009771782,-0.010409906,0.017754154,-0.004671795,-0.030469967,0.008477209,-0.005218282,-0.0058480743,-0.020153364,-0.0032805866,0.004248601,0.0051449724,0.006791097,0.007650814,0.003458861,-0.0031223053,-0.01932697,-0.033615597,0.00745088,0.006321252,-0.0038154104,0.014555207,0.027697546,-0.02828402,0.0066711367,0.0077107945,0.01794076,0.011349596,-0.0052715978,0.014755142,-0.019753495,-0.011156326,0.011202978,0.022126047,0.00846388,0.030549942,-0.0041386373,0.018847128,-0.00033655585,0.024925126,-0.003555496,-0.019300312,0.010749794,0.0075308536,-0.018287312,-0.016567878,-0.012869096,-0.015528221,0.0078107617,-0.011156326,0.013522214,-0.020646535,-0.01211601,0.055928253,0.011596181,-0.017247654,0.0005939711,-0.026977783,-0.003942035,-0.009583511,-0.0055248477,-0.028737204,0.023179034,0.003995351,0.0219661,-0.008470545,0.023392297,0.010469886,-0.015874773,0.007890735,-0.009690142,-0.00024970944,0.012775794,0.0114762215,0.013422247,0.010429899,-0.03686786,-0.006717788,-0.027484283,0.011556195,-0.036068123,-0.013915418,-0.0016327957,0.0151016945,-0.020473259,0.004671795,-0.012555866,0.0209531,0.01982014,0.024485271,0.0105431955,-0.005178295,0.033162415,-0.013795458,0.007150979,0.010243294,0.005644808,0.017260984,-0.0045618312,0.0024725192,0.004305249,-0.008197301,0.0014203656,0.0018460588,0.005015015,-0.011142998,0.01439526,0.022965772,0.02552493,0.007757446,-0.0019726837,0.009503538,-0.032042783,0.008403899,-0.04609149,0.013808787,0.011749465,0.036388017,0.016314628,0.021939443,-0.0250051,-0.017354285,-0.012962398,0.00006107364,0.019113706,0.03081652,-0.018114036,-0.0084572155,0.009643491,-0.0034721901,0.0072642746,-0.0090636825,0.01642126,0.013428912,0.027724205,0.0071243206,-0.6858542,-0.031029783,-0.014595194,-0.011449563,0.017514233,0.01743426,0.009950057,0.0029706885,-0.015714826,-0.001806072,0.011856096,0.026444625,-0.0010663156,-0.006474535,0.0016161345,-0.020313311,0.0148351155,-0.0018393943,0.0057347785,0.018300641,-0.018647194,0.03345565,-0.008070676,0.0071443142,0.014301958,0.0044818576,0.003838736,-0.007350913,-0.024525259,-0.001142124,-0.018620536,0.017247654,0.007037683,0.010236629,0.06046009,0.0138887605,-0.012122675,0.037694257,0.0055081863,0.042492677,0.00021784494,-0.011656162,0.010276617,0.022325981,0.005984696,-0.009496873,0.013382261,-0.0010563189,0.0026507939,-0.041639622,0.008637156,0.026471283,-0.008403899,0.024858482,-0.00066686375,-0.0016252982,0.027590916,0.0051449724,0.0058647357,-0.008743787,-0.014968405,0.027724205,-0.011596181,0.0047650975,-0.015381602,0.0043718936,0.002159289,0.035908177,-0.008243952,-0.030443309,0.027564257,0.042625964,-0.0033688906,0.01843393,0.019087048,0.024578573,0.03268257,-0.015608194,-0.014128681,-0.0033538956,-0.0028757197,-0.004121976,-0.032389335,0.0034322033,0.058807302,0.010943064,-0.030523283,0.008903735,0.017500903,0.00871713,-0.0029406983,0.013995391,-0.03132302,-0.019660193,-0.00770413,-0.0038853872,0.0015894766,-0.0015294964,-0.006251275,-0.021099718,-0.010256623,-0.008863748,0.028550599,0.02020668,-0.0012962399,-0.003415542,-0.0022509254,0.0119360695,0.027590916,-0.046971202,-0.0015194997,-0.022405956,0.0016677842,-0.00018535563,-0.015421589,-0.031802863,0.03814744,0.0065411795,0.016567878,-0.015621523,0.022899127,-0.011076353,0.02841731,-0.002679118,-0.002342562,0.015341615,0.01804739,-0.020566562,-0.012989056,-0.002990682,0.01643459,0.00042527664,0.008243952,-0.013715484,-0.004835075,-0.009803439,0.03129636,-0.021432944,0.0012087687,-0.015741484,-0.0052016205,0.00080890034,-0.01755422,0.004811749,-0.017967418,-0.026684547,-0.014128681,0.0041386373,-0.013742141,-0.010056688,-0.013268964,-0.0110630235,-0.028337335,0.015981404,-0.00997005,-0.02424535,-0.013968734,-0.028310679,-0.027750863,-0.020699851,0.02235264,0.001057985,0.00081639783,-0.0099367285,0.013522214,-0.012016043,-0.00086471526,0.013568865,0.0019376953,-0.019020405,0.017460918,-0.023045745,0.008503866,0.0064678704,-0.011509543,0.018727167,-0.003372223,-0.0028690554,-0.0027024434,-0.011902748,-0.012182655,-0.015714826,-0.0098634185,0.00593138,0.018753825,0.0010146659,0.013029044,0.0003521757,-0.017620865,0.04102649,0.00552818,0.024485271,-0.009630162,-0.015608194,0.0006718621,-0.0008418062,0.012395918,0.0057980907,0.016221326,0.010616505,0.004838407,-0.012402583,0.019900113,-0.0034521967,0.000247002,-0.03153628,0.0011038032,-0.020819811,0.016234655,-0.00330058,-0.0032289368,0.00078973995,-0.021952773,-0.022459272,0.03118973,0.03673457,-0.021472929,0.0072109587,-0.015075036,0.004855068,-0.0008151483,0.0069643734,0.010023367,-0.010276617,-0.023019087,0.0068244194,-0.0012520878,-0.0015086699,0.022046074,-0.034148756,-0.0022192693,0.002427534,-0.0027124402,0.0060346797,0.015461575,0.0137554705,0.009230294,-0.009583511,0.032629255,0.015994733,-0.019167023,-0.009203636,0.03393549,-0.017274313,-0.012042701,-0.0009930064,0.026777849,-0.013582194,-0.0027590916,-0.017594207,-0.026804507,-0.0014236979,-0.022032745,0.0091236625,-0.0042419364,-0.00858384,-0.0033905501,-0.020739838,0.016821127,0.022539245,0.015381602,0.015141681,0.028817179,-0.019726837,-0.0051283115,-0.011489551,-0.013208984,-0.0047017853,-0.0072309524,0.01767418,0.0025658219,-0.010323267,0.012609182,-0.028097415,0.026871152,-0.010276617,0.021912785,0.0022542577,0.005124979,-0.0019710176,0.004518512,-0.040360045,0.010969722,-0.0031539614,-0.020366628,-0.025778178,-0.0110030435,-0.016221326,0.0036587953,0.016207997,0.003007343,-0.0032555948,0.0044052163,-0.022046074,-0.0008822095,-0.009363583,0.028230704,-0.024538586,0.0029840174,0.0016044717,-0.014181997,0.031349678,-0.014381931,-0.027750863,0.02613806,0.0004136138,-0.005748107,-0.01868718,-0.0010138329,0.0054348772,0.010703143,-0.003682121,0.0030856507,-0.004275259,-0.010403241,0.021113047,-0.022685863,-0.023032416,0.031429652,0.001792743,-0.005644808,-0.011842767,-0.04078657,-0.0026874484,0.06915057,-0.00056939584,-0.013995391,0.010703143,-0.013728813,-0.022939114,-0.015261642,-0.022485929,0.016807798,0.007964044,0.0144219175,0.016821127,0.0076241563,0.005461535,-0.013248971,0.015301628,0.0085171955,-0.004318578,0.011136333,-0.0059047225,-0.010249958,-0.018207338,0.024645219,0.021752838,0.0007614159,-0.013648839,0.01111634,-0.010503208,-0.0038487327,-0.008203966,-0.00397869,0.0029740208,0.008530525,0.005261601,0.01642126,-0.0038753906,-0.013222313,0.026537929,0.024671877,-0.043505676,0.014195326,0.024778508,0.0056914594,-0.025951454,0.017620865,-0.0021359634,0.008643821,0.021299653,0.0041686273,-0.009017031,0.04044002,0.024378639,-0.027777521,-0.014208655,0.0028623908,0.042119466,0.005801423,-0.028124074,-0.03129636,0.022139376,-0.022179363,-0.04067994,0.013688826,0.013328944,0.0046184794,-0.02828402,-0.0063412455,-0.0046184794,-0.011756129,-0.010383247,-0.0018543894,-0.0018593877,-0.00052024535,0.004815081,0.014781799,0.018007403,0.01306903,-0.020433271,0.009043689,0.033189073,-0.006844413,-0.019766824,-0.018767154,0.00533491,-0.0024575242,0.018727167,0.0058080875,-0.013835444,0.0040719924,0.004881726,0.012029372,0.005664801,0.03193615,0.0058047553,0.002695779,0.009290274,0.02361889,0.017834127,0.0049017193,-0.0036388019,0.010776452,-0.019793482,0.0067777685,-0.014208655,-0.024911797,0.002385881,0.0034988478,0.020899786,-0.0025858153,-0.011849431,0.033189073,-0.021312982,0.024965113,-0.014635181,0.014048708,-0.0035921505,-0.003347231,0.030869836,-0.0017161017,-0.0061346465,0.009203636,-0.025165047,0.0068510775,0.021499587,0.013782129,-0.0024475274,-0.0051149824,-0.024445284,0.006167969,0.0068844,-0.00076183246,0.030150073,-0.0055948244,-0.011162991,-0.02057989,-0.009703471,-0.020646535,0.008004031,0.0066378145,-0.019900113,-0.012169327,-0.01439526,0.0044252095,-0.004018677,0.014621852,-0.025085073,-0.013715484,-0.017980747,0.0071043274,0.011456228,-0.01010334,-0.0035321703,-0.03801415,-0.012036037,-0.0028990454,-0.05419549,-0.024058744,-0.024272008,0.015221654,0.027964126,0.03182952,-0.015354944,0.004855068,0.011522872,0.004771762,0.0027874154,0.023405626,0.0004242353,-0.03132302,0.007057676,0.008763781,-0.0027057757,0.023005757,-0.0071176565,-0.005238275,0.029110415,-0.010989714,0.013728813,-0.009630162,-0.029137073,-0.0049317093,-0.0008630492,-0.015248313,0.0043219104,-0.0055681667,-0.013175662,0.029723546,0.025098402,0.012849103,-0.0009996708,0.03118973,-0.0021709518,0.0260181,-0.020526575,0.028097415,-0.016141351,0.010509873,-0.022965772,0.002865723,0.0020493253,0.0020509914,-0.0041419696,-0.00039695262,0.017287642,0.0038987163,0.014795128,-0.014661839,-0.008950386,0.004431874,-0.009383577,0.0012604183,-0.023019087,0.0029273694,-0.033135757,0.009176978,-0.011023037,-0.002102641,0.02663123,-0.03849399,-0.0044152127,0.0004527676,-0.0026924468,0.02828402,0.017727496,0.035135098,0.02728435,-0.005348239,-0.001467017,-0.019766824,0.014715155,0.011982721,0.0045651635,0.023458943,-0.0010046692,-0.0031373003,-0.0006972704,0.0019043729,-0.018967088,-0.024311995,0.0011546199,0.007977373,-0.004755101,-0.010016702,-0.02780418,-0.004688456,0.013022379,-0.005484861,0.0017227661,-0.015394931,-0.028763862,-0.026684547,0.0030589928,-0.018513903,0.028363993,0.0044818576,-0.009270281,0.038920518,-0.016008062,0.0093902415,0.004815081,-0.021059733,0.01451522,-0.0051583014,0.023765508,-0.017874114,-0.016821127,-0.012522544,-0.0028390652,0.0040886537,0.020259995,-0.031216389,-0.014115352,-0.009176978,0.010303274,0.020313311,0.0064112223,-0.02235264,-0.022872468,0.0052449396,0.0005723116,0.0037321046,0.016807798,-0.018527232,-0.009303603,0.0024858483,-0.0012662497,-0.007110992,0.011976057,-0.007790768,-0.042999174,-0.006727785,-0.011829439,0.007024354,0.005278262,-0.017740825,-0.0041519664,0.0085905045,0.027750863,-0.038387362,0.024391968,0.00087721116,0.010509873,-0.00038508154,-0.006857742,0.0183273,-0.0037054466,0.015461575,0.0017394272,-0.0017944091,0.014181997,-0.0052682655,0.009023695,0.00719763,-0.013522214,0.0034422,0.014941746,-0.0016711164,-0.025298337,-0.017634194,0.0058714002,-0.005321581,0.017834127,0.0110630235,-0.03369557,0.029190388,-0.008943722,0.009363583,-0.0034222065,-0.026111402,-0.007037683,-0.006561173,0.02473852,-0.007084334,-0.010110005,-0.008577175,0.0030439978,-0.022712521,0.0054582027,-0.0012620845,-0.0011954397,-0.015741484,0.0129557345,-0.00042111133,0.00846388,0.008930393,0.016487904,0.010469886,-0.007917393,-0.011762793,-0.0214596,0.000917198,0.021672864,0.010269952,-0.007737452,-0.010243294,-0.0067244526,-0.015488233,-0.021552904,0.017127695,0.011109675,0.038067464,0.00871713,-0.0025591573,0.021312982,-0.006237946,0.034628596,-0.0045251767,0.008357248,0.020686522,0.0010696478,0.0076708077,0.03772091,-0.018700508,-0.0020676525,-0.008923728,-0.023298996,0.018233996,-0.010256623,0.0017860786,0.009796774,-0.00897038,-0.01269582,-0.018527232,0.009190307,-0.02372552,-0.042119466,0.008097334,-0.0066778013,-0.021046404,0.0019593548,0.011083017,-0.0016028056,0.012662497,-0.000059095124,0.0071043274,-0.014675168,0.024831824,-0.053582355,0.038387362,0.0005698124,0.015954746,0.021552904,0.031589597,-0.009230294,-0.0006147976,0.002625802,-0.011749465,-0.034362018,-0.0067844326,-0.018793812,0.011442899,-0.008743787,0.017474247,-0.021619547,0.01831397,-0.009037024,-0.0057247817,-0.02728435,0.010363255,0.034415334,-0.024032086,-0.0020126705,-0.0045518344,-0.019353628,-0.018340627,-0.03129636,-0.0034038792,-0.006321252,-0.0016161345,0.033642255,-0.000056075285,-0.005005019,0.004571828,-0.0024075406,-0.00010215386,0.0098634185,0.1980148,-0.003825407,-0.025191706,0.035161756,0.005358236,0.025111731,0.023485601,0.0023342315,-0.011882754,0.018287312,-0.0068910643,0.003912045,0.009243623,-0.001355387,-0.028603915,-0.012802451,-0.030150073,-0.014795128,-0.028630573,-0.0013487226,0.002667455,0.00985009,-0.0033972147,-0.021486258,0.009503538,-0.017847456,0.013062365,-0.014341944,0.005078328,0.025165047,-0.015594865,-0.025924796,-0.0018177348,0.010996379,-0.02993681,0.007324255,0.014475234,-0.028577257,0.005494857,0.00011725306,-0.013315615,0.015941417,0.009376912,0.0025158382,0.008743787,0.023832154,-0.008084005,-0.014195326,-0.008823762,0.0033455652,-0.032362677,-0.021552904,-0.0056081535,0.023298996,-0.025444955,0.0097301295,0.009736794,0.015274971,-0.0012937407,-0.018087378,-0.0039387033,0.008637156,-0.011189649,-0.00023846315,-0.011582852,0.0066411467,-0.018220667,0.0060846633,0.0376676,-0.002709108,0.0072776037,0.0034188742,-0.010249958,-0.0007747449,-0.00795738,-0.022192692,0.03910712,0.032122757,0.023898797,0.0076241563,-0.007397564,-0.003655463,0.011442899,-0.014115352,-0.00505167,-0.031163072,0.030336678,-0.006857742,-0.022259338,0.004048667,0.02072651,0.0030156737,-0.0042119464,0.00041861215,-0.005731446,0.011103011,0.013822115,0.021512916,0.009216965,-0.006537847,-0.027057758,-0.04054665,0.010403241,-0.0056281467,-0.005701456,-0.002709108,-0.00745088,-0.0024841821,0.009356919,-0.022659205,0.004061996,-0.013175662,0.017074378,-0.006141311,-0.014541878,0.02993681,-0.00028448965,-0.025271678,0.011689484,-0.014528549,0.004398552,-0.017274313,0.0045751603,0.012455898,0.004121976,-0.025458284,-0.006744446,0.011822774,-0.015035049,-0.03257594,0.014675168,-0.0039187097,0.019726837,-0.0047251107,0.0022825818,0.011829439,0.005391558,-0.016781142,-0.0058747325,0.010309938,-0.013049036,0.01186276,-0.0011246296,0.0062112883,0.0028190718,-0.021739509,0.009883412,-0.0073175905,-0.012715813,-0.017181009,-0.016607866,-0.042492677,-0.0014478565,-0.01794076,0.012302616,-0.015194997,-0.04433207,-0.020606548,0.009696807,0.010303274,-0.01694109,-0.004018677,0.019353628,-0.001991011,0.000058938927,0.010536531,-0.17274313,0.010143327,0.014235313,-0.024152048,0.025684876,-0.0012504216,0.036601283,-0.003698782,0.0007310093,0.004165295,-0.0029157067,0.017101036,-0.046891227,-0.017460918,0.022965772,0.020233337,-0.024072073,0.017220996,0.009370248,0.0010363255,0.0194336,-0.019606877,0.01818068,-0.020819811,0.007410893,0.0019326969,0.017887443,0.006651143,0.00067394477,-0.011889419,-0.025058415,-0.008543854,0.021579562,0.0047484366,0.014062037,0.0075508473,-0.009510202,-0.009143656,0.0046817916,0.013982063,-0.0027990784,0.011782787,0.014541878,-0.015701497,-0.029350337,0.021979429,0.01332228,-0.026244693,-0.0123492675,-0.003895384,0.0071576433,-0.035454992,-0.00046984528,0.0033522295,0.039347045,0.0005119148,0.00476843,-0.012995721,0.0024042083,-0.006931051,-0.014461905,-0.0127558,0.0034555288,-0.0074842023,-0.030256703,-0.007057676,-0.00807734,0.007804097,-0.006957709,0.017181009,-0.034575284,-0.008603834,-0.005008351,-0.015834786,0.02943031,0.016861115,-0.0050849924,0.014235313,0.0051449724,0.0025924798,-0.0025741523,0.04289254,-0.002104307,0.012969063,-0.008310596,0.00423194,0.0074975314,0.0018810473,-0.014248641,-0.024725191,0.0151016945,-0.017527562,0.0018727167,0.0002830318,0.015168339,0.0144219175,-0.004048667,-0.004358565,0.011836103,-0.010343261,-0.005911387,0.0022825818,0.0073175905,0.00403867,0.013188991,0.03334902,0.006111321,0.008597169,0.030123414,-0.015474904,0.0017877447,-0.024551915,0.013155668,0.023525586,-0.0255116,0.017220996,0.004358565,-0.00934359,0.0099967085,0.011162991,0.03092315,-0.021046404,-0.015514892,0.0011946067,-0.01816735,0.010876419,-0.10124666,-0.03550831,0.0056348112,0.013942076,0.005951374,0.020419942,-0.006857742,-0.020873128,-0.021259667,0.0137554705,0.0057880944,-0.029163731,-0.018767154,-0.021392956,0.030896494,-0.005494857,-0.0027307675,-0.006801094,-0.014821786,0.021392956,-0.0018110704,-0.0018843795,-0.012362596,-0.0072176233,-0.017194338,-0.018713837,-0.024272008,0.03801415,0.00015880188,0.0044951867,-0.028630573,-0.0014070367,-0.00916365,-0.026537929,-0.009576847,-0.013995391,-0.0077107945,0.0050016865,0.00578143,-0.04467862,0.008363913,0.010136662,-0.0006268769,-0.006591163,0.015341615,-0.027377652,-0.00093136,0.029243704,-0.020886457,-0.01041657,-0.02424535,0.005291591,-0.02980352,-0.009190307,0.019460259,-0.0041286405,0.004801752,0.0011787785,-0.001257086,-0.011216307,-0.013395589,0.00088137644,-0.0051616337,0.03876057,-0.0033455652,0.00075850025,-0.006951045,-0.0062112883,0.018140694,-0.006351242,-0.008263946,0.018154023,-0.012189319,0.0075508473,-0.044358727,-0.0040153447,0.0093302615,-0.010636497,0.032789204,-0.005264933,-0.014235313,-0.018393943,0.007297597,-0.016114693,0.015021721,0.020033404,0.0137688,0.0011046362,0.010616505,-0.0039453674,0.012109346,0.021099718,-0.0072842683,-0.019153694,-0.003768759,0.039320387,-0.006747778,-0.0016852784,0.018154023,0.0010963057,-0.015035049,-0.021033075,-0.04345236,0.017287642,0.016341286,-0.008610498,0.00236922,0.009290274,0.028950468,-0.014475234,-0.0035654926,0.015434918,-0.03372223,0.004501851,-0.012929076,-0.008483873,-0.0044685286,-0.0102233,0.01615468,0.0022792495,0.010876419,-0.0059647025,0.01895376,-0.0069976957,-0.0042952523,0.017207667,-0.00036133936,0.0085905045,0.008084005,0.03129636,-0.016994404,-0.014915089,0.020100048,-0.012009379,-0.006684466,0.01306903,0.00015765642,-0.00530492,0.0005277429,0.015421589,0.015528221,0.032202728,-0.003485519,-0.0014286962,0.033908837,0.001367883,0.010509873,0.025271678,-0.020993087,0.019846799,0.006897729,-0.010216636,-0.00725761,0.01818068,-0.028443968,-0.011242964,-0.014435247,-0.013688826,0.006101324,-0.0022509254,0.013848773,-0.0019077052,0.017181009,0.03422873,0.005324913,-0.0035188415,0.014128681,-0.004898387,0.005038341,0.0012320944,-0.005561502,-0.017847456,0.0008538855,-0.0047884234,0.011849431,0.015421589,-0.013942076,0.0029790192,-0.013702155,0.0001199605,-0.024431955,0.019926772,0.022179363,-0.016487904,-0.03964028,0.0050849924,0.017487574,0.022792496,0.0012504216,0.004048667,-0.00997005,0.0076041627,-0.014328616,-0.020259995,0.0005598157,-0.010469886,0.0016852784,0.01716768,-0.008990373,-0.001987679,0.026417969,0.023792166,0.0046917885,-0.0071909656,-0.00032051947,-0.023259008,-0.009170313,0.02071318,-0.03156294,-0.030869836,-0.006324584,0.013795458,-0.00047151142,0.016874444,0.00947688,0.00985009,-0.029883493,0.024205362,-0.013522214,-0.015075036,-0.030603256,0.029270362,0.010503208,0.021539574,0.01743426,-0.023898797,0.022019416,-0.0068777353,0.027857494,-0.021259667,0.0025758184,0.006197959,0.006447877,-0.00025200035,-0.004941706,-0.021246338,-0.005504854,-0.008390571,-0.0097301295,0.027244363,-0.04446536,0.05216949,0.010243294,-0.016008062,0.0122493,-0.0199401,0.009077012,0.019753495,0.006431216,-0.037960835,-0.027377652,0.016381273,-0.0038620618,0.022512587,-0.010996379,-0.0015211658,-0.0102233,0.007071005,0.008230623,-0.009490209,-0.010083347,0.024431955,0.002427534,0.02828402,0.0035721571,-0.022192692,-0.011882754,0.010056688,0.0011904413,-0.01426197,-0.017500903,-0.00010985966,0.005591492,-0.0077707744,-0.012049366,0.011869425,0.00858384,-0.024698535,-0.030283362,0.020140035,0.011949399,-0.013968734,0.042732596,-0.011649498,-0.011982721,-0.016967745,-0.0060913274,-0.007130985,-0.013109017,-0.009710136}; + + // Specifies that the vector search will consider the 150 nearest neighbors + // in the specified index + var options = new VectorSearchOptions() + { + IndexName = "vector_index", + NumberOfCandidates = 150 + }; + + // Builds aggregation pipeline and specifies that the $vectorSearch stage + // returns 10 results + var results = queryableCollection + .VectorSearch(m => m.Embedding, vector, 10, options) + .Select(m => new { m.Title, m.Plot }); + +The results of the preceding example contain the following documents: + +.. code-block:: json + + { "_id" : ObjectId("573a13a0f29313caabd04a4f"), "plot" : "A reporter, learning of time travelers visiting 20th century disasters, tries to change the history they know by averting upcoming disasters.", "title" : "Thrill Seekers" } + { "_id" : ObjectId("573a13d8f29313caabda6557"), "plot" : "At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.", "title" : "About Time" } + { "_id" : ObjectId("573a13a5f29313caabd13b4b"), "plot" : "Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.", "title" : "The Time Machine" } + { "_id" : ObjectId("573a13aef29313caabd2e2d7"), "plot" : "After using his mother's newly built time machine, Dolf gets stuck involuntary in the year 1212. He ends up in a children's crusade where he confronts his new friends with modern techniques...", "title" : "Crusade in Jeans" } + { "_id" : ObjectId("573a1399f29313caabceec0e"), "plot" : "An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.", "title" : "Timecop" } + { "_id" : ObjectId("573a1399f29313caabcee36f"), "plot" : "A time-travel experiment in which a robot probe is sent from the year 2073 to the year 1973 goes terribly wrong thrusting one of the project scientists, a man named Nicholas Sinclair into a...", "title" : "A.P.E.X." } + { "_id" : ObjectId("573a13c6f29313caabd715d3"), "plot" : "Agent J travels in time to M.I.B.'s early days in 1969 to stop an alien from assassinating his friend Agent K and changing history.", "title" : "Men in Black 3" } + { "_id" : ObjectId("573a13d4f29313caabd98c13"), "plot" : "Bound by a shared destiny, a teen bursting with scientific curiosity and a former boy-genius inventor embark on a mission to unearth the secrets of a place somewhere in time and space that exists in their collective memory.", "title" : "Tomorrowland" } + { "_id" : ObjectId("573a13b6f29313caabd477fa"), "plot" : "With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.", "title" : "Love Story 2050" } + { "_id" : ObjectId("573a13e5f29313caabdc40c9"), "plot" : "A dimension-traveling wizard gets stuck in the 21st century because cell-phone radiation interferes with his magic. With his home world on the brink of war, he seeks help from a jaded ...", "title" : "The Portal" } + +For more information about Atlas Vector Search, Atlas Vector Search indexes, and how +to incorporate them into your application, see :atlas:`Atlas Vector Search Overview ` +in the Atlas manual. For more examples about running Atlas Vector Search queries using the +{+driver-short+}, see :atlas:`Run Vector Search Queries ` +in the Atlas manual and select :guilabel:`C#` from the language dropdown. + +Bitwise Operators +~~~~~~~~~~~~~~~~~ + +This section describes the :wikipedia:`bitwise operators ` +supported by the {+driver-short+} that you can use in an aggregation pipeline. +You can use multiple bitwise operators in the same +stage. The following guidelines apply when using bitwise operators: + +- All operands must be of type ``int`` or ``long``. + +- ``$bitAnd``, ``$bitOr``, and ``$bitXor`` take two or more operands. ``$bitNot`` takes one operand. + +- Bitwise operations are evaluated from left to right. + +The examples in this section use the following documents in a collection called +``ingredients``: + +.. code-block:: json + + { "_id" : 1, "name" : "watermelon", "is_available" : 1, "is_cheap" : 1 }, + { "_id" : 2, "name" : "onions", "is_available" : 1, "is_cheap" : 0 }, + { "_id" : 3, "name" : "eggs", "is_available" : 0, "is_cheap" : 0 }, + { "_id" : 4, "name" : "potatoes", "is_available" : 1, "is_cheap" : 1 }, + { "_id" : 5, "name" : "pasta", "is_available" : 0, "is_cheap" : 1 }, + { "_id" : 6, "name" : "cheese", "is_available" : 1 } + +The ``"is_available"`` field represents if an ingredient is available. If this +field has a value of ``0``, the ingredient is not available. If it has a value +of ``1``, the ingredient is available. + +The ``"is_cheap"`` field represents if an ingredient is cheap. If this field has +a value of ``0``, the ingredient is not cheap. If it has a value of ``1``, the +ingredient is cheap. + +The following ``Ingredient`` class models the documents in the ``ingredients`` +collection: + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-ingredient-model + :end-before: end-ingredient-model + +.. note:: Missing or Undefined Operands + + If the operands you pass to any bitwise operator are of type `nullable `__ + ``int`` or ``long`` and contain a missing or undefined value, the entire expression + evaluates to ``null``. If the operands are of type non-nullable ``int`` or + ``long`` and contain a missing or undefined value, the {+driver-short+} will + throw an error. + +$bitAnd ++++++++ + +The ``$bitAnd`` aggregation operator performs a bitwise AND operation on the given +arguments. You can use the ``$bitAnd`` operator by connecting two or more +clauses with a ``&`` character. + +The following example shows how to create a ``$bitAnd`` stage by using LINQ. The +code retrieves the document in which the ``Name`` field has the +value ``"watermelon"``. It then performs a bitwise AND operation on the values of the +``IsAvailable`` and ``IsCheap`` fields in this document. + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitAnd-example + :end-before: end-bitAnd-example + +The preceding code returns ``1``, the result of the AND operation on the values +of the ``IsAvailable`` field (``1``) and the ``IsCheap`` field (``1``). + +The following example performs the same bitwise AND operation on all +documents in the collection: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitAnd-collection-example + :end-before: end-bitAnd-collection-example + + .. output:: + :language: json + :visible: false + + 1 + 0 + 0 + 1 + 0 + null + +The ``null`` result comes from the document where the ``Name`` field +has the value of ``"cheese"``. This document is missing an ``IsCheap`` field, so +the expression evaluates to ``null``. + +$bitOr +++++++ + +The ``$bitOr`` aggregation operator performs a bitwise OR operation on the given +arguments. You can use the ``$bitOr`` operator by connecting two or more +clauses with a ``|`` character. + +The following example shows how to create a ``$bitOr`` stage by using LINQ. The +code retrieves the document in which the ``Name`` field has the +value ``"onions"``. It then performs a bitwise OR operation on the values of the +``IsAvailable`` and ``IsCheap`` fields in this document. + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitOr-example + :end-before: end-bitOr-example + +The preceding code returns ``1``, the result of the OR operation on the values +of the ``IsAvailable`` field (``1``) and the ``IsCheap`` field (``0``). + +$bitNot ++++++++ + +The ``$bitNot`` aggregation operator performs a bitwise NOT operation on the given +argument. You can use the ``$bitNot`` operator by preceding an +operand with a ``~`` character. ``$bitNot`` only takes one argument. The +following example shows how to create a ``$bitNot`` stage by using LINQ: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitNot-example + :end-before: end-bitNot-example + + .. output:: + :language: json + :visible: false + + -2 + -1 + -1 + -2 + -2 + null + +$bitXor ++++++++ + +The ``$bitXor`` aggregation operator performs a bitwise XOR operation on the given +arguments. You can use the ``$bitXor`` operator by connecting two or more +clauses with a ``^`` character. + +The following example shows how to create a ``$bitXor`` stage by using LINQ. The +code retrieves the documents in which the ``Name`` field has +the value ``"watermelon"`` or ``"onions"``. It then performs a bitwise XOR +operation on the values of the ``IsAvailable`` and ``IsCheap`` fields in these +documents. + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitXor-example + :end-before: end-bitXor-example + +The result contains the following values: + +.. code-block:: json + + 0 + 1 + + +Unsupported Aggregation Stages +------------------------------ + +The {+driver-long+} implementation of LINQ does not support the following +aggregation stages: + +- ``$redact`` +- ``$geoNear`` +- ``$out`` + +To learn how to create an aggregation pipeline with the ``$out`` stage by using Builders, see +the :ref:`` section. + +Supported Methods +----------------- + +The following are some methods supported by the {+driver-long+} implementation of LINQ: + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - Method Name + - Description + + * - ``Any`` + - Determines if any documents match the specified criteria + + * - ``Average`` + - Calculates the average of the specified fields + + * - ``Count`` + - Returns an ``Int32`` that represents the number of documents that match the specified criteria + + * - ``LongCount`` + - Returns an ``Int64`` that represents the number of documents that match the specified criteria + + * - ``DateFromString`` + - Converts a ``string`` to a ``DateTime`` object + + * - ``Distinct`` + - Returns distinct documents that match the specified criteria + + * - ``DistinctMany`` + - Returns distinct documents from an array that match the specified criteria + + * - ``Exists`` + - Tests whether a field exists + + * - ``First`` + - Returns the first matching document, and throws an exception if none are found + + * - ``FirstOrDefault`` + - Returns the first matching document, or ``null`` if none are found + + * - ``GroupBy`` + - Groups documents based on specified criteria + + * - ``GroupJoin`` + - Performs a left outer join to another collection in the same database + + * - ``IsMissing`` + - Returns ``true`` if a field is missing and false otherwies + + * - ``IsNullOrMissing`` + - Returns ``true`` if a field is null or missing and false otherwise + + * - ``Max`` + - Returns the document with the maximum specified value + + * - ``OfType`` + - Returns documents that match the specified type + + * - ``OrderBy``, ``OrderByDescending`` + - Returns results in a specified sort order + + * - ``ThenBy``, ``ThenByDescending`` + - Allows a secondary sort to be specified + + * - ``Select`` + - Selects documents based on specified criteria + + * - ``SelectMany`` + - Projects each element of a sequence and combines the resulting sequences into one document + + * - ``Single`` + - Returns the only matching document, and throws an exception if there is not exactly one document + + * - ``SingleOrDefault`` + - Returns a single matching document or ``null`` if no documents match + + * - ``Skip`` + - Skips over a specified number of documents and returns the rest of the results + + * - ``Sum`` + - Returns the sum of the values in a specified field + + * - ``Take`` + - Specifies the number of results to return + + * - ``Where`` + - Returns all documents that match your specified criteria + +View Translated Queries +----------------------- + +When you run a LINQ query, the {+driver-short+} automatically translates your +query into an aggregation pipeline written with the {+query-api+}. You can view +the translated query by using the ``ToString()`` method or the +``LoggedStages`` property. + +To see the translated query for **non-scalar operations**, use the ``ToString()`` +method. Non-scalar operations are operations that return a query object, such +as: + +- ``Where`` +- ``Select`` +- ``SelectMany`` +- ``GroupJoin`` + +The following example calls the ``ToString()`` method on a LINQ query and prints +the translated query: + +.. io-code-block:: + + .. input:: + :language: csharp + + var queryableCollection = _restaurantsCollection.AsQueryable(); + var query = queryableCollection + .Where(r => r.Name == "The Movable Feast"); + + var queryTranslated = query.ToString(); + Console.WriteLine(queryTranslated); + + .. output:: + + sample_restaurants.restaurants.Aggregate([{ "$match" : { "name" : "The Movable Feast" } }]) + +To get the translated query for **scalar operations** use the ``LoggedStages`` +property. Scalar operations are operations that return a scalar result rather than a +query object, such as: + +- ``First`` +- ``Sum`` +- ``Count`` +- ``Min`` +- ``Max`` + +To get a translated query with the ``LoggedStages`` property, you must save +the translated query directly after it is executed, and before executing any +other queries with the same queryable object. + +The following example uses the ``LoggedStages`` property on a LINQ query that +uses a scalar operation, then prints the translated query: + +.. io-code-block:: + + .. input:: + :language: csharp + :emphasize-lines: 6 + + + var queryableCollection = _restaurantsCollection.AsQueryable(); + var query = queryableCollection + .Where(r => r.Name == "The Movable Feast"); + + var result = query.FirstOrDefault(); + var queryTranslated = query.LoggedStages; + + Console.WriteLine(queryTranslated.ToJson()); + + .. output:: + + [{ "$match" : { "name" : "The Movable Feast" } }, { "$limit" : NumberLong(1) }] + +.. important:: + + ``LoggedStages`` is not thread-safe. Executing a query and accessing the + associated ``LoggedStages`` property from multiple threads might have + non-deterministic results. + +Troubleshooting +--------------- + +.. include:: /includes/troubleshooting/unsupported-filter-expression.rst \ No newline at end of file diff --git a/source/aggregation/linq.txt b/source/aggregation/linq.txt deleted file mode 100644 index a66598c0..00000000 --- a/source/aggregation/linq.txt +++ /dev/null @@ -1,1069 +0,0 @@ -.. _csharp-linq: - -==== -LINQ -==== - -.. contents:: On this page - :local: - :backlinks: none - :depth: 3 - :class: singlecol - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, query, aggregation - - -Overview --------- - -.. include:: /includes/linq-vs-builders.rst - -In this guide you can learn how to use -`LINQ `__ -with the {+driver-long+}. LINQ allows you to construct queries against -strongly typed collections of objects by using language keywords and operators. -The {+driver-short+} automatically translates LINQ queries into -:manual:`aggregation operations `. - -.. important:: - - LINQ3 is the only LINQ provider available in the {+driver-long+}. If you have - manually configured your project to use LINQ2, it will not compile. - -The examples in this guide use the ``restaurants`` collection -in the ``sample_restaurants`` database provided in the :atlas:`Atlas sample datasets `. -To learn how to create a free MongoDB Atlas cluster and load the sample datasets, -see the :ref:``. - -The following ``Restaurant``, ``Address`` and ``GradeEntry`` classes model the -documents in this collection: - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-restaurant-model - :end-before: end-restaurant-model - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-address-model - :end-before: end-address-model - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-grade-model - :end-before: end-grade-model - -.. include:: /includes/convention-pack-note.rst - -.. _csharp-linq-queryable: - -Make A Collection Queryable ---------------------------- - -To use LINQ to query your collection, you must first create an -an `IQueryable -`__ -object that links to the collection. To create the object, use the ``AsQueryable()`` method -as follows: - -.. code-block:: csharp - :emphasize-lines: 3 - - var restaurantsDatabase = client.GetDatabase("sample_restaurants"); - var restaurantsCollection = restaurantsDatabase.GetCollection("restaurants"); - var queryableCollection = restaurantsCollection.AsQueryable(); - -Once you have the queryable object, you can compose a query using -**method syntax**. Some pipeline stages also support **query comprehension syntax**, -which resembles SQL query syntax. - -Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see -how to compose a query using LINQ: - -.. tabs:: - - .. tab:: Method Syntax - :tabid: method-syntax - - .. code-block:: csharp - - var query = queryableCollection - .Where(r => r.Name == "The Movable Feast") - .Select(r => new { r.Name, r.Address }); - - .. tab:: Query Syntax - :tabid: query-syntax - - .. code-block:: csharp - - var query = from r in queryableCollection - where r.Name == "The Movable Feast" - select new { r.Name, r.Address }; - -You can print the results of the preceding example as follows: - -.. io-code-block:: - - .. input:: - :language: csharp - - foreach (var restaurant in query) - { - Console.WriteLine(restaurant.ToJson()); - } - - .. output:: - - { "name" : "The Movable Feast", "address" : { "building" : "284", "coord" : [-73.982923900000003, 40.6580753], "street" : "Prospect Park West", "zipcode" : "11215" } } - -.. tip:: Accessing Query Results - - You can also access the results of your query by using the ``ToList()`` or - ``ToCursor()`` methods: - - .. code-block:: csharp - - var results = query.ToList(); - - .. code-block:: csharp - - var results = query.ToCursor(); - - -Supported Aggregation Stages ----------------------------- - -You can use LINQ to create an :ref:`aggregation pipeline `. -The {+driver-short+} automatically translates each LINQ statement into the corresponding -aggregation pipeline stages. In this section you can learn which -aggregation pipeline stages are supported. - -To learn more about the aggregation pipeline stages, see the -:ref:`aggregation-pipeline-operator-reference` page in the server manual. - -$project -~~~~~~~~ - -The ``$project`` aggregation stage returns a document containing only the specified -fields. - -Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate a ``$project`` stage using LINQ: - -.. tabs:: - - .. tab:: Method Syntax - :tabid: method-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = queryableCollection - .Select(r => new { r.Name, r.Address }); - - .. tab:: Query Syntax - :tabid: query-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = from r in queryableCollection - select new { r.Name, r.Address }; - -The result of the preceding example contains the following document: - -.. code-block:: json - - { "name" : "The Movable Feast", "address" : { "building" : "284", "coord" : [-73.982923900000003, 40.6580753], "street" : "Prospect Park West", "zipcode" : "11215" } } - -.. note:: Excluding the ``_id`` Field - - If you don't include the ``_id`` field in your LINQ projection, the {+driver-short+} - automatically excludes it from the results. - -$match -~~~~~~ - -The ``$match`` aggregation stage returns the documents that match a specified -criteria. - -Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate a ``$match`` stage using LINQ: - -.. tabs:: - - .. tab:: Method Syntax - :tabid: method-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = queryableCollection - .Where(r => r.Name == "The Movable Feast"); - - .. tab:: Query Syntax - :tabid: query-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = from r in queryableCollection - where r.Name == "The Movable Feast" - select r; - -The result of the preceding example contains the following document: - -.. code-block:: json - - // Results Truncated - - { "_id" : ObjectId(...), "name" : "The Movable Feast", "restaurant_id" : "40361606", "cuisine" : "American", "address" : {...}, "borough" : "Brooklyn", "grades" : [...] } - -$limit -~~~~~~ - -The ``$limit`` aggregation stage limits the number of documents returned by the -query. The following example shows how to generate a ``$limit`` stage using LINQ: - -.. code-block:: csharp - :emphasize-lines: 4 - - var query = queryableCollection - .Where(r => r.Cuisine == "Italian") - .Select(r => new {r.Name, r.Cuisine}) - .Take(5); - -The result of the preceding example contains the following documents: - -.. code-block:: json - - { "name" : "Philadelhia Grille Express", "cuisine" : "Italian" } - { "name" : "Isle Of Capri Resturant", "cuisine" : "Italian" } - { "name" : "Marchis Restaurant", "cuisine" : "Italian" } - { "name" : "Crystal Room", "cuisine" : "Italian" } - { "name" : "Forlinis Restaurant", "cuisine" : "Italian" } - -$sample -~~~~~~~ - -The ``$sample`` aggregation stage returns a random sample of documents from a -collection. The following example shows how to generate a ``$sample`` stage by using -LINQ: - -.. code-block:: csharp - :emphasize-lines: 4 - - var query = queryableCollection - .Aggregate() - .Sample(4) - .ToList(); - -The result of the preceding example contains the following documents: - -.. code-block:: json - - // Results Truncated - - { "name" : "Von Dolhens", "cuisine" : "Ice Cream, Gelato, Yogurt, Ices" } - { "name" : "New York Mercantile Exchange", "cuisine" : "American" } - { "name" : "Michaelangelo's Restaurant", "cuisine" : "Italian" } - { "name" : "Charlie Palmer Steak", "cuisine" : "American" } - -$skip -~~~~~ - -The ``$skip`` aggregation stage skips over a specified number of documents returned -by a query, then returns the rest of the results. The following example shows how to generate -a ``$skip`` stage using LINQ: - -.. code-block:: csharp - :emphasize-lines: 4 - - var query = queryableCollection - .Where(r => r.Cuisine == "Italian") - .Select(r => new {r.Name, r.Cuisine}) - .Skip(2); - -The preceding example skips the first two restaurants that match the criteria, and -returns the rest. The result contains the following documents: - -.. code-block:: json - - // Results Truncated - - { "name" : "Marchis Restaurant", "cuisine" : "Italian" } - { "name" : "Crystal Room", "cuisine" : "Italian" } - { "name" : "Forlinis Restaurant", "cuisine" : "Italian" } - ... - -$unwind -~~~~~~~ - -The ``$unwind`` aggregation stage deconstructs a specified array field and returns -a document for each element in that array. - -Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate an ``$unwind`` stage using LINQ: - -.. tabs:: - - .. tab:: Method Syntax - :tabid: method-syntax - - .. code-block:: csharp - :emphasize-lines: 3 - - var query = queryableCollection - .Where(r => r.Name == "The Movable Feast") - .SelectMany(r => r.Grades); - - .. tab:: Query Syntax - :tabid: query-syntax - - .. code-block:: csharp - :emphasize-lines: 3 - - var query = from r in queryableCollection - where r.Name == "The Movable Feast" - from grade in r.Grades - select grade; - -The query in the preceding example finds the document where the ``Name`` field -has the value "The Movable Feast." Then, for each element in this document's -``Grades`` array, the query returns a new document. The result contains the -following documents: - -.. code-block:: json - - { "date" : ISODate("2014-11-19T00:00:00Z"), "grade" : "A", "score" : 11 } - { "date" : ISODate("2013-11-14T00:00:00Z"), "grade" : "A", "score" : 2 } - { "date" : ISODate("2012-12-05T00:00:00Z"), "grade" : "A", "score" : 13 } - { "date" : ISODate("2012-05-17T00:00:00Z"), "grade" : "A", "score" : 11 } - -Nested Statements -+++++++++++++++++ - -You can chain or nest ``Select`` and ``SelectMany`` statements to unwind nested -arrays. Consider a collection that contains documents with a **new** schema. These -documents contain a ``restaurants`` field, which holds an array of documents -represented by the ``Restaurant`` class. The documents within the array each have -a ``grades`` field that holds an array of documents represented by -the ``Grade`` class. The following code is an example of a single document in -this collection: - -.. code-block:: json - - { - "_id": { "$oid": ... }, - "restaurants": [ - { - "_id": { ... } , - "address": { ... }, - "name": "Tov Kosher Kitchen", - "grades": [ - { - "date" : ISODate("2014-11-24T00:00:00Z"), - "grade" : "Z", - "score" : 20.0 - }, - { - "date" : ISODate("2013-01-17T00:00:00Z"), - "grade" : "A", - "score" : 13.0 - } - ] - ... - }, - { - "_id": { ... } , - "address": { ... }, - "name": "Harriet's Kitchen", - "grades": [ - { - "date" : ISODate("2014-04-19T00:00:00Z"), - "grade" : "B", - "score" : 12.0 - } - ], - ... - }, - ... - ] - } - -You can nest ``SelectMany`` statements within ``SelectMany`` or ``Select`` -statements. The following example nests a ``SelectMany`` statement within a -``Select`` statement to retrieve an array from each document in the collection. -Each array holds all grade objects from all restaurants in each document. - -.. io-code-block:: - :copyable: true - - .. input:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :start-after: start-nested-SelectMany - :end-before: end-nested-SelectMany - - .. output:: - :visible: false - :language: json - - // output for first document in collection - [ - { "date" : ISODate("2014-11-24T00:00:00Z"), - "grade" : "Z", - "score" : 20.0 - }, - { "date" : ISODate("2013-01-17T00:00:00Z"), - "grade" : "A", - "score" : 13.0 - }, - { - "date" : ISODate("2014-04-19T00:00:00Z"), - "grade" : "B", - "score" : 12.0 - }, - ... - ], - // output for second document in collection - [ - ... - ] - -$group -~~~~~~ - -The ``$group`` aggregation stage separates documents into groups according to -the criteria you specify. - -Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate an ``$group`` stage using LINQ: - -.. tabs:: - - .. tab:: Method Syntax - :tabid: method-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = queryableCollection - .GroupBy(r => r.Cuisine) - .Select(g => new { Cuisine = g.Key, Count = g.Count() }); - - .. tab:: Query Syntax - :tabid: query-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = from r in queryableCollection - group r by r.Cuisine into g - select new {Cuisine = g.Key, Count = g.Count()}; - -The preceding example groups each document by the value in its ``Cuisine`` field, -then counts how many documents have each ``Cuisine`` value. The result contains -the following documents: - -.. code-block:: json - - // Results Truncated - - { "cuisine" : "Caribbean", "count" : 657 } - { "cuisine" : "Café/Coffee/Tea", "count" : 1214 } - { "cuisine" : "Iranian", "count" : 2 } - { "cuisine" : "Nuts/Confectionary", "count" : 6 } - { "cuisine" : "Middle Eastern", "count" : 168 } - ... - -.. note:: Result Order - - The preceding queries don't always return results in the same order. Running - this example may return the results in a different order than shown above. - -$sort -~~~~~ - -The ``$sort`` aggregation stage returns the results of your query in the order -that you specify. - -Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate an ``$sort`` stage using LINQ: - -.. tabs:: - - .. tab:: Method Syntax - :tabid: method-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = queryableCollection - .OrderBy(r => r.Name) - .ThenByDescending(r => r.RestaurantId); - - .. tab:: Query Syntax - :tabid: query-syntax - - .. code-block:: csharp - :emphasize-lines: 2 - - var query = from r in queryableCollection - orderby r.Name, r.RestaurantId descending - select r; - -The preceding example returns the query results sorted alphabetically by the -``Name`` field, with a secondary descending sort on the ``RestaurantId`` field. -The following is a subset of the documents contained in the returned results: - -.. code-block:: json - - // Results Truncated - - ... - { "_id" : ObjectId(...), "name" : "Aba Turkish Restaurant", "restaurant_id" : "41548686", "cuisine" : "Turkish", "address" : {...}, "borough" : "Manhattan", "grades" : [...] } - { "_id" : ObjectId(...), "name" : "Abace Sushi", "restaurant_id" : "50006214", "cuisine" : "Japanese", "address" : { ... }, "borough" : "Manhattan", "grades" : [...] } - { "_id" : ObjectId(...), "name" : "Abacky Potluck", "restaurant_id" : "50011222", "cuisine" : "Asian", "address" : { ... }, "borough" : "Manhattan", "grades" : [...] } - { "_id" : ObjectId(...), "name" : "Abaleh", "restaurant_id" : "50009096", "cuisine" : "Mediterranean", "address" : { ... }, "borough" : "Manhattan", "grades" : [...] } - ... - -$lookup -~~~~~~~ - -The ``$lookup`` aggregation stage joins documents from one collection to documents -from another collection in the same database. The ``$lookup`` stage adds a new -array field to each input document. The new array field contains the matching -documents from the "joined" collection. - -.. note:: - - To perform a lookup, you must make both collections queryable by using the - ``AsQueryable()`` method. - - To learn how to make a collection queryable, see :ref:`csharp-linq-queryable`. - -Consider a second collection in the ``sample_restaurants`` database called -``reviews`` that has restaurant reviews. You can join documents from that collection -to documents with the same ``name`` value in the ``restaurants`` collection using -the ``$lookup`` stage. - -The following ``Review`` class models the documents in the ``reviews`` collection: - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-review-model - :end-before: end-review-model - -Select the :guilabel:`Method Syntax` or :guilabel:`Query Syntax` tab to see how -to generate a ``$lookup`` stage by using LINQ: - -.. tabs:: - - .. tab:: Method Syntax - :tabid: method-syntax - - .. code-block:: csharp - - var query = queryableCollection - .GroupJoin(reviewCollection, - restaurant => restaurant.Name, - review => review.RestaurantName, - (restaurant, reviews) => - new { Restaurant = restaurant, Reviews = reviews } - ); - - .. tab:: Query Syntax - :tabid: query-syntax - - .. code-block:: csharp - - var query = from restaurant in queryableCollection - join rv in reviewCollection on restaurant.Name equals rv.RestaurantName into reviews - select new { restaurant, reviews }; - -The preceding example returns all documents from the ``restaurants`` collection. Each -restaurant document has an added field called ``reviews``, which contains all -reviews for that restaurant. A review matches a restaurant if the value of the -``name`` field in the review document matches the ``name`` field of the restaurant -document. - -The following shows a subset of the returned results: - -.. code-block:: json - - // Results Truncated - - { - "restaurant": { - "_id": ObjectId("..."), - "name": "The Movable Feast", - "restaurant_id": "40361606", - "cuisine": "American", - "address": { ... }, - "borough": "Brooklyn", - "grades": [ ... ] - }, - "reviews": [ - { - "_id": ObjectId("..."), - "restaurant_name": "The Movable Feast", - "reviewer": "Lazlo Cravensworth", - "review_text": "Great restaurant! 12/10 stars!" - }, - { - "_id": ObjectId("..."), - "restaurant_name": "The Movable Feast", - "reviewer": "Michael Scarn", - "review_text": "It really was a feast" - } - ] - } - -$vectorSearch -~~~~~~~~~~~~~ - -The ``$vectorSearch`` aggregation stage performs an *approximate nearest neighbor* search -on a vector in the specified field. Your collection *must* have a -defined Atlas Vector Search index before you can perform a vector search on your data. - -.. tip:: - - To obtain the sample dataset used in the following example, see :ref:`csharp-get-started`. - To create the sample Atlas Vector Search index used in the following example, see - :atlas:`Create an Atlas Vector Search Index ` in the - Atlas manual. - -Consider the ``embedded_movies`` collection in the ``sample_mflix`` database. You -can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding`` -field of the documents in the collection. - -The following ``EmbeddedMovie`` class models the documents in the ``embedded_movies`` -collection: - -.. code-block:: csharp - - [BsonIgnoreExtraElements] - public class EmbeddedMovie - { - [BsonIgnoreIfDefault] - public string Title { get; set; } - - public string Plot { get; set; } - - [BsonElement("plot_embedding")] - public double[] Embedding { get; set; } - } - -The following example shows how to generate a ``$vectorSearch`` stage to search -the ``plot_embedding`` field using vector embeddings for the string ``"time travel"``: - -.. code-block:: csharp - - // Defines vector embeddings for the string "time travel" - var vector = new[] {-0.0016261312,-0.028070757,-0.011342932,-0.012775794,-0.0027440966,0.008683807,-0.02575152,-0.02020668,-0.010283281,-0.0041719596,0.021392956,0.028657231,-0.006634482,0.007490867,0.018593878,0.0038187427,0.029590257,-0.01451522,0.016061379,0.00008528442,-0.008943722,0.01627464,0.024311995,-0.025911469,0.00022596726,-0.008863748,0.008823762,-0.034921836,0.007910728,-0.01515501,0.035801545,-0.0035688248,-0.020299982,-0.03145631,-0.032256044,-0.028763862,-0.0071576433,-0.012769129,0.012322609,-0.006621153,0.010583182,0.024085402,-0.001623632,0.007864078,-0.021406285,0.002554159,0.012229307,-0.011762793,0.0051682983,0.0048484034,0.018087378,0.024325324,-0.037694257,-0.026537929,-0.008803768,-0.017767483,-0.012642504,-0.0062712682,0.0009771782,-0.010409906,0.017754154,-0.004671795,-0.030469967,0.008477209,-0.005218282,-0.0058480743,-0.020153364,-0.0032805866,0.004248601,0.0051449724,0.006791097,0.007650814,0.003458861,-0.0031223053,-0.01932697,-0.033615597,0.00745088,0.006321252,-0.0038154104,0.014555207,0.027697546,-0.02828402,0.0066711367,0.0077107945,0.01794076,0.011349596,-0.0052715978,0.014755142,-0.019753495,-0.011156326,0.011202978,0.022126047,0.00846388,0.030549942,-0.0041386373,0.018847128,-0.00033655585,0.024925126,-0.003555496,-0.019300312,0.010749794,0.0075308536,-0.018287312,-0.016567878,-0.012869096,-0.015528221,0.0078107617,-0.011156326,0.013522214,-0.020646535,-0.01211601,0.055928253,0.011596181,-0.017247654,0.0005939711,-0.026977783,-0.003942035,-0.009583511,-0.0055248477,-0.028737204,0.023179034,0.003995351,0.0219661,-0.008470545,0.023392297,0.010469886,-0.015874773,0.007890735,-0.009690142,-0.00024970944,0.012775794,0.0114762215,0.013422247,0.010429899,-0.03686786,-0.006717788,-0.027484283,0.011556195,-0.036068123,-0.013915418,-0.0016327957,0.0151016945,-0.020473259,0.004671795,-0.012555866,0.0209531,0.01982014,0.024485271,0.0105431955,-0.005178295,0.033162415,-0.013795458,0.007150979,0.010243294,0.005644808,0.017260984,-0.0045618312,0.0024725192,0.004305249,-0.008197301,0.0014203656,0.0018460588,0.005015015,-0.011142998,0.01439526,0.022965772,0.02552493,0.007757446,-0.0019726837,0.009503538,-0.032042783,0.008403899,-0.04609149,0.013808787,0.011749465,0.036388017,0.016314628,0.021939443,-0.0250051,-0.017354285,-0.012962398,0.00006107364,0.019113706,0.03081652,-0.018114036,-0.0084572155,0.009643491,-0.0034721901,0.0072642746,-0.0090636825,0.01642126,0.013428912,0.027724205,0.0071243206,-0.6858542,-0.031029783,-0.014595194,-0.011449563,0.017514233,0.01743426,0.009950057,0.0029706885,-0.015714826,-0.001806072,0.011856096,0.026444625,-0.0010663156,-0.006474535,0.0016161345,-0.020313311,0.0148351155,-0.0018393943,0.0057347785,0.018300641,-0.018647194,0.03345565,-0.008070676,0.0071443142,0.014301958,0.0044818576,0.003838736,-0.007350913,-0.024525259,-0.001142124,-0.018620536,0.017247654,0.007037683,0.010236629,0.06046009,0.0138887605,-0.012122675,0.037694257,0.0055081863,0.042492677,0.00021784494,-0.011656162,0.010276617,0.022325981,0.005984696,-0.009496873,0.013382261,-0.0010563189,0.0026507939,-0.041639622,0.008637156,0.026471283,-0.008403899,0.024858482,-0.00066686375,-0.0016252982,0.027590916,0.0051449724,0.0058647357,-0.008743787,-0.014968405,0.027724205,-0.011596181,0.0047650975,-0.015381602,0.0043718936,0.002159289,0.035908177,-0.008243952,-0.030443309,0.027564257,0.042625964,-0.0033688906,0.01843393,0.019087048,0.024578573,0.03268257,-0.015608194,-0.014128681,-0.0033538956,-0.0028757197,-0.004121976,-0.032389335,0.0034322033,0.058807302,0.010943064,-0.030523283,0.008903735,0.017500903,0.00871713,-0.0029406983,0.013995391,-0.03132302,-0.019660193,-0.00770413,-0.0038853872,0.0015894766,-0.0015294964,-0.006251275,-0.021099718,-0.010256623,-0.008863748,0.028550599,0.02020668,-0.0012962399,-0.003415542,-0.0022509254,0.0119360695,0.027590916,-0.046971202,-0.0015194997,-0.022405956,0.0016677842,-0.00018535563,-0.015421589,-0.031802863,0.03814744,0.0065411795,0.016567878,-0.015621523,0.022899127,-0.011076353,0.02841731,-0.002679118,-0.002342562,0.015341615,0.01804739,-0.020566562,-0.012989056,-0.002990682,0.01643459,0.00042527664,0.008243952,-0.013715484,-0.004835075,-0.009803439,0.03129636,-0.021432944,0.0012087687,-0.015741484,-0.0052016205,0.00080890034,-0.01755422,0.004811749,-0.017967418,-0.026684547,-0.014128681,0.0041386373,-0.013742141,-0.010056688,-0.013268964,-0.0110630235,-0.028337335,0.015981404,-0.00997005,-0.02424535,-0.013968734,-0.028310679,-0.027750863,-0.020699851,0.02235264,0.001057985,0.00081639783,-0.0099367285,0.013522214,-0.012016043,-0.00086471526,0.013568865,0.0019376953,-0.019020405,0.017460918,-0.023045745,0.008503866,0.0064678704,-0.011509543,0.018727167,-0.003372223,-0.0028690554,-0.0027024434,-0.011902748,-0.012182655,-0.015714826,-0.0098634185,0.00593138,0.018753825,0.0010146659,0.013029044,0.0003521757,-0.017620865,0.04102649,0.00552818,0.024485271,-0.009630162,-0.015608194,0.0006718621,-0.0008418062,0.012395918,0.0057980907,0.016221326,0.010616505,0.004838407,-0.012402583,0.019900113,-0.0034521967,0.000247002,-0.03153628,0.0011038032,-0.020819811,0.016234655,-0.00330058,-0.0032289368,0.00078973995,-0.021952773,-0.022459272,0.03118973,0.03673457,-0.021472929,0.0072109587,-0.015075036,0.004855068,-0.0008151483,0.0069643734,0.010023367,-0.010276617,-0.023019087,0.0068244194,-0.0012520878,-0.0015086699,0.022046074,-0.034148756,-0.0022192693,0.002427534,-0.0027124402,0.0060346797,0.015461575,0.0137554705,0.009230294,-0.009583511,0.032629255,0.015994733,-0.019167023,-0.009203636,0.03393549,-0.017274313,-0.012042701,-0.0009930064,0.026777849,-0.013582194,-0.0027590916,-0.017594207,-0.026804507,-0.0014236979,-0.022032745,0.0091236625,-0.0042419364,-0.00858384,-0.0033905501,-0.020739838,0.016821127,0.022539245,0.015381602,0.015141681,0.028817179,-0.019726837,-0.0051283115,-0.011489551,-0.013208984,-0.0047017853,-0.0072309524,0.01767418,0.0025658219,-0.010323267,0.012609182,-0.028097415,0.026871152,-0.010276617,0.021912785,0.0022542577,0.005124979,-0.0019710176,0.004518512,-0.040360045,0.010969722,-0.0031539614,-0.020366628,-0.025778178,-0.0110030435,-0.016221326,0.0036587953,0.016207997,0.003007343,-0.0032555948,0.0044052163,-0.022046074,-0.0008822095,-0.009363583,0.028230704,-0.024538586,0.0029840174,0.0016044717,-0.014181997,0.031349678,-0.014381931,-0.027750863,0.02613806,0.0004136138,-0.005748107,-0.01868718,-0.0010138329,0.0054348772,0.010703143,-0.003682121,0.0030856507,-0.004275259,-0.010403241,0.021113047,-0.022685863,-0.023032416,0.031429652,0.001792743,-0.005644808,-0.011842767,-0.04078657,-0.0026874484,0.06915057,-0.00056939584,-0.013995391,0.010703143,-0.013728813,-0.022939114,-0.015261642,-0.022485929,0.016807798,0.007964044,0.0144219175,0.016821127,0.0076241563,0.005461535,-0.013248971,0.015301628,0.0085171955,-0.004318578,0.011136333,-0.0059047225,-0.010249958,-0.018207338,0.024645219,0.021752838,0.0007614159,-0.013648839,0.01111634,-0.010503208,-0.0038487327,-0.008203966,-0.00397869,0.0029740208,0.008530525,0.005261601,0.01642126,-0.0038753906,-0.013222313,0.026537929,0.024671877,-0.043505676,0.014195326,0.024778508,0.0056914594,-0.025951454,0.017620865,-0.0021359634,0.008643821,0.021299653,0.0041686273,-0.009017031,0.04044002,0.024378639,-0.027777521,-0.014208655,0.0028623908,0.042119466,0.005801423,-0.028124074,-0.03129636,0.022139376,-0.022179363,-0.04067994,0.013688826,0.013328944,0.0046184794,-0.02828402,-0.0063412455,-0.0046184794,-0.011756129,-0.010383247,-0.0018543894,-0.0018593877,-0.00052024535,0.004815081,0.014781799,0.018007403,0.01306903,-0.020433271,0.009043689,0.033189073,-0.006844413,-0.019766824,-0.018767154,0.00533491,-0.0024575242,0.018727167,0.0058080875,-0.013835444,0.0040719924,0.004881726,0.012029372,0.005664801,0.03193615,0.0058047553,0.002695779,0.009290274,0.02361889,0.017834127,0.0049017193,-0.0036388019,0.010776452,-0.019793482,0.0067777685,-0.014208655,-0.024911797,0.002385881,0.0034988478,0.020899786,-0.0025858153,-0.011849431,0.033189073,-0.021312982,0.024965113,-0.014635181,0.014048708,-0.0035921505,-0.003347231,0.030869836,-0.0017161017,-0.0061346465,0.009203636,-0.025165047,0.0068510775,0.021499587,0.013782129,-0.0024475274,-0.0051149824,-0.024445284,0.006167969,0.0068844,-0.00076183246,0.030150073,-0.0055948244,-0.011162991,-0.02057989,-0.009703471,-0.020646535,0.008004031,0.0066378145,-0.019900113,-0.012169327,-0.01439526,0.0044252095,-0.004018677,0.014621852,-0.025085073,-0.013715484,-0.017980747,0.0071043274,0.011456228,-0.01010334,-0.0035321703,-0.03801415,-0.012036037,-0.0028990454,-0.05419549,-0.024058744,-0.024272008,0.015221654,0.027964126,0.03182952,-0.015354944,0.004855068,0.011522872,0.004771762,0.0027874154,0.023405626,0.0004242353,-0.03132302,0.007057676,0.008763781,-0.0027057757,0.023005757,-0.0071176565,-0.005238275,0.029110415,-0.010989714,0.013728813,-0.009630162,-0.029137073,-0.0049317093,-0.0008630492,-0.015248313,0.0043219104,-0.0055681667,-0.013175662,0.029723546,0.025098402,0.012849103,-0.0009996708,0.03118973,-0.0021709518,0.0260181,-0.020526575,0.028097415,-0.016141351,0.010509873,-0.022965772,0.002865723,0.0020493253,0.0020509914,-0.0041419696,-0.00039695262,0.017287642,0.0038987163,0.014795128,-0.014661839,-0.008950386,0.004431874,-0.009383577,0.0012604183,-0.023019087,0.0029273694,-0.033135757,0.009176978,-0.011023037,-0.002102641,0.02663123,-0.03849399,-0.0044152127,0.0004527676,-0.0026924468,0.02828402,0.017727496,0.035135098,0.02728435,-0.005348239,-0.001467017,-0.019766824,0.014715155,0.011982721,0.0045651635,0.023458943,-0.0010046692,-0.0031373003,-0.0006972704,0.0019043729,-0.018967088,-0.024311995,0.0011546199,0.007977373,-0.004755101,-0.010016702,-0.02780418,-0.004688456,0.013022379,-0.005484861,0.0017227661,-0.015394931,-0.028763862,-0.026684547,0.0030589928,-0.018513903,0.028363993,0.0044818576,-0.009270281,0.038920518,-0.016008062,0.0093902415,0.004815081,-0.021059733,0.01451522,-0.0051583014,0.023765508,-0.017874114,-0.016821127,-0.012522544,-0.0028390652,0.0040886537,0.020259995,-0.031216389,-0.014115352,-0.009176978,0.010303274,0.020313311,0.0064112223,-0.02235264,-0.022872468,0.0052449396,0.0005723116,0.0037321046,0.016807798,-0.018527232,-0.009303603,0.0024858483,-0.0012662497,-0.007110992,0.011976057,-0.007790768,-0.042999174,-0.006727785,-0.011829439,0.007024354,0.005278262,-0.017740825,-0.0041519664,0.0085905045,0.027750863,-0.038387362,0.024391968,0.00087721116,0.010509873,-0.00038508154,-0.006857742,0.0183273,-0.0037054466,0.015461575,0.0017394272,-0.0017944091,0.014181997,-0.0052682655,0.009023695,0.00719763,-0.013522214,0.0034422,0.014941746,-0.0016711164,-0.025298337,-0.017634194,0.0058714002,-0.005321581,0.017834127,0.0110630235,-0.03369557,0.029190388,-0.008943722,0.009363583,-0.0034222065,-0.026111402,-0.007037683,-0.006561173,0.02473852,-0.007084334,-0.010110005,-0.008577175,0.0030439978,-0.022712521,0.0054582027,-0.0012620845,-0.0011954397,-0.015741484,0.0129557345,-0.00042111133,0.00846388,0.008930393,0.016487904,0.010469886,-0.007917393,-0.011762793,-0.0214596,0.000917198,0.021672864,0.010269952,-0.007737452,-0.010243294,-0.0067244526,-0.015488233,-0.021552904,0.017127695,0.011109675,0.038067464,0.00871713,-0.0025591573,0.021312982,-0.006237946,0.034628596,-0.0045251767,0.008357248,0.020686522,0.0010696478,0.0076708077,0.03772091,-0.018700508,-0.0020676525,-0.008923728,-0.023298996,0.018233996,-0.010256623,0.0017860786,0.009796774,-0.00897038,-0.01269582,-0.018527232,0.009190307,-0.02372552,-0.042119466,0.008097334,-0.0066778013,-0.021046404,0.0019593548,0.011083017,-0.0016028056,0.012662497,-0.000059095124,0.0071043274,-0.014675168,0.024831824,-0.053582355,0.038387362,0.0005698124,0.015954746,0.021552904,0.031589597,-0.009230294,-0.0006147976,0.002625802,-0.011749465,-0.034362018,-0.0067844326,-0.018793812,0.011442899,-0.008743787,0.017474247,-0.021619547,0.01831397,-0.009037024,-0.0057247817,-0.02728435,0.010363255,0.034415334,-0.024032086,-0.0020126705,-0.0045518344,-0.019353628,-0.018340627,-0.03129636,-0.0034038792,-0.006321252,-0.0016161345,0.033642255,-0.000056075285,-0.005005019,0.004571828,-0.0024075406,-0.00010215386,0.0098634185,0.1980148,-0.003825407,-0.025191706,0.035161756,0.005358236,0.025111731,0.023485601,0.0023342315,-0.011882754,0.018287312,-0.0068910643,0.003912045,0.009243623,-0.001355387,-0.028603915,-0.012802451,-0.030150073,-0.014795128,-0.028630573,-0.0013487226,0.002667455,0.00985009,-0.0033972147,-0.021486258,0.009503538,-0.017847456,0.013062365,-0.014341944,0.005078328,0.025165047,-0.015594865,-0.025924796,-0.0018177348,0.010996379,-0.02993681,0.007324255,0.014475234,-0.028577257,0.005494857,0.00011725306,-0.013315615,0.015941417,0.009376912,0.0025158382,0.008743787,0.023832154,-0.008084005,-0.014195326,-0.008823762,0.0033455652,-0.032362677,-0.021552904,-0.0056081535,0.023298996,-0.025444955,0.0097301295,0.009736794,0.015274971,-0.0012937407,-0.018087378,-0.0039387033,0.008637156,-0.011189649,-0.00023846315,-0.011582852,0.0066411467,-0.018220667,0.0060846633,0.0376676,-0.002709108,0.0072776037,0.0034188742,-0.010249958,-0.0007747449,-0.00795738,-0.022192692,0.03910712,0.032122757,0.023898797,0.0076241563,-0.007397564,-0.003655463,0.011442899,-0.014115352,-0.00505167,-0.031163072,0.030336678,-0.006857742,-0.022259338,0.004048667,0.02072651,0.0030156737,-0.0042119464,0.00041861215,-0.005731446,0.011103011,0.013822115,0.021512916,0.009216965,-0.006537847,-0.027057758,-0.04054665,0.010403241,-0.0056281467,-0.005701456,-0.002709108,-0.00745088,-0.0024841821,0.009356919,-0.022659205,0.004061996,-0.013175662,0.017074378,-0.006141311,-0.014541878,0.02993681,-0.00028448965,-0.025271678,0.011689484,-0.014528549,0.004398552,-0.017274313,0.0045751603,0.012455898,0.004121976,-0.025458284,-0.006744446,0.011822774,-0.015035049,-0.03257594,0.014675168,-0.0039187097,0.019726837,-0.0047251107,0.0022825818,0.011829439,0.005391558,-0.016781142,-0.0058747325,0.010309938,-0.013049036,0.01186276,-0.0011246296,0.0062112883,0.0028190718,-0.021739509,0.009883412,-0.0073175905,-0.012715813,-0.017181009,-0.016607866,-0.042492677,-0.0014478565,-0.01794076,0.012302616,-0.015194997,-0.04433207,-0.020606548,0.009696807,0.010303274,-0.01694109,-0.004018677,0.019353628,-0.001991011,0.000058938927,0.010536531,-0.17274313,0.010143327,0.014235313,-0.024152048,0.025684876,-0.0012504216,0.036601283,-0.003698782,0.0007310093,0.004165295,-0.0029157067,0.017101036,-0.046891227,-0.017460918,0.022965772,0.020233337,-0.024072073,0.017220996,0.009370248,0.0010363255,0.0194336,-0.019606877,0.01818068,-0.020819811,0.007410893,0.0019326969,0.017887443,0.006651143,0.00067394477,-0.011889419,-0.025058415,-0.008543854,0.021579562,0.0047484366,0.014062037,0.0075508473,-0.009510202,-0.009143656,0.0046817916,0.013982063,-0.0027990784,0.011782787,0.014541878,-0.015701497,-0.029350337,0.021979429,0.01332228,-0.026244693,-0.0123492675,-0.003895384,0.0071576433,-0.035454992,-0.00046984528,0.0033522295,0.039347045,0.0005119148,0.00476843,-0.012995721,0.0024042083,-0.006931051,-0.014461905,-0.0127558,0.0034555288,-0.0074842023,-0.030256703,-0.007057676,-0.00807734,0.007804097,-0.006957709,0.017181009,-0.034575284,-0.008603834,-0.005008351,-0.015834786,0.02943031,0.016861115,-0.0050849924,0.014235313,0.0051449724,0.0025924798,-0.0025741523,0.04289254,-0.002104307,0.012969063,-0.008310596,0.00423194,0.0074975314,0.0018810473,-0.014248641,-0.024725191,0.0151016945,-0.017527562,0.0018727167,0.0002830318,0.015168339,0.0144219175,-0.004048667,-0.004358565,0.011836103,-0.010343261,-0.005911387,0.0022825818,0.0073175905,0.00403867,0.013188991,0.03334902,0.006111321,0.008597169,0.030123414,-0.015474904,0.0017877447,-0.024551915,0.013155668,0.023525586,-0.0255116,0.017220996,0.004358565,-0.00934359,0.0099967085,0.011162991,0.03092315,-0.021046404,-0.015514892,0.0011946067,-0.01816735,0.010876419,-0.10124666,-0.03550831,0.0056348112,0.013942076,0.005951374,0.020419942,-0.006857742,-0.020873128,-0.021259667,0.0137554705,0.0057880944,-0.029163731,-0.018767154,-0.021392956,0.030896494,-0.005494857,-0.0027307675,-0.006801094,-0.014821786,0.021392956,-0.0018110704,-0.0018843795,-0.012362596,-0.0072176233,-0.017194338,-0.018713837,-0.024272008,0.03801415,0.00015880188,0.0044951867,-0.028630573,-0.0014070367,-0.00916365,-0.026537929,-0.009576847,-0.013995391,-0.0077107945,0.0050016865,0.00578143,-0.04467862,0.008363913,0.010136662,-0.0006268769,-0.006591163,0.015341615,-0.027377652,-0.00093136,0.029243704,-0.020886457,-0.01041657,-0.02424535,0.005291591,-0.02980352,-0.009190307,0.019460259,-0.0041286405,0.004801752,0.0011787785,-0.001257086,-0.011216307,-0.013395589,0.00088137644,-0.0051616337,0.03876057,-0.0033455652,0.00075850025,-0.006951045,-0.0062112883,0.018140694,-0.006351242,-0.008263946,0.018154023,-0.012189319,0.0075508473,-0.044358727,-0.0040153447,0.0093302615,-0.010636497,0.032789204,-0.005264933,-0.014235313,-0.018393943,0.007297597,-0.016114693,0.015021721,0.020033404,0.0137688,0.0011046362,0.010616505,-0.0039453674,0.012109346,0.021099718,-0.0072842683,-0.019153694,-0.003768759,0.039320387,-0.006747778,-0.0016852784,0.018154023,0.0010963057,-0.015035049,-0.021033075,-0.04345236,0.017287642,0.016341286,-0.008610498,0.00236922,0.009290274,0.028950468,-0.014475234,-0.0035654926,0.015434918,-0.03372223,0.004501851,-0.012929076,-0.008483873,-0.0044685286,-0.0102233,0.01615468,0.0022792495,0.010876419,-0.0059647025,0.01895376,-0.0069976957,-0.0042952523,0.017207667,-0.00036133936,0.0085905045,0.008084005,0.03129636,-0.016994404,-0.014915089,0.020100048,-0.012009379,-0.006684466,0.01306903,0.00015765642,-0.00530492,0.0005277429,0.015421589,0.015528221,0.032202728,-0.003485519,-0.0014286962,0.033908837,0.001367883,0.010509873,0.025271678,-0.020993087,0.019846799,0.006897729,-0.010216636,-0.00725761,0.01818068,-0.028443968,-0.011242964,-0.014435247,-0.013688826,0.006101324,-0.0022509254,0.013848773,-0.0019077052,0.017181009,0.03422873,0.005324913,-0.0035188415,0.014128681,-0.004898387,0.005038341,0.0012320944,-0.005561502,-0.017847456,0.0008538855,-0.0047884234,0.011849431,0.015421589,-0.013942076,0.0029790192,-0.013702155,0.0001199605,-0.024431955,0.019926772,0.022179363,-0.016487904,-0.03964028,0.0050849924,0.017487574,0.022792496,0.0012504216,0.004048667,-0.00997005,0.0076041627,-0.014328616,-0.020259995,0.0005598157,-0.010469886,0.0016852784,0.01716768,-0.008990373,-0.001987679,0.026417969,0.023792166,0.0046917885,-0.0071909656,-0.00032051947,-0.023259008,-0.009170313,0.02071318,-0.03156294,-0.030869836,-0.006324584,0.013795458,-0.00047151142,0.016874444,0.00947688,0.00985009,-0.029883493,0.024205362,-0.013522214,-0.015075036,-0.030603256,0.029270362,0.010503208,0.021539574,0.01743426,-0.023898797,0.022019416,-0.0068777353,0.027857494,-0.021259667,0.0025758184,0.006197959,0.006447877,-0.00025200035,-0.004941706,-0.021246338,-0.005504854,-0.008390571,-0.0097301295,0.027244363,-0.04446536,0.05216949,0.010243294,-0.016008062,0.0122493,-0.0199401,0.009077012,0.019753495,0.006431216,-0.037960835,-0.027377652,0.016381273,-0.0038620618,0.022512587,-0.010996379,-0.0015211658,-0.0102233,0.007071005,0.008230623,-0.009490209,-0.010083347,0.024431955,0.002427534,0.02828402,0.0035721571,-0.022192692,-0.011882754,0.010056688,0.0011904413,-0.01426197,-0.017500903,-0.00010985966,0.005591492,-0.0077707744,-0.012049366,0.011869425,0.00858384,-0.024698535,-0.030283362,0.020140035,0.011949399,-0.013968734,0.042732596,-0.011649498,-0.011982721,-0.016967745,-0.0060913274,-0.007130985,-0.013109017,-0.009710136}; - - // Specifies that the vector search will consider the 150 nearest neighbors - // in the specified index - var options = new VectorSearchOptions() - { - IndexName = "vector_index", - NumberOfCandidates = 150 - }; - - // Builds aggregation pipeline and specifies that the $vectorSearch stage - // returns 10 results - var results = queryableCollection - .VectorSearch(m => m.Embedding, vector, 10, options) - .Select(m => new { m.Title, m.Plot }); - -The results of the preceding example contain the following documents: - -.. code-block:: json - - { "_id" : ObjectId("573a13a0f29313caabd04a4f"), "plot" : "A reporter, learning of time travelers visiting 20th century disasters, tries to change the history they know by averting upcoming disasters.", "title" : "Thrill Seekers" } - { "_id" : ObjectId("573a13d8f29313caabda6557"), "plot" : "At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.", "title" : "About Time" } - { "_id" : ObjectId("573a13a5f29313caabd13b4b"), "plot" : "Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.", "title" : "The Time Machine" } - { "_id" : ObjectId("573a13aef29313caabd2e2d7"), "plot" : "After using his mother's newly built time machine, Dolf gets stuck involuntary in the year 1212. He ends up in a children's crusade where he confronts his new friends with modern techniques...", "title" : "Crusade in Jeans" } - { "_id" : ObjectId("573a1399f29313caabceec0e"), "plot" : "An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.", "title" : "Timecop" } - { "_id" : ObjectId("573a1399f29313caabcee36f"), "plot" : "A time-travel experiment in which a robot probe is sent from the year 2073 to the year 1973 goes terribly wrong thrusting one of the project scientists, a man named Nicholas Sinclair into a...", "title" : "A.P.E.X." } - { "_id" : ObjectId("573a13c6f29313caabd715d3"), "plot" : "Agent J travels in time to M.I.B.'s early days in 1969 to stop an alien from assassinating his friend Agent K and changing history.", "title" : "Men in Black 3" } - { "_id" : ObjectId("573a13d4f29313caabd98c13"), "plot" : "Bound by a shared destiny, a teen bursting with scientific curiosity and a former boy-genius inventor embark on a mission to unearth the secrets of a place somewhere in time and space that exists in their collective memory.", "title" : "Tomorrowland" } - { "_id" : ObjectId("573a13b6f29313caabd477fa"), "plot" : "With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.", "title" : "Love Story 2050" } - { "_id" : ObjectId("573a13e5f29313caabdc40c9"), "plot" : "A dimension-traveling wizard gets stuck in the 21st century because cell-phone radiation interferes with his magic. With his home world on the brink of war, he seeks help from a jaded ...", "title" : "The Portal" } - -For more information about Atlas Vector Search, Atlas Vector Search indexes, and how -to incorporate them into your application, see :atlas:`Atlas Vector Search Overview ` -in the Atlas manual. For more examples about running Atlas Vector Search queries using the -{+driver-short+}, see :atlas:`Run Vector Search Queries ` -in the Atlas manual and select :guilabel:`C#` from the language dropdown. - -Bitwise Operators -~~~~~~~~~~~~~~~~~ - -This section describes the :wikipedia:`bitwise operators ` -supported by the {+driver-short+} that you can use in an aggregation pipeline. -You can use multiple bitwise operators in the same -stage. The following guidelines apply when using bitwise operators: - -- All operands must be of type ``int`` or ``long``. - -- ``$bitAnd``, ``$bitOr``, and ``$bitXor`` take two or more operands. ``$bitNot`` takes one operand. - -- Bitwise operations are evaluated from left to right. - -The examples in this section use the following documents in a collection called -``ingredients``: - -.. code-block:: json - - { "_id" : 1, "name" : "watermelon", "is_available" : 1, "is_cheap" : 1 }, - { "_id" : 2, "name" : "onions", "is_available" : 1, "is_cheap" : 0 }, - { "_id" : 3, "name" : "eggs", "is_available" : 0, "is_cheap" : 0 }, - { "_id" : 4, "name" : "potatoes", "is_available" : 1, "is_cheap" : 1 }, - { "_id" : 5, "name" : "pasta", "is_available" : 0, "is_cheap" : 1 }, - { "_id" : 6, "name" : "cheese", "is_available" : 1 } - -The ``"is_available"`` field represents if an ingredient is available. If this -field has a value of ``0``, the ingredient is not available. If it has a value -of ``1``, the ingredient is available. - -The ``"is_cheap"`` field represents if an ingredient is cheap. If this field has -a value of ``0``, the ingredient is not cheap. If it has a value of ``1``, the -ingredient is cheap. - -The following ``Ingredient`` class models the documents in the ``ingredients`` -collection: - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-ingredient-model - :end-before: end-ingredient-model - -.. note:: Missing or Undefined Operands - - If the operands you pass to any bitwise operator are of type `nullable `__ - ``int`` or ``long`` and contain a missing or undefined value, the entire expression - evaluates to ``null``. If the operands are of type non-nullable ``int`` or - ``long`` and contain a missing or undefined value, the {+driver-short+} will - throw an error. - -$bitAnd -+++++++ - -The ``$bitAnd`` aggregation operator performs a bitwise AND operation on the given -arguments. You can use the ``$bitAnd`` operator by connecting two or more -clauses with a ``&`` character. - -The following example shows how to create a ``$bitAnd`` stage by using LINQ. The -code retrieves the document in which the ``Name`` field has the -value ``"watermelon"``. It then performs a bitwise AND operation on the values of the -``IsAvailable`` and ``IsCheap`` fields in this document. - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-bitAnd-example - :end-before: end-bitAnd-example - -The preceding code returns ``1``, the result of the AND operation on the values -of the ``IsAvailable`` field (``1``) and the ``IsCheap`` field (``1``). - -The following example performs the same bitwise AND operation on all -documents in the collection: - -.. io-code-block:: - :copyable: true - - .. input:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-bitAnd-collection-example - :end-before: end-bitAnd-collection-example - - .. output:: - :language: json - :visible: false - - 1 - 0 - 0 - 1 - 0 - null - -The ``null`` result comes from the document where the ``Name`` field -has the value of ``"cheese"``. This document is missing an ``IsCheap`` field, so -the expression evaluates to ``null``. - -$bitOr -++++++ - -The ``$bitOr`` aggregation operator performs a bitwise OR operation on the given -arguments. You can use the ``$bitOr`` operator by connecting two or more -clauses with a ``|`` character. - -The following example shows how to create a ``$bitOr`` stage by using LINQ. The -code retrieves the document in which the ``Name`` field has the -value ``"onions"``. It then performs a bitwise OR operation on the values of the -``IsAvailable`` and ``IsCheap`` fields in this document. - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-bitOr-example - :end-before: end-bitOr-example - -The preceding code returns ``1``, the result of the OR operation on the values -of the ``IsAvailable`` field (``1``) and the ``IsCheap`` field (``0``). - -$bitNot -+++++++ - -The ``$bitNot`` aggregation operator performs a bitwise NOT operation on the given -argument. You can use the ``$bitNot`` operator by preceding an -operand with a ``~`` character. ``$bitNot`` only takes one argument. The -following example shows how to create a ``$bitNot`` stage by using LINQ: - -.. io-code-block:: - :copyable: true - - .. input:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-bitNot-example - :end-before: end-bitNot-example - - .. output:: - :language: json - :visible: false - - -2 - -1 - -1 - -2 - -2 - null - -$bitXor -+++++++ - -The ``$bitXor`` aggregation operator performs a bitwise XOR operation on the given -arguments. You can use the ``$bitXor`` operator by connecting two or more -clauses with a ``^`` character. - -The following example shows how to create a ``$bitXor`` stage by using LINQ. The -code retrieves the documents in which the ``Name`` field has -the value ``"watermelon"`` or ``"onions"``. It then performs a bitwise XOR -operation on the values of the ``IsAvailable`` and ``IsCheap`` fields in these -documents. - -.. literalinclude:: /includes/fundamentals/code-examples/linq.cs - :language: csharp - :dedent: - :start-after: start-bitXor-example - :end-before: end-bitXor-example - -The result contains the following values: - -.. code-block:: json - - 0 - 1 - - -Unsupported Aggregation Stages ------------------------------- - -The {+driver-long+} implementation of LINQ does not support the following -aggregation stages: - -- ``$redact`` -- ``$geoNear`` -- ``$out`` - -To learn how to create an aggregation pipeline with the ``$out`` stage by using Builders, see -the :ref:`` section. - -Supported Methods ------------------ - -The following are some methods supported by the {+driver-long+} implementation of LINQ: - -.. list-table:: - :header-rows: 1 - :widths: 40 60 - - * - Method Name - - Description - - * - ``Any`` - - Determines if any documents match the specified criteria - - * - ``Average`` - - Calculates the average of the specified fields - - * - ``Count`` - - Returns an ``Int32`` that represents the number of documents that match the specified criteria - - * - ``LongCount`` - - Returns an ``Int64`` that represents the number of documents that match the specified criteria - - * - ``DateFromString`` - - Converts a ``string`` to a ``DateTime`` object - - * - ``Distinct`` - - Returns distinct documents that match the specified criteria - - * - ``DistinctMany`` - - Returns distinct documents from an array that match the specified criteria - - * - ``Exists`` - - Tests whether a field exists - - * - ``First`` - - Returns the first matching document, and throws an exception if none are found - - * - ``FirstOrDefault`` - - Returns the first matching document, or ``null`` if none are found - - * - ``GroupBy`` - - Groups documents based on specified criteria - - * - ``GroupJoin`` - - Performs a left outer join to another collection in the same database - - * - ``IsMissing`` - - Returns ``true`` if a field is missing and false otherwies - - * - ``IsNullOrMissing`` - - Returns ``true`` if a field is null or missing and false otherwise - - * - ``Max`` - - Returns the document with the maximum specified value - - * - ``OfType`` - - Returns documents that match the specified type - - * - ``OrderBy``, ``OrderByDescending`` - - Returns results in a specified sort order - - * - ``ThenBy``, ``ThenByDescending`` - - Allows a secondary sort to be specified - - * - ``Select`` - - Selects documents based on specified criteria - - * - ``SelectMany`` - - Projects each element of a sequence and combines the resulting sequences into one document - - * - ``Single`` - - Returns the only matching document, and throws an exception if there is not exactly one document - - * - ``SingleOrDefault`` - - Returns a single matching document or ``null`` if no documents match - - * - ``Skip`` - - Skips over a specified number of documents and returns the rest of the results - - * - ``Sum`` - - Returns the sum of the values in a specified field - - * - ``Take`` - - Specifies the number of results to return - - * - ``Where`` - - Returns all documents that match your specified criteria - -View Translated Queries ------------------------ - -When you run a LINQ query, the {+driver-short+} automatically translates your -query into an aggregation pipeline written with the {+query-api+}. You can view -the translated query by using the ``ToString()`` method or the -``LoggedStages`` property. - -To see the translated query for **non-scalar operations**, use the ``ToString()`` -method. Non-scalar operations are operations that return a query object, such -as: - -- ``Where`` -- ``Select`` -- ``SelectMany`` -- ``GroupJoin`` - -The following example calls the ``ToString()`` method on a LINQ query and prints -the translated query: - -.. io-code-block:: - - .. input:: - :language: csharp - - var queryableCollection = _restaurantsCollection.AsQueryable(); - var query = queryableCollection - .Where(r => r.Name == "The Movable Feast"); - - var queryTranslated = query.ToString(); - Console.WriteLine(queryTranslated); - - .. output:: - - sample_restaurants.restaurants.Aggregate([{ "$match" : { "name" : "The Movable Feast" } }]) - -To get the translated query for **scalar operations** use the ``LoggedStages`` -property. Scalar operations are operations that return a scalar result rather than a -query object, such as: - -- ``First`` -- ``Sum`` -- ``Count`` -- ``Min`` -- ``Max`` - -To get a translated query with the ``LoggedStages`` property, you must save -the translated query directly after it is executed, and before executing any -other queries with the same queryable object. - -The following example uses the ``LoggedStages`` property on a LINQ query that -uses a scalar operation, then prints the translated query: - -.. io-code-block:: - - .. input:: - :language: csharp - :emphasize-lines: 6 - - - var queryableCollection = _restaurantsCollection.AsQueryable(); - var query = queryableCollection - .Where(r => r.Name == "The Movable Feast"); - - var result = query.FirstOrDefault(); - var queryTranslated = query.LoggedStages; - - Console.WriteLine(queryTranslated.ToJson()); - - .. output:: - - [{ "$match" : { "name" : "The Movable Feast" } }, { "$limit" : NumberLong(1) }] - -.. important:: - - ``LoggedStages`` is not thread-safe. Executing a query and accessing the - associated ``LoggedStages`` property from multiple threads might have - non-deterministic results. - -Troubleshooting ---------------- - -.. include:: /includes/troubleshooting/unsupported-filter-expression.rst \ No newline at end of file diff --git a/source/atlas-vector-search.txt b/source/atlas-vector-search.txt index 4a92f822..73e37027 100644 --- a/source/atlas-vector-search.txt +++ b/source/atlas-vector-search.txt @@ -1,4 +1,21 @@ -.. TODO: integrate into existing page +.. _csharp-atlas-vector-search: + +=================== +Atlas Vector Search +=================== + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: semantic + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol Sample Class ------------ diff --git a/source/connect/connection-options/csot.txt b/source/connect/connection-options/csot.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt new file mode 100644 index 00000000..e69de29b diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 6e0877a6..6c914198 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -18,8 +18,6 @@ using the {+driver-long+} to connect to a MongoDB deployment. This page addresses only connection issues. If you encounter any other issues with MongoDB or the driver, visit the following resources: - - The :ref:`Frequently Asked Questions (FAQ) ` for the - {+driver-short+} - The :ref:`Issues & Help ` page, which has information about reporting bugs, contributing to the driver, and finding additional resources diff --git a/source/crud.txt b/source/crud.txt index 2292d8e8..e18b8ec5 100644 --- a/source/crud.txt +++ b/source/crud.txt @@ -13,7 +13,8 @@ CRUD Operations Insert Documents Query Documents - Update Documents + Update One Document + Update Many Documents Replace Documents Delete Documents Bulk Write Operations diff --git a/source/crud/insert.txt b/source/crud/insert.txt index e7f3e53f..0530e7df 100644 --- a/source/crud/insert.txt +++ b/source/crud/insert.txt @@ -228,8 +228,8 @@ The following code uses the ``InsertMany()`` method to insert five new The ``InsertMany()`` method has no return value. You can verify that your documents were successfully inserted by executing a ``Find()`` -operation on the collection. For an example on how to find a document, -see :ref:`csharp-find-one`. +operation on the collection. For an example of how to find a document, +see :ref:`csharp-find`. .. _csharp-ordered-behavior: diff --git a/source/crud/query/count.txt b/source/crud/query/count.txt index 53dcede1..cc2e4aa1 100644 --- a/source/crud/query/count.txt +++ b/source/crud/query/count.txt @@ -231,7 +231,6 @@ guides: - :ref:`csharp-specify-query` - :ref:`csharp-bson` - :ref:`csharp-guids` -- :ref:`csharp-builders` - :ref:`csharp-poco` API Documentation diff --git a/source/crud/query/find.txt b/source/crud/query/find.txt index 4527d807..f5f2526e 100644 --- a/source/crud/query/find.txt +++ b/source/crud/query/find.txt @@ -1,4 +1,4 @@ -.. _csharp-retrieve: +.. _csharp-find: ============= Retrieve Data diff --git a/source/crud/query/specify-documents-to-return.txt b/source/crud/query/specify-documents-to-return.txt index 8f99716e..54a3b1c7 100644 --- a/source/crud/query/specify-documents-to-return.txt +++ b/source/crud/query/specify-documents-to-return.txt @@ -203,7 +203,7 @@ skipping the first ``10`` documents: Additional Information ---------------------- -For more information about retrieving documents, see the :ref:`csharp-retrieve` guide. +For more information about retrieving documents, see the :ref:`csharp-find` guide. For more information about specifying a query, see the :ref:`csharp-specify-query` guide. diff --git a/source/crud/query/specify-query.txt b/source/crud/query/specify-query.txt index a45d2bb6..bf508679 100644 --- a/source/crud/query/specify-query.txt +++ b/source/crud/query/specify-query.txt @@ -109,8 +109,6 @@ same documents as the preceding example: var result = _guitarsCollection.Find(Builders.Filter.Empty).ToList(); -To learn more about using builders, see :ref:`csharp-builders`. - Comparison Operators -------------------- @@ -171,9 +169,6 @@ same documents as the preceding example: { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null } - -To learn more about using builders, see :ref:`csharp-builders`. - Logical Operators ----------------- @@ -232,8 +227,6 @@ same documents as the preceding example: { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 } -To learn more about using builders, see :ref:`csharp-builders`. - Array Operators --------------- @@ -285,8 +278,6 @@ documents that have 3 elements in the ``models`` field: { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 } { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null } -To learn more about using builders, see :ref:`csharp-builders`. - Element Operators ----------------- @@ -313,8 +304,6 @@ documents that have a ``rating`` field: { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 } { "_id" : 5, "make" : "Ibanez", "models" : ["RG", "AZ"], "establishedYear" : 1957, "rating" : 7 } -To learn more about using builders, see :ref:`csharp-builders`. - Evaluation Operators -------------------- @@ -332,7 +321,7 @@ documents that have a value in the ``make`` field that starts with the letter .. io-code-block:: :copyable: - .. input:: ../../../includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs + .. input:: /includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs :language: csharp .. output:: @@ -341,8 +330,6 @@ documents that have a value in the ``make`` field that starts with the letter { "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 } -To learn more about using builders, see :ref:`csharp-builders`. - Additional Information ---------------------- @@ -355,8 +342,6 @@ following Server Manual Entries: - :manual:`Element Query Operators ` - :manual:`Evaluation Query Operators ` -To learn more about using Builders, see :ref:`csharp-builders`. - To learn how to specify queries using LINQ, see :ref:`csharp-linq`. .. TODO: integrate into existing page diff --git a/source/crud/update-many.txt b/source/crud/update-many.txt index fcb15029..d4db84ef 100644 --- a/source/crud/update-many.txt +++ b/source/crud/update-many.txt @@ -20,8 +20,8 @@ Update Many .. toctree:: :caption: Update Documents - Fields - Arrays + Fields + Arrays .. include:: /includes/page-templates/update/update.rst diff --git a/source/crud/update-one.txt b/source/crud/update-one.txt index ab07f9f9..5bdd1db7 100644 --- a/source/crud/update-one.txt +++ b/source/crud/update-one.txt @@ -20,8 +20,8 @@ Update One .. toctree:: :caption: Update Documents - Fields - Arrays + Fields + Arrays .. include:: /includes/page-templates/update/update.rst diff --git a/source/data-formats/custom-types.txt b/source/data-formats/custom-types.txt index e69de29b..d05e1fc3 100644 --- a/source/data-formats/custom-types.txt +++ b/source/data-formats/custom-types.txt @@ -0,0 +1,26 @@ +.. _csharp-custom-types: + +============ +Custom Types +============ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: polymorphism, serialization, deserialization, poco + +.. toctree:: + :caption: Custom Types + + Class Mapping + POCOs + Polymorphic Objects + Serialization \ No newline at end of file diff --git a/source/data-formats/custom-types/poco.txt b/source/data-formats/custom-types/poco.txt index 143d3059..196249ad 100644 --- a/source/data-formats/custom-types/poco.txt +++ b/source/data-formats/custom-types/poco.txt @@ -728,9 +728,6 @@ Additional Information For a full list of serialization-related attributes, see the `Serialization.Attributes API documentation <{+new-api-root+}/MongoDB.Bson/MongoDB.Bson.Serialization.Attributes.html>`__. -For additional read and write operation examples using POCOs, see the :ref:`Usage Examples -` or the :ref:`CRUD Fundamentals Pages `. - To learn more about how the driver maps BSON documents to POCOs, see :ref:`csharp-class-mapping`. diff --git a/source/data-formats/custom-types/serialization.txt b/source/data-formats/custom-types/serialization.txt index a144c98a..af352a0b 100644 --- a/source/data-formats/custom-types/serialization.txt +++ b/source/data-formats/custom-types/serialization.txt @@ -17,14 +17,6 @@ Serialization :depth: 2 :class: singlecol -.. toctree:: - :caption: Serialization - - Class Mapping - POCOs - Polymorphic Objects - GUIDs - Overview -------- diff --git a/source/data-formats/extended-json.txt b/source/data-formats/extended-json.txt index e69de29b..c2a69aa8 100644 --- a/source/data-formats/extended-json.txt +++ b/source/data-formats/extended-json.txt @@ -0,0 +1,11 @@ +.. _csharp-extended-json: + +============= +Extended JSON +============= + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol \ No newline at end of file diff --git a/source/data-formats/time-series.txt b/source/data-formats/time-series.txt index b1b2e6c0..78384c13 100644 --- a/source/data-formats/time-series.txt +++ b/source/data-formats/time-series.txt @@ -90,7 +90,7 @@ Query a Time Series Collection ------------------------------ To query a time series collection, follow the conventions for retrieving and aggregating -data. For more information about these conventions, see the :ref:`csharp-retrieve` and +data. For more information about these conventions, see the :ref:`csharp-find` and :ref:`csharp-aggregation` guides. Additional Information diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 73da433d..41d961eb 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -19,7 +19,7 @@ Databases and Collections :class: singlecol .. toctree:: - /fundamentals/databases-collections/run-command + /run-command Overview -------- diff --git a/source/get-started.txt b/source/get-started.txt index 0bd5be2b..2642c9ea 100644 --- a/source/get-started.txt +++ b/source/get-started.txt @@ -239,9 +239,10 @@ and retrieves a document that matches a query. Learn more about the {+driver-short+} from the following resources: -- Learn how to insert documents in the :ref:`` section. -- Learn how to find documents in the :ref:`` section. -- Learn how to update documents in the :ref:`` section. -- Learn how to delete documents in the :ref:`` section. +- Learn how to insert documents in the :ref:`` section. +- Learn how to find documents in the :ref:`` section. +- Learn how to update documents in the :ref:`` and + :ref:`` sections. +- Learn how to delete documents in the :ref:`` section. .. include:: /includes/get-started/quickstart-troubleshoot.rst \ No newline at end of file diff --git a/source/index.txt b/source/index.txt index b764a51f..50626999 100644 --- a/source/index.txt +++ b/source/index.txt @@ -22,7 +22,7 @@ MongoDB C# Driver Indexes Run a Database Command Atlas Search - Atlas Vector Search + Atlas Vector Search Logging and Monitoring Security Integrations diff --git a/source/integrations.txt b/source/integrations.txt index f17bf8e7..65fe78ad 100644 --- a/source/integrations.txt +++ b/source/integrations.txt @@ -21,7 +21,7 @@ Integrations and Tools .. toctree:: :maxdepth: 1 - :ref:`OData ` + OData Entity Framework Provider {+analyzer-short+} diff --git a/source/reference/issues-and-help.txt b/source/issues-and-help.txt similarity index 100% rename from source/reference/issues-and-help.txt rename to source/issues-and-help.txt diff --git a/source/reference.txt b/source/reference.txt index 780ca790..d1d5e55b 100644 --- a/source/reference.txt +++ b/source/reference.txt @@ -14,6 +14,7 @@ Reference .. toctree:: Quick Reference + Release Notes Compatibility Upgrade Versions 2.0 to 2.18 diff --git a/source/reference/quick-reference.txt b/source/reference/quick-reference.txt index dc82f454..8b03bd9e 100644 --- a/source/reference/quick-reference.txt +++ b/source/reference/quick-reference.txt @@ -23,7 +23,6 @@ their related reference and API documentation. * - | **Find a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -47,7 +46,6 @@ their related reference and API documentation. * - | **Find a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.FindAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -72,7 +70,6 @@ their related reference and API documentation. * - | **Find Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -100,7 +97,6 @@ their related reference and API documentation. * - | **Find Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. io-code-block:: @@ -128,7 +124,6 @@ their related reference and API documentation. * - | **Insert a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -139,7 +134,6 @@ their related reference and API documentation. * - | **Insert a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -150,7 +144,6 @@ their related reference and API documentation. * - | **Insert Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertMany.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -165,7 +158,6 @@ their related reference and API documentation. * - | **Insert Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.InsertManyAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -180,7 +172,6 @@ their related reference and API documentation. * - | **Update a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -197,7 +188,6 @@ their related reference and API documentation. * - | **Update a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -214,7 +204,6 @@ their related reference and API documentation. * - | **Update Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateMany.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -231,7 +220,6 @@ their related reference and API documentation. * - | **Update Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.UpdateManyAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -270,7 +258,6 @@ their related reference and API documentation. * - | **Replace a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -303,7 +290,6 @@ their related reference and API documentation. * - | **Replace a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.ReplaceOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -336,7 +322,6 @@ their related reference and API documentation. * - | **Delete a Document** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteOne.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -350,7 +335,6 @@ their related reference and API documentation. * - | **Delete a Document (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteOneAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -364,7 +348,6 @@ their related reference and API documentation. * - | **Delete Multiple Documents** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteMany.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp @@ -378,7 +361,6 @@ their related reference and API documentation. * - | **Delete Multiple Documents (Async)** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.DeleteManyAsync.html>`__ - | :ref:`Usage Example ` | :ref:`Fundamentals ` - .. code-block:: csharp diff --git a/source/reference/release-notes.txt b/source/reference/release-notes.txt index 263e0fc9..28687c76 100644 --- a/source/reference/release-notes.txt +++ b/source/reference/release-notes.txt @@ -1,8 +1,9 @@ .. _csharp-whats-new: +.. _csharp-release-notes: -========== -What's New -========== +============= +Release Notes +============= .. contents:: On this page :local: @@ -61,7 +62,8 @@ The 3.1 driver release includes the following new features: in the Atlas Search documentation. - Adds support for the ``sort`` option to be passed to update commands. To learn more about - using update commands with the {+driver-short+}, see :ref:`csharp-crud-write-operations`. + using update commands with the {+driver-short+}, see the :ref:`csharp-update-one` and + :ref:`csharp-update-many` guides. For more information about this release, see the :github:`v3.1 release notes `. diff --git a/source/security.txt b/source/security.txt index 82b6bbe4..56e5458a 100644 --- a/source/security.txt +++ b/source/security.txt @@ -14,5 +14,5 @@ Security .. toctree:: Authentication - In-Use Encryption + In-Use Encryption TLS/SSL \ No newline at end of file diff --git a/source/security/authentication.txt b/source/security/authentication.txt index e6a52726..c7944be5 100644 --- a/source/security/authentication.txt +++ b/source/security/authentication.txt @@ -20,12 +20,12 @@ Authentication Mechanisms .. toctree:: :caption: Authentication - SCRAM - X.509 - AWS IAM - OIDC - LDAP (PLAIN) - Kerberos (GSSAPI) + SCRAM + X.509 + AWS IAM + OIDC + LDAP (PLAIN) + Kerberos (GSSAPI) Overview -------- From 862f417346c3a9db2ead2c695cbb2b1a20840e7a Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Mon, 7 Apr 2025 10:57:07 -0500 Subject: [PATCH 10/10] mm feedback --- source/databases-collections.txt | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/databases-collections.txt b/source/databases-collections.txt index 41d961eb..9cf8ad93 100644 --- a/source/databases-collections.txt +++ b/source/databases-collections.txt @@ -18,9 +18,6 @@ Databases and Collections :depth: 2 :class: singlecol -.. toctree:: - /run-command - Overview --------