PYCBC-1597: Support for base64 encoded vector types

Motivation
==========
Add support for base64 encoded vector types.

Modification
============
* Update VectorQuery to handle vector of either List[float] or str.
* Update VectorQuery vector validation.
* Update search request to add vector_base64 to request if that is the
  VectorQuery vector type.
* Add unit test to confirm functionality.

Change-Id: I47525fff85a390513faf1a929ace85ee82172342
Reviewed-on: https://review.couchbase.org/c/couchbase-python-client/+/210668
Reviewed-by: Dimitris Christodoulou <dimitris.christodoulou@couchbase.com>
Tested-by: Build Bot <build@couchbase.com>

Author: thejcfactor

couchbase/logic/search.py

@@ -961,9 +961,12 @@ def encode_vector_search(self) -> Optional[List[Dict[str, Any]]]:
         for query in self._vector_search.queries:
             encoded_query = {
                 'field': query.field_name,
-                'vector': query.vector,
                 'k': query.num_candidates if query.num_candidates is not None else 3
             }
+            if query.vector is not None:
+                encoded_query['vector'] = query.vector
+            else:
+                encoded_query['vector_base64'] = query.vector_base64
             if query.boost is not None:
                 encoded_query['boost'] = query.boost
             encoded_queries.append(encoded_query)

couchbase/logic/vector_search.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import List, Optional
+from typing import (List,
+                    Optional,
+                    Union)
 
 from couchbase.exceptions import InvalidArgumentException
 from couchbase.options import VectorSearchOptions
@@ -37,30 +39,29 @@ class VectorQuery:
 
     Args:
         field_name (str): The name of the field in the search index that stores the vector.
-        vector (List[float]): The vector to use in the query.
+        vector (Union[List[float], str]): The vector to use in the query.
         num_candidates (int, optional): Specifies the number of results returned. If provided, must be greater or equal to 1.
         boost (float, optional): Add boost to query.
 
     Raises:
         :class:`~couchbase.exceptions.InvalidArgumentException`: If the vector is not provided.
-        :class:`~couchbase.exceptions.InvalidArgumentException`: If all values of the provided vector are not instances of float.
+        :class:`~couchbase.exceptions.InvalidArgumentException`: If the vector is not a list or str.
+        :class:`~couchbase.exceptions.InvalidArgumentException`: If vector is a list and all values of the provided vector are not instances of float.
 
     Returns:
         :class:`~couchbase.vector_search.VectorQuery`: The created vector query.
     """  # noqa: E501
 
     def __init__(self,
                  field_name,  # type: str
-                 vector,  # type: List[float]
+                 vector,  # type: Union[List[float], str]
                  num_candidates=None,  # type: Optional[int]
                  boost=None,  # type: Optional[float]
                  ):
         self._field_name = field_name
-        if vector is None or len(vector) == 0:
-            raise InvalidArgumentException('Provided vector cannot be empty.')
-        if not all(map(lambda q: isinstance(q, float), vector)):
-            raise InvalidArgumentException('All vector values must be a float.')
-        self._vector = vector
+        self._vector = None
+        self._vector_base64 = None
+        self._validate_and_set_vector(vector)
         self._num_candidates = self._boost = None
         if num_candidates is not None:
             self.num_candidates = num_candidates
@@ -116,19 +117,46 @@ def num_candidates(self,
         self._num_candidates = value
 
     @property
-    def vector(self) -> List[float]:
+    def vector(self) -> Optional[List[float]]:
         """
         **UNCOMMITTED** This API is unlikely to change,
         but may still change as final consensus on its behavior has not yet been reached.
 
