Requesting Multiple Entity Connections with a Request

You can use a single API request to request for multiple connected entities of an entity.

Use the API request for UI-API coordination optimization. Specify each connection using the following parameters:

In relation types: Retrieves the relations with specified types, and with the specified entity as the end entity.
Out relation types: Retrieves the relations with specified types, and with the specified entity as the start entity.
Group types: Retrieves the group types that have specified entity as a member.
Entity types: Retrieves only the specified entity types returned in results.
Offset: Specifies which element in the list to return first. Results in each connection group could be sorted, and only one page of results returned.
Max: Retrieves the number of results to return in each facet.
Filter: Retrieves the filter expression to filter results.
Suggested: Retrieves the references to other connection groups.

Connections can be at a distance greater than one from a specified entity, that is, an entity may have connections that in turn have their own connections. In such a case, the connection should be specified as a connections list. Here you would request entities with a first connection, then request all connections for entities returned at step 1 using a second connection, and so on.

Note: There is a limit of relations per entity for this request. If an entity has more than 500,000 relations, then the API reads only the first 500,000 relations from the database to build the response. If this happens, the API response contains "limitExceeded" : true.

You can also mark some suggested relations as ignored. Ignored relations do not appear as suggested.

Filtering by Active Connections

By default, the connection request returns only active connections; that is, for which both objects, relation and entity, do not have the endDate property or endDate > NOW.

There are two request parameters you can use to change this default behavior:

activeness_date: The value of this parameter should be the timestamp in milliseconds. Using this parameter, the response will contain active connections and connections where both objects, relation and entity, have endDate > activeness_date.
Example
```
POST {TenantURL}/entities/{entity id}/_connections?activeness_date=1524640582963
```
activeness_enabled: The value of this parameter is true or false. The default value is true. With this parameter the response will contain all connections with active and inactive entities and relations, that is, regardless of their endDate values.
Example
```
POST {TenantURL}/entities/{entity id}/_connections?activeness_enabled=false
```

Important: activeness_date is normalized to 00:00 UTC. This means that if, for example, 1524808800000 (which is Friday, 27 April 2018 06:00:00 UTC) was passed as activeness_date, it will be converted to 1524787200000 (Friday, 27 April 2018 00:00:00 UTC) internally, and the filtering is done based on this new date.

Request

POST {TenantURL}/entities/{entity id}/_connections

Table 1. Parameters
Parameter		Required	Description
Headers	Content-Type	Yes	Should be "`Content-Type: application/json`".
Body		Yes	JSON object with tenant storage configuration.

Table 2. Query Parameters
Parameter	Required	Description
limitCreditConsumption	No	Boolean value, which can be true or false. If you set this value to `true`, then an error is displayed when the response contains more connections than what is specified in the `reltio.graphservice.maxEntitiesToLoadForLimitedGraph` attribute.
returnDataAnyway	No	Boolean value, which can be true or false. This value is applicable only if you have set the limitCreditConsumption option to `true`. If you set this value as true, and coupled with limitCreditConsumption option also set as true, then the API ignores sorting and filtering of data when the credit limit is reached and returns only the data that is fetched. In other words, you will not see an error message because the limit is exceeded, but you will get the unsorted and unfiltered data in the response. Note: In the response, the dataSorted flag is set to false if the filtering and sorting is not completed.

Table 3. Connection Specification Format
Property name	Required	Description
sortBy	No	Specifies how to sort the results. Type: String (values: `"entities"`, `relations`, default: `"entities"`, `"suggested"`: in case of suggested buckets presence)
inRelations	No	Specifies the types of relations that has `endEntity` equal to the current entity. JSON array of Strings or JSON array of `{ "uri": "{uri}", "label": "{label}" }` `{uri}`: URI of Relation Parameters for label: `literals`: strings that are in label as is. `directionalLabel`: is substituted by directional label from relationship (should be in curly brackets). `attribute.<rel attribute ,name>` : is substituted with an attribute value (should be in curly brackets).
outRelations	No	Specifies the types of relations that has `startEntity` equal to current entity. JSON array of Strings or JSON array of `{ "uri": "{uri}", "label": "{label}" }` `{uri}`: URI of Relation Parameters for label: `literals`: strings that are used in the label as is. `directionalLabel`: is substituted by directional label from relationship (should be in curly brackets). `attribute.<rel attribute name>`: is substituted with an attribute value (should be in curly brackets).
entityTypes	Yes	Specifies the entity types that will be returned. Type: JSON array of Strings
offset	No	Specifies the first element in the request. Type: Integer (default = `0` )
max	No	Specifies the maximum numbers of elements. Type: Integer (default = `10` )
showRelationship	No	Specifies the alternative way to show some specific page of connections. Specifying the `uri` of relationship in '`showRelationship`' would cause connections group to show page on which this relationship should be present in this group in accordance with ordering and page size set by other parameters Type: `uri`.
showEntity	No	Specifies the alternative way to show some specific page of connections. Specifying the `uri` of the connected entity in `"showEntity"` would cause the connections group to show the page on which this connected entity should be present in this group in accordance with ordering and page size set by other parameters. See example:Request to Retrieve Specific Page of Connections Containing Reference ObjectType: `uri`.
nextEntry	No	Specifies the next connection specification if connection path does not equal one hop.
groups	No	Specifies the list of groups types that have entities as a member. Type: JSON array of Strings.
filter	No	Enables the filtering of entities using a condition. Format for filter query parameter: `filter=({Condition Type}[AND/OR {Condition Type}]*).` For more information see Filtering Entities.
returnObjects	No	Specifies whether the whole object data would be put into result (entities, relations). The default value is `false`.
returnDates	No	Specifies whether the activeness (`startDate`, `endDate`) attributes would be put into result (entities, relations). The default value is `false`.
returnLabels	No	Specifies whether the `entityLabel` and `relationLabel` fields are contained in the response. The default value is `true`. Note: If you change the value to `false`: The response will not contain the `entityLabel` and `relationLabel` fields. The response time is enhanced.
id	No	Specifies the identifier for this connections group. It must be used in the suggested field.
suggested	No	Specifies the other buckets from this connections request that must be mixed into this bucket. Type: Array of Strings (ids of other buckets).

