Search instances

Search instances.

Parameters:

view (ViewId) – View to search in.
query (str | None) – Query string that will be parsed and used for search.
instance_type (Literal['node', 'edge'] | type[T_Node] | type[T_Edge]) – Whether to search for nodes or edges. You can also pass a custom typed node (or edge class) inheriting from TypedNode (or TypedEdge). See apply, retrieve_nodes or retrieve_edges for an example.
properties (list[str] | None) – Optional array of properties you want to search through. If you do not specify one or more properties, the service will search all text fields within the view.
target_units (list[TargetUnit] | None) – Properties to convert to another unit. The API can only convert to another unit if a unit has been defined as part of the type on the underlying container being queried.
space (str | SequenceNotStr[str] | None) – Restrict instance search to the given space (or list of spaces).
filter (Filter | dict[str, Any] | None) – Advanced filtering of instances.
include_typing (bool) – Whether to include typing information.
limit (int | None) – Maximum number of instances to return. Defaults to 25. Will return the maximum number of results (1000) if set to None, -1, or math.inf.
sort (Sequence[InstanceSort | dict] | InstanceSort | dict | None) – How you want the listed instances information ordered.
operator (Literal['AND', 'OR']) – Controls how multiple search terms are combined when matching documents. AND (default): 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. OR: A document matches if it contains any of the query terms in the searchable fields. This typically returns more results but with lower precision.

Returns:

Search result with matching nodes or edges.

Return type:

NodeList[T_Node] | EdgeList[T_Edge]

Examples

Search for equipment containing both ‘centrifugal’ and ‘pump’ in the description:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes.data_modeling import ViewId
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> view = ViewId("assetSpace", "EquipmentView", "v1")
>>> res = client.data_modeling.instances.search(
...     view, query="centrifugal pump", properties=["description"], operator="AND"
... )

Search for ‘pump’, ‘valve’ or ‘compressor’, but filter on those installed after 2015:

>>> from cognite.client.data_classes.data_modeling import ViewId
>>> from cognite.client.data_classes import filters
>>> installed_after_2015 = filters.Range(
...     ["assetSpace", "EquipmentView/v1", "installationYear"],
...     gt=2015,
... )
>>> res = client.data_modeling.instances.search(
...     view,
...     query="pump valve compressor",
...     properties=["name", "description"],
...     filter=installed_after_2015,
...     operator="OR",
... )