Accelerate the Value of Data

Iterate Relations by Type

Iterate through relations of a specified type within a specified tenant.

Each request returns a specified number of relations (see the pageSize parameter of the initial request), but no more than 150 relations, and a cursor that should be provided as the parameter of the next request in order to retrieve the next data portion.

Request

POST {TenantURL}/relations/_dbscan
Table 1. Parameters
Parameter Required Details
Headers Authorization Yes Information about the authentication access token in the format of a "Bearer <accessToken>" (see details in Authentication API ).
Body Request definition Yes JSON object defining the request. When requesting the first portion of the data, the JSON object must have relationship types to filter relations. All the subsequent requests must contain a cursor that defines how to continue requesting data. Examples:
  • First request: { "type" : "configuration/relationTypes/HasAddress", "pageSize" : 15 }
  • Subsequent requests: { "cursor" : "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs="}

In a request, some filters can be put inside the first request's cursor specification.

Table 2. Request Definition Filter Options
Option Description
returnObjects This is a boolean flag that specifies only the object URIs that must be returned as a result of scanning.
type This option indicates the relationship type filter. This is a string property that defines the type of relationships that must be returned.
startDate This is a long value property that defines the modification or creation date of relations to filter. You can retrieve all the relations changed or created since the specified time.
pageSize This option specifies how many relationships to return in each request. The default value is 10.
filter This option enables relationships filtering by a condition. The format is the same as for filter in the "Entity Search" request. For more information, see Filtering Entities.
timeLimit This option specifies the amount of time (in ms) before the relations return a cursor, if nothing or fewer entities than pageSize are found. The default value is 0 (no time limit).
options This option indicates a comma-separated list of different options that affect the relationship's JSON content in the response. Following are the available options:
  • sendHidden - This option is disabled by default. Entity's JSON contains the hidden attributes if this option is enabled.
  • ovOnly - This option only returns the attribute values that have the Operational Value (OV) flag set to true.
  • nonOvOnly - This option only returns the attribute values that have the Operational Value (OV) flag set to false. If you have a nested or reference attribute value where the Operational Value (OV) flag is set to true, but for the sub-attributes the Operational Value (OV) flag is set to false, then these sub-attributes do not appear in the response.

Response

JSON object with the cursor specification and response part.

First Request - Get first 150 entities having Individual type

POST {TenantURL}/relations/_dbscan
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
{
  "type": "configuration/relationTypes/HasAddress",
  "pageSize": 10,
  "filter": "equals(attributes.ExternalID, '123456')",
  "timeLimit": 0
}

Response

POST {TenantURL}/relations/_dbscan
Headers: Authorization: Bearer 204938 ca-2 cf7-44 b0-b11a-1 b4c59984512 
{
	"cursor": {
		"cursor": "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs="
	},
	"objects": [{
		"URI": "relations/0Fglh8Z",
		...
	}, {
		"URI": "relations/0Fglh11",
		...
	},...]
}

Example: Subsequent Request - Get next data part

This is the subsequent request to get the next data part.

POST {TenantURL}/relations/_dbscan
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
{
  "cursor": "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs="
}              					

Response

POST {TenantURL}/relations/_dbscan
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512
{
      "cursor": {
            "cursor": "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs="
      },
      "objects": [{
            "URI": "relations/0Fglh34",
            ...
      }, {
            "URI": "relations/0Fglh89",
            ...
      },...]
}