Search Connections
Use this API to search and filter entities using attributes or crosswalk IDs.
Use the Search connections to search for entities using attributes or crosswalk IDs and retrieve these entities along with their relationships. You can also specify additional filtering on the attributes.
Let's use an example to understand the endpoint.
We have the following three entity types:
-
Person - James Young, Kira Lofton, James Smith
-
Agreement - Agreement1, Agreement2, Agreement3, Agreement4
-
Household - Household1, Household 2, Household3, Household4
We also have the following relations between these entity types:
-
Person to Agreement
-
Person to Household
Person | Person to Agreement | Person to Household |
---|---|---|
James Young | Agreement 1, Agreement 2, Agreement 3 | Household1, Household2 |
Kira Lofton | Agreement 3, Agreement 4 | Household3, Household4 |
James Smith | Agreement 1, Agreement 4 | Household1 |
Search entities by attributes
- Request
-
POST /entities/_searchConnections?&max=25&returnFullRelations=false&returnAnalyticAttributes=false&returnReferenceAttributes=false&options=searchRelationsWithFilter { "filter": "equals(type,'configuration/entityTypes/Person') and fuzzy(attributes.FirstName,'James')", "connections": [ { "relationFilter": "equals(attributes.Status,'Active')", "outRelations": [ { "uri": "configuration/relationTypes/PersonToAgreement" } ] }, { "outRelations": [ { "uri": "configuration/relationTypes/PersonToHousehold" } ] } ] }
- Query Parameters
-
-
max: The maximum number of entities to search for connections. The number of returned entities may exceed this max value as this parameter isn't applied to the search for connections, only to the initial entities search. Use
connectedEntitiesMax
to limit the connected entities returned. options
:searchRelationsWithFilter
: Searches relations using the Elastic Search (ES) service instead of the database. For additional options, see Get Entity.
- returnAnalyticAttributes: Indicates whether analytical attributes must be returned for entities. If true, the latency of the API is higher, even if there are no analytical attributes for the returned entities.
-
returnFullRelations: If false, returns only the attributes and crosswalk details about the relation or connection details such as relationship type, start entity URI, and end entity URI. If true, returns all relations but the latency of the call is higher.
-
returnReferenceAttributes : Indicates whether reference attributes of the entity must be returned. If true, the latency of the API could be higher even if there are no reference attributes for returned entities. By default, this is set to false.
-
- Body Parameters
-
connectedEntitiesMax
: Limit the number of related entities returned for each main entity found. For example, if you configureconnectedEntitiesMax
to 20 and 10 entities are found in the entity search, then each of those 10 entities will have a maximum of 20 end objects.connections
:inRelations
: Specifies relation types where the entity is the end object.outRelations
: Specifies relation types where the entity is the start object.relationFilter
: Filters relations when query parameteroptions=searchRelationsWithFilter
. The format isrelationFilter=({Condition Type}[AND/OR {Condition Type}]*)
. For example,relationFilter=equals(attributes.AddressRank, '1')
. For more information, see Elastic search based filtering.
filter
: Defines conditions to match specific entities (e.g., type, name). The format is filter=({Condition Type}[AND/OR {Condition Type}]*). For more information see Filtering Entities.
- Response
-
{ "entities": [ { "uri": "entities/01bpkU9", "type": "configuration/entityTypes/Agreement", "attributes": { "Type": [ { "value": "Copyright", } ], "Number": [ { "value": "2", } ] }, "isFavorite": false, "crosswalks": [ { "type": "configuration/sources/HMS", "value": "Agreement2", } ], "analyticsAttributes": {}, "label": "Copyright 2", "secondaryLabel": "" }, { "uri": "entities/01bp87p", "type": "configuration/entityTypes/Household", "attributes": { "Caption": [ { "value": "Household1", } ] }, "isFavorite": false, "crosswalks": [ { "value": "01bp87p", } ], "analyticsAttributes": {}, "label": "Household1", "secondaryLabel": "" }, { "uri": "entities/01bpokP", "type": "configuration/entityTypes/Agreement", "attributes": { "Type": [ { "value": "Copyright", } ], "Number": [ { "value": "3", } ] }, "isFavorite": false, "crosswalks": [ { "value": "Agreement3", } ], "analyticsAttributes": {}, "label": "Copyright 3", "secondaryLabel": "" }, { "uri": "entities/01bpt0f", "type": "configuration/entityTypes/Agreement", "attributes": { "Type": [ { "value": "Copyright", } ], "Number": [ { "value": "4", } ] }, "isFavorite": false, "crosswalks": [ { "value": "Agreement4", } ], "analyticsAttributes": {}, "label": "Copyright 4", "secondaryLabel": "" }, { "uri": "entities/01bpgDt", "type": "configuration/entityTypes/Agreement", "attributes": { "Type": [ { "value": "Copyright", } ], "Number": [ { "value": "1", } ] }, "isFavorite": false, "crosswalks": [ { "value": "Agreement1", } ], "analyticsAttributes": {}, "label": "Copyright 1", "secondaryLabel": "" }, { "uri": "entities/01bpxGv", "type": "configuration/entityTypes/Person", "attributes": { "LastName": [ { "value": "Smith", } ], "FirstName": [ { "value": "James", } ] }, "isFavorite": false, "crosswalks": [ { "value": "01bpxGv", } ], "analyticsAttributes": {}, "label": "James Smith,", "secondaryLabel": "" }, { "uri": "entities/01bpCO5", "type": "configuration/entityTypes/Household", "attributes": { "Caption": [ { "value": "Household2", } ] }, "isFavorite": false, "crosswalks": [ { "value": "01bpCO5", } ], "analyticsAttributes": {}, "label": "Household2", "secondaryLabel": "" }, { "uri": "entities/01boiYH", "type": "configuration/entityTypes/Person", "attributes": { "LastName": [ { "value": "Young", } ], "FirstName": [ { "value": "James", } ] }, "isFavorite": false, "crosswalks": [ { "value": "01boiYH", } ], "analyticsAttributes": {}, "label": "James Young,", "secondaryLabel": "" } ], "relations": [ { "uri": "relations/01bos8r", "type": "configuration/relationTypes/PersonToAgreement", "startObject": { "objectURI": "entities/01bpxGv" }, "endObject": { "objectURI": "entities/01bpgDt" } }, { "uri": "relations/01bob5p", "type": "configuration/relationTypes/PersonToHousehold", "startObject": { "objectURI": "entities/01boiYH" }, "endObject": { "objectURI": "entities/01bp87p" } }, { "uri": "relations/01boK2n", "type": "configuration/relationTypes/PersonToAgreement", "startObject": { "objectURI": "entities/01boiYH" }, "endObject": { "objectURI": "entities/01bpkU9" } }, { "uri": "relations/01bp0fN", "type": "configuration/relationTypes/PersonToHousehold", "startObject": { "objectURI": "entities/01bpxGv" }, "endObject": { "objectURI": "entities/01bp87p" } }, { "uri": "relations/01boOJ3", "type": "configuration/relationTypes/PersonToAgreement", "startObject": { "objectURI": "entities/01boiYH" }, "endObject": { "objectURI": "entities/01bpokP" } }, { "uri": "relations/01bowP7", "type": "configuration/relationTypes/PersonToAgreement", "startObject": { "objectURI": "entities/01bpxGv" }, "endObject": { "objectURI": "entities/01bpt0f" } }, { "uri": "relations/01boFmX", "type": "configuration/relationTypes/PersonToAgreement", "startObject": { "objectURI": "entities/01boiYH" }, "endObject": { "objectURI": "entities/01bpgDt" } }, { "uri": "relations/01bofM5", "type": "configuration/relationTypes/PersonToHousehold", "startObject": { "objectURI": "entities/01boiYH" }, "endObject": { "objectURI": "entities/01bpCO5" } } ] }
Search entities by URIs
- Request
POST /entities/_searchConnections?uris=entities/01bomoX [ { "outRelations": [ { "uri": "configuration/relationTypes/PersonToAgreement" } ] }, "outRelations": [ { "uri": "configuration/relationTypes/PersonToHousehold" } ] } ]
- Response
{ "entities": [ { "uri": "entities/01bpKub", "type": "configuration/entityTypes/Household", "createdBy": "sergey.zagorodin@reltio.com", "createdTime": 1644904339566, "updatedBy": "sergey.zagorodin@reltio.com", "updatedTime": 1644904339566, "attributes": { "Caption": [ { "value": "Household4", } ] }, "isFavorite": false, "crosswalks": [ { "type": "configuration/sources/Reltio", "value": "01bpKub", } ], "analyticsAttributes": {}, "label": "Household4", "secondaryLabel": "" }, { "uri": "entities/01bomoX", "type": "configuration/entityTypes/Person", "attributes": { "LastName": [ { "value": "Lofton", } ], "FirstName": [ { "value": "Kira", } ] }, "isFavorite": false, "crosswalks": [ { "type": "configuration/sources/Reltio", "value": "01bomoX", } ], "analyticsAttributes": {}, "label": "Kira Lofton,", "secondaryLabel": "" }, { "uri": "entities/01bpt0f", "type": "configuration/entityTypes/Agreement", "attributes": { "Type": [ { "value": "Copyright", } ], "Number": [ { "value": "4", } ] }, "isFavorite": false, "crosswalks": [ { "type": "configuration/sources/HMS", "value": "Agreement4", } ], "analyticsAttributes": {}, "label": "Copyright 4", "secondaryLabel": "" }, { "uri": "entities/01bpGeL", "type": "configuration/entityTypes/Household", "attributes": { "Caption": [ { "value": "Household3", } ] }, "isFavorite": false, "crosswalks": [ { "type": "configuration/sources/Reltio", "value": "01bpGeL", } ], "analyticsAttributes": {}, "label": "Household3", "secondaryLabel": "" }, { "uri": "entities/01bpokP", "type": "configuration/entityTypes/Agreement", "attributes": { "Type": [ { "value": "Copyright", } ], "Number": [ { "value": "3", } ] }, "isFavorite": false, "crosswalks": [ { "type": "configuration/sources/HMS", "value": "Agreement3", } ], "analyticsAttributes": {}, "label": "Copyright 3", "secondaryLabel": "" } ], "relations": [ { "uri": "relations/01bonsb", "type": "configuration/relationTypes/PersonToHousehold", "startRefPinned": false, "startRefIgnored": false, "endRefPinned": false, "endRefIgnored": false, "attributes": {}, "crosswalks": [ { "type": "configuration/sources/Reltio", "value": "01bonsb", } ], "startObject": { "objectURI": "entities/01bomoX", "crosswalks": [] }, "endObject": { "objectURI": "entities/01bpKub", "crosswalks": [] } }, { "uri": "relations/01boSZJ", "type": "configuration/relationTypes/PersonToAgreement", "startRefPinned": false, "startRefIgnored": false, "endRefPinned": false, "endRefIgnored": false, "attributes": { "Type": [ { "value": "RN", } ], "Commenters": [ { "value": "thermostat", } ] }, "crosswalks": [ { "value": "01boSZJ", } } ], "startObject": { "objectURI": "entities/01bomoX", "crosswalks": [] }, "endObject": { "objectURI": "entities/01bpokP", "crosswalks": [ { "uri": "entities/01bpokP/crosswalks/D0Z6TrJ", "type": "configuration/sources/HMS", "value": "Agreement3" } ] } }, { "uri": "relations/01bojcL", "type": "configuration/relationTypes/PersonToHousehold", "startRefPinned": false, "startRefIgnored": false, "endRefPinned": false, "endRefIgnored": false, "attributes": {}, "crosswalks": [ { "type": "configuration/sources/Reltio", "value": "01bojcL", } ], "startObject": { "objectURI": "entities/01bomoX", "crosswalks": [] }, "endObject": { "objectURI": "entities/01bpGeL", "crosswalks": [] } }, { "uri": "relations/01boWpZ", "type": "configuration/relationTypes/PersonToAgreement", "startRefPinned": false, "startRefIgnored": false, "endRefPinned": false, "endRefIgnored": false, "attributes": { "Type": [ { "value": "Resident", } ], "Commenters": [ { "value": "clock, watch", } ] }, "crosswalks": [ { "type": "configuration/sources/Reltio", "value": "01boWpZ", } ], "startObject": { "objectURI": "entities/01bomoX", "crosswalks": [] }, "endObject": { "objectURI": "entities/01bpt0f", "crosswalks": [ { "uri": "entities/01bpt0f/crosswalks/D0Z6ge5", "type": "configuration/sources/HMS", "value": "Agreement4" } ] } } ] }