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/describe
Verify 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.
![Describe Response for Workers Resource Describe Response for Workers Resource](images/WorkersDescribe.png)
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 null
Query 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 PositionId
s. 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