Skip to content

Commit 7825e03

Browse files
rustagirrustagir
authored
Merge branch 'master' into DOCSP-36218-filters-data-class
2 parents 050ac55 + 904348b commit 7825e03

21 files changed

+271
-90
lines changed

‎examples/src/test/kotlin/AggregatesBuilderTest.kt

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ import config.getConfig
3434
import kotlinx.coroutines.flow.firstOrNull
3535
import kotlinx.coroutines.flow.toList
3636
import kotlinx.coroutines.runBlocking
37+
import org.bson.BinaryVector
3738
import org.bson.Document
3839
import org.bson.codecs.pojo.annotations.BsonId
3940
import org.bson.types.ObjectId
@@ -970,7 +971,8 @@ class AggregatesBuilderTest {
970971
assertEquals(1, results.first().get("count", Document::class.java).get("lowerBound", java.lang.Long::class.java)?.toInt())
971972
}
972973

973-
/* NOTE: Test is not run by default. Vector search requires the creation of a vector search index on the collection before running.
974+
/* NOTE: Test is not run by default. Vector search requires the creation of
975+
a vector search index on the collection before running.
974976
*/
975977
@Ignore
976978
fun vectorSearchTest() = runBlocking {
@@ -979,7 +981,7 @@ class AggregatesBuilderTest {
979981
// :snippet-start: vector-search
980982
Aggregates.vectorSearch(
981983
SearchPath.fieldPath(MovieAlt::plotEmbedding.name),
982-
listOf(-0.0072121937, -0.030757688, -0.012945653),
984+
BinaryVector.floatVector(floatArrayOf(0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f)),
983985
"mflix_movies_embedding_index",
984986
1.toLong(),
985987
exactVectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))

‎examples/src/test/kotlin/BulkTest.kt

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@ import com.mongodb.client.model.DeleteOneModel
66
import com.mongodb.client.model.Filters
77
import com.mongodb.client.model.InsertOneModel
88
import com.mongodb.client.model.ReplaceOneModel
9+
import com.mongodb.client.model.ReplaceOptions
10+
import com.mongodb.client.model.Sorts
911
import com.mongodb.client.model.UpdateOneModel
12+
import com.mongodb.client.model.UpdateOptions
1013
import com.mongodb.client.model.Updates
1114
import com.mongodb.kotlin.client.coroutine.MongoClient
1215
import config.getConfig
@@ -95,6 +98,11 @@ internal class BulkTest {
9598
val insert = Person(1, "Celine Stork", location = "San Diego, CA")
9699
val doc = ReplaceOneModel(filter, insert)
97100
// :snippet-end:
101+
102+
// :snippet-start: replace-model-options
103+
val opts = ReplaceOptions().sort(Sorts.ascending("_id"))
104+
// :snippet-end:
105+
98106
// Junit test for the above code
99107
val insertTest = collection.bulkWrite(listOf(doc))
100108
assertTrue(insertTest.wasAcknowledged())
@@ -107,6 +115,11 @@ internal class BulkTest {
107115
val update = Updates.inc(Person::age.name, 1)
108116
val doc = UpdateOneModel<Person>(filter, update)
109117
// :snippet-end:
118+
119+
// :snippet-start: update-model-options
120+
val opts = UpdateOptions().sort(Sorts.ascending("_id"))
121+
// :snippet-end:
122+
110123
// Junit test for the above code
111124
val updateTest = collection.bulkWrite(listOf(doc))
112125
assertTrue(updateTest.wasAcknowledged())

‎examples/src/test/kotlin/ChangeTest.kt

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11

22
import com.mongodb.client.model.Filters
3+
import com.mongodb.client.model.ReplaceOptions
4+
import com.mongodb.client.model.Sorts
5+
import com.mongodb.client.model.UpdateOptions
36
import com.mongodb.client.model.Updates
47
import com.mongodb.kotlin.client.coroutine.MongoClient
58
import config.getConfig
@@ -63,6 +66,11 @@ internal class ChangeTest {
6366
println("Matched document count: $result.matchedCount")
6467
println("Modified document count: $result.modifiedCount")
6568
// :snippet-end:
69+
70+
// :snippet-start: update-one-options
71+
val opts = UpdateOptions().sort(Sorts.ascending(PaintOrder::color.name))
72+
// :snippet-end:
73+
6674
// Junit test for the above code
6775
assertEquals(1, result.modifiedCount)
6876
}
@@ -90,6 +98,11 @@ internal class ChangeTest {
9098
println("Matched document count: $result.matchedCount")
9199
println("Modified document count: $result.modifiedCount")
92100
// :snippet-end:
101+
102+
// :snippet-start: replace-one-options
103+
val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))
104+
// :snippet-end:
105+
93106
// Junit test for the above code
94107
assertEquals(1, result.modifiedCount)
95108
}

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ toc_landing_pages = [
1212
"/fundamentals/builders",
1313
"/usage-examples",
1414
"/api-documentation",
15+
"/fundamentals/builders/aggregates",
1516
]
1617
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
1718

‎source/examples/generated/AggregatesBuilderTest.snippet.vector-search.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
Aggregates.vectorSearch(
22
SearchPath.fieldPath(MovieAlt::plotEmbedding.name),
3-
listOf(-0.0072121937, -0.030757688, -0.012945653),
3+
BinaryVector.floatVector(floatArrayOf(0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f)),
44
"mflix_movies_embedding_index",
55
1.toLong(),
66
exactVectorSearchOptions().filter(Filters.gte(MovieAlt::year.name, 2016))

‎source/examples/generated/BulkTest.snippet.replace-model-options.kt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
val opts = ReplaceOptions().sort(Sorts.ascending("_id"))

‎source/examples/generated/BulkTest.snippet.update-model-options.kt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
val opts = UpdateOptions().sort(Sorts.ascending("_id"))

‎source/examples/generated/ChangeTest.snippet.replace-one-options.kt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
val opts = ReplaceOptions().sort(Sorts.ascending(PaintOrder::color.name))

‎source/examples/generated/ChangeTest.snippet.update-one-options.kt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
val opts = UpdateOptions().sort(Sorts.ascending(PaintOrder::color.name))

‎source/fundamentals.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ Fundamentals
1414
Stable API </fundamentals/stable-api>
1515
Databases & Collections </fundamentals/databases-collections>
1616
Data Formats </fundamentals/data-formats>
17-
CRUD Operations /fundamentals/crud
17+
CRUD Operations </fundamentals/crud>
1818
Builders </fundamentals/builders>
1919
Aggregation </fundamentals/aggregation>
2020
Aggregation Expressions </fundamentals/aggregation-expression-operations>

‎source/fundamentals/builders.txt

Lines changed: 12 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,11 +108,21 @@ builders in the {+driver-short+}:
108108
Available Builders
109109
------------------
110110

111-
- :ref:`Aggregates <aggregates-builders>` for building aggregation pipelines.
111+
- :ref:`Aggregates <aggregates-builders>` for building aggregation
112+
pipelines.
113+
114+
- :ref:`kotlin-atlas-vector-search` for using the
115+
``Aggregates.vectorSearch()`` method to use the Atlas Vector
116+
Search feature.
117+
112118
- :ref:`Filters <filters-builders>` for building query filters.
119+
113120
- :ref:`Indexes <indexes-builders>` for creating index keys.
114-
- :ref:`Projections <projections-builders>` for building projections.
121+
122+
- :ref:`Projections <projections-builders>` for building projections.
123+
115124
- :ref:`Sorts <sorts-builders>` for building sort criteria.
125+
116126
- :ref:`Updates <updates-builders>` for building updates.
117127

118128
The :ref:`kotlin-builders-data-classes` guide provides examples on

‎source/fundamentals/builders/aggregates.txt

Lines changed: 4 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,10 @@ Aggregates Builders
1717
:depth: 2
1818
:class: singlecol
1919

20+
.. toctree::
21+
22+
Atlas Vector Search </fundamentals/builders/vector-search>
23+
2024
Overview
2125
--------
2226

@@ -906,46 +910,3 @@ aggregation stage:
906910

907911
Learn more about this helper from the
908912
`searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__.
909-
910-
.. _kotlin-atlas-vector-search:
911-
912-
Atlas Vector Search
913-
-------------------
914-
915-
.. important::
916-
917-
To learn about which versions of MongoDB Atlas support this feature, see
918-
:atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
919-
in the Atlas documentation.
920-
921-
Use the ``vectorSearch()`` method to create a :atlas:`$vectorSearch </atlas-vector-search/vector-search-stage/>`
922-
pipeline stage that specifies a **semantic search**. A semantic search is
923-
a type of search that locates pieces of information that are similar in meaning.
924-
925-
To use this feature when performing an aggregation on a collection, you
926-
must create a vector search index and index your vector embeddings. To
927-
learn how to set up search indexes in MongoDB Atlas, see :atlas:`How to
928-
Index Vector Embeddings for Vector Search
929-
</atlas-search/field-types/knn-vector/>` in the Atlas documentation.
930-
931-
The example in this section uses data modeled with the following Kotlin data class:
932-
933-
.. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.vector-search-data-class.kt
934-
:language: kotlin
935-
936-
This example shows how to build an aggregation pipeline that uses the
937-
``vectorSearch()`` method to perform an exact vector search with the following
938-
specifications:
939-
940-
- Searches ``plotEmbedding`` field values by using vector embeddings of a
941-
string value
942-
- Uses the ``mflix_movies_embedding_index`` vector search index
943-
- Returns 1 document
944-
- Filters for documents in which the ``year`` value is at least ``2016``
945-
946-
.. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.vector-search.kt
947-
:language: kotlin
948-
949-
To learn more about this helper, see the
950-
`vectorSearch() API documentation
951-
<{+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)>`__.

‎source/fundamentals/builders/updates.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
.. _updates-builders:
2+
.. _kotlin-updates-builders:
23

34
================
45
Updates Builders

‎source/fundamentals/builders/vector-search.txt

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
.. _kotlin-atlas-vector-search:
2+
3+
===================
4+
Atlas Vector Search
5+
===================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, semantic, nearest
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the :atlas:`Atlas Vector Search
24+
</atlas-vector-search/vector-search-overview/>` feature
25+
in the {+driver-short+}. The ``Aggregates`` builders class provides the
26+
the ``vectorSearch()`` helper method that you can use to
27+
create a :atlas:`$vectorSearch </atlas-vector-search/vector-search-stage/>`
28+
pipeline stage. This pipeline stage allows you to perform a **semantic
29+
search** on your documents. A semantic search is a type of search which
30+
locates information that is similar in meaning, but not necessarily
31+
identical, to your provided search term or phrase.
32+
33+
.. important:: Feature Compatibility
34+
35+
To learn what versions of MongoDB Atlas support this feature, see
36+
:atlas:`Limitations </atlas-vector-search/vector-search-stage/#limitations>`
37+
in the MongoDB Atlas documentation.
38+
39+
Perform a Vector Search
40+
-----------------------
41+
42+
To use this feature, you must create a vector search index and index your
43+
vector embeddings. To learn about how to programmatically create a
44+
vector search index, see the :ref:`kotlin-search-indexes` section in the
45+
Indexes guide. To learn more about vector embeddings, see
46+
:atlas:`How to Index Vector Embeddings for Vector Search
47+
</atlas-search/field-types/knn-vector/>` in the Atlas documentation.
48+
49+
After you create a vector search index on your vector embeddings, you
50+
can reference this index in your pipeline stage, as shown in the
51+
following section.
52+
53+
Vector Search Example
54+
~~~~~~~~~~~~~~~~~~~~~
55+
56+
The example in this section uses data modeled with the following Kotlin data class:
57+
58+
.. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.vector-search-data-class.kt
59+
:language: kotlin
60+
61+
This example shows how to build an aggregation pipeline that uses the
62+
``vectorSearch()`` method to perform an exact vector search with the following
63+
specifications:
64+
65+
- Searches ``plotEmbedding`` field values by using vector embeddings of a
66+
string value
67+
- Uses the ``mflix_movies_embedding_index`` vector search index
68+
- Returns 1 document
69+
- Filters for documents in which the ``year`` value is at least ``2016``
70+
71+
.. literalinclude:: /examples/generated/AggregatesBuilderTest.snippet.vector-search.kt
72+
:language: kotlin
73+
74+
.. tip:: Query Vector Type
75+
76+
The preceding example creates an instance of ``BinaryVector`` to
77+
serve as the query vector, but you can also create a ``List`` of
78+
``Double`` instances. However, we recommend that you use the
79+
``BinaryVector`` type to improve storage efficiency.
80+
81+
.. tip:: {+language+} Vector Search Examples
82+
83+
Visit the :atlas:`Atlas documentation </atlas-vector-search/tutorials/>`
84+
to find more tutorials on using the {+driver-short+} to perform Atlas
85+
Vector Searches.
86+
87+
API Documentation
88+
-----------------
89+
90+
To learn more about the methods and types mentioned in this
91+
guide, see the following API documentation:
92+
93+
- `Aggregates.vectorSearch()
94+
<{+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)>`__
95+
96+
- `FieldSearchPath
97+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/FieldSearchPath.html>`__
98+
99+
- `VectorSearchOptions
100+
<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/VectorSearchOptions.html>`__
101+
102+
- `BinaryVector <{+api+}/apidocs/bson/org/bson/BinaryVector.html>`__

‎source/fundamentals/crud/write-operations.txt

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,15 @@
1+
.. _kotlin-fundamentals-write-operations:
2+
13
================
24
Write Operations
35
================
46

5-
- :doc:`/fundamentals/crud/write-operations/insert`
6-
- :doc:`/fundamentals/crud/write-operations/delete`
7-
- :doc:`/fundamentals/crud/write-operations/modify`
8-
- :doc:`/fundamentals/crud/write-operations/embedded-arrays`
9-
- :doc:`/fundamentals/crud/write-operations/upsert`
10-
- :doc:`/fundamentals/crud/write-operations/bulk`
7+
- :ref:`kotlin-fundamentals-insert`
8+
- :ref:`kotlin-fundamentals-delete`
9+
- :ref:`kotlin-fundamentals-change-document`
10+
- :ref:`kotlin-fundamentals-update-array`
11+
- :ref:`kotlin-fundamentals-upsert`
12+
- :ref:`kotlin-fundamentals-bulkwrite`
1113

1214
.. toctree::
1315
:caption: Write Operations

0 commit comments

Comments
 (0)