Query
Note:
To use this functionality, you've to set theREST-Framework-Version header to
2 or higher.
You can use the q parameter to query and filter a collection by comparing attribute values. Use these operators to compare an attribute value.
If you query on a child resource, it has no impact on the child objects that are expanded. For example, if you query on an assignment number for the workers resource, it returns the worker records matching the query criteria. But, expanding on the assignment not only returns the assignment that matches the query criteria, it also expands the whole assignments array.
| Operator |
Attribute Comparison |
| = |
Equal to a value |
| > |
Greater than a value |
| < |
Less than a value |
| >= |
Greater than or equal to a value |
| <= |
Less than or equal to a value |
| <> |
Not equal to a value |
| in |
In a list of values |
| is null |
Value is null |
| is not null |
Value is not null |
| between |
Between two values |
| like |
Compare string values |
| and |
Used for and comparisons |
| or |
Used for or comparisons |
| upper |
Used for comparisons that are case sensitive. |
Describe
To get information on the structure of a resource, including which attributes are queryable and what finders are available, use the describe function. Here's an example for the workers resource.
GET /hcmRestApi/resources/11.13.18.05/workers/describeVerify the queryable property of the attributes in the describe response to identify which attributes can be queried.
PersonId and
PersonNumber is set to true. Therefore, these attributes can be queried. The queryable property of the attribute
CorrespondenceLanguage is set to false, so this attribute can't be queried. If you run a query on an attribute that can't be queried, the request fails and returns the
400 Bad Request status code in the response.
Query Numeric Attributes
You can use operators to query numeric attributes and retrieve records that match the query criteria. Here are some examples.
GET /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber=1000
GET /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber>1000
GET /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber between 1000 and 1100
GET /hcmRestApi/resources/11.13.18.05/workers?q=PersonNumber in (1053, 1200, 1300)
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/child/workRelationships/26787/child/assignments?q=BusinessUnitId is not nullQuery String Attributes
You can use operators to query string attributes and retrieve records that match the query criteria. Here are some examples.
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/child/names?q=FirstName like '%Ki%'
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/child/names?q=FirstName not like '%Ki%'
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/child/names?q=FirstName is null
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/child/names?q=upper(FirstName) = 'KIM'
GET /hcmRestApi/resources/11.13.18.05/workers/00020000000EACED0005/child/names?q=upper(FirstName) like 'KI%'Query Date Attributes
You can use operators to query date attributes and retrieve records that match the query criteria. Here are some examples.
GET /hcmRestApi/resources/11.13.18.05/workers?q=DateOfBirth > '1960-01-01'
GET /hcmRestApi/resources/11.13.18.05/workers?q=DateOfBirth between '1960-01-01' and '1960-01-10'Query Child Resource Attributes
You can use the q query parameter to perform a subquery on the top-level resource. The query returns the top-level resource records with child or grandchild resource records that meet the query criteria.
In these examples, workRelationships and names are child resources of theworkers resource and assignments is the grandchild resource. The first example returns all the workers with work relationships that have assignments with the specified PositionIds. The second example returns all the workers whose first name contains the letters Ki.
GET /hcmRestApi/resources/11.13.18.05/workers?q=workRelationships.assignments.PositionId in (407, 67, 23)GET /hcmRestApi/resources/11.13.18.05/workers?q=names.FirstName like '%Ki%'Query by Combining Criteria
You can use logical operators and and or to combine query criteria and retrieve records that match the criteria. Here are some examples.
GET /hcmRestApi/resources/11.13.18.05/workers?q=(legislativeInfo.Gender = 'M' AND citizenships.CitizenshipStatus = 'A') or (ethnicities.Ethnicity = '1')
GET /hcmRestApi/resources/11.13.18.05/workers?q=(DateOfBirth > '1960-01-01') and (workRelationships.assignments.PositionId in (13,18))Query Using Finders
Finders are pre-defined queries associated with a resource. You can use finders to retrieve records that match the query criteria. You can also combine finders with query parameters to retrieve specific records. Here are some examples.
GET /hcmRestApi/resources/11.13.18.05/payrollRelationships?finder=findByAssignmentNumberPersonNumber;AssignmentNumber=12345
GET /hcmRestApi/resources/11.13.18.05/workers?finder=findByPersonId;PersonId=1564072335