DOCSP-49237: bson vector subtype

Author: rustagir

snooty.toml

@@ -27,5 +27,5 @@ patch-version-number = "{+version-number+}.0"
 version = "v{+version-number+}"
 stable-api = "Stable API"
 api-root = "https://www.mongodb.com/docs/ruby-driver/current/api/"
-bson-version = "5.0.2"
+bson-version = "5.1.0"
 avs = "Atlas Vector Search"

source/data-formats.txt

@@ -33,4 +33,4 @@ application. To learn how to work with these data formats, see the following
 sections:
 
 - :ref:`ruby-time-series`: Learn how to create a time series collection and interact with time series data.
-- :ref:`ruby-bson-tutorial`: Learn how to work with BSON data by using the {+driver-short+}'s BSON library.
+- :ref:`ruby-bson`: Learn how to work with BSON data by using the {+driver-short+}'s BSON library.

source/data-formats/bson.txt

@@ -447,6 +447,45 @@ You can use these methods to convert from one representation to another:
    BSON::Binary.from_uuid('77665544-3322-1100-ffeeddccbbaa9988',:java_legacy).to_uuid(:csharp_legacy)
    # => "33221100-5544-7766-8899aabbccddeeff"
 
+.. _ruby-bson-vector:
+
+BSON::Vector
+~~~~~~~~~~~~
+
+Starting in ``bson`` v5.1, you can use the
+``BSON::Vector`` type to represent vectors of numeric values.
+
+Because this type is serialized as a BSON binary vector (subtype 9), you
+can use the ``Vector`` type for improved storage efficiency. To learn
+more, see the `BSON specification <https://bsonspec.org/spec.html>`__.
+
+You can create a ``Vector`` object to store values of the following
+types:
+
+- ``int8``
+- ``float32``
+- ``packed_bit``
+
+You can use the optional ``dtype`` and ``padding`` atrributes to specify
+the data type of the vector and the bit padding, respectively.
+
+The following example demonstrates how to create a ``Vector`` object:
+
+.. code-block:: ruby
+
+   BSON::Vector.new([ -0.0016261312, -0.028070757, -0.011342932 ], :float32)
+
+The following list describes some methods that you can use
+to handle conversions between ``BSON::Binary`` and ``BSON::Vector``:
+
+- ``Binary.as_vector``: Decodes binary data as a ``Vector`` object
+- ``Binary.from_vector``: Constructs a binary object from a ``Vector`` object
+
+.. tip:: {+avs+}
+
+   To view an example that leverages the ``Vector`` type
+   to perform efficient {+avs+} queries, see the :ref:`ruby-avs-examples`.
+
 BSON::Code
 ~~~~~~~~~~
 

source/vector-search.txt

@@ -82,13 +82,15 @@ You must define the following fields in your ``$vectorSearch`` stage:
      - Field that contains vector embeddings
 
    * - ``queryVector``
-     - array of numbers
+     - ``BSON::Vector`` instance or array of numbers
      - Vector representation of your query
 
    * - ``limit``
      - number
      - Number of results to return
 
+.. _ruby-avs-examples:
+
 Atlas Search Query Examples
 ---------------------------
 
@@ -124,6 +126,15 @@ embedding of the phrase "time travel":
       {"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"}
       {"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"}
 
+.. tip:: Query Vector Type
+
+   The preceding example creates an instance of
+   ``BSON::Vector``, introduced in ``bson`` gem v5.1,
+   to serve as the query vector. You can also use an array of
+   numbers as a query vector, but we recommend that you use the
+   ``Vector`` type to improve storage efficiency. To learn more about
+   this type, see the :ref:`ruby-bson-vector` section of the BSON guide.
+
 Vector Search Score
 ~~~~~~~~~~~~~~~~~~~