[PYG-430] 😃Enable operator for search endpoint (#530)

# Description

**Reviewer**: All code inside `examples/` is generated.

This is just enabling the `operator` for the `/instances/search/`
enpoint

<img width="1181" height="386" alt="image"
src="https://github.com/user-attachments/assets/133bbf3f-4a0b-451f-a894-1dff97b3b9e9"
/>


## Bump

- [x] Patch
- [ ] Minor
- [ ] Skip

## Changelog
### Fixed

- [alpha] The `.search` method in the QueryExecutor now support the
`operator` argument.

Author: doctrino

cognite/pygen/_query/interface.py

@@ -61,6 +61,7 @@ def search(
         filter: filters.Filter | None = None,
         search_properties: str | SequenceNotStr[str] | None = None,
         sort: Sequence[dm.InstanceSort] | dm.InstanceSort | None = None,
+        operator: Literal["AND", "OR"] | None = None,
         limit: int | None = None,
         instance_types: list[Literal["node", "edge"]] | None = None,
     ) -> list[dict[str, Any]]:
@@ -77,6 +78,11 @@ def search(
             filter: The filter to apply ahead of the search.
             search_properties: The properties to search. If None, all text properties are searched.
             sort: The sort order of the results.
+            operator: Controls how multiple search terms are combined when matching documents.
+                OR (default): A document matches if it contains any of the query terms in the searchable fields.
+                    This typically returns more results but with lower precision.
+                AND: A document matches only if it contains all of the query terms across the searchable fields.
+                    This typically returns fewer results but with higher relevance.
             limit: The maximum number of results to return. Max 1000.
             instance_types: The instance types to search. If None, defaults to the view's supported types.
 
@@ -89,7 +95,9 @@ def search(
 
         """
         filter = self._equals_none_to_not_exists(filter)
-        return self._execute_search(view, properties, query, filter, search_properties, sort, limit, instance_types)
+        return self._execute_search(
+            view, properties, query, filter, search_properties, sort, limit, operator, instance_types
+        )
 
     def _execute_search(
         self,
@@ -100,8 +108,12 @@ def _execute_search(
         search_properties: str | SequenceNotStr[str] | None = None,
         sort: Sequence[dm.InstanceSort] | dm.InstanceSort | None = None,
         limit: int | None = None,
+        operator: Literal["AND", "OR"] | None = None,
         instance_types: list[Literal["node", "edge"]] | None = None,
     ) -> list[dict[str, Any]]:
+        # The SDK requires the operator to be set to AND or OR, however we want to
+        # just use the default if not specified as this is expected to change in the future.
+        operator_arg: dict[str, Any] = {"operator": operator} if operator is not None else {}
         view = self._get_view(view_id)
         flatten_props, are_flat_properties = self._as_property_list(properties, "list") if properties else (None, False)
         if properties is None or are_flat_properties:
@@ -119,21 +131,23 @@ def _execute_search(
                     filter=filter,
                     limit=limit or SEARCH_LIMIT,
                     sort=sort,
+                    **operator_arg,
                 )
                 all_results.extend(
                     self._prepare_list_result(search_instance_result, set(flatten_props) if flatten_props else None)
                 )
             return all_results
         elif view.used_for == "edge":
             raise ValueError("Nested properties are not supported for edges")
-        search_result = self._client.data_modeling.instances.search(  # type: ignore[call-overload]
+        search_result = self._client.data_modeling.instances.search(  # type: ignore[call-overload, misc]
             view_id,
             query,
             instance_type="node",
             properties=search_properties,  # type: ignore[arg-type]
             filter=filter,
             limit=limit or SEARCH_LIMIT,
             sort=sort,
+            **operator_arg,
         )
         # Lookup nested properties:
         order_by_node_ids = {node.as_id(): no for no, node in enumerate(search_result)}

examples/cognite_core/_api_client.py

@@ -7,7 +7,7 @@ readme="README.md"
 requires-python = ">=3.10,<4.0"
 license = "Apache-2.0"
 dependencies = [
-    "cognite-sdk>=7.75.0, <8.0.0",
+    "cognite-sdk>=7.86.0, <8.0.0",
     # pydantic 2.7.0 is the latest versoion supported by pyodide '0.26.2' which is what is used in the
     # Cognite JupyterLab environment.
     # Thus, we pin it to ensure compatibility with the pyodide build.

examples/omni/_api_client.py

@@ -274,6 +274,28 @@ def test_search_nested_properties(cognite_client: CogniteClient, omni_views: dic
     assert not ill_formed_subitems, f"Subitems with unexpected properties: {ill_formed_subitems}"
 
 
+def test_search_AND(cognite_client: CogniteClient, omni_client: OmniClient, omni_views: dict[str, dm.View]) -> None:
+    items = omni_client.primitive_required.list(limit=1)
+    assert len(items) > 0
+    item = items[0]
+    words = item.text.split(" ")
+    # The text property should be at least 3 words. (It is generated lorem ipsum text.)
+    assert len(words) > 2
+
+    view = omni_views["PrimitiveRequired"]
+    executor = QueryExecutor(cognite_client, views=[view], unpack_edges="include")
+    selected_properties: list[str | dict[str, Any]] = ["text", "boolean", "externalId"]
+    result = executor.search(view.as_id(), selected_properties, query=" ".join(words), operator="AND", limit=5)
+
+    assert isinstance(result, list)
+    assert len(result) > 0
+    properties_set = set(selected_properties)
+    ill_formed_items = [item for item in result if not (set(item.keys()) <= properties_set)]
+    assert not ill_formed_items, f"Items with unexpected properties: {ill_formed_items}"
+    # As we are searching with AND, we expect only one result
+    assert len(result) == 1
+
+
 def test_query_list_root_nodes(cognite_client: CogniteClient) -> None:
     executor = QueryExecutor(cognite_client, unpack_edges="include")
     view_id = dm.ViewId("cdf_cdm", "CogniteAsset", "v1")