OS1 Services

Data Listing and Query (DLQS) Search

7min

Overview
The Data Listing & Query Service (DLQS) provides robust APIs for querying and summarizing data objects on an ElasticSearch cluster. This service empowers application developers with the capability to execute precise queries on data objects or entities residing on OS1.
DLQS includes two key API endpoints:
﻿SearchQuery: Enables detailed querying of data objects, allowing developers to execute specific searches tailored to their needs.
﻿AggregateQuery: Complements the search functionality by providing summarized data views. This API is useful for efficiently aggregating transactional data, such as counting documents with specific criteria or assessing the status of various entities.
Together, these APIs offer a comprehensive suite for data listing, searching, and aggregation, catering to a wide range of application development requirements in data analysis and management.
Prerequisites: Defining App Role Config for DLQS Access
Developers can use the SearchQuery and AggregateQuery endpoints by setting up the App Role Config to enable an app with permissions. This configuration can be defined in either JSON or YAML format.
Structure:
App Roles Configuration generally consist of the following sections:
Resources:
This should declare only App level resources. CoreOS resources are standard and need not be mentioned.
Each resource should start with the keyword app:<app_short_name>:.
﻿Permissions:
 This is a combination of the resource name and the allowed HTTP methods.
Roles:
This lists the roles and the associated permissions for each role. Note that roles, once defined, cannot be deprecated or removed from AAA.
In the example below, we’ll add the Platform:Role:platform:app:coreos:dlq-search permission for the tenant:operations:facility_supervisor role.
JSON
app:
 name: facility_as_a_service
 shortName: faas
 id: 'fpa:app:faas$app'
configVersion: v1.0
resources:
 - name: 'fpa:app:faas:facilities$resource'
   url: /faas/api/v1/facilities
   methods:
     - GET
     - POST
 - name: 'fpa:app:faas:facilities:id$resource'
   url: '/faas/api/v1/facilities/:id'
   methods:
     - GET
     - PUT
permissions:
 - name: 'fpa:app:faas:facilities:view$permission'
   resource: 'fpa:app:faas:facilities$resource'
   method: GET
 - name: 'fpa:app:faas:facilities:id:view$permission'
   resource: 'fpa:app:faas:facilities:id$resource'
   method: GET
 - name: 'fpa:app:faas:facilities:create$permission'
   resource: 'fpa:app:faas:facilities$resource'
   method: POST
 - name: 'fpa:app:faas:facilities:id:update$permission'
   resource: 'fpa:app:faas:facilities:id$resource'
   method: PUT
roles:
 - name: admin
   permissions:
     - '*'
   objects:
     - '*'
   attributes:
     include: '*'
 - name: 'tenant:operations:facility_associate'
   permissions:
     - 'core:participants:facilities'
     - 'fpa:app:faas:facilities:view$permission'
     - 'fpa:app:faas:facilities:id:view$permission'
   objects:
     facilities:
       participantId: self.workLocation
   attributes:
     exclude:
       - rental_details
 - name: 'tenant:operations:facility_supervisor'
   permissions:
     - 'core:participants:facilities'
     - 'fpa:app:faas:facilities:view$permission'
     - 'fpa:app:faas:facilities:id:view$permission'
     - 'fpa:app:faas:facilities:create$permission'
     - 'Platform:Role:platform:app:coreos:dlq-search'   # Added role for DLQS access
   objects:
     users:
       manager: self.participantId
     facilities:
       participantId: users.workLocation
   attributes:
     exclude:
       - rental_details
app:
 name: facility_as_a_service
 shortName: faas
 id: 'fpa:app:faas$app'
configVersion: v1.0
resources:
 - name: 'fpa:app:faas:facilities$resource'
   url: /faas/api/v1/facilities
   methods:
     - GET
     - POST
 - name: 'fpa:app:faas:facilities:id$resource'
   url: '/faas/api/v1/facilities/:id'
   methods:
     - GET
     - PUT
permissions:
 - name: 'fpa:app:faas:facilities:view$permission'
   resource: 'fpa:app:faas:facilities$resource'
   method: GET
 - name: 'fpa:app:faas:facilities:id:view$permission'
   resource: 'fpa:app:faas:facilities:id$resource'
   method: GET
 - name: 'fpa:app:faas:facilities:create$permission'
   resource: 'fpa:app:faas:facilities$resource'
   method: POST
 - name: 'fpa:app:faas:facilities:id:update$permission'
   resource: 'fpa:app:faas:facilities:id$resource'
   method: PUT
roles:
 - name: admin
   permissions:
     - '*'
   objects:
     - '*'
   attributes:
     include: '*'
 - name: 'tenant:operations:facility_associate'
   permissions:
     - 'core:participants:facilities'
     - 'fpa:app:faas:facilities:view$permission'
     - 'fpa:app:faas:facilities:id:view$permission'
   objects:
     facilities:
       participantId: self.workLocation
   attributes:
     exclude:
       - rental_details
 - name: 'tenant:operations:facility_supervisor'
   permissions:
     - 'core:participants:facilities'
     - 'fpa:app:faas:facilities:view$permission'
     - 'fpa:app:faas:facilities:id:view$permission'
     - 'fpa:app:faas:facilities:create$permission'
     - 'Platform:Role:platform:app:coreos:dlq-search'   # Added role for DLQS access
   objects:
     users:
       manager: self.participantId
     facilities:
       participantId: users.workLocation
   attributes:
     exclude:
       - rental_details
