Cognite Instances API
The Instances API from Cognite — 9 operation(s) for instances.
OpenAPI Specification
openapi: 3.1.0
info:
title: Cognite 3D Asset Mapping Instances API
description: "# Introduction\nThis is the reference documentation for the Cognite API with\nan overview of all the available methods.\n\n# Postman\nSelect the **Download** button to download our OpenAPI specification to get started.\n\nTo import your data into Postman, select **Import**, and the Import modal opens.\nYou can import items by dragging or dropping files or folders. You can choose how to import your API and manage the import settings in **View Import Settings**.\n\nIn the Import Settings, set the **Folder organization** to **Tags**, select\n**Enable optional parameters** to turn off the settings, and select **Always inherit authentication** to turn on the settings. Select **Import**.\n\nSet the Authorization to **Oauth2.0**. By default, the settings are for Open Industrial Data. Navigate to [Cognite Hub](https://hub.cognite.com/open-industrial-data-211) to understand how to get the credentials for use in Postman.\n\nFor more information, see [Getting Started with Postman](https://developer.cognite.com/dev/guides/postman/).\n\n# Pagination\nMost resource types can be paginated, indicated by the field `nextCursor` in the response.\nBy passing the value of `nextCursor` as the cursor you will get the next page of `limit` results.\nNote that all parameters except `cursor` has to stay the same.\n\n# Parallel retrieval\nAs general guidance, Parallel Retrieval is a technique that should be used when due to query complexity, retrieval of data in a single request is significantly slower than it would otherwise be for a simple request. Parallel retrieval does not act as a speed multiplier on optimally running queries. By parallelizing such requests, data retrieval performance can be tuned to meet the client application needs. \n\nCDF supports parallel retrieval through the `partition` parameter, which has the format `m/n` where `n` is the amount of partitions you would like to split the entire data set into.\nIf you want to download the entire data set by splitting it into 10 partitions, do the following in parallel with `m` running from 1 to 10:\n - Make a request to `/events` with `partition=m/10`.\n - Paginate through the response by following the cursor as explained above. Note that the `partition` parameter needs to be passed to all subqueries.\n\nProcessing of parallel retrieval requests is subject to concurrency quota availability. The request returns the `429` response upon exceeding concurrency limits. See the Request throttling chapter below.\n\nTo prevent unexpected problems and to maximize read throughput, you should at most use 10 partitions. \nSome CDF resources will automatically enforce a maximum of 10 partitions.\nFor more specific and detailed information, please read the ```partition``` attribute documentation for the CDF resource you're using. \n\n# Requests throttling\nCognite Data Fusion (CDF) returns the HTTP `429` (too many requests) response status code when project capacity exceeds the limit.\n\nThe throttling can happen:\n - If a user or a project sends too many (more than allocated) concurrent requests.\n - If a user or a project sends a too high (more than allocated) rate of requests in a given amount of time.\n\nCognite recommends using a retry strategy based on truncated exponential backoff to handle sessions with HTTP response codes 429.\n\nCognite recommends using a reasonable number (up to 10) of `Parallel retrieval` partitions.\n\nFollowing these strategies lets you slow down the request frequency to maximize productivity without having to re-submit/retry failing requests.\n\nSee more [here](https://docs.cognite.com/dev/concepts/resource_throttling).\n\n# API versions\n## Version headers\nThis API uses calendar versioning, and version names follow the `YYYYMMDD` format.\nYou can find the versions currently available by using the version selector at the top of this page.\n\nTo use a specific API version, you can pass the `cdf-version: $version` header along with your requests to the API.\n\n## Beta versions\nThe beta versions provide a preview of what the stable version will look like in the future.\nBeta versions contain functionality that is reasonably mature, and highly likely to become a part of the stable API.\n\nBeta versions are indicated by a `-beta` suffix after the version name. For example, the beta version header for the\n2023-01-01 version is then `cdf-version: 20230101-beta`.\n\n## Alpha versions\nAlpha versions contain functionality that is new and experimental, and not guaranteed to ever become a part of the stable API.\nThis functionality presents no guarantee of service, so its use is subject to caution.\n\nAlpha versions are indicated by an `-alpha` suffix after the version name. For example, the alpha version header for\nthe 2023-01-01 version is then `cdf-version: 20230101-alpha`."
version: v1
contact:
name: Cognite Support
url: https://support.cognite.com
email: support@cognite.com
servers:
- url: https://{cluster}.cognitedata.com/api/v1/projects/{project}
description: The URL for the CDF cluster to connect to
variables:
cluster:
enum:
- api
- az-tyo-gp-001
- az-eastus-1
- az-power-no-northeurope
- westeurope-1
- asia-northeast1-1
- gc-dsm-gp-001
default: api
description: The CDF cluster to connect to
project:
default: publicdata
description: The CDF project name.
security:
- oidc-token:
- https://{cluster}.cognitedata.com/.default
- oauth2-client-credentials:
- https://{cluster}.cognitedata.com/.default
- oauth2-open-industrial-data:
- https://api.cognitedata.com/.default
- oauth2-auth-code:
- https://{cluster}.cognitedata.com/.default
tags:
- name: Instances
paths:
/models/instances:
post:
tags:
- Instances
summary: Create or update nodes/edges
description: "\n\n> **Required capabilities:** `dataModelsAcl:WRITE`\n\nCreate or update nodes and edges in a transaction. The ```items``` field of the payload is an array of objects\nwhere each object describes a node or an edge to create, patch or replace. The ```instanceType``` field of\neach object must be ```node``` or ```edge``` and determines how the rest of the object is interpreted.\n\nThis operation is currently limited to 1000 nodes and/or edges at a time.\n\nIndividual nodes and edges are uniquely identified by their externalId and space.\n\nInstances will be returned in the same order as they are supplied in the request.\n\nFor more details on ingesting instances into a graph, see [Ingesting instances]\n(https://docs.cognite.com/cdf/dm/dm_concepts/dm_ingestion).\n\n### Creating new instances\n\nWhen there is no node or edge with the given externalId in the given space, a node will be created and the\nproperties provided for each of the containers or views in the ```sources``` array will be populated for the\nnode/edge. Nodes can also be created implicitly when an edge between them is created (if\n```autoCreateStartNodes``` and/or ``` autoCreateEndNodes``` is set), or when a direct relation\nproperty is set, the target node does not exist and ```autoCreateDirectRelations``` is set.\n\nTo add a node or edge, the user must have capabilities to access (write to) both the view(s) referenced in\n```sources``` and the container(s) underlying these views, as well as any directly referenced containers.\n\n### Updating (patching) or replacing instances\n\nWhen a node or edge (instance) with the given externalId already exists in a space, the\nproperties named in the ```sources``` field will be written to the instance. Other properties will remain\nunchanged. To replace the whole set of properties for an instance (a node or an edge) rather than patch the\ninstance, set the ```replace``` parameter to ```true```.\n\nNote: When using ```replace``` as ```true``` it will replace any omitted property to either it's default\nvalue as defined on the container(s) or null if no default value is set. All properties on the related\ncontainer(s) referenced in the provided ```sources``` view(s) will be replaced, so even when the provided\nview(s) only contains a subset of properties from a container all the properties in that container for that\ninstance will be replaced. If the underlying container(s) have any required properties that are not provided,\nthe operation will fail.\n\nIf you use a writable view to update properties (that is, the source you are referring to in ```sources```\nis a view), you must have write access to the view as well as all of its backing containers.\n\n### No-change patch operations\nWhen a node/edge item has no changes compared to the existing instance - that is, when the supplied property\nvalues are equal to the corresponding values in the existing node/edge, the node/edge will stay unchanged.\nIn this case, the ```lastUpdatedTime``` values for the nodes/edges in question will not change.\n\n### Deleting instances\nIt's also possible to delete instances by passing instance references to the `delete` field. Upserts and\ndeletes can be combined in the same request and will be executed atomically. The total number of ingested and\ndeleted items cannot exceed 1000. If an instance doesnâ\x80\x99t exist, the delete operation skips it and it won't be\nincluded in the response.\n"
operationId: applyNodeAndEdges
requestBody:
description: Nodes/edges to add or update.
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceBulk'
required: true
x-capability:
- dataModelsAcl:WRITE
responses:
'200':
$ref: '#/components/responses/SlimNodeAndEdgeCollectionResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
'409':
description: Ingestion conflict
content:
application/json:
schema:
$ref: '#/components/schemas/UpsertConflict'
x-code-samples:
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply\nnode = NodeApply(\"mySpace\", \"myNodeId\")\nres = client.data_modeling.instances.apply(node)\n\nfrom cognite.client.data_classes.data_modeling import EdgeApply, NodeOrEdgeData, NodeApply, ViewId\nactor = NodeApply(\n space=\"actors\",\n external_id=\"arnold_schwarzenegger\",\n sources=[\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"PersonView\", \"v1\"),\n {\"name\": \"Arnold Schwarzenegger\", \"birthYear\": 1947}\n ),\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"ActorView\", \"v1\"),\n {\"wonOscar\": False}\n )\n ]\n)\nmovie = NodeApply(\n space=\"movies\",\n external_id=\"Terminator\",\n sources=[\n NodeOrEdgeData(\n ViewId(\"mySpace\", \"MovieView\", \"v1\"),\n {\"title\": \"Terminator\", \"releaseYear\": 1984}\n )\n ]\n)\n# This is one-to-many edge, in this case from a person to a movie\nactor_to_movie = EdgeApply(\n space=\"actors\",\n external_id=\"relation:arnold_schwarzenegger:terminator\",\n type=(\"types\", \"acts-in\"),\n start_node=(\"actors\", \"arnold_schwarzenegger\"),\n end_node=(\"movies\", \"Terminator\"),\n)\nres = client.data_modeling.instances.apply([actor, movie], [actor_to_movie])\n\nfrom cognite.client.data_classes.data_modeling import EdgeApply\nactor_to_movie = EdgeApply(\n space=\"actors\",\n external_id=\"relation:arnold_schwarzenegger:terminator\",\n type=(\"types\", \"acts-in\"),\n start_node=(\"actors\", \"arnold_schwarzenegger\"),\n end_node=(\"movies\", \"Terminator\"),\n)\nres = client.data_modeling.instances.apply(\n edges=actor_to_movie,\n auto_create_start_nodes=True,\n auto_create_end_nodes=True\n)\n\nfrom cognite.client.utils import datetime_to_ms_iso_timestamp\nfrom datetime import datetime, timezone\nmy_date = datetime(2020, 3, 14, 15, 9, 26, 535000, tzinfo=timezone.utc)\ndata_model_timestamp = datetime_to_ms_iso_timestamp(my_date) # \"2020-03-14T15:09:26.535+00:00\"\n\nfrom cognite.client.data_classes.data_modeling import TypedNodeApply, PropertyOptions\nclass PersonApply(TypedNodeApply):\n birth_year = PropertyOptions(identifier=\"birthYear\")\n\n def __init__(self, space: str, external_id, name: str, birth_year: int):\n super().__init__(space, external_id, type=(\"sp_model_space\", \"Person\"))\n self.name = name\n self.birth_year = birth_year\n def get_source(self):\n return ViewId(\"sp_model_space\", \"Person\", \"v1\")\nperson = PersonApply(\"sp_date_space\", \"my_person\", \"John Doe\", 1980)\nres = client.data_modeling.instances.apply(nodes=person)\n"
/models/instances/list:
post:
tags:
- Instances
summary: Filter nodes/edges
description: '
> **Required capabilities:** `dataModelsAcl:READ`
Filter the instances - nodes and edges - in a project.'
operationId: advancedListInstance
requestBody:
description: Filter based on the instance type, the name, the external-ids, and on properties. The filter supports sorting and pagination. The instances must have data in all the views referenced by the sources field. Properties for up to 10 views can be retrieved in one query.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeOrEdgeListRequestV3'
required: true
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/NodeAndEdgeCollectionResponseWithCursorV3'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: "instance_list = client.data_modeling.instances.list(limit=5)\n\ninstance_list = client.data_modeling.instances.list(space=\"my-space\")\n\nfrom cognite.client.data_classes.data_modeling import InstanceSort\nproperty_sort = InstanceSort(\n property=('space', 'view_xid/view_version', 'some_property'),\n direction=\"descending\",\n nulls_first=True)\ninstance_list = client.data_modeling.instances.list(sort=property_sort)\n\nfor instance in client.data_modeling.instances:\n instance # do something with the instance\n\nfor instance_list in client.data_modeling.instances(chunk_size=100):\n instance_list # do something with the instances\n"
/models/instances/byids:
post:
tags:
- Instances
summary: Retrieve nodes/edges by their external ids
description: '
> **Required capabilities:** `dataModelsAcl:READ`
Retrieve up to 1000 nodes or edges by their external ids.'
operationId: byExternalIdsInstances
requestBody:
description: List of external-ids for nodes or edges to retrieve. Properties for **up to 10 unique views** (in total across the external ids requested) can be retrieved in one query.
content:
application/json:
schema:
$ref: '#/components/schemas/ListOfSpaceExternalIdsRequestWithTyping'
required: true
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/ByIdsResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: "res = client.data_modeling.instances.retrieve(\n nodes=(\"mySpace\", \"myNodeExternalId\"),\n edges=(\"mySpace\", \"myEdgeExternalId\"),\n sources=(\"mySpace\", \"myViewExternalId\", \"myViewVersion\"))\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId, ViewId\nres = client.data_modeling.instances.retrieve(\n NodeId(\"mySpace\", \"myNode\"),\n EdgeId(\"mySpace\", \"myEdge\"),\n ViewId(\"mySpace\", \"myViewExternalId\", \"myViewVersion\"))\n\nfrom cognite.client.data_classes.data_modeling import NodeId, EdgeId\nres = client.data_modeling.instances.retrieve(\n NodeId(\"mySpace\", \"myNode\"),\n EdgeId(\"mySpace\", \"myEdge\"),\n sources=(\"myspace\", \"myView\"))\nfrom cognite.client.data_classes.data_modeling import EdgeId, TypedEdge, PropertyOptions, DirectRelationReference, ViewId\nclass Flow(TypedEdge):\n flow_rate = PropertyOptions(identifier=\"flowRate\")\n\n def __init__(\n self,\n space: str,\n external_id: str,\n version: int,\n type: DirectRelationReference,\n last_updated_time: int,\n created_time: int,\n flow_rate: float,\n start_node: DirectRelationReference,\n end_node: DirectRelationReference,\n deleted_time: int | None = None,\n ) -> None:\n super().__init__(\n space, external_id, version, type, last_updated_time, created_time, start_node, end_node, deleted_time\n )\n self.flow_rate = flow_rate\n\n @classmethod\n def get_source(cls) -> ViewId:\n return ViewId(\"sp_model_space\", \"flow\", \"1\")\nres = client.data_modeling.instances.retrieve_edges(\n EdgeId(\"mySpace\", \"theFlow\"), edge_cls=Flow\n)\nisinstance(res, Flow)\nfrom cognite.client.data_classes.data_modeling import NodeId, TypedNode, PropertyOptions, DirectRelationReference, ViewId\nclass Person(TypedNode):\n birth_year = PropertyOptions(identifier=\"birthYear\")\n\n def __init__(\n self,\n space: str,\n external_id: str,\n version: int,\n last_updated_time: int,\n created_time: int,\n name: str,\n birth_year: int | None = None,\n type: DirectRelationReference | None = None,\n deleted_time: int | None = None,\n ):\n super().__init__(\n space=space,\n external_id=external_id,\n version=version,\n last_updated_time=last_updated_time,\n created_time=created_time,\n type=type,\n deleted_time=deleted_time\n )\n self.name = name\n self.birth_year = birth_year\n\n @classmethod\n def get_source(cls) -> ViewId:\n return ViewId(\"myModelSpace\", \"Person\", \"1\")\nres = client.data_modeling.instances.retrieve_nodes(\n NodeId(\"myDataSpace\", \"myPerson\"), node_cls=Person\n)\nisinstance(res, Person)\n"
/models/instances/search:
post:
tags:
- Instances
summary: Search for nodes/edges
description: '
> **Required capabilities:** `DataModels:READ`
Search text fields in views for nodes or edge(s). The service will return up to 1000 results. This operation orders the results by relevance, across the specified spaces.'
operationId: searchInstances
requestBody:
description: The search specification.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeOrEdgeSearchRequest'
required: true
x-capability:
- DataModels:READ
responses:
'200':
$ref: '#/components/responses/SearchResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes.data_modeling import ViewId\nres = client.data_modeling.instances.search(\n ViewId(\"mySpace\", \"PersonView\", \"v1\"),\n query=\"Arnold\",\n properties=[\"name\"])\n\nfrom cognite.client.data_classes.data_modeling import ViewId\nfrom cognite.client.data_classes import filters\nborn_after_1970 = filters.Range([\"mySpace\", \"PersonView/v1\", \"birthYear\"], gt=1970)\nres = client.data_modeling.instances.search(\n ViewId(\"mySpace\", \"PersonView\", \"v1\"),\n query=\"Quentin\",\n properties=[\"name\"],\n filter=born_after_1970)\n"
/models/instances/aggregate:
post:
tags:
- Instances
summary: Aggregate data across nodes/edges
description: '
> **Required capabilities:** `dataModelsAcl:READ`
Aggregate data for nodes or edges in a project. You can use an optional query or filter specification to limit the result.'
operationId: aggregateInstances
requestBody:
description: Aggregation specification.
content:
application/json:
schema:
$ref: '#/components/schemas/AggregationRequest'
required: true
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/AggregationResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: 'from cognite.client.data_classes.data_modeling import ViewId, aggregations as aggs
avg_run_time = aggs.Avg("runTimeMinutes")
view_id = ViewId("mySpace", "PersonView", "v1")
res = client.data_modeling.instances.aggregate(view_id, avg_run_time, group_by="releaseYear")
from cognite.client.data_classes.data_modeling import aggregations as aggs, ViewId
birth_by_decade = aggs.Histogram("birthYear", interval=10.0)
view_id = ViewId("mySpace", "PersonView", "v1")
res = client.data_modeling.instances.histogram(view_id, birth_by_decade)
'
/models/instances/delete:
post:
tags:
- Instances
summary: Delete nodes/edges
description: '
> **Required capabilities:** `dataModelsAcl:WRITE`
Delete nodes and edges in a transaction. Limited to 1000 nodes/edges at a time.
When a node is selected for deletion, all connected incoming and outgoing edges that point to or from it are also deleted. However, please note that the operation might fail if the node has a high number of edge connections. If this is the case, consider deleting the edges connected to the node before deleting the node itself.
Nodes and/or edges that do not exist in the graph when the delete request is processed will be ignored. The rationale for this is that the end-state will reflect the desired state regardless of the instance''s previous state.
Note that attempting to delete something from a space that does not exist will be considered an invalid request, as the API does not affect spaces themselves, only graph nodes and edges. '
operationId: deleteBulk
requestBody:
description: List of types, spaces, and external-ids for nodes and edges to delete.
content:
application/json:
schema:
$ref: '#/components/schemas/NodeOrEdgeDeleteRequest'
required: true
x-capability:
- dataModelsAcl:WRITE
responses:
'200':
$ref: '#/components/responses/NodeOrEdgeDeleteResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: 'client.data_modeling.instances.delete(nodes=("mySpace", "myNode"))
from cognite.client.data_classes.data_modeling import NodeId, EdgeId
client.data_modeling.instances.delete(NodeId(''mySpace'', ''myNode''), EdgeId(''mySpace'', ''myEdge''))
from cognite.client.data_classes.data_modeling import NodeId, EdgeId
my_view = client.data_modeling.views.retrieve((''mySpace'', ''myView''))
my_nodes = client.data_modeling.instances.list(instance_type=''node'', sources=my_view, limit=None)
client.data_modeling.instances.delete(nodes=my_nodes.as_ids())
'
/models/instances/query:
post:
tags:
- Instances
summary: Query nodes/edges
description: '
> **Required capabilities:** `dataModelsAcl:READ`
Specification of query endpoint. For more information, see [Query language](https://docs.cognite.com/cdf/dm/dm_concepts/dm_querying).'
operationId: queryContent
requestBody:
description: Query specification.
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequest'
required: true
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/QueryResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes.data_modeling.query import Query, Select, NodeResultSetExpression, EdgeResultSetExpression, SourceSelector\nfrom cognite.client.data_classes.filters import Range, Equals\nfrom cognite.client.data_classes.data_modeling.ids import ViewId\nmovie_id = ViewId(\"mySpace\", \"MovieView\", \"v1\")\nactor_id = ViewId(\"mySpace\", \"ActorView\", \"v1\")\nquery = Query(\n with_ = {\n \"movies\": NodeResultSetExpression(filter=Range(movie_id.as_property_ref(\"releaseYear\"), lt=2000)),\n \"actors_in_movie\": EdgeResultSetExpression(from_=\"movies\", filter=Equals([\"edge\", \"type\"], {\"space\": movie_id.space, \"externalId\": \"Movie.actors\"})),\n \"actors\": NodeResultSetExpression(from_=\"actors_in_movie\"),\n },\n select = {\n \"actors\": Select(\n [SourceSelector(actor_id, [\"name\"])], sort=[InstanceSort(actor_id.as_property_ref(\"name\"))]),\n },\n)\nres = client.data_modeling.instances.query(query)\n\nfrom cognite.client.data_classes.data_modeling.data_types import UnitReference, UnitSystemReference\nselected_source = SourceSelector(\n source=ViewId(\"my-space\", \"my-xid\", \"v1\"),\n properties=[\"f32_prop1\", \"f32_prop2\", \"f64_prop1\", \"f64_prop2\"],\n target_units=[\n TargetUnit(\"f32_prop1\", UnitReference(\"pressure:kilopa\")),\n TargetUnit(\"f32_prop2\", UnitReference(\"pressure:barg\")),\n TargetUnit(\"f64_prop1\", UnitSystemReference(\"SI\")),\n TargetUnit(\"f64_prop2\", UnitSystemReference(\"Imperial\")),\n ],\n)\n\nSourceSelector(source=ViewId(\"my-space\", \"my-xid\", \"v1\"), properties=[\"*\"])\n"
/models/instances/sync:
post:
tags:
- Instances
summary: Sync nodes/edges
description: '
> **Required capabilities:** `dataModelsAcl:READ`
Subscribe to changes for nodes and edges in a project, matching a supplied filter. This endpoint will always return a ```NextCursor```. The sync specification mirrors the query interface, but sorting is not currently supported. For more information, see [Query language](https://docs.cognite.com/cdf/dm/dm_concepts/dm_querying).'
operationId: syncContent
requestBody:
description: Change filter specification
content:
application/json:
schema:
$ref: '#/components/schemas/SyncRequest'
required: true
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/QueryResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes.data_modeling.instances import InstanceSort\nfrom cognite.client.data_classes.data_modeling.query import Query, Select, NodeResultSetExpression, EdgeResultSetExpression, SourceSelector\nfrom cognite.client.data_classes.filters import Range, Equals\nfrom cognite.client.data_classes.data_modeling.ids import ViewId\nmovie_id = ViewId(\"mySpace\", \"MovieView\", \"v1\")\nactor_id = ViewId(\"mySpace\", \"ActorView\", \"v1\")\nquery = Query(\n with_ = {\n \"movies\": NodeResultSetExpression(filter=Range(movie_id.as_property_ref(\"releaseYear\"), lt=2000)),\n \"actors_in_movie\": EdgeResultSetExpression(from_=\"movies\", filter=Equals([\"edge\", \"type\"], {\"space\": movie_id.space, \"externalId\": \"Movie.actors\"})),\n \"actors\": NodeResultSetExpression(from_=\"actors_in_movie\"),\n },\n select = {\n \"actors\": Select(\n [SourceSelector(actor_id, [\"name\"])], sort=[InstanceSort(actor_id.as_property_ref(\"name\"))]),\n },\n)\nres = client.data_modeling.instances.sync(query)\nquery.cursors = res.cursors\nres_new = client.data_modeling.instances.sync(query)\n"
/models/instances/inspect:
post:
tags:
- Instances
summary: Inspect instances
operationId: instanceInspect
requestBody:
description: Change filter specification
content:
application/json:
schema:
$ref: '#/components/schemas/InstanceInspectRequest'
required: true
x-capability:
- dataModelsAcl:READ
responses:
'200':
$ref: '#/components/responses/InstanceInspectResponse'
'400':
$ref: '#/components/responses/ErrorResponse'
x-code-samples:
- lang: Python
label: Python SDK
source: "from cognite.client.data_classes.data_modeling import NodeId, EdgeId\nres = client.data_modeling.instances.inspect(\n nodes=NodeId(\"my-space\", \"foo1\"),\n edges=EdgeId(\"my-space\", \"bar2\"),\n)\n"
description: '
> **Required capabilities:** `dataModelsAcl:READ`
'
components:
schemas:
SortingNotice:
type: object
oneOf:
- $ref: '#/components/schemas/SortNotBackedByIndexNotice'
- $ref: '#/components/schemas/FilterMatchesCursorableSortNotice'
- $ref: '#/components/schemas/FilterMatchesBrokenCursorableIndexNotice'
discriminator:
propertyName: code
mapping:
sortNotBackedByIndex: '#/components/schemas/SortNotBackedByIndexNotice'
filterMatchesCursorableSort: '#/components/schemas/FilterMatchesCursorableSortNotice'
filterMatchesBrokenCursorableIndex: '#/components/schemas/FilterMatchesBrokenCursorableIndexNotice'
AggregatedHistogramValue:
type: object
required:
- aggregate
- interval
- property
- buckets
properties:
aggregate:
type: string
enum:
- histogram
interval:
type: number
example: 50
property:
type: string
example: duration
buckets:
type: array
description: List (array) of buckets to use for histogram aggregates.
items:
type: object
required:
- start
- count
properties:
start:
description: Start value for a histogram bucket
type: number
example: 1050
count:
description: Number of items in the histogram bucket
type: integer
example: 7
IntractableCursorWithNestedFilterNotice:
description: Emitted when a query supplies both a cursor and a nested filter on the same result set expression. Nested filters require a join that invalidates cursor positions, making pagination results unreliable.
type: object
required:
- code
- category
- hint
- level
- grade
- resultExpression
properties:
code:
type: string
enum:
- intractableCursorWithNestedFilter
category:
type: string
enum:
- cursoring
level:
type: string
enum:
- warning
grade:
type: string
enum:
- D
hint:
type: string
description: A user-friendly message explaining why cursoring is intractable with a nested filter.
resultExpression:
type: string
description: Identifier for the result set expression that the notice applies to.
QueryUnionTableExpressionV3:
title: union
description: 'Return the union of the specified result sets. We will remove the results that match the optional
exception result sets. But this operation does not result in duplicate results as it performs
deduplication.
Note: You should use the `unionAll` operation whenever possible. Using it enables a built-in optimization.
I.e. `A unionAll B` with `limit: n` will execute set operation B, if and only if, A returns less than
n records.
'
type: object
required:
- union
properties:
union:
type: array
items:
oneOf:
- $ref: '#/components/schemas/QuerySetOperationTableExpressionV3'
- type: string
# --- truncated at 32 KB (158 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cognite/refs/heads/main/openapi/cognite-instances-api-openapi.yml