Filter nodes/edges
Required capabilities:
dataModelsAcl:READ
Filter the instances - nodes and edges - in a project.
POST
/
models
/
instances
/
list
Python SDK
instance_list = client.data_modeling.instances.list(limit=5)
instance_list = client.data_modeling.instances.list(space="my-space")
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)
for instance in client.data_modeling.instances:
instance # do something with the instance
for instance_list in client.data_modeling.instances(chunk_size=100):
instance_list # do something with the instancescurl --request POST \
--url https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"includeTyping": false,
"sources": [
{
"source": {
"type": "view",
"space": "<string>",
"externalId": "<string>",
"version": "<string>"
},
"targetUnits": [
{
"property": "<string>",
"unit": {
"externalId": "<string>"
}
}
]
}
],
"instanceType": "node",
"debug": {
"emitResults": true,
"timeout": 27500,
"profile": false
},
"cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
"limit": 1000,
"sort": [
{
"property": [
"<string>"
],
"direction": "ascending",
"nullsFirst": false
}
],
"filter": {
"and": [
{
"in": {
"property": [
"tag"
],
"values": [
"1001_1",
"1001_1"
]
}
},
{
"range": {
"property": [
"weight"
],
"gte": 0
}
}
]
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
includeTyping: false,
sources: [
{
source: {type: 'view', space: '<string>', externalId: '<string>', version: '<string>'},
targetUnits: [{property: '<string>', unit: {externalId: '<string>'}}]
}
],
instanceType: 'node',
debug: {emitResults: true, timeout: 27500, profile: false},
cursor: '4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo',
limit: 1000,
sort: [{property: ['<string>'], direction: 'ascending', nullsFirst: false}],
filter: {
and: [
{in: {property: ['tag'], values: ['1001_1', '1001_1']}},
{range: {property: ['weight'], gte: 0}}
]
}
})
};
fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'includeTyping' => false,
'sources' => [
[
'source' => [
'type' => 'view',
'space' => '<string>',
'externalId' => '<string>',
'version' => '<string>'
],
'targetUnits' => [
[
'property' => '<string>',
'unit' => [
'externalId' => '<string>'
]
]
]
]
],
'instanceType' => 'node',
'debug' => [
'emitResults' => true,
'timeout' => 27500,
'profile' => false
],
'cursor' => '4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo',
'limit' => 1000,
'sort' => [
[
'property' => [
'<string>'
],
'direction' => 'ascending',
'nullsFirst' => false
]
],
'filter' => [
'and' => [
[
'in' => [
'property' => [
'tag'
],
'values' => [
'1001_1',
'1001_1'
]
]
],
[
'range' => [
'property' => [
'weight'
],
'gte' => 0
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list"
payload := strings.NewReader("{\n \"includeTyping\": false,\n \"sources\": [\n {\n \"source\": {\n \"type\": \"view\",\n \"space\": \"<string>\",\n \"externalId\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"targetUnits\": [\n {\n \"property\": \"<string>\",\n \"unit\": {\n \"externalId\": \"<string>\"\n }\n }\n ]\n }\n ],\n \"instanceType\": \"node\",\n \"debug\": {\n \"emitResults\": true,\n \"timeout\": 27500,\n \"profile\": false\n },\n \"cursor\": \"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo\",\n \"limit\": 1000,\n \"sort\": [\n {\n \"property\": [\n \"<string>\"\n ],\n \"direction\": \"ascending\",\n \"nullsFirst\": false\n }\n ],\n \"filter\": {\n \"and\": [\n {\n \"in\": {\n \"property\": [\n \"tag\"\n ],\n \"values\": [\n \"1001_1\",\n \"1001_1\"\n ]\n }\n },\n {\n \"range\": {\n \"property\": [\n \"weight\"\n ],\n \"gte\": 0\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"includeTyping\": false,\n \"sources\": [\n {\n \"source\": {\n \"type\": \"view\",\n \"space\": \"<string>\",\n \"externalId\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"targetUnits\": [\n {\n \"property\": \"<string>\",\n \"unit\": {\n \"externalId\": \"<string>\"\n }\n }\n ]\n }\n ],\n \"instanceType\": \"node\",\n \"debug\": {\n \"emitResults\": true,\n \"timeout\": 27500,\n \"profile\": false\n },\n \"cursor\": \"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo\",\n \"limit\": 1000,\n \"sort\": [\n {\n \"property\": [\n \"<string>\"\n ],\n \"direction\": \"ascending\",\n \"nullsFirst\": false\n }\n ],\n \"filter\": {\n \"and\": [\n {\n \"in\": {\n \"property\": [\n \"tag\"\n ],\n \"values\": [\n \"1001_1\",\n \"1001_1\"\n ]\n }\n },\n {\n \"range\": {\n \"property\": [\n \"weight\"\n ],\n \"gte\": 0\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"includeTyping\": false,\n \"sources\": [\n {\n \"source\": {\n \"type\": \"view\",\n \"space\": \"<string>\",\n \"externalId\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"targetUnits\": [\n {\n \"property\": \"<string>\",\n \"unit\": {\n \"externalId\": \"<string>\"\n }\n }\n ]\n }\n ],\n \"instanceType\": \"node\",\n \"debug\": {\n \"emitResults\": true,\n \"timeout\": 27500,\n \"profile\": false\n },\n \"cursor\": \"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo\",\n \"limit\": 1000,\n \"sort\": [\n {\n \"property\": [\n \"<string>\"\n ],\n \"direction\": \"ascending\",\n \"nullsFirst\": false\n }\n ],\n \"filter\": {\n \"and\": [\n {\n \"in\": {\n \"property\": [\n \"tag\"\n ],\n \"values\": [\n \"1001_1\",\n \"1001_1\"\n ]\n }\n },\n {\n \"range\": {\n \"property\": [\n \"weight\"\n ],\n \"gte\": 0\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"instanceType": "node",
"version": 123,
"space": "<string>",
"externalId": "<string>",
"createdTime": 1730204346000,
"lastUpdatedTime": 1730204346000,
"type": {
"space": "<string>",
"externalId": "<string>"
},
"deletedTime": 1730204346000,
"properties": {}
}
],
"typing": {},
"nextCursor": "<string>"
}{
"error": {
"code": 401,
"message": "Could not authenticate.",
"missing": [
{}
],
"duplicated": [
{}
]
}
}Authorizations
oidc-tokenoauth2-client-credentialsoauth2-open-industrial-dataoauth2-auth-code
Access token issued by the CDF project's configured identity provider. Access token must be an OpenID Connect token, and the project must be configured to accept OpenID Connect tokens. Use a header key of 'Authorization' with a value of 'Bearer $accesstoken'. The token can be obtained through any flow supported by the identity provider.
Scopes
Body
application/json
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.
Cursor for paging through results. In general, if a response contains a nextCursor
property, it means that there may be more results, and you should pass that value as the
cursor parameter in the next request.
Note that the cursor may or may not be encrypted, but either way, it is not intended to be decoded. Its internal structure is not a part of the public API, and may change without notice. You should treat it as an opaque string and not attempt to craft your own cursors.
Should we return property type information as part of the result?
Retrieve properties from the listed - by reference - views. The node/edge must have data in all the sources defined in the list.
Maximum array length:
10Show child attributes
Show child attributes
The type of instance you are querying for; an edge or a node. If the instance type isn't specified, we list nodes. When instanceType is edge, property can refer to any container and is defined as ["edge", "type"], and value contains the value of the property.
Example:
{
“includeTyping”: true,
“instanceType”: "edge",
“filter”: {
“equals”: {
"property": [
"edge",
"type" // VALID VALUES:[space, externalId, createdTime, lastUpdatedTime, startNode, endNode, type ]
],
"value": {
"space": "apm_simple",
"externalId": "WMT:23-FO-96187"
}
}
}
}
Available options:
node, edge Return query debug notices.
Show child attributes
Show child attributes
Example:
"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo"
Limits the number of results to return.
Required range:
1 <= x <= 1000Maximum array length:
5Show child attributes
Show child attributes
Build a new query by combining other queries, using boolean operators. We support the and, or, and
not boolean operators.
- and
- or
- not
- equals
- in
- range
- prefix
- exists
- containsAny
- containsAll
- matchAll
- nested
- overlaps
- hasData
- instanceReferences
Show child attributes
Show child attributes
Example:
{
"and": [
{
"in": {
"property": ["tag"],
"values": ["1001_1", "1001_1"]
}
},
{
"range": { "property": ["weight"], "gte": 0 }
}
]
}
Response
List of matching nodes and edges
⌘I
Python SDK
instance_list = client.data_modeling.instances.list(limit=5)
instance_list = client.data_modeling.instances.list(space="my-space")
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)
for instance in client.data_modeling.instances:
instance # do something with the instance
for instance_list in client.data_modeling.instances(chunk_size=100):
instance_list # do something with the instancescurl --request POST \
--url https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"includeTyping": false,
"sources": [
{
"source": {
"type": "view",
"space": "<string>",
"externalId": "<string>",
"version": "<string>"
},
"targetUnits": [
{
"property": "<string>",
"unit": {
"externalId": "<string>"
}
}
]
}
],
"instanceType": "node",
"debug": {
"emitResults": true,
"timeout": 27500,
"profile": false
},
"cursor": "4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo",
"limit": 1000,
"sort": [
{
"property": [
"<string>"
],
"direction": "ascending",
"nullsFirst": false
}
],
"filter": {
"and": [
{
"in": {
"property": [
"tag"
],
"values": [
"1001_1",
"1001_1"
]
}
},
{
"range": {
"property": [
"weight"
],
"gte": 0
}
}
]
}
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
includeTyping: false,
sources: [
{
source: {type: 'view', space: '<string>', externalId: '<string>', version: '<string>'},
targetUnits: [{property: '<string>', unit: {externalId: '<string>'}}]
}
],
instanceType: 'node',
debug: {emitResults: true, timeout: 27500, profile: false},
cursor: '4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo',
limit: 1000,
sort: [{property: ['<string>'], direction: 'ascending', nullsFirst: false}],
filter: {
and: [
{in: {property: ['tag'], values: ['1001_1', '1001_1']}},
{range: {property: ['weight'], gte: 0}}
]
}
})
};
fetch('https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'includeTyping' => false,
'sources' => [
[
'source' => [
'type' => 'view',
'space' => '<string>',
'externalId' => '<string>',
'version' => '<string>'
],
'targetUnits' => [
[
'property' => '<string>',
'unit' => [
'externalId' => '<string>'
]
]
]
]
],
'instanceType' => 'node',
'debug' => [
'emitResults' => true,
'timeout' => 27500,
'profile' => false
],
'cursor' => '4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo',
'limit' => 1000,
'sort' => [
[
'property' => [
'<string>'
],
'direction' => 'ascending',
'nullsFirst' => false
]
],
'filter' => [
'and' => [
[
'in' => [
'property' => [
'tag'
],
'values' => [
'1001_1',
'1001_1'
]
]
],
[
'range' => [
'property' => [
'weight'
],
'gte' => 0
]
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list"
payload := strings.NewReader("{\n \"includeTyping\": false,\n \"sources\": [\n {\n \"source\": {\n \"type\": \"view\",\n \"space\": \"<string>\",\n \"externalId\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"targetUnits\": [\n {\n \"property\": \"<string>\",\n \"unit\": {\n \"externalId\": \"<string>\"\n }\n }\n ]\n }\n ],\n \"instanceType\": \"node\",\n \"debug\": {\n \"emitResults\": true,\n \"timeout\": 27500,\n \"profile\": false\n },\n \"cursor\": \"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo\",\n \"limit\": 1000,\n \"sort\": [\n {\n \"property\": [\n \"<string>\"\n ],\n \"direction\": \"ascending\",\n \"nullsFirst\": false\n }\n ],\n \"filter\": {\n \"and\": [\n {\n \"in\": {\n \"property\": [\n \"tag\"\n ],\n \"values\": [\n \"1001_1\",\n \"1001_1\"\n ]\n }\n },\n {\n \"range\": {\n \"property\": [\n \"weight\"\n ],\n \"gte\": 0\n }\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"includeTyping\": false,\n \"sources\": [\n {\n \"source\": {\n \"type\": \"view\",\n \"space\": \"<string>\",\n \"externalId\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"targetUnits\": [\n {\n \"property\": \"<string>\",\n \"unit\": {\n \"externalId\": \"<string>\"\n }\n }\n ]\n }\n ],\n \"instanceType\": \"node\",\n \"debug\": {\n \"emitResults\": true,\n \"timeout\": 27500,\n \"profile\": false\n },\n \"cursor\": \"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo\",\n \"limit\": 1000,\n \"sort\": [\n {\n \"property\": [\n \"<string>\"\n ],\n \"direction\": \"ascending\",\n \"nullsFirst\": false\n }\n ],\n \"filter\": {\n \"and\": [\n {\n \"in\": {\n \"property\": [\n \"tag\"\n ],\n \"values\": [\n \"1001_1\",\n \"1001_1\"\n ]\n }\n },\n {\n \"range\": {\n \"property\": [\n \"weight\"\n ],\n \"gte\": 0\n }\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://{cluster}.cognitedata.com/api/v1/projects/{project}/models/instances/list")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"includeTyping\": false,\n \"sources\": [\n {\n \"source\": {\n \"type\": \"view\",\n \"space\": \"<string>\",\n \"externalId\": \"<string>\",\n \"version\": \"<string>\"\n },\n \"targetUnits\": [\n {\n \"property\": \"<string>\",\n \"unit\": {\n \"externalId\": \"<string>\"\n }\n }\n ]\n }\n ],\n \"instanceType\": \"node\",\n \"debug\": {\n \"emitResults\": true,\n \"timeout\": 27500,\n \"profile\": false\n },\n \"cursor\": \"4zj0Vy2fo0NtNMb229mI9r1V3YG5NBL752kQz1cKtwo\",\n \"limit\": 1000,\n \"sort\": [\n {\n \"property\": [\n \"<string>\"\n ],\n \"direction\": \"ascending\",\n \"nullsFirst\": false\n }\n ],\n \"filter\": {\n \"and\": [\n {\n \"in\": {\n \"property\": [\n \"tag\"\n ],\n \"values\": [\n \"1001_1\",\n \"1001_1\"\n ]\n }\n },\n {\n \"range\": {\n \"property\": [\n \"weight\"\n ],\n \"gte\": 0\n }\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"instanceType": "node",
"version": 123,
"space": "<string>",
"externalId": "<string>",
"createdTime": 1730204346000,
"lastUpdatedTime": 1730204346000,
"type": {
"space": "<string>",
"externalId": "<string>"
},
"deletedTime": 1730204346000,
"properties": {}
}
],
"typing": {},
"nextCursor": "<string>"
}{
"error": {
"code": 401,
"message": "Could not authenticate.",
"missing": [
{}
],
"duplicated": [
{}
]
}
}