﻿
﻿
Endpoints: 
GET - /core/api/v1/dlqs/search/{domain}/{type}
Path Parameters
Parameter
Data Type
Description
Example
domain
string
The domain of the index to search. Possible values are: 
participants (for participants-service)
containers (for containers-service)
entities (for entity service) 
system (for dispatch-service and order-service)
containers
type
string
The type parameter specifies the entity type to search for, in all lowercase. It's formulated by removing special characters and combining the appId and entityPluralName, also in lowercase.
For dispatch-service: type = dispatch
For order-service: type = order
If entityPluralName is "Type:1" and appId is "app:123-456", then type = app123456type1
Query Parameters
Parameter
Data Type
Description
Example
limit
integer
The maximum number of search results to return. Default is 50.
limit=10
offset
integer
Specifies the number of records or entries to bypass before starting to return results. Default is 0.
offset=20
select
string
Specifies the list of attributes to be included in the response. If not specified, all attributes are included in the response. This needs to be passed as a comma-separated string of attribute names.
select=userName,userAge
sortKey
string
The key to be used for sorting the result data. Sorting is allowed only on number and string type of values.
sortKey=userAge.keyword or sortKey=userAge
sortBy
string
Key to specify if result data is to be fetched in ascending ("asc") or descending ("desc") order. Allowed values are "asc", "desc". Default is "desc".
sortBy=asc
query
string
Key to pass filters on the result data. This should be URI encoded.
query=name%20EQ%20John
Possible values:
match
term
terms
range
regexp
exists
prefix
geo_distance
geo_bounding_box
geo_polygon
﻿
﻿
GET - /core/api/v1/dlqs/aggregate/{domain}/{type}
Path Parameters
Parameter
Data Type
Description
Example
domain
string
The domain of the index to search. Possible values are: 
participants (for participants-service)
containers (for containers-service)
entities (for entity service) 
system (for dispatch-service and order-service)
containers
type
string
The type parameter specifies the entity type to search for, in all lowercase. It's formulated by removing special characters and combining the appId and entityPluralName, also in lowercase.
For dispatch-service: type = dispatch
For order-service: type = order
If entityPluralName is "Type:1" and appId is "app:123-456", then type = app123456type1
Query Parameters
Parameter
Data Type
Description
Example
query
string
Key to pass filters on the result data. This should be URI encoded.
Possible values:
match
term
terms
range
regexp
exists
prefix
﻿
﻿
aggregateQuery
string
Query criteria
Possible values:
min
max
sum
avg
value_count
terms
﻿
﻿

Parameter	Data Type	Description	Example
domain	string	The domain of the index to search. Possible values are: participants (for participants-service) containers (for containers-service) entities (for entity service) system (for dispatch-service and order-service)	containers
type	string	The type parameter specifies the entity type to search for, in all lowercase. It's formulated by removing special characters and combining the appId and entityPluralName, also in lowercase.	For dispatch-service: type = dispatch For order-service: type = order If entityPluralName is "Type:1" and appId is "app:123-456", then type = app123456type1

Parameter	Data Type	Description	Example
limit	integer	The maximum number of search results to return. Default is 50.	limit=10
offset	integer	Specifies the number of records or entries to bypass before starting to return results. Default is 0.	offset=20
select	string	Specifies the list of attributes to be included in the response. If not specified, all attributes are included in the response. This needs to be passed as a comma-separated string of attribute names.	select=userName,userAge
sortKey	string	The key to be used for sorting the result data. Sorting is allowed only on number and string type of values.	sortKey=userAge.keyword or sortKey=userAge
sortBy	string	Key to specify if result data is to be fetched in ascending ("asc") or descending ("desc") order. Allowed values are "asc", "desc". Default is "desc".	sortBy=asc
query	string	Key to pass filters on the result data. This should be URI encoded.	query=name%20EQ%20John Possible values: match term terms range regexp exists prefix geo_distance geo_bounding_box geo_polygon

Parameter	Data Type	Description	Example
domain	string	The domain of the index to search. Possible values are: participants (for participants-service) containers (for containers-service) entities (for entity service) system (for dispatch-service and order-service)	containers
type	string	The type parameter specifies the entity type to search for, in all lowercase. It's formulated by removing special characters and combining the appId and entityPluralName, also in lowercase.	For dispatch-service: type = dispatch For order-service: type = order If entityPluralName is "Type:1" and appId is "app:123-456", then type = app123456type1

Parameter	Data Type	Description	Example
query	string	Key to pass filters on the result data. This should be URI encoded.	Possible values: match term terms range regexp exists prefix
aggregateQuery	string	Query criteria	Possible values: min max sum avg value_count terms

Updated 17 Sep 2024

Did this page help you?

Scheduler Service

Search Query Format