List instances

List instances.

Parameters:

instance_type (Literal['node', 'edge'] | type[T_Node] | type[T_Edge]) – Whether to query 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.
include_typing (bool) – Whether to return property type information as part of the result.
sources (Source | Sequence[Source] | None) – Views to retrieve properties from.
space (str | SequenceNotStr[str] | None) – Only return instances in the given space (or list of spaces).
limit (int | None) – Maximum number of instances to return. Defaults to 25. Set to -1, float(“inf”) or None to return all items.
sort (Sequence[InstanceSort | dict] | InstanceSort | dict | None) – How you want the listed instances information ordered.
filter (Filter | dict[str, Any] | None) – Advanced filtering of instances.
debug (DebugParameters | None) – Debug settings for profiling and troubleshooting.

Returns:

List of requested instances

Return type:

NodeList[T_Node] | EdgeList[T_Edge]

Examples

List instances and limit to 5:

>>> from cognite.client import CogniteClient, AsyncCogniteClient
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> instance_list = client.data_modeling.instances.list(limit=5)

List some instances in the space ‘my-space’:

>>> instance_list = client.data_modeling.instances.list(space="my-space")

List instances and sort by some property:

>>> from cognite.client.data_classes.data_modeling import InstanceSort
>>> property_sort = InstanceSort(
...     property=("space", "view_xid/view_version", "some_property"),
...     direction="descending",
...     nulls_first=True,
... )
>>> instance_list = client.data_modeling.instances.list(sort=property_sort)

Iterate over instances (nodes by default), one-by-one:

>>> for node in client.data_modeling.instances():
...     node
>>> for edge in client.data_modeling.instances(instance_type="edge"):
...     edge

Iterate over chunks of instances to reduce memory load:

>>> for instance_list in client.data_modeling.instances(chunk_size=100):
...     instance_list  # do something with the instances

List instances with a view as source:

>>> from cognite.client.data_classes.data_modeling import ViewId
>>> my_view = ViewId("mySpace", "myView", "v1")
>>> instance_list = client.data_modeling.instances.list(sources=my_view)

Convert instances to pandas DataFrame with expanded properties (expand_properties=True). This will add the properties directly as dataframe columns. Specifying camel_case=True will convert the basic columns to camel case (e.g. externalId), but leave the property names as-is.

>>> df = instance_list.to_pandas(
...     expand_properties=True,
...     camel_case=True,
... )

To debug and/or profile your query, you can use the debug parameter:

>>> from cognite.client.data_classes.data_modeling.debug import DebugParameters
>>> debug_params = DebugParameters(
...     emit_results=False,
...     include_plan=True,  # Include the postgres execution plan
...     include_translated_query=True,  # Include the internal representation of the query.
...     profile=True,
... )
>>> res = client.data_modeling.instances.list(debug=debug_params, sources=my_view)
>>> print(res.debug)