Search Entity with Cursor
Search Entity with Cursor feature works like a cursor in relational databases.
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",
...
},
...
]
}