Request Several Connection Groups in One Request

POST {
	TenantURL
}
/entities/ {
	entity id
}
/_connections [{
		"sortBy": "entities",
		"inRelations": [{
			"uri": "configuration/relationTypes/Parent",
			"label": "{directionalLabel}"
		}],
		"entityTypes": [
			"configuration/entityTypes/Individual"
		],
		"offset": 0,
		"max": 10
	},
	{
		"sortBy": "entities",
		"inRelations": [{
			"uri": "configuration/relationTypes/Parent",
			"label": "{directionalLabel}"
		}],
		"outRelations": [{
			"uri": "configuration/relationTypes/Parent",
			"label": "{directionalLabel}"
		}],
		"entityTypes": [
			"configuration/entityTypes/Individual"
		],
		"nextEntry": {
			"outRelations": [{
				"uri": "configuration/relationTypes/Parent",
				"label": "{directionalLabel}"
			}],
			"entityTypes": [
				"configuration/entityTypes/Individual"
			],
			"nextEntry": {
				"sortBy": "entities",
				"outRelations": [{
					"uri": "configuration/relationTypes/HasAddress",
					"label": "{directionalLabel}"
				}],
				"entityTypes": [
					"configuration/entityTypes/Location"
				],
				"offset": 0,
				"max": 10
			}
		}
	}
]

Request by Groups

POST {
	TenantURL
}
/entities/ {
	entity id
}
/_connections [{
"sortBy": "entities",
"groups": [
	"configuration/groupTypes/PathHHGroupType"
],
"entityTypes": [
	"configuration/entityTypes/Individual"
],
"offset": 0,
"max": 10
}]

Request with Filtering

POST {
	TenantURL
}
/entities/ {
	entity id
}
/_connections [{
		"sortBy": "entities",
		"filter": "containsWordStartingWith(entity.label,iri)",
		"inRelations": [{
			"uri": "configuration/relationTypes/Parent",
			"label": "{directionalLabel}"
		}],
		"entityTypes": [
			"configuration/entityTypes/Individual"
		],
		"offset": 0,
		"max": 10
	},
	{
		"sortBy": "entities",
		"filter": "containsWordStartingWith(relation.label,fath)",
		"inRelations": [{
			"uri": "configuration/relationTypes/Parent",
			"label": "{directionalLabel}"
		}],
		"outRelations": [{
			"uri": "configuration/relationTypes/Parent",
			"label": "{directionalLabel}"
		}],
		"entityTypes": [
			"configuration/entityTypes/Individual"
		],
		"offset": 0,
		"max": 10
	}
]

Request to Retrieve Specific Page of Connections Containing Reference Object

POST {
	TenantURL
}
/entities/ {
	entity id
}
/_connections [{
"sortBy": "entities",
"filter": "containsWordStartingWith(entity.label,iri)",
"inRelations": [{
	"uri": "configuration/relationTypes/Parent",
	"label": "{directionalLabel}"
}],
"entityTypes": [
	"configuration/entityTypes/Individual"
],
"showEntity": "entities/EEEE",
"max": 10
}]

Example of a Response That Exceeds a Limit

[{
	"index": 0,
	"total": 500000,
	"limitExceeded": true,
	"connections": [{
			"entity": {
				...
			},
			"relation": {
				...
			}
		},
		{
			"entity": {
				...
			},
			"relation": {
				...
			}
		},
		...
	]
}]

Request Connection Groups when the content of one connection group should be populated as a suggested relationship in another connection group

In this example, the second bucket of connections has reference to first bucket in the "suggested" field. Note that special field "id" should be set in the bucket needed to be referenced. As a result of this example request, in second bucket API would return a mix of connections from first and second bucket. All connections from the referenced bucket would be marked with a special field "suggested". Note that connections would be mixed and sorted in order specified by sortBy field. To get connections grouped as "suggested" and not suggested, the sortBy attribute should have a value of "suggested". The "total" field contains the total number of connections in the bucket after mix, with total of original connections + total of suggested connections.

POST {
	TenantURL
}
/entities/ {
	entity id
}
/_connections [{
		"id": "1",
		"inRelations": [
			"configuration/relationTypes/Parent"
		],
		"entityTypes": [
			"configuration/entityTypes/Individual"
		],
		"offset": 10,
		"max": 10
	},
	{
		"suggested": [
			"1"
		],
		"sortBy": "suggested",
		"outRelations": [
			"configuration/relationTypes/HasAddress"
		],
		"entityTypes": [
			"configuration/entityTypes/Location"
		],
		"offset": 20 o,
		"max": 10
	}
]

Accelerate the Value of Data