-        List[float]: Returns the vector query's vector.
+        Optional[List[float]]: Returns the vector query's vector.
         """
         return self._vector
 
+    @property
+    def vector_base64(self) -> Optional[str]:
+        """
+        **UNCOMMITTED** This API is unlikely to change,
+        but may still change as final consensus on its behavior has not yet been reached.
+
+        Optional[str]: Returns the vector query's base64 vector str.
+        """
+        return self._vector_base64
+
+    def _validate_and_set_vector(self,
+                                 vector,  # type: Union[List[float], str]
+                                 ) -> None:
+        if vector is None:
+            raise InvalidArgumentException('Provided vector cannot be empty.')
+        if isinstance(vector, list):
+            if len(vector) == 0:
+                raise InvalidArgumentException('Provided vector cannot be empty.')
+            if not all(map(lambda q: isinstance(q, float), vector)):
+                raise InvalidArgumentException('All vector values must be a float.')
+            self._vector = vector
+            return
+        elif not isinstance(vector, str):
+            raise InvalidArgumentException('Provided vector must be either a List[float] or base64 encoded str.')
+
+        self._vector_base64 = vector
+
     @classmethod
     def create(cls,
                field_name,  # type: str
-               vector,  # type: List[float]
+               vector,  # type: Union[List[float], str]
                num_candidates=None,  # type: Optional[int]
                boost=None,  # type: Optional[float]
                ) -> VectorQuery:
@@ -139,13 +167,14 @@ def create(cls,
 
         Args:
             field_name (str): The name of the field in the search index that stores the vector.
-            vector (List[float]): The vector to use in the query.
+            vector (Union[List[float], str]): The vector to use in the query.
             num_candidates (int, optional): Specifies the number of results returned. If provided, must be greater or equal to 1.
             boost (float, optional): Add boost to query.
 
         Raises:
-            :class:`~couchbase.exceptions.InvalidArgumentException`: If the vector is not provided.
-            :class:`~couchbase.exceptions.InvalidArgumentException`: If all values of the provided vector are not instances of float.
+        :class:`~couchbase.exceptions.InvalidArgumentException`: If the vector is not provided.
+        :class:`~couchbase.exceptions.InvalidArgumentException`: If the vector is not a list or str.
+        :class:`~couchbase.exceptions.InvalidArgumentException`: If vector is a list and all values of the provided vector are not instances of float.
 
         Returns:
             :class:`~couchbase.vector_search.VectorQuery`: The created vector query.

couchbase/tests/search_params_t.py

@@ -868,12 +868,15 @@ class VectorSearchParamTestSuite:
                    -0.02059517428278923,
                    0.019551364704966545]
 
+    TEST_VECTOR_BASE64 = 'SSdtIGp1c3QgYSB0ZXN0IHN0cmluZw=='
+
     TEST_MANIFEST = [
         'test_search_request_invalid',
         'test_vector_query_invalid_boost',
         'test_vector_query_invalid_num_candidates',
         'test_vector_query_invalid_vector',
         'test_vector_search',
+        'test_vector_search_base64',
         'test_vector_search_invalid',
         'test_vector_search_multiple_queries'
     ]
@@ -933,6 +936,9 @@ def test_vector_query_invalid_vector(self):
             VectorQuery('vector_field', [1])
         with pytest.raises(InvalidArgumentException):
             VectorQuery('vector_field', [1.111, 2, 3.14159])
+        # if not a list, should be a str
+        with pytest.raises(InvalidArgumentException):
+            VectorQuery('vector_field', {})
 
     def test_vector_search(self, cb_env):
         exp_json = {
@@ -958,6 +964,30 @@ def test_vector_search(self, cb_env):
         encoded_q = cb_env.get_encoded_query(search_query)
         assert exp_json == encoded_q
 
+    def test_vector_search_base64(self, cb_env):
+        exp_json = {
+            'query': {'match_none': None},
+            'index_name': cb_env.TEST_INDEX_NAME,
+            'metrics': True,
+            'show_request': False,
+            'vector_search': [
+                {
+                    'field': 'vector_field',
+                    'vector_base64': self.TEST_VECTOR_BASE64,
+                    'k': 3
+                }
+            ]
+        }
+
+        vector_search = VectorSearch.from_vector_query(VectorQuery('vector_field', self.TEST_VECTOR_BASE64))
+        req = SearchRequest.create(vector_search)
+        search_query = search.SearchQueryBuilder.create_search_query_from_request(
+            cb_env.TEST_INDEX_NAME,
+            req
+        )
+        encoded_q = cb_env.get_encoded_query(search_query)
+        assert exp_json == encoded_q
+
     def test_vector_search_invalid(self):
         with pytest.raises(InvalidArgumentException):
             VectorSearch([])