From c8c26ed2707484ede6a00a2c04c317bd1dca8f3c Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 19 Aug 2024 16:12:51 -0400 Subject: [PATCH 1/9] DOCSP-39685: Indexes landing page --- .../usage-examples/index-code-examples.java | 105 ++++++ .../sample-index-application.java | 39 ++ source/indexes.txt | 355 +++++++++--------- 3 files changed, 323 insertions(+), 176 deletions(-) create mode 100644 source/includes/usage-examples/index-code-examples.java create mode 100644 source/includes/usage-examples/sample-index-application.java diff --git a/source/includes/usage-examples/index-code-examples.java b/source/includes/usage-examples/index-code-examples.java new file mode 100644 index 00000000..1a9b3c4e --- /dev/null +++ b/source/includes/usage-examples/index-code-examples.java @@ -0,0 +1,105 @@ +package org.example; + +import com.mongodb.ConnectionString; +import com.mongodb.MongoClientSettings; +import com.mongodb.ServerApi; +import com.mongodb.ServerApiVersion; + +import com.mongodb.client.model.ClusteredIndexOptions; +import com.mongodb.client.model.CreateCollectionOptions; +import com.mongodb.client.model.IndexOptions; +import com.mongodb.client.model.Indexes; +import com.mongodb.reactivestreams.client.*; +import org.bson.Document; +import reactor.core.publisher.Flux; + +public class IndexOperations { + public static void main(String[] args) { + // Replace the placeholder with your Atlas connection string + String uri = ""; + + // Construct a ServerApi instance using the ServerApi.builder() method + ServerApi serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .build(); + + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString(uri)) + .serverApi(serverApi) + .build(); + + // Create a new client and connect to the server + try (MongoClient mongoClient = MongoClients.create(settings)) { + MongoDatabase database = mongoClient.getDatabase("sample_mflix"); + MongoCollection collection = database.getCollection("movies"); + + // start-single-field + collection.createIndex(Indexes.ascending("")); + // end-single-field + + // start-compound + collection.createIndex(Indexes.ascending("", "")); + // end-compound + + // start-multikey + collection.createIndex(Indexes.ascending("")); + // end-multikey + + // start-search-create + Document index = new Document("mappings", new Document("dynamic", true)); + collection.createSearchIndex("", index); + // end-search-create + + // start-search-list + ListSearchIndexesPublisher listIndexesPublisher = collection.listSearchIndexes(); + + Flux.from(listIndexesPublisher) + .doOnNext(System.out::println) + .blockLast(); + // end-search-list + + // start-search-update + Document newIndex = new Document("mappings", new Document("dynamic", true)); + collection.updateSearchIndex("", newIndex); + // end-search-update + + // start-search-delete + collection.dropIndex(""); + // end-search-delete + + // start-text + collection.createIndex(Indexes.text("")); + // end-text + + // start-geo + collection.createIndex(Indexes.geo2dsphere("")); + // end-geo + + // start-unique + IndexOptions indexOptions = new IndexOptions().unique(true); + collection.createIndex(Indexes.ascending(""), indexOptions); + // end-unique + + // start-wildcard + collection.createIndex(Indexes.ascending("$**")); + // end-wildcard + + // start-clustered + ClusteredIndexOptions clusteredIndexOptions = new ClusteredIndexOptions( + Indexes.ascending("_id"), + true + ); + + CreateCollectionOptions createCollectionOptions= new CreateCollectionOptions() + .clusteredIndexOptions(clusteredIndexOptions); + + MongoCollection collection = database.createCollection(""); + // end-remove + } + } +} \ No newline at end of file diff --git a/source/includes/usage-examples/sample-index-application.java b/source/includes/usage-examples/sample-index-application.java new file mode 100644 index 00000000..0660e310 --- /dev/null +++ b/source/includes/usage-examples/sample-index-application.java @@ -0,0 +1,39 @@ +package org.example; + +import com.mongodb.ConnectionString; +import com.mongodb.MongoClientSettings; +import com.mongodb.ServerApi; +import com.mongodb.ServerApiVersion; + +import com.mongodb.client.model.Indexes; +import com.mongodb.reactivestreams.client.*; +import org.bson.Document; +import org.bson.conversions.Bson; +import reactor.core.publisher.Flux; + +public class IndexOperations { + public static void main(String[] args) { + // Replace the placeholder with your Atlas connection string + String uri = ""; + + // Construct a ServerApi instance using the ServerApi.builder() method + ServerApi serverApi = ServerApi.builder() + .version(ServerApiVersion.V1) + .build(); + + MongoClientSettings settings = MongoClientSettings.builder() + .applyConnectionString(new ConnectionString(uri)) + .serverApi(serverApi) + .build(); + + // Create a new client and connect to the server + try (MongoClient mongoClient = MongoClients.create(settings)) { + MongoDatabase database = mongoClient.getDatabase(""); + MongoCollection collection = database.getCollection(""); + + // Start example code here + + // End example code here + } + } +} \ No newline at end of file diff --git a/source/indexes.txt b/source/indexes.txt index 2c76d4fa..df856147 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -1,249 +1,252 @@ .. _java-rs-indexes: -============== -Create Indexes -============== - -.. facet:: - :name: genre - :values: reference - -.. meta:: - :keywords: code example, optimize, covered query +================================= +Optimize Queries by Using Indexes +================================= .. contents:: On this page :local: :backlinks: none - :depth: 1 + :depth: 2 :class: singlecol -Indexes support the efficient execution of queries in MongoDB. To -create an index on a field or fields, pass an index specification -document to the ``MongoCollection.createIndex()`` method. - -The {+driver-short+} provides the ``Indexes`` class that includes -static factory methods to create index specification documents for the -various MongoDB index key types. To learn more about index types, see -:manual:`Indexes ` in the Server manual. - -.. note:: - - MongoDB only creates an index if an index of the same specification - does not already exist. - -Prerequisites -------------- - -You must include the following import statements in your program to run the -code examples in this guide: - -.. code-block:: java - - import com.mongodb.reactivestreams.client.MongoClient; - import com.mongodb.reactivestreams.client.MongoClients; - import com.mongodb.reactivestreams.client.MongoDatabase; - import com.mongodb.reactivestreams.client.MongoCollection; - import org.bson.Document; - - import com.mongodb.client.model.Indexes; - import com.mongodb.client.model.IndexOptions; - import com.mongodb.client.model.Filters; - -.. include:: /includes/subscriber-note.rst - -Connect to a MongoDB Deployment -------------------------------- - -.. include:: /includes/connect-section.rst - -Ascending Index ---------------- - -To create a specification for an ascending index, use the -``Indexes.ascending()`` static helper method. - -Single Ascending Index -~~~~~~~~~~~~~~~~~~~~~~ +.. facet:: + :name: genre + :values: reference + +.. meta:: + :description: Learn how to use indexes by using the MongoDB Java Reactive Streams driver. + :keywords: query, optimization, efficiency, usage example, code example -The following example creates an ascending index on the ``name`` field: +Overview +-------- -.. code-block:: java +On this page, you can see copyable code examples that show how to manage different +types of indexes by using the {+driver-short+}. - collection.createIndex(Indexes.ascending("name")) - .subscribe(new PrintToStringSubscriber()); +.. .. tip:: -Compound Ascending Index -~~~~~~~~~~~~~~~~~~~~~~~~ +.. To learn more about working with indexes, see the :ref:`java-rs-work-with-indexes` +.. guide. To learn more about any of the indexes shown on this page, see the link +.. provided in each section. -The following example creates an ascending compound index on the -``stars`` field and the ``name`` field: +To use an example from this page, copy the code example into the +:ref:`sample application ` or your own application. +Be sure to replace all placeholders in the code examples, such as ````, with +the relevant values for your MongoDB deployment. -.. code-block:: java +.. _java-rs-index-sample: - collection.createIndex(Indexes.ascending("stars", "name")) - .subscribe(new PrintToStringSubscriber()); +.. include:: /includes/usage-examples/sample-app-intro.rst -To view an alternative way to create a compound index, see the :ref:`Compound -Indexes ` section. +.. literalinclude:: /includes/usage-examples/sample-index-application.java + :language: java + :copyable: + :linenos: + :emphasize-lines: 34-36 -Descending Index ----------------- +Single Field Index +------------------ -To create a specification of a descending index, use the -``Indexes.descending()`` static helper method. +The following example creates an ascending index on the specified field: -Single Descending Key Index -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-single-field + :end-before: end-single-field + :language: java + :copyable: + :dedent: -The following example creates a descending index on the ``stars`` field: +To learn more about single field indexes, see the :ref:`java-rs-single-field-index` guide. -.. code-block:: java +Compound Index +-------------- - collection.createIndex(Indexes.descending("stars")) - .subscribe(new PrintToStringSubscriber()); +The following example creates a compound index on the specified fields: -Compound Descending Key Index -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-compound + :end-before: end-compound + :language: java + :copyable: + :dedent: -The following example creates a descending compound index on the -``stars`` field and the ``name`` field: +.. TODO: To learn more about compound indexes, see the :ref:`java-rs-compound-index` +.. guide. -.. code-block:: java +Multikey Index +-------------- - collection.createIndex(Indexes.descending("stars", "name")) - .subscribe(new PrintToStringSubscriber()); +The following example creates a multikey index on the specified array-valued field: -To view an alternative way to create a compound index, see the :ref:`Compound -Indexes ` section. +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-multikey + :end-before: end-multikey + :language: java + :copyable: + :dedent: -.. _javars-compound-indexes: +.. TODO To learn more about multikey indexes, see the :ref:`java-rs-multikey-index` +.. guide. -Compound Indexes +Geospatial Index ---------------- -To create a specification for a compound index, use the -``Indexes.compoundIndex()`` static helper method. - -.. note:: +The following example creates a 2dsphere index on the specified field that contains +GeoJSON objects: - To create a specification for a compound index where all the keys are - ascending, you can use the ``ascending()`` method. To create a - specification for a compound index where all the keys are descending, - you can use the ``descending()`` method. +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-geo + :end-before: end-geo + :language: java + :copyable: + :dedent: -The following example creates a compound index on the ``stars`` field -in descending order and the ``name`` field in ascending order: +.. TODO: To learn more about geospatial indexes, see the :ref:`java-rs-geospatial-index` +.. guide. -.. code-block:: java +Unique Index +------------ - collection.createIndex( - Indexes.compoundIndex(Indexes.descending("stars"), - Indexes.ascending("name")) - ).subscribe(new PrintToStringSubscriber()); +The following example creates a unique index on the specified field: -Text Indexes ------------- +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-unique + :end-before: end-unique + :language: java + :copyable: + :dedent: -MongoDB provides text indexes to support text search of string -content. Text indexes can include any field whose value is a string or -an array of string elements. To create a specification for a text -index, use the ``Indexes.text()`` static helper method. +.. TODO: To learn more about unique indexes, see the :ref:`java-rs-unique-index` +.. guide. -The following example creates a text index on the ``name`` field: +Wildcard Index +-------------- -.. code-block:: java +The following example creates a wildcard index in the specified collection: - collection.createIndex(Indexes.text("name")) - .subscribe(new PrintToStringSubscriber()); +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-wildcard + :end-before: end-wildcard + :language: java + :copyable: + :dedent: -Hashed Index ------------- +.. TODO: To learn more about wildcard indexes, see the :ref:`java-rs-wildcard-index` +.. guide. -To create a specification for a hashed index index, use the -``Indexes.hashed()`` static helper method. +Clustered Index +--------------- -The following example creates a hashed index on the ``_id`` field: +The following example creates a new collection with a clustered index on the ``_id`` +field: -.. code-block:: java +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-clustered + :end-before: end-clustered + :language: java + :copyable: + :dedent: - collection.createIndex(Indexes.hashed("_id")) - .subscribe(new PrintToStringSubscriber()); +.. TODO: To learn more about wildcard indexes, see the :ref:`java-rs-clustered-index` +.. guide. -Geospatial Indexes ------------------- +Atlas Search Index Management +----------------------------- -To support geospatial queries, MongoDB supports various geospatial +The following sections contain code examples that describe how to manage Atlas Search indexes. -2dsphere -~~~~~~~~ +.. TODO: To learn more about Atlas search indexes, see the :ref:`java-rs-atlas-search-index` +.. guide. -To create a specification for a ``2dsphere`` index, use the -``Indexes.geo2dsphere()`` static helper method. +Create Search Index +~~~~~~~~~~~~~~~~~~~ -The following example creates a ``2dsphere`` index on the -``contact.location`` field: +The following example creates an Atlas search index on the specified field: -.. code-block:: java +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-search-create + :end-before: end-search-create + :language: java + :copyable: + :dedent: - collection.createIndex(Indexes.geo2dsphere("contact.location")) - .subscribe(new PrintToStringSubscriber()); +.. TODO: To learn more about creating serach indexes, see the :ref:`java-rs-atlas-search-index-create` +.. guide. -IndexOptions ------------- +List Search Indexes +~~~~~~~~~~~~~~~~~~~ -In addition to the index specification document, the -``createIndex()`` method can take an index options document, that -directs the driver to create unique indexes or partial indexes. +The following example prints a list of Atlas search indexes in the specified collection: -The driver provides the ``IndexOptions`` class to specify various -index options. +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-search-list + :end-before: end-search-list + :language: java + :copyable: + :dedent: -Add the following import statement to your code to create an -``IndexOptions`` instance. +.. TODO: To learn more about listing search indexes, see the :ref:`java-rs-atlas-search-index-list` +.. guide. -.. code-block:: java +Update Search Indexes +~~~~~~~~~~~~~~~~~~~~~ - import com.mongodb.client.model.IndexOptions; +The following example updates an existing Atlas search index with the specified +new index definition: -Unique Index -~~~~~~~~~~~~ +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-search-update + :end-before: end-search-update + :language: java + :copyable: + :dedent: -The following code specifies the ``unique(true)`` option to create a -unique index on the ``name`` and ``stars`` fields: +.. TODO: To learn more about updating search indexes, see the :ref:`java-rs-atlas-search-index-update` +.. guide. -.. code-block:: java +Delete Search Indexes +~~~~~~~~~~~~~~~~~~~~~ - IndexOptions indexOptions = new IndexOptions().unique(true); - collection.createIndex(Indexes.ascending("name", "stars"), indexOptions) - .subscribe(new PrintToStringSubscriber()); +The following example deletes an Atlas search index with the specified name: -Partial Index -~~~~~~~~~~~~~ +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-search-delete + :end-before: end-search-delete + :language: java + :copyable: + :dedent: -To create a partial index, include the ``partialFilterExpression`` index -option. +.. TODO: To learn more about deleting search indexes, see the :ref:`java-rs-atlas-search-index-drop` +.. guide. -The following example creates a partial index on documents in which the -value of the ``status`` field is ``"A"``. +Text Index +---------- -.. code-block:: java +The following example creates a text index on the specified string field: - IndexOptions partialFilterIndexOptions = new IndexOptions() - .partialFilterExpression(Filters.exists("contact.email")); - collection.createIndex( - Indexes.descending("name", "stars"), partialFilterIndexOptions) - .subscribe(new PrintToStringSubscriber()); +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-text + :end-before: end-text + :language: java + :copyable: + :dedent: -Get a List of Indexes on a Collection -------------------------------------- +.. TODO: To learn more about text indexes, see the :ref:`java-rs-text-index` +.. guide. -Use the ``listIndexes()`` method to get a list of indexes. The following code -lists the indexes on the collection: +Delete an Index +--------------- -.. code-block:: java +The following example deletes an index with the specified name: - collection.listIndexes().subscribe(new PrintDocumentSubscriber()); +.. literalinclude:: /includes/usage-examples/index-code-examples.java + :start-after: start-remove + :end-before: end-remove + :language: java + :copyable: + :dedent: -To learn about other index options, see :manual:`Index Properties -` in the Server manual. +.. TODO: To learn more about removing indexes, see :ref:`java-rs-indexes-remove` +.. in the Work with Indexes guide. \ No newline at end of file From 7c6ad5aae98ba4779e693d34ff871bd09cd973cf Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Mon, 19 Aug 2024 16:41:04 -0400 Subject: [PATCH 2/9] Fix --- source/includes/usage-examples/index-code-examples.java | 2 +- source/includes/usage-examples/sample-index-application.java | 2 +- source/indexes.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/includes/usage-examples/index-code-examples.java b/source/includes/usage-examples/index-code-examples.java index 1a9b3c4e..33a035e8 100644 --- a/source/includes/usage-examples/index-code-examples.java +++ b/source/includes/usage-examples/index-code-examples.java @@ -16,7 +16,7 @@ public class IndexOperations { public static void main(String[] args) { // Replace the placeholder with your Atlas connection string - String uri = ""; + String uri = ""; // Construct a ServerApi instance using the ServerApi.builder() method ServerApi serverApi = ServerApi.builder() diff --git a/source/includes/usage-examples/sample-index-application.java b/source/includes/usage-examples/sample-index-application.java index 0660e310..e04535e7 100644 --- a/source/includes/usage-examples/sample-index-application.java +++ b/source/includes/usage-examples/sample-index-application.java @@ -14,7 +14,7 @@ public class IndexOperations { public static void main(String[] args) { // Replace the placeholder with your Atlas connection string - String uri = ""; + String uri = ""; // Construct a ServerApi instance using the ServerApi.builder() method ServerApi serverApi = ServerApi.builder() diff --git a/source/indexes.txt b/source/indexes.txt index df856147..a6ee1c38 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -57,7 +57,7 @@ The following example creates an ascending index on the specified field: :copyable: :dedent: -To learn more about single field indexes, see the :ref:`java-rs-single-field-index` guide. +.. TODO: To learn more about single field indexes, see the :ref:`java-rs-single-field-index` guide. Compound Index -------------- From eda99fe8d9636b81eb22207d7406348d4ab4471e Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 20 Aug 2024 10:58:50 -0400 Subject: [PATCH 3/9] Address NR feedback --- .../usage-examples/index-code-examples.java | 2 +- source/indexes.txt | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/source/includes/usage-examples/index-code-examples.java b/source/includes/usage-examples/index-code-examples.java index 33a035e8..a7b23bb1 100644 --- a/source/includes/usage-examples/index-code-examples.java +++ b/source/includes/usage-examples/index-code-examples.java @@ -93,7 +93,7 @@ public static void main(String[] args) { CreateCollectionOptions createCollectionOptions= new CreateCollectionOptions() .clusteredIndexOptions(clusteredIndexOptions); - MongoCollection collection = database.createCollection(" collection = database.createCollection("", createCollectionOptions); // end-clustered diff --git a/source/indexes.txt b/source/indexes.txt index a6ee1c38..b8d6d1bc 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -92,7 +92,7 @@ The following example creates a multikey index on the specified array-valued fie Geospatial Index ---------------- -The following example creates a 2dsphere index on the specified field that contains +The following example creates a ``2dsphere`` index on the specified field that contains GeoJSON objects: .. literalinclude:: /includes/usage-examples/index-code-examples.java @@ -157,13 +157,13 @@ Atlas Search Index Management The following sections contain code examples that describe how to manage Atlas Search indexes. -.. TODO: To learn more about Atlas search indexes, see the :ref:`java-rs-atlas-search-index` +.. TODO: To learn more about Atlas Search indexes, see the :ref:`java-rs-atlas-search-index` .. guide. Create Search Index ~~~~~~~~~~~~~~~~~~~ -The following example creates an Atlas search index on the specified field: +The following example creates an Atlas Search index on the specified field: .. literalinclude:: /includes/usage-examples/index-code-examples.java :start-after: start-search-create @@ -172,13 +172,13 @@ The following example creates an Atlas search index on the specified field: :copyable: :dedent: -.. TODO: To learn more about creating serach indexes, see the :ref:`java-rs-atlas-search-index-create` +.. TODO: To learn more about creating search indexes, see the :ref:`java-rs-atlas-search-index-create` .. guide. List Search Indexes ~~~~~~~~~~~~~~~~~~~ -The following example prints a list of Atlas search indexes in the specified collection: +The following example prints a list of Atlas Search indexes in the specified collection: .. literalinclude:: /includes/usage-examples/index-code-examples.java :start-after: start-search-list @@ -193,7 +193,7 @@ The following example prints a list of Atlas search indexes in the specified col Update Search Indexes ~~~~~~~~~~~~~~~~~~~~~ -The following example updates an existing Atlas search index with the specified +The following example updates an existing Atlas Search index with the specified new index definition: .. literalinclude:: /includes/usage-examples/index-code-examples.java @@ -209,7 +209,7 @@ new index definition: Delete Search Indexes ~~~~~~~~~~~~~~~~~~~~~ -The following example deletes an Atlas search index with the specified name: +The following example deletes an Atlas Search index with the specified name: .. literalinclude:: /includes/usage-examples/index-code-examples.java :start-after: start-search-delete From dbc0dd9bcc58f486be5bcc696d9c80938452847f Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 27 Aug 2024 13:33:11 -0400 Subject: [PATCH 4/9] Address technical feedback --- .../usage-examples/index-code-examples.java | 45 ++++++++++++------- .../usage-examples/sample-index-app-intro.rst | 11 +++++ .../sample-index-application.java | 9 ++-- 3 files changed, 47 insertions(+), 18 deletions(-) create mode 100644 source/includes/usage-examples/sample-index-app-intro.rst diff --git a/source/includes/usage-examples/index-code-examples.java b/source/includes/usage-examples/index-code-examples.java index a7b23bb1..51c5a6ae 100644 --- a/source/includes/usage-examples/index-code-examples.java +++ b/source/includes/usage-examples/index-code-examples.java @@ -1,5 +1,3 @@ -package org.example; - import com.mongodb.ConnectionString; import com.mongodb.MongoClientSettings; import com.mongodb.ServerApi; @@ -11,9 +9,11 @@ import com.mongodb.client.model.Indexes; import com.mongodb.reactivestreams.client.*; import org.bson.Document; +import org.reactivestreams.Publisher; import reactor.core.publisher.Flux; +import reactor.core.publisher.Mono; -public class IndexOperations { +public class IndexExamples { public static void main(String[] args) { // Replace the placeholder with your Atlas connection string String uri = ""; @@ -33,21 +33,28 @@ public static void main(String[] args) { MongoDatabase database = mongoClient.getDatabase("sample_mflix"); MongoCollection collection = database.getCollection("movies"); + Publisher dropAllResult = collection.dropIndexes(); + Mono.from(dropAllResult).block(); + // start-single-field - collection.createIndex(Indexes.ascending("")); + Publisher result = collection.createIndex(Indexes.ascending("")); + Mono.from(result).block(); // end-single-field // start-compound - collection.createIndex(Indexes.ascending("", "")); + Publisher result = collection.createIndex(Indexes.ascending("", "")); + Mono.from(result).block(); // end-compound // start-multikey - collection.createIndex(Indexes.ascending("")); + Publisher result = collection.createIndex(Indexes.ascending("")); + Mono.from(result).block(); // end-multikey // start-search-create Document index = new Document("mappings", new Document("dynamic", true)); - collection.createSearchIndex("", index); + Publisher result = collection.createSearchIndex("", index); + Mono.from(result).block(); // end-search-create // start-search-list @@ -60,28 +67,34 @@ public static void main(String[] args) { // start-search-update Document newIndex = new Document("mappings", new Document("dynamic", true)); - collection.updateSearchIndex("", newIndex); + Publisher result = collection.updateSearchIndex("", newIndex); + Mono.from(result).block(); // end-search-update // start-search-delete - collection.dropIndex(""); + Publisher result = collection.dropIndex(""); + Mono.from(result).block(); // end-search-delete // start-text - collection.createIndex(Indexes.text("")); + Publisher result = collection.createIndex(Indexes.text("")); + Mono.from(result).block(); // end-text // start-geo - collection.createIndex(Indexes.geo2dsphere("")); + Publisher result = collection.createIndex(Indexes.geo2dsphere("")); + Mono.from(result).block(); // end-geo // start-unique IndexOptions indexOptions = new IndexOptions().unique(true); - collection.createIndex(Indexes.ascending(""), indexOptions); + Publisher result = collection.createIndex(Indexes.ascending(""), indexOptions); + Mono.from(result).block(); // end-unique // start-wildcard - collection.createIndex(Indexes.ascending("$**")); + Publisher result = collection.createIndex(Indexes.ascending("$**")); + Mono.from(result).block(); // end-wildcard // start-clustered @@ -93,12 +106,14 @@ public static void main(String[] args) { CreateCollectionOptions createCollectionOptions= new CreateCollectionOptions() .clusteredIndexOptions(clusteredIndexOptions); - MongoCollection collection = database.createCollection("", + Publisher clusteredCollection = database.createCollection("", createCollectionOptions); + Mono.from(clusteredCollection).block(); // end-clustered // start-remove - collection.dropIndex(""); + Publisher result = collection.dropIndex(""); + Mono.from(result).block(); // end-remove } } diff --git a/source/includes/usage-examples/sample-index-app-intro.rst b/source/includes/usage-examples/sample-index-app-intro.rst new file mode 100644 index 00000000..8adf19b3 --- /dev/null +++ b/source/includes/usage-examples/sample-index-app-intro.rst @@ -0,0 +1,11 @@ +You can use the following sample application to test the code examples on this +page. To use the sample application, perform the following steps: + +1. Create a new Java project in your IDE. +#. Install the {+driver-short+} in your Java project. +#. Install the `Project Reactor library + `__ in your + Java project. +#. Copy the following code and paste it into a new Java file named ``IndexApp.java``. +#. Copy a code example from this page and paste it on the specified lines in the + file. \ No newline at end of file diff --git a/source/includes/usage-examples/sample-index-application.java b/source/includes/usage-examples/sample-index-application.java index e04535e7..23af4f60 100644 --- a/source/includes/usage-examples/sample-index-application.java +++ b/source/includes/usage-examples/sample-index-application.java @@ -1,15 +1,18 @@ -package org.example; - import com.mongodb.ConnectionString; import com.mongodb.MongoClientSettings; import com.mongodb.ServerApi; import com.mongodb.ServerApiVersion; +import com.mongodb.client.model.ClusteredIndexOptions; +import com.mongodb.client.model.CreateCollectionOptions; +import com.mongodb.client.model.IndexOptions; import com.mongodb.client.model.Indexes; import com.mongodb.reactivestreams.client.*; import org.bson.Document; -import org.bson.conversions.Bson; +import org.reactivestreams.Publisher; import reactor.core.publisher.Flux; +import reactor.core.publisher.Mono; + public class IndexOperations { public static void main(String[] args) { From 669901335d7bbedc5fa696b37f0b50267c3d0ecc Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 27 Aug 2024 13:54:31 -0400 Subject: [PATCH 5/9] Fix --- source/indexes.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/indexes.txt b/source/indexes.txt index b8d6d1bc..9f540ea3 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -37,13 +37,13 @@ the relevant values for your MongoDB deployment. .. _java-rs-index-sample: -.. include:: /includes/usage-examples/sample-app-intro.rst +.. include:: /includes/usage-examples/sample-index-app-intro.rst .. literalinclude:: /includes/usage-examples/sample-index-application.java :language: java :copyable: :linenos: - :emphasize-lines: 34-36 + :emphasize-lines: 37-39 Single Field Index ------------------ From f89382b03d9db7fb54abc47344981a8dd4c08306 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 27 Aug 2024 15:56:10 -0400 Subject: [PATCH 6/9] fix --- source/includes/usage-examples/sample-index-application.java | 1 - source/indexes.txt | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/source/includes/usage-examples/sample-index-application.java b/source/includes/usage-examples/sample-index-application.java index 23af4f60..e9a88616 100644 --- a/source/includes/usage-examples/sample-index-application.java +++ b/source/includes/usage-examples/sample-index-application.java @@ -13,7 +13,6 @@ import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; - public class IndexOperations { public static void main(String[] args) { // Replace the placeholder with your Atlas connection string diff --git a/source/indexes.txt b/source/indexes.txt index 9f540ea3..84032d81 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -43,7 +43,7 @@ the relevant values for your MongoDB deployment. :language: java :copyable: :linenos: - :emphasize-lines: 37-39 + :emphasize-lines: 36-38 Single Field Index ------------------ From 90d0245415b971891e6fd1600e4a4c163f6a5fb7 Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 27 Aug 2024 16:16:33 -0400 Subject: [PATCH 7/9] Fix --- source/includes/usage-examples/index-code-examples.java | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/includes/usage-examples/index-code-examples.java b/source/includes/usage-examples/index-code-examples.java index 51c5a6ae..03781210 100644 --- a/source/includes/usage-examples/index-code-examples.java +++ b/source/includes/usage-examples/index-code-examples.java @@ -33,9 +33,6 @@ public static void main(String[] args) { MongoDatabase database = mongoClient.getDatabase("sample_mflix"); MongoCollection collection = database.getCollection("movies"); - Publisher dropAllResult = collection.dropIndexes(); - Mono.from(dropAllResult).block(); - // start-single-field Publisher result = collection.createIndex(Indexes.ascending("")); Mono.from(result).block(); From 638a476fe011783a1f74e8a7fe29f863147f9dcc Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 27 Aug 2024 16:17:24 -0400 Subject: [PATCH 8/9] Fix --- source/includes/usage-examples/sample-index-application.java | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/usage-examples/sample-index-application.java b/source/includes/usage-examples/sample-index-application.java index e9a88616..75177265 100644 --- a/source/includes/usage-examples/sample-index-application.java +++ b/source/includes/usage-examples/sample-index-application.java @@ -13,7 +13,7 @@ import reactor.core.publisher.Flux; import reactor.core.publisher.Mono; -public class IndexOperations { +public class IndexApp { public static void main(String[] args) { // Replace the placeholder with your Atlas connection string String uri = ""; From 4a07841ec76df9adf7bdc77fd1645f9f4fefeeeb Mon Sep 17 00:00:00 2001 From: Michael Morisi Date: Tue, 10 Sep 2024 09:25:53 -0400 Subject: [PATCH 9/9] Address further technical feedback --- .../usage-examples/index-code-examples.java | 44 +++++++++---------- source/indexes.txt | 26 +++++++++++ 2 files changed, 48 insertions(+), 22 deletions(-) diff --git a/source/includes/usage-examples/index-code-examples.java b/source/includes/usage-examples/index-code-examples.java index 03781210..1b8958af 100644 --- a/source/includes/usage-examples/index-code-examples.java +++ b/source/includes/usage-examples/index-code-examples.java @@ -34,24 +34,24 @@ public static void main(String[] args) { MongoCollection collection = database.getCollection("movies"); // start-single-field - Publisher result = collection.createIndex(Indexes.ascending("")); - Mono.from(result).block(); + Publisher publisher = collection.createIndex(Indexes.ascending("")); + Mono.from(publisher).block(); // end-single-field // start-compound - Publisher result = collection.createIndex(Indexes.ascending("", "")); - Mono.from(result).block(); + Publisher publisher = collection.createIndex(Indexes.ascending("", "")); + Mono.from(publisher).block(); // end-compound // start-multikey - Publisher result = collection.createIndex(Indexes.ascending("")); - Mono.from(result).block(); + Publisher publisher = collection.createIndex(Indexes.ascending("")); + Mono.from(publisher).block(); // end-multikey // start-search-create Document index = new Document("mappings", new Document("dynamic", true)); - Publisher result = collection.createSearchIndex("", index); - Mono.from(result).block(); + Publisher publisher = collection.createSearchIndex("", index); + Mono.from(publisher).block(); // end-search-create // start-search-list @@ -64,34 +64,34 @@ public static void main(String[] args) { // start-search-update Document newIndex = new Document("mappings", new Document("dynamic", true)); - Publisher result = collection.updateSearchIndex("", newIndex); - Mono.from(result).block(); + Publisher publisher = collection.updateSearchIndex("", newIndex); + Mono.from(publisher).block(); // end-search-update // start-search-delete - Publisher result = collection.dropIndex(""); - Mono.from(result).block(); + Publisher publisher = collection.dropIndex(""); + Mono.from(publisher).block(); // end-search-delete // start-text - Publisher result = collection.createIndex(Indexes.text("")); - Mono.from(result).block(); + Publisher publisher = collection.createIndex(Indexes.text("")); + Mono.from(publisher).block(); // end-text // start-geo - Publisher result = collection.createIndex(Indexes.geo2dsphere("")); - Mono.from(result).block(); + Publisher publisher = collection.createIndex(Indexes.geo2dsphere("")); + Mono.from(publisher).block(); // end-geo // start-unique IndexOptions indexOptions = new IndexOptions().unique(true); - Publisher result = collection.createIndex(Indexes.ascending(""), indexOptions); - Mono.from(result).block(); + Publisher publisher = collection.createIndex(Indexes.ascending(""), indexOptions); + Mono.from(publisher).block(); // end-unique // start-wildcard - Publisher result = collection.createIndex(Indexes.ascending("$**")); - Mono.from(result).block(); + Publisher publisher = collection.createIndex(Indexes.ascending("$**")); + Mono.from(publisher).block(); // end-wildcard // start-clustered @@ -109,8 +109,8 @@ public static void main(String[] args) { // end-clustered // start-remove - Publisher result = collection.dropIndex(""); - Mono.from(result).block(); + Publisher publisher = collection.dropIndex(""); + Mono.from(publisher).block(); // end-remove } } diff --git a/source/indexes.txt b/source/indexes.txt index 84032d81..dda9ca86 100644 --- a/source/indexes.txt +++ b/source/indexes.txt @@ -35,6 +35,32 @@ To use an example from this page, copy the code example into the Be sure to replace all placeholders in the code examples, such as ````, with the relevant values for your MongoDB deployment. +Project Reactor Implementation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This guide uses the {+pr+} library to consume ``Publisher`` instances returned +by the {+driver-short+} methods. To learn more about the {+pr+} library +and how to use it, see `Getting Started `__ +in the Reactor documentation. + +There are also other ways to consume ``Publisher`` instances. You can use one of many alternative libraries such as +`RxJava `__ or call ``Publisher.subscribe()`` directly and pass your own +implementation of a ``Subscriber``. + +This guide uses the ``Mono.block()`` method from Reactor to subscribe to a ``Publisher`` and block the current +thread until the ``Publisher`` reaches its terminal state. To learn more about the Reactive Streams initiative, see `Reactive Streams `__. + +.. important:: Publishers Returned are Cold + + All ``Publisher`` instances returned by the {+driver-short+} methods are cold, + which means that the corresponding operation does not happen unless you + subscribe to the returned ``Publisher``. We recommend only subscribing to + the returned ``Publisher`` once, because subscribing more than once can lead + to errors. + +Sample Application +~~~~~~~~~~~~~~~~~~ + .. _java-rs-index-sample: .. include:: /includes/usage-examples/sample-index-app-intro.rst