Backport 655 to v5.0 (#662)

* [Java Sync] P1 - Shift Java ToC (#615)

* fix redirects (#616)

* [Java Sync] P2 - Shift Java ToC  (#617)

* toc tweaks

* databases adn collections

* rm reference landing

* vale error

Author: rachel-mack

.github/workflows/vale-tdbx.yml

@@ -12,6 +12,9 @@ jobs:
       - name: checkout
         uses: actions/checkout@master
 
+      - name: Install docutils
+        run: sudo apt-get install -y docutils
+
       - id: files
         uses: masesgroup/retrieve-changed-files@v2
         with:

config/redirects

@@ -5,9 +5,67 @@ define: versions v4.3 v4.4 v4.5 v4.6 v4.7 v4.8 v4.9 v4.10 v4.11 v5.0 master
 raw: ${prefix}/ -> ${base}/current/
 raw: ${prefix}/master -> ${base}/upcoming/
 
-[*-master]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${base}/${version}/fundamentals/stable-api/
+[*-v5.2]: ${prefix}/${version}/fundamentals/versioned-api/ -> ${base}/${version}/fundamentals/stable-api/
 [*-v4.6]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/fundamentals/crud/read-operations/retrieve/
 [*-master]: ${prefix}/${version}/fundamentals/csfle/ -> ${base}/${version}/fundamentals/encrypt-fields/
 [*-master]: ${prefix}/${version}/fundamentals/crud/write-operations/change-a-document/ -> ${base}/${version}/fundamentals/crud/write-operations/modify/
 [*-v4.10]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/
 [*-v4.8]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/ -> ${base}/${version}/crud/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/ -> ${base}/${version}/crud/read-operations/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/retrieve/ -> ${base}/${version}/crud/read-operations/retrieve/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/cursor/ -> ${base}/${version}/crud/read-operations/cursor/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/change-streams/ -> ${base}/${version}/logging-monitoring/change-streams/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/sort/ -> ${base}/${version}/crud/read-operations/sort/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/skip/ -> ${base}/${version}/crud/read-operations/skip/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/limit/ -> ${base}/${version}/crud/read-operations/limit/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/project/ -> ${base}/${version}/crud/read-operations/project/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/geo/ -> ${base}/${version}/crud/read-operations/geo/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/read-operations/text/ -> ${base}/${version}/crud/read-operations/text/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/ -> ${base}/${version}/crud/write-operations/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/insert/ -> ${base}/${version}/crud/write-operations/insert/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/delete/ -> ${base}/${version}/crud/write-operations/delete/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/modify/ -> ${base}/${version}/crud/write-operations/modify/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/embedded-arrays/ -> ${base}/${version}/crud/write-operations/embedded-arrays/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/upsert/ -> ${base}/${version}/crud/write-operations/upsert/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/write-operations/bulk/ -> ${base}/${version}/crud/write-operations/bulk/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/query-document/ -> ${base}/${version}/crud/query-document/
+[v5.0-master]: ${prefix}/${version}/fundamentals/crud/compound-operations/ -> ${base}/${version}/crud/compound-operations/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/ -> ${base}/${version}/data-formats/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-bson/ -> ${base}/${version}/data-formats/document-data-format-bson/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-extended-json/ -> ${base}/${version}/data-formats/document-data-format-extended-json/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/documents/ -> ${base}/${version}/data-formats/documents/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-pojo/ -> ${base}/${version}/data-formats/document-data-format-pojo/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/document-data-format-record/ -> ${base}/${version}/data-formats/document-data-format-record/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/pojo-customization/ -> ${base}/${version}/data-formats/pojo-customization/
+[v5.0-master]: ${prefix}/${version}/fundamentals/data-formats/codecs/ -> ${base}/${version}/data-formats/codecs/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/ -> ${base}/${version}/connection/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/connect/ -> ${base}/${version}/connection/connect/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/connection-options/ -> ${base}/${version}/connection/connection-options/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/mongoclientsettings/ -> ${base}/${version}/connection/mongoclientsettings/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/network-compression/ -> ${base}/${version}/connection/network-compression/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/socks/ -> ${base}/${version}/connection/socks/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/tls/ -> ${base}/${version}/security/tls/
+[v5.0-master]: ${prefix}/${version}/fundamentals/connection/jndi/ -> ${base}/${version}/connection/jndi/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/ -> ${base}/${version}/crud/builders/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/aggregates/ -> ${base}/${version}/crud/builders/aggregates/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/filters/ -> ${base}/${version}/crud/builders/filters/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/indexes/ -> ${base}/${version}/crud/builders/indexes/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/projections/ -> ${base}/${version}/crud/builders/projections/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/sort/ -> ${base}/${version}/crud/builders/sort/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/updates/ -> ${base}/${version}/crud/builders/updates/
+[v5.0-master]: ${prefix}/${version}/fundamentals/builders/vector-search -> ${base}/${version}/atlas-vector-search/
+[v5.0-master]: ${prefix}/${version}/fundamentals/aggregation/ -> ${base}/${version}/crud/aggregation/
+[v5.0-master]: ${prefix}/${version}/fundamentals/aggregation-expression-operations/ -> ${base}/${version}/crud/aggregation-expression-operations/
+[v5.0-master]: ${prefix}/${version}/fundamentals/collations/ -> ${base}/${version}/crud/collations/
+[v5.0-master]: ${prefix}/${version}/fundamentals/stable-api/ -> ${base}/${version}/connection/stable-api/
+[v5.0-master]: ${prefix}/${version}/connection-troubleshooting/ -> ${base}/${version}/connection/connection-troubleshooting/
+[v5.0-master]: ${prefix}/${version}/fundamentals/gridfs/ -> ${base}/${version}/crud/gridfs/
+[v5.0-master]: ${prefix}/${version}/fundamentals/transactions/ -> ${base}/${version}/crud/transactions/
+[v5.0-master]: ${prefix}/${version}/fundamentals/time-series/ -> ${base}/${version}/data-formats/time-series/
+[v5.0-master]: ${prefix}/${version}/quick-start/ -> ${base}/${version}/getting-started/
+[v5.0-master]: ${prefix}/${version}/fundamentals/databases-collections/ -> ${base}/${version}/getting-started/databases-collections/
+[v5.0-master]: ${prefix}/${version}/integrations/ -> ${base}/${version}/getting-started/integrations/
+[v5.0-master]: ${prefix}/${version}/quick-reference/ -> ${base}/${version}/getting-started/quick-reference/
+[v5.0-master]: ${prefix}/${version}/fundamentals/enterprise-auth/ -> ${base}/${version}/security/enterprise-auth/
+[v5.0-master]: ${prefix}/${version}/connection/socks/ -> ${base}/${version}/security/socks/

snooty.toml

@@ -7,11 +7,13 @@ intersphinx = [
 ]
 
 toc_landing_pages = [
-    "/fundamentals/connection",
-    "/fundamentals/crud",
-    "/fundamentals/builders",
-    "/fundamentals/aggregation",
-    "/usage-examples",
+    "/getting-started",
+    "/connection",
+    "/crud",
+    "/aggregation",
+    "/builders",
+    "/data-formats",
+    "/api-documentation"
 ]
 sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 

source/fundamentals/aggregation.txt renamed to source/aggregation.txt

@@ -17,6 +17,10 @@ Aggregation
    :depth: 2
    :class: singlecol
 
+.. toctree::
+
+   Aggregation Expressions </aggregation/aggregation-expression-operations>
+
 Overview
 --------
 

source/fundamentals/aggregation-expression-operations.txt renamed to source/aggregation/aggregation-expression-operations.txt

@@ -0,0 +1,21 @@
+.. _java-atlas-search:
+
+============
+Atlas Search
+============
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene
+   :description: Learn about how to use Atlas Search in the {+driver-long+}.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+See :atlas:`Atlas Search </atlas-search/>` in the MongoDB Atlas documentation.

source/atlas-search.txt

@@ -0,0 +1,107 @@
+.. _java-atlas-vector-search:
+
+===================
+Atlas Vector Search
+===================
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene, AI, artificial intelligence, code example, semantic, nearest
+   :description: Learn about how to use Atlas Vector Search in the {+driver-long+}.
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In this guide, you can learn how to use the :atlas:`Atlas Vector Search
+</atlas-vector-search/vector-search-overview/>` feature
+in the {+driver-short+}. The ``Aggregates``  builders class provides the
+the ``vectorSearch()`` helper method that you can use to
+create a :atlas:`$vectorSearch </atlas-vector-search/vector-search-stage/>`
+pipeline stage. This pipeline stage allows you to perform a **semantic
+search** on your documents. A semantic search is a type of search which
+locates information that is similar in meaning, but not necessarily
+identical, to your provided search term or phrase.
+
+.. important:: Feature Compatibility
+
+   To learn what versions of MongoDB Atlas support this feature, see
+   :atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
+   in the MongoDB Atlas documentation.
+
+Perform a Vector Search
+-----------------------
+
+To use this feature, you must create a vector search index and index your
+vector embeddings. To learn about how to programmatically create a
+vector search index, see the :ref:`java-search-indexes` section in the
+Indexes guide. To learn more about vector embeddings, see
+:atlas:`How to Index Vector Embeddings for Vector Search
+</atlas-search/field-types/knn-vector/>` in the Atlas documentation.
+
+After you create a vector search index on your vector embeddings, you
+can reference this index in your pipeline stage, as shown in the
+following section.
+
+Vector Search Example
+~~~~~~~~~~~~~~~~~~~~~
+
+The following example shows how to build an aggregation pipeline that uses the
+``vectorSearch()`` and ``project()`` methods to compute a vector search score:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java
+   :start-after: // begin vectorSearch
+   :end-before: // end vectorSearch
+   :language: java
+   :dedent:
+
+.. tip:: Query Vector Type
+
+   The preceding example creates an instance of ``BinaryVector`` to
+   serve as the query vector, but you can also create a ``List`` of
+   ``Double`` instances. However, we recommend that you use the
+   ``BinaryVector`` type to improve storage efficiency.
+
+The following example shows how you can run the aggregation and print
+the vector search meta-score from the result of the preceding
+aggregation pipeline:
+
+.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggBuilders.java
+   :start-after: // begin vectorSearch-output
+   :end-before: // end vectorSearch-output
+   :language: java
+   :dedent:
+
+.. tip:: Java Driver Vector Search Examples
+    
+   Visit the :atlas:`Atlas documentation </atlas-vector-search/tutorials/>`
+   to find more tutorials on using the {+driver-short+} to perform Atlas
+   Vector Searches.
+
+API Documentation
+-----------------
+
+To learn more about the methods and types mentioned in this
+guide, see the following API documentation:
+
+- `Aggregates.vectorSearch()
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#vectorSearch(com.mongodb.client.model.search.FieldSearchPath,java.lang.Iterable,java.lang.String,long,com.mongodb.client.model.search.VectorSearchOptions)>`__
+
+- `FieldSearchPath
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/FieldSearchPath.html>`__
+
+- `VectorSearchOptions
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/VectorSearchOptions.html>`__
+
+- `Projections.metaVectorSearchScore()
+  <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Projections.html#metaVectorSearchScore(java.lang.String)>`__
+
+- `BinaryVector <{+api+}/apidocs/bson/org/bson/BinaryVector.html>`__

source/atlas-vector-search.txt

@@ -8,12 +8,12 @@ Builders
 
 .. toctree::
 
-   Aggregation </fundamentals/builders/aggregates>
-   Filters </fundamentals/builders/filters>
-   Indexes </fundamentals/builders/indexes>
-   Projection </fundamentals/builders/projections>
-   Sort </fundamentals/builders/sort>
-   Update </fundamentals/builders/updates>
+   Aggregation </builders/aggregates>
+   Filters </builders/filters>
+   Indexes </builders/indexes>
+   Projection </builders/projections>
+   Sort </builders/sort>
+   Update </builders/updates>
 
 .. contents:: On this page
    :local:

source/fundamentals/builders.txt renamed to source/builders.txt

@@ -15,6 +15,10 @@ Aggregates Builders
    :depth: 2
    :class: singlecol
 
+.. toctree::
+
+   Atlas Vector Search </builders/vector-search>
+
 .. _aggregates-builders:
 
 Overview
@@ -86,7 +90,7 @@ Project
 
 Use the ``project()`` method to create a :manual:`$project </reference/operator/aggregation/project/>`
 pipeline stage that project specified document fields. Field projection
-in aggregation follows the same rules as :doc:`field projection in queries </fundamentals/crud/read-operations/project>`.
+in aggregation follows the same rules as :doc:`field projection in queries </crud/read-operations/project>`.
 
 .. tip::
 

source/fundamentals/builders/aggregates.txt renamed to source/builders/aggregates.txt

@@ -20,7 +20,7 @@ In this guide, you can learn how to use **builders** to specify
 
 Builders are classes provided by the MongoDB Java driver that help you
 construct :ref:`BSON <bson>` objects. To learn more, see our :doc:`guide
-on builders </fundamentals/builders/>`. 
+on builders </builders/>`. 
 
 Filters are the operations MongoDB uses to limit your results to what
 you want to see. 

source/fundamentals/builders/filters.txt renamed to source/builders/filters.txt

@@ -16,7 +16,7 @@ Overview
 --------
 
 In this guide, you can learn how to specify **indexes** using
-:doc:`builders </fundamentals/builders/>` in the MongoDB Java driver.
+:doc:`builders </builders/>` in the MongoDB Java driver.
 The ``Indexes`` builder provides helper methods for constructing the
 following types of indexes:  
 

source/fundamentals/builders/indexes.txt renamed to source/builders/indexes.txt

@@ -16,7 +16,7 @@ Overview
 --------
 
 In this guide, you can learn how to specify **projections** using
-:doc:`builders </fundamentals/builders/>` in the MongoDB Java driver.
+:doc:`builders </builders/>` in the MongoDB Java driver.
 
 MongoDB supports **field projection**, specifying which fields to include and exclude when returning results from a
 query. Projection in MongoDB follows some basic rules:

source/fundamentals/builders/projections.txt renamed to source/builders/projections.txt

@@ -32,14 +32,14 @@ examples of sort criteria are:
 
 Builders are classes provided by the MongoDB Java driver that help you
 construct :ref:`BSON <bson>` objects. To learn more, see our :doc:`guide
-on builders </fundamentals/builders/>`. 
+on builders </builders/>`. 
 
 You should read this guide if you would like to use builders to specify sort
 criteria for your queries.
 
 If you want to learn the fundamentals of sorting in the MongoDB Java
 driver, consider reading our
-:doc:`guide on sorting </fundamentals/crud/read-operations/sort/>`.
+:doc:`guide on sorting </crud/read-operations/sort/>`.
 
 .. _sorts-builders-sort-sample:
 
@@ -63,7 +63,7 @@ criteria operators supported by MongoDB. These methods return a ``Bson`` object
 that you can pass to the  ``sort()`` method of a ``FindIterable`` instance or to 
 ``Aggregates.sort()``. If you want to learn more about the ``Aggregates``
 class, see our 
-:doc:`guide on the Aggregates builder </fundamentals/builders/aggregates>`.
+:doc:`guide on the Aggregates builder </builders/aggregates>`.
 
 For more information about the classes and interfaces in this section, see the
 following API Documentation:

source/fundamentals/builders/sort.txt renamed to source/builders/sort.txt

@@ -6,13 +6,13 @@ Connection Guide
 
 .. toctree::
 
-   Connect to MongoDB </fundamentals/connection/connect>
-   Connection Options </fundamentals/connection/connection-options>
-   MongoClient Settings </fundamentals/connection/mongoclientsettings>
-   Network Compression </fundamentals/connection/network-compression>
-   TLS/SSL </fundamentals/connection/tls>
-   SOCKS5 Proxy </fundamentals/connection/socks>
-   JNDI Datasource </fundamentals/connection/jndi>
+   Connect to MongoDB </connection/connect>
+   Connection Options </connection/connection-options>
+   MongoClient Settings </connection/mongoclientsettings>
+   Stable API </connection/stable-api>
+   Network Compression </connection/network-compression>
+   JNDI Datasource </connection/jndi>
+   Connection Troubleshooting </connection/connection-troubleshooting>
    AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
 
 .. contents:: On this page

source/fundamentals/builders/updates.txt renamed to source/builders/updates.txt

@@ -26,9 +26,7 @@ Use the ``MongoClients.create()`` method to construct a ``MongoClient``.
 
    As each ``MongoClient`` represents a thread-safe pool of connections to the
    database, most applications only require a single instance of a
-   ``MongoClient``, even across multiple threads. To learn more about
-   how connection pools work in the driver, see the :ref:`FAQ page <java-faq-connection-pool>`.
-
+   ``MongoClient``, even across multiple threads. 
 All resource usage limits, such as max connections, apply to individual
 ``MongoClient`` instances.
 

source/usage-examples/command.txt renamed to source/command.txt

@@ -194,7 +194,7 @@ parameters of the connection URI to specify the behavior of the client.
    * - **authMechanism**
      - string
      - Specifies the :doc:`authentication mechanism
-       </fundamentals/auth>` that the driver uses if a credential
+       </security/auth>` that the driver uses if a credential
        was supplied.
 
        | **Default**: By default, the client picks the most secure

source/fundamentals/connection.txt renamed to source/connection.txt

@@ -31,8 +31,6 @@ Connection Troubleshooting
            finding more resources
          - The `MongoDB Community Forums <{+communityForums+}>`__ for
            questions, discussions, or general technical support
-         - The :ref:`Frequently Asked Questions (FAQ) <java-faq>` page for
-           answers to common questions about the {+driver-short+}
 
    .. replacement:: server-selection-timeout-error
 
@@ -150,11 +148,6 @@ Connection Troubleshooting
 
       ``maxIdleTimeMS``
 
-   .. replacement:: connection-pools-learn-more
-
-      To learn more about how connection pooling works in the driver, see
-      :ref:`java-faq-connection-pool` in the FAQ.
-
    .. replacement:: scram-failure-error
 
       .. code-block::