---
keyword: [Extend, Workday Graph API, Graph API, GraphQL]
nav: wcp_docs
parent_url: /wcp_docs/
title: Graph API Queries
layout: subsection
---
To fetch data using Graph API, submit a `query` that retrieves the business object and related data in the schema. In the `query`, specify the data source, filter criteria, and response fields that are available in the schema. Ensure that you've configured the proper permissions for the query security domains listed in the schema.
The Generate Query option on the Graph API Explorer can help you write a query.
## Query Structure
A query begins with the `query` keyword, and follows this basic structure:
```
query operationName ( $dataSourceVariable: DataSourceType!, $variable: Type ) {
rootQueryField ( dataSource: $dataSourceVariable, argument: $variable ) {
data {
responseField1
responseObjectField2 {
responseField2
}
}
}
}
```
The rootQueryField is a top-level query field in the Graph API schema, and represents the object data you can query.
The rootQueryField determines the elements that you'll need in your query. It defines the arguments, which enable you to pass input variables through the operation name. The query elements that start with `$` are [Input Variables](/wcp_docs/qxq1671067079349.html#section-input-variables), which you must define as [Query Variables](/wcp_docs/qxq1671067079349.html#section-query-variables).
The return type of the rootQueryField defines the [Response Data Fields](/wcp_docs/qxq1671067079349.html#section-response-data-fields) that you can select in your query.
Example: The `worker` root query field in the Graph API schema:
## Input Variables
If you want to send dynamic data to the query arguments, declare input variables with a query operation name:
operationName ( $dataSourceVariable: DataSourceType!, $variable: Type )
Where:
- operationName( )
A name you can assign to the query. The operation name requires parentheses `( )`, which contains input variable declarations.
If your query uses input variables, start the query with operationName( $variable: Type).
If your query doesn't use input variables, start the query with rootQueryField( arguments ). Example:
```
query {
worker( dataSource: { processingWorker : {} } ) {
data {
workdayID {
id
}
}
}
}
```
- $dataSourceVariable: DataSourceType!
- `$dataSourceVariable`
An input variable containing the data source and data source arguments, including filters. Always begin an input variable with `$`. Define the input variable in the Query Variables as a JSON map containing the required and optional data source arguments. For details about the data source, see [Query Data Source](/wcp_docs/qxq1671067079349.html#section-the-query-data-source).
- `DataSourceType!`
The type of the data source.
In the schema, the `dataSource` argument of the query specifies the data source type, which uses the `_DataSources` suffix. Always append the data source type of the input variable with `!`, indicating that it's non-nullable and required.
- $variable: Type
- `$variable`
An input variable for any of the other query arguments, such as `where`, `limit`, or `offset`.
Always begin an input variable with `$`. Define the input variable in the Query Variables as a JSON key-value pair.
- `Type`
The type of the variable.
In the schema, each argument of the query specifies the type. If the type ends with `!` indicating it's required, append the input variable type with `!`.
This sample query starts with the getWorkerById operation name and workerId input variable:
```
query getWorkerById($workerId: ID!) {
worker(
dataSource: {indexedAllWorkers: {filter: {indexedAllWorkersFilter: {}}}}
where: {workdayID: {in: [{id: $workerId}]}}
) {
data {
descriptor
businessTitle
}
}
}
```
## Root Query Field and Arguments
Specify the root query field and its arguments:
rootQueryField ( dataSource: $dataSourceVariable, argument: $variable )
Where:
- rootQueryField( )
The name of the top-level query field, as defined in the FIELDS list of the Query root type in the schema. The query requires parentheses `( )`, which contains the query arguments.
- dataSource: $dataSourceVariable
- `dataSource`
A required query argument. For details about the `dataSource` argument, see [Query Data Source](/wcp_docs/qxq1671067079349.html#section-the-query-data-source).
- ``$dataSourceVariable``
The data source variable, as specified in the input variable declaration. Always begin an input variable with `$`.
- argument: $variable
- `argument`
The name of a query argument, as defined in the schema.
A query provides these optional arguments:
- `where` - An object containing query filters, including Workday ID filters and advanced filtering. See [Query Filters](/wcp_docs/GUID-1a496a09-dbf2-4958-9d1f-12bea23b8855-enHYPHENus.html).
- `limit` - The maximum number of objects in a single response. See [Pagination of Graph API Query Results](/wcp_docs/jgu1675374294877.html).
- `offset` - The zero-based starting position of the row in the query results. See [Pagination of Graph API Query Results](/wcp_docs/jgu1675374294877.html).
- `orderBy` - A list containing sort fields and their sort order. See the Sorting Data section in this topic.
- `$variable`
The corresponding input variable, as specified in the input variable declaration. Always begin an input variable with `$`.
In this query snippet, `worker` is a root query field in the schema. Its arguments are `dataSource`, `limit`, and `offset`:
```
worker ( dataSource: $dataSourceVariable, limit: $limit, offset: $offset )
```
## Response Data Fields
After the root query field and its arguments, specify the response data fields in `{ }`.
Within `data { }`, select schema fields from the `data[ ]` array in the Collection return type.
If a schema field is a nested object, enclose its subfields in braces `{ }`.
You can also select `total`, which is the total number of items retrieved by the query.
In this query snippet, `data { }` contains fields from the `Worker` type, as shown by `data[Worker!]!` within the `WorkerCollection` return type.
```
{
data {
descriptor
workdayID {
id
}
businessTitle
}
}
```
The query returns the data fields in `data.worker.data[]`. Example:
```
{
"data": {
"worker": {
"data": [
{
"descriptor": "Maria Cardoza",
"workdayID": {
"id": "cc7fb31eecd544e9ae8e03653c63bfab"
},
"businessTitle": "Sr Director"
}
]
}
}
}
```
## Query Variables
If you specified an operation name with input variables, you must define all input variables in a JSON map, where:
- key
The input variable name, as specified in the input variable declaration with the operation name.
- value
The value, whose type matches the schema type in the input variable declaration.
The `dataSource` variable is an object map whose structure matches the data source type in the schema.
- The key is the field name of the data source type.
- For information about the data source variable, see [Query Data Source](/wcp_docs/qxq1671067079349.html#section-the-query-data-source).
Sample query variables:
```
{
"dataSourceVariable": {
"indexedAllWorkers": {
"filter": {
"indexedAllWorkersFilter": {
"isActive": true
}
}
}
},
"limit": 50,
"offset": 0
}
```
## Query Data Source
Queries fetch data from a given data source. If a query has a default data source, you can use the default data source by excluding the `dataSource` argument from your query. To override the default data source, specify the `dataSource` argument. Specify an object containing the data source name and a data source filter, if available.
To see the available data sources for your query, see the `dataSource` argument in the schema documentation of the root query. The Documentation Explorer displays the default data source value. If the default data source has a corresponding default filter, the Documentation Explorer also displays the default filter values. The `dataSource` type uses the `_DataSources` suffix and contains the available data sources for the query.
Example: For the `worker` query, the `dataSource` type is `Worker_DataSources`. The FIELDS section lists the available data sources: `indexedAllWorkers`, `processingWorker`, `workersForHCMReporting`.
In this `worker` query snippet, the `dataSource` argument specifies the `indexedAllWorkers` data source:
```
query{
worker(
dataSource: {
indexedAllWorkers: {
filter: {
indexedAllWorkersFilter: {
isActive: true
}
}
}
}
) {
data {
workdayID { id }
businessTitle
}
}
}
```
Note: Ensure that the security domain policy for the data source is active and has the proper permissions. Example: If you use the `indexedAllWorkers` data source, ensure that the Indexed Data Source: Workers security policy is active.
To fetch from multiple data sources, you can include multiple root query fields in the query. For each root query field, you can specify the `dataSource` argument with the data source you want to use. The response data will include data from each query field. This sample query uses multiple root query fields, each with a data source:
```
query {
leaveType(dataSource: {allLeaveOfAbsenceTypes: {}}) {
data {
descriptor
workdayID {id}
}
}
timeOffPlan(dataSource: {allAbsencePlans: {}}) {
data {
displayName
workdayID {id}
}
}
}
```
Note: The above sample queries provide explicit data sources. These simpler equivalent queries don’t specify the `dataSource` argument, which uses the default data sources:
```
query {
leaveType {
data {
descriptor
workdayID {id}
}
}
timeOffPlan {
data {
displayName
workdayID {id}
}
}
}
```
## Data Source Filter
If the data source provides filters, you can specify within the data source object a `filter` containing fields that filter the data collection.
If you specify multiple filter fields, the query performs an exact match of all the specified filter values. If the data source requires a filter but you don't need a filter, specify an empty filter.
Example: The `indexedAllWorkers` data source provides the `indexedAllWorkersFilter` filter.
The `indexedAllWorkersFilter` type is `IndexedAllWorkers_IndexedAllWorkersFilter_Filter`, which contains these filter fields.
In this query snippet, the `indexedAllWorkers` data source specifies the `indexedAllWorkersFilter` filter. The sample filter matches workers that are active in the San Francisco location.
```
{
worker(
dataSource: {indexedAllWorkers: {
filter: {indexedAllWorkersFilter: {
isActive: true,
location: {
id: "San_Francisco",
type: "Location_ID"
}
}
}
}
}
)
}
```
If a data source doesn't provide a filter, specify an empty data source object, `{ }`. Example: The `dataSource` argument of this `company` query specifies the `companies` data source. Its `CompaniesDataSource` type doesn't provide a filter, so `companies` is an empty data source object.
```
query {
company(
dataSource: { companies: { } }
) {
data{
descriptor
}
}
}
```
Where criteria filters
You can use a `where` criteria filter to refine the results of a data source filter. In the `where` argument of a query, you can specify criteria conditions with a boolean expression or a set of criteria fields (that use an implicit AND). See [Query Filters](/wcp_docs/GUID-1a496a09-dbf2-4958-9d1f-12bea23b8855-enHYPHENus.html) and [Sample Query Filters](/wcp_docs/GUID-892f38dd-d294-42e2-bf4b-19ed68e72980-enHYPHENus.html).
## Sorting Data
You can sort query results by either ascending or descending order on values of specified fields. In your query, specify the orderBy argument using this format:
```
orderBy: [
{sortField1 : ASC|DESC},
{sortFieldN : ASC|DESC}
]
```
Each sort field:
- Is a field in the `_OrderInput` schema type. In the Graph API schema, a query includes the argument `orderBy: [_OrderInput]`.
- Must specify either `ASC` for ascending order or `DESC` for descending order.
- Can be of type String, Int, Float, ID, Instant, or LocalDateTime. The type of the `_OrderInput` field in the schema defines the type of the sort field. We currently don’t support Currency and LocalDataTimeZone fields.
If you specify only 1 sort field, you can remove the brackets. You can specify a maximum of 10 sort fields.
Note: Sorting affects query performance.
The query response contains a sorted data collection in the specified order.
## Examples
This query gets all active workers. It uses the `worker` query and sorts the results by the descriptor.
```
query getActiveWorker1($dataSourceVariable: Worker_DataSources!, $limit: BigInt, $offset: BigInt) {
worker(dataSource: $dataSourceVariable, limit: $limit, offset: $offset,
orderBy: {descriptor:ASC}) {
data {
descriptor
workdayID {
id
}
businessTitle
}
total
}
}
```
This JSON map contains the query variables for the corresponding input variable. dataSourceVariable contains the `indexedAllWorkers` data source and the `indexedAllWorkersFilter` filter, which contains the `isActive` filter field.
```
{
"dataSourceVariable": {
"indexedAllWorkers": {
"filter": {
"indexedAllWorkersFilter": {
"isActive": true
}
}
}
},
"limit": 50,
"offset": 0
}
```
Sample response:
```
{
"data": {
"worker": {
"data": [
{
"descriptor": "Aaron Turner [C]",
"workdayID": {
"id": "3bb3dfb98eb310027181e922a9910000"
},
"businessTitle": "Facilities Administrator"
},
{
"descriptor": "Abby Brennan [C]",
"workdayID": {
"id": "6dcb8106e8b74b5aabb1fc3ab8ef2b92"
},
"businessTitle": "Senior Customer Services Representative"
},
{
"descriptor": "Adam Carlton",
"workdayID": {
"id": "1da8b422311b4929bfa4520f7f0b4e83"
},
"businessTitle": "Staff Payroll Specialist"
},
. . .
],
"total": 496
}
}
}
```
This next query is a variation of the getActiveWorkers1 example. Instead of using `$dataSourceVariable`, it declares `$active` as the input variable, and embeds the data source structure inside the query arguments. This query sorts by hire date in descending order and by employee ID in ascending order.
```
query getActiveWorkers2($active: Boolean, $limit: BigInt, $offset: BigInt) {
worker(
dataSource: {indexedAllWorkers: {filter: {indexedAllWorkersFilter: {isActive: $active}}}}
limit: $limit
offset: $offset
orderBy: [{hireDate:DESC}, {employeeID:ASC}]
) {
data {
descriptor
workdayID {
id
}
businessTitle
}
total
}
}
```
The query variables now contain the simpler active scalar variable.
```
{
"active": true,
"limit": 50,
"offset": 0
}
```
The getActiveWorkers1 and getActiveWorkers2 examples return the same response.
Note: You can decide whether to include the data source object as a query argument or as a query variable. It can depend on the complexity of the data source structure and filter. Including the data source structure as an input variable simplifies the construction of the query arguments. However, if there's only 1 filter field, you can include the data source structure in the query and specify the filter field as a query variable. Using simpler query variables can also simplify the construction of query variables in an Extend app.
### Related Information
[Generate Queries on Graph API Explorer](/wcp_docs/uip1679531855079.html)
[Sample Queries](/wcp_docs/rwv1654130107088.html)
[Workday Graph API](/wcp_docs/vyw1671061988370.html)