---
title: "What is Workday Query Language (WQL)? Access and syntax"
description: "WQL is Workday's SQL-like language for reading data sources and fields. The access you need, syntax limits, alias naming rules, a worked query and where to…"
url: https://kiweely.com/guides/workday-wql
---

# What is Workday Query Language (WQL), and how do you write and run a query?

Workday Query Language (WQL) is Workday’s SQL-like language for reading data from data sources and fields instead of reports. You need the Workday Query Language domain in the System functional area; an external caller also needs an API client with System scope.

-   **Checked** against Workday on November 19
-   Applies to **Workday WQL**
-   6 min read
-   Published September 19
-   By Kiweely

Workday Query Language (WQL) is Workday’s SQL-like language for reading data from data sources and their fields, without building a report. To use it you need access to the **Workday Query Language** domain in the System functional area; to call it from outside Workday you also register an API client with **System** scope. You can test a query in the **View WQL Query Result** report, which returns up to 500 rows.

**Kiweely Vine** is a desktop AI agent for Workday consultants and developers (Mac and Windows) that does the Workday work in the tenant you connect: it writes WQL queries, runs them in your tenant and checks the results. See how it works below.

## What access do I need to use WQL?

Workday’s WQL concept page names two requirements.

-   **Security:** access to the *Workday Query Language* domain in the System functional area. A query only sees the data sources and fields that your account has access to. The View WQL Query Result report has the same domain requirement.
-   **From outside Workday:** register an API client with the **Register API Client for Integrations** task and select *System* in the Scope (Functional Areas) prompt. When you manage the refresh token, pick a Workday account that can run reports; the API calls run as that account. You do not register an API client for WQL inside a Workday Extend or Orchestration app.

## Where do WQL data source and field names come from?

Names are aliases. Every Workday-delivered object has a WQL alias, and Workday also creates aliases for calculated fields, delivered or not. You can edit the alias of a calculated field. Because WQL follows security, the same tenant can show a different set to a different person, so read the metadata for the tenant and account you are using rather than copying an alias from an example.

To look them up, call these endpoints from the WQL REST API:

| What | Call |
| --- | --- |
| All data sources | GET /dataSources |
| One data source | GET /dataSources/{WorkdayID} |
| Filters and their prompts | GET /dataSources/{WorkdayID}/dataSourceFilters |
| Fields and calculated fields | GET /dataSources/{WorkdayID}/fields |

In Workday you can instead use the related actions menu on a field, calculated field or data source to view its WQL alias, or build a custom report on the Data Sources or Fields data source with the WQL Alias field. Workday’s tip: find the data source ID with GET /dataSources (the `alias` parameter filters the list), then call GET /dataSources/{ID} to read the aliases to use.

## How do I write my first WQL query?

```
SELECT fullName
FROM allWorkers
WHERE fullName startswith 'Logan'
LIMIT 1
```

`SELECT` and `FROM` are both required. `FROM` names the data source, optionally with a data source filter and its prompts, or `effectiveAsOfDate` and `entryMoment` values for standard Workday-delivered data sources. An optional `PARAMETERS` clause goes at the very start to supply built-in prompt values; `WHERE ON` goes before `WHERE`; `HAVING` works only with `GROUP BY`.

## What are the WQL syntax limits?

| Limit | Source and what we saw |
| --- | --- |
| No `SELECT *` | SELECT reference. In our Development tenant it returned: “Enter a valid report field. This field is invalid: \*.” |
| No `LIKE` | Not in WHERE’s operator list, which has `contains`, `not contains`, `startswith`, `endswith` (case insensitive), `in`, `not in`, `is empty`, `is not empty` and comparisons. In the tenant, LIKE returned “Invalid WQL syntax.” |
| `WHERE ON` before `WHERE` | WHERE reference limitation |
| `LIMIT` must be above 0 and below 1 million, and does not make the query faster | LIMIT reference: Workday retrieves the whole result set before cutting it |
| Cannot group by aggregated fields, currency fields or multi-instance fields | GROUP BY reference |
| No related business object fields with `GROUP BY`; a multi-instance related object holds up to 500 values | Related business objects concept |
| Dates `YYYY-MM-DD`; datetimes `YYYY-MM-DD HH:MM:SS` (Pacific) or with `Z` for UTC | WHERE reference |
| Query text under 2,048 characters for GET /data; 2,048 to 16,000 with POST /data | WQL REST API reference |
| At most 1 million rows per query; tenanted hosts time out after 30 minutes, the WCP API Gateway after 5 | WQL result limits |

## What are the rules for naming an alias in WQL?

Workday’s SELECT reference gives these rules for a custom alias (`SELECT max(yearsOfService) as Seniority`):

-   It cannot be a WQL keyword.
-   WQL does not support escape characters.
-   Some special characters and spaces work in single or double quotes. Workday lists `~ @ $ * - _ / ? : ;` as examples.
-   If two fields share an alias, WQL returns the first field defined in Workday. When you select several fields from the same related object, give each its own alias.

What we saw in the Development tenant, read only, on 16 Nov 2026:

| Alias | Result |
| --- | --- |
| `AS Full_Name` | 200, column `Full_Name` |
| `AS 1st` | 200, column `1st` |
| `AS 'Full Name'` | 200, the column key came back as `'Full Name'`, quotes included |
| `AS Full Name` (no quotes) | 400 “Invalid WQL syntax.” at ‘Name’ |
| `AS from` and `AS select` | 400 “Invalid WQL syntax.” at the keyword |

## How do I select fields from a related business object?

Curly braces select fields from a related business object, as in `SELECT worker, dependents{legalName_FirstName, age} FROM allWorkers`. Filters on those fields go in `WHERE ON`, written without the braces and before the main `WHERE`:

```
SELECT worker, dependents{legalName_LastName}
FROM allWorkers
WHERE ON dependents legalName_LastName startswith "N"
```

Not every instance field has a related object that WQL can traverse, so check the field metadata.

## Where can I run a WQL query?

-   **View WQL Query Result** report: up to 500 rows; Workday truncates when there is no limit or a limit above 500. You can save a query from it.
-   **WQL REST API**: GET /data or POST /data on the tenanted host (`/api/wql/{version}/{tenant}`) or the WCP API Gateway (`api.workday.com/wql/{version}`). Results are viewed 10,000 rows at a time. For more than 500 rows see [getting more than 500 rows from WQL](https://kiweely.com/guides/wql-more-than-500-rows).
-   **Workday Extend or Orchestrate app**: runs WQL in the app’s context without an API client.

See [RaaS, WQL or REST](https://kiweely.com/guides/workday-raas-wql-rest) for choosing a route.

## Worked example: count workers by a field

For Workday’s All Workers data source (`allWorkers`) in a demo tenant with Logan McNeil, check two things first: that you have the Workday Query Language domain, and the alias of the field. Then run:

```
SELECT fullName AS Worker_Name
FROM allWorkers
WHERE fullName startswith 'Logan'
LIMIT 1
```

The tenant returned status 200 and `{"total":1,"data":[{"Worker_Name":"Logan McNeil"}]}`. Changing `startswith` to `LIKE` returned 400 “Invalid WQL syntax.” and replacing the field list with `*` returned the invalid-field message above. For a count, Workday’s own View WQL Query Results page uses `SELECT location, count() FROM allWorkers GROUP BY location ORDER BY count() LIMIT 4`.

## Can AI write a WQL query for me?

Workday provides a Generate WQL API and sample app that turn a natural-language question into a WQL statement. The statement still runs under your security and still has to be checked against the real tenant. For exact error messages see [why a WQL query fails](https://kiweely.com/guides/wql-error-messages).

## Where Kiweely fits

**Kiweely Vine** is a desktop AI agent for Workday consultants and developers (Mac and Windows) that does the Workday work in the tenant you connect. It builds reports and WQL queries in your tenant from a plain business question and checks the results.

In a recorded run in Kiweely’s own Workday Development tenant (with fictional sample data, not a customer result), Vine built a custom report from a plain business question (who works in a supervisory organization and its teams, with years of service and counts), ran it and checked it: **3 of 3 checks passed**, 38 minutes from the question to the checked report. The first result wrongly included an outside manager; Vine corrected it and reran it for a second organization ([watch the film](https://youtu.be/6CQCmhRAtWI)).

Vine Free is $0 on a personal developer tenant with $5 of Kiweely Credits included, and Vine Personal ($99/month) and Vine Team ($149/seat/month) connect to any Workday tenant ([pricing](https://kiweely.com/pricing)). [Start free](https://kiweely.com/download).

## Frequently asked questions

### What is WQL in Workday?

Workday Query Language, a SQL-like syntax for reading Workday data through data sources, data source filters and fields instead of building a report. It can be run in the View WQL Query Result report, through the WQL REST API, or inside a Workday Extend or Orchestrate app.

### What security access do I need to use WQL?

Access to the Workday Query Language domain in the System functional area. Results are limited to the data sources and fields your account can already see. An external system also needs an API client registered with System scope; an Extend or Orchestration app does not.

### Does WQL support SELECT \* or LIKE?

No to both. Workday's SELECT reference says WQL does not support SELECT \*, and in our Development tenant LIKE returned a syntax error. Use contains, startswith or endswith for text matching.

### What are the rules for naming an alias in WQL?

A custom alias after AS cannot be a WQL keyword, and WQL has no escape-character syntax. Workday says some special characters and spaces work when the alias is in quotes. Two fields with the same alias return the first one defined in Workday, so give each a unique alias.

### How many characters can a WQL query have?

GET /data takes queries under 2,048 characters. For queries between 2,048 and 16,000 characters, use POST /data and put the query in the request body.

## Sources checked

-   [Workday Query Language (concept, enabling WQL, security)](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/aht1611188422513.html)
-   [WQL reference: FROM](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/wql-reference/kba1611189724822.html)
-   [WQL reference: SELECT](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/wql-reference/wif1611189270836.html)
-   [WQL reference: WHERE](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/wql-reference/fsf1611267464081.html)
-   [WQL reference: LIMIT](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/wql-reference/gpc1611882698475.html)
-   [WQL reference: GROUP BY](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/wql-reference/kqk1611267573270.html)
-   [WQL aliases](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/ktw1644956621314.html)
-   [Related business objects in WQL](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/pog1611884088079.html)
-   [View WQL Query Results](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/dsv1647475571660.html)
-   [WQL result limits](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/future--reference--wql-result-limits.html)
-   [WQL REST API](https://doc.workday.com/admin-guide/en-us/reporting-and-analytics/custom-reports-and-analytics/workday-query-language-wql-/srr1614364076622.html)
-   [Generate WQL REST API](https://developer.workday.com/documentation/GUID-e50a3478-d091-4f09-87f9-d96d77bb6a71-enHYPHENus)

## Related guides

[All guides](https://kiweely.com/guides)

-   [### WQL Cheat Sheet: Workday Query Language Syntax, Data Sources and Working Examples Workday Query Language reads Workday data sources with SQL-like clauses: PARAMETERS, SELECT, FROM, WHERE ON, WHERE, GROUP BY, HAVING, ORDER BY and LIMIT. Syntax, operators and examples to copy.](https://kiweely.com/guides/workday-wql-cheat-sheet)
-   [### Should I use RaaS, WQL or the REST API to extract data from Workday? Use RaaS for a saved report’s output, WQL for a filtered, grouped or paged extract of up to 1 million rows, and REST for small, low-latency reads of one resource. Limits and sources are in the table.](https://kiweely.com/guides/workday-raas-wql-rest)
-   [### Why does my Workday WQL query fail? The exact error messages and how to fix each one Workday has no WQL message worded ‘instance set invalid for prompt’. A rejected prompt value returns ‘Invalid Parameter Values for parameter’ or ‘does not meet the restrictions defined for this field’. This page quotes each common error as Workday returned it, with the fix.](https://kiweely.com/guides/wql-error-messages)
-   [### How do I get more than 500 rows from a Workday WQL query? The 500-row stop belongs to the View WQL Query Result report. The WQL REST API returns up to 10,000 rows per page: pass limit (0 to 10,000) and offset. A worked run pages 48,491 rows in five calls, with Workday’s exact errors for a limit above 10,000 and an offset past the end.](https://kiweely.com/guides/wql-more-than-500-rows)

### More guides on WQL

[All 31 guides](https://kiweely.com/guides#wql)

-   [Why does WQL return 403 permission denied S22 for an ISU?](https://kiweely.com/guides/workday-wql-403-s22-as-isu)
-   [Why does Convert Report to WQL break after a field rename?](https://kiweely.com/guides/workday-convert-report-to-wql-after-field-rename)
-   [Why does Convert Report to WQL say this field is missing an adhoc alias?](https://kiweely.com/guides/convert-report-to-wql-adhoc-alias)
-   [How do I build a Workday integration inventory report with every integration system, its template, schedule, last run and owner?](https://kiweely.com/guides/workday-integration-inventory-report-wql)
-   [Retrieving Eligible Absence Plans and Live Balances for a Worker via Workday APIs](https://kiweely.com/guides/workday-absence-balances-api-eligible-plans-for-worker)
-   [Querying the Workday Worker Directory, Supervisory Hierarchy, and Cost Centers with WQL](https://kiweely.com/guides/workday-worker-directory-org-chart-search-fields-wql)
-   [Querying Open Job Requisitions and Supervisory Org Headcount via Workday Staffing APIs](https://kiweely.com/guides/workday-staffing-api-job-requisitions-open-positions-managers)
-   [Finding Unsubmitted Workday Time Blocks and Project Hours with WQL](https://kiweely.com/guides/workday-project-time-tracking-unsubmitted-hours-wql)

### From the blog on WQL

[All posts](https://kiweely.com/blog)

-   [Build vs. Buy a Workday MCP Server: OAuth 2.1, SOAP, WQL, and Twice-Yearly Releases](https://kiweely.com/blog/build-vs-buy-workday-mcp-server-engineering-cost)
-   [What happens after ChatGPT writes your WQL query](https://kiweely.com/blog/after-chatgpt-writes-your-wql)
-   [Answering Executive Span-of-Control and Headcount Questions Live from Workday](https://kiweely.com/blog/executive-org-span-of-control-attrition-questions-live-workday)

## Let Workday check the work.

Kiweely writes WQL and builds orchestrations in your own tenant, and Workday, not Kiweely, says whether they passed.

[Start for free](https://kiweely.com/download) [See how it works](https://kiweely.com/vine/how-it-works)

## Get the next guide in your inbox.

One email a month with new guides and one Extend tip. Nothing else.
