Search Entity with Cursor
Learn about searching for entities with a cursor-based approach.
The Search Entity with Cursor operation retrieves entities that match specific criteria in a defined order. When you send the initial request, the response includes a cursor string.
You can use this cursor in follow-up requests to retrieve the next portion of data, continuing from where the previous request ended. No data is repeated in the returned dataset, and the reading session itself is not time-limited.
The default cursor Time to Live (TTL) is one day after the last read. If the preserveCursor option is set in the tenant configuration, the persistent cursor TTL is reduced to one hour after the last read.
It returns a character sequence to the API user as a part of the response. All subsequent requests are returned with the cursor and then the next portion of data in the defined order. As soon as all data is returned, there will be only a cursor (without data) in the response.
Search Entity with Cursor feature returns the records that are matched with specific criteria in a strictly defined order.
preserveCursor is set in tenant configuration, the Persistent cursor TTL is one hour after the last read. The entire reading session is not time-limited.Request:
POST {TenantURL}/entities/_scanTo search the entity with a cursor, use the parameters listed in Table 1: Search for the entity with cursor.
| Parameter | Required | Details | Example | |
|---|---|---|---|---|
| Headers | Authorization
| Yes | Information about authentication access token in the format of "Bearer <accessToken>" (See, Authentication API ). | |
| Query | filter
| Yes, in first request in sequence (scan request without filter would cause an error) | Enables entity filtering by a condition. Format for the filter query parameter is, filter=({Condition Type}[AND/OR {Condition Type}]*)For more information, see Filtering Entities. | Consider the following examples: Filter by entity type: filter=(equals(type,'configuration/entityTypes/Organization'))Filter by a String across all attributes: filter=(equals(attributes,'Ann'))Fill text search across all blog entries: filter=(fullText(attributes.Blogs, 'Golf'))Find Individual entities that have first name starting with 'An': filter=(equals(type,'configuration/entityTypes/Individual') and startsWith(attributes.FirstName, 'An'))Find active entities by 2005-10-17: filter=(gt(activeness.startDate, 1129507200) and lt(activeness.endDate,1129507200))Find entities created in time or time period: filter=(equals(createdTime, 1129507200))
Find all entities having value from file filter=listEquals(attributes.Education.University,'URL:https://reltio.com/example.txt')Find all entities that have first name matching a wildcard expression '?nn*': filter=(contains(attributes.FirstName, '?nn*'))) |
| activeness | Available options:
| activeness=active | ||
| Request body | Cursor definition | Yes for all requests except first one | Indicates the JSON object that defines the cursor value and must have one JSON attribute cursor with the sub-JSON structure having one string attribute value. |
|
Response:
Indicates a JSON object with the cursor specification and the response part.
First Request - Get first 100 entities having Addresses in California
POST {TenantURL}/entities/_scan?filter=equals(attributes.Address.StateProvince, 'CA')&max=100
Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512Response
POST {TenantURL}/entities/_scan?filter=equals(attributes.Address.StateProvince, 'CA')&max=100Headers: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512{
"cursor" : {
"value" : "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs="
},
"objects" : [
{
"uri" : "entities/0Fglh8Z",
...
},
{
"uri" : "entities/0Fglh11",
...
},
...
]
}Consequent Request - get next data part
POST {TenantURL}/entities/_scanHeaders: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512{
"cursor": {
"value": "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs="
}
}Response
POST {TenantURL}/entities/_scanHeaders: Authorization: Bearer 204938ca-2cf7-44b0-b11a-1b4c59984512{
"cursor" : {
"value" : "cXVlcnlBbmRGZXRjaDsxOzE0NDI3OmpzdTdBNGNnUWU2YlBqc1JQbTlNbnc7MDs="
},
"objects" : [
{
"uri" : "entities/0Fglh34",
...
},
{
"uri" : "entities/0Fglh89",
...
},
...
]
}