Requesting Multiple Entity Connections with a Request

Learn to use a single API request to request 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 where both objects, relation and entity, do not have the endDate property or endDate > NOW.

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

activeness_date: The value of this parameter is the timestamp in milliseconds. Using this parameter, the response contains 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	"`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.
options	No	Search relations from Elastic search service with `options=searchRelationsWithFilter`. If not specified, by default, the request searches relations from the database. For more details see Elastic search based filtering.

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). Note: In the response, the relation section includes a label from the `startObject` section of the relation configuration.
outRelations	No	Specifies the types of relations that have `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). Note: In the response, the relation section includes a label from the `endObject` section of the relation configuration.
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.
relationFilter	No	Enables you to filter relations when query parameter `options=searchRelationsWithFilter`. Format for the body filter parameter is `relationFilter=({Condition Type}[AND/OR {Condition Type}]*)`. For example, `relationFilter=equals(attributes.AddressRank, '1')`. For more information, see the Elastic search based filtering section below.
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
	}
]

Elastic search based filtering

When you make a _connections request, by default, it searches the database to retrieve the information. But in instances when you have a large amount of data, it would be better to retrieve details from Elastic search, instead of the database. Use the new option searchRelationsWithFilter to achieve just this i.e. search and retrieve information from Elastic search.

In addition to this new option, use the relationFilter property along with the filter property to further filter relationships. This new property helps you exclude relations that are not relevant, such as inactive relationships.

Note: Make sure you use the relationFilter property only when searching relations using Elastic search. In other words, you must include the options=searchRelationsWithFilter query parameter in your request if you want to use the relationFilter parameter.

When using the filter and relationFilter properties, ensure you are using the correct attributes for filtering. In case of the the filter property, use entity attributes. For the relationFilter property, use relationship based attributes. In other words, using relationship based attributes with the filter property and entity attributes with the relationFilter property will not achieve the desired result.

Key points regarding the use of Elastic search:

The Elastic Search configuration may require updates, and enabling indexRelation is also necessary.
There may be a delay between the creation of a relationship and its retrieval with _connections with Elastic Search, as indexing takes some time.
The maximum number of connections from Elastic Search depends on maxNumberOfResults in searchStorageConfiguration [Tenant Configuration] which can be 10k maximum.
Filtering with Elastic Search does not return end-dated relations.

Example request:

POST {TenantURL}/entities/{entity id}/_connections?options=searchRelationsWithFilter
{
	"outRelations": [
		{
			"uri": "configuration/relationTypes/HasAddress"
		},
		{
			"uri": "configuration/relationTypes/Employment"
		}
	],
	"filter": "equals(type,'configuration/entityTypes/Location')",
	"relationFilter": "equals(attributes.AddressRank,'1')",
	"returnObjects": false
}

Response

[
    {
        "returnObjects": false,
        "returnDates": false,
        "index": 0,
        "total": 1,
        "connections": [
            {
                "entity": {
                    "entityUri": "entities/0000ZRz",
                    "entityType": "configuration/entityTypes/Individual",
                    "entityLabel": ""
                },
                "relation": {
                    "relationUri": "relations/0000NjH",
                    "relationType": "configuration/relationTypes/HasAddress",
                    "relationLabel": "",
                    "direction": "out"
                }
            }
        ]
    }
]

Accelerate the Value of Data