--- title: "Enhanced Querying with JQL" canonical: "https://docs.getxray.app/space/XRAYCLOUD/44565225/Enhanced%20Querying%20with%20JQL" format: markdown ---

Table of Contents

> Macro (toc)

# Overview JQL (Jira Query Language) functions in Xray provide querying capabilities that help you retrieve Test-related information efficiently. These functions enable you to explore relationships between Xray Issue Types, such as [Tests](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565156), [Test Sets](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565163), [Test Executions](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565117), Requirements, and more. By leveraging these functions, teams can filter and analyze data for better Test management and reporting. > ℹ️ DC Compatible JQL functions are currently in Closed **[Beta](https://docs.getxray.app/space/XRAYCLOUD/44565225/Enhanced+Querying+with+JQL#Limitations)**. Access to these functions is behind a [Feature toggle](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565845). If you are interested in participating in this program, please submit your **[access request here](https://www.getxray.app/lp/xray-jqlfunction-request)****.** The Xray team will review your request and provide further guidance. # How It Works Xray extends Jira's native JQL functionality by introducing custom functions that interact with Test-related Issues. These functions can be used within Jira's Issue Search page to refine queries and extract meaningful insights. Each function operates by accepting specific parameters, such as Issue keys, project identifiers, saved filters, [Test statuses](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44566467), and [environments](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565129). Depending on the function, it returns relevant Issue Types, allowing teams to track [Test coverage](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565225), identify gaps, and monitor execution results. The JQL functions in Xray follow a structured format where users can input key parameters, such as: - Test Issue keys. - Test Set Issue keys. - Requirement Issue keys. - Test Execution statuses. - Fix Versions. - Environments. ## Impact Using these JQL functions enhances Test management operations by: - **Improving traceability:** enables linking Tests, Requirements, and Test Executions for comprehensive tracking. - **Enhancing efficiency:** reduces manual efforts in identifying relationships between different Test entities. - **Supporting advanced reporting:** helps generate precise Test execution and Requirement coverage reports. - **Ensuring quality assurance:** identifies gaps in Test coverage and monitors defect trends effectively. # JQL Functions The following JQL functions are available to query Xray Issues on the Issue Search Page. They enable you to query the relationships between Xray Issue Types. ## Types of JQL Functions There are two types of JQL functions available in Xray: ### Default JQL Functions (Event-based Caching) - `testPlanTestExecutions` - `testSetTests` - `defectsCreatedDuringTestExecution` - `testsWithoutTestExecution` ### Closed Beta JQL Functions (Cached, DC-compatible) - Instructions for Customers Enrolled in Closed Beta Some customers have access to **Closed Beta JQL functions** that behave the same as Xray DC functions and include caching. If your instance is enrolled in Closed Beta, you can switch between event-based and DC-compatible cached JQL functions, as explained below. > Macro (rw-ui-steps-macro) > > > Macro (rw-step) > > On your Jira Cloud instance, go to the [Global Settings Features](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565845) screen (Admin only). > > > Macro (rw-step) > > Under *Your apps* (Figure 1 - 1), click the ellipsis icon (Figure 1 - 2) next to *Xray *and then *App settings* (Figure 1 - 3). > > ![Figure 1 - Apps.png](media://c924c418-4fbd-4614-aef3-d6f4735d0c20) > > > Macro (rw-step) > > The *Features* screen will open (Figure 2). Use the toggle to enable/disable the *Xray DC compatible JQL Functions* option (Figure 2 - 2). **When this option is disabled, only the four functions mentioned above (*****testPlanTestExecutions*****, *****testSetTests*****, *****defectsCreatedDuringTestExecution*****, and *****testsWithoutTestExecution*****) are available.** > > ![Figure 2 - Features](media://4726bed5-1456-4f7e-abab-d35b281a5449) ## JQL Functions - Technical Details | **JQL Function** | **Parameters** | **Description** | **Example** | **Notes** | | --- | --- | --- | --- | --- | | **testSetTests** | **Event-based:**
P1 - Test Set Issue Key or ID of Test Sets (mandatory) | Returns a list of Test Issues associated with the input Test Set Issue key | ^{issuetype = 'Test' and key in testSetTests('DEMO-5')} | You can send several Test Sets keys separated by “|” (instead of just one). | | **testsWithoutTestExecution** | **Event-based:**
P1 - Project key (mandatory)
P2 - Fix version
P3 - Affects version | Returns a list of Tests that are not associated with a Test Execution to be executed | ^{issuetype = Test and issue in testsWithoutTestExecution(PROJ-123)} | Three parameters:
- *Project* (mandatory) - *FixVersion* (optional) - *AffectsVersion *(optional) | | **defectsCreatedDuringTestExecution** | **Event-based:**
P1 - Test Execution issue Key or ID of Test Executions (mandatory)
**DC Compatibility:**
P1 - Test Execution issue Key or Filter Name/ID of Test Executions
P2 - List of users separated by "|" (pipe) (optional) | Returns a list of Defects created during the execution of the specified Test Executions; can optionally be filtered by the Defect Issue Assignee username | ^{(1) issue in}
^{defectsCreatedDuringTestExecution(TEST-123)}
^{(2) issue in}
^{defectsCreatedDuringTestExecution(saved_filter)}
^{(3) issue in}
^{defectsCreatedDuringTestExecution(saved_filter, 'user1|user2')}
^{(4) issue in}
^{defectsCreatedDuringTestExecution(TEST-123, 'user1|user2')} | **Event-based: **
- The* Filters* parameter is not available. - You can send several Test Execution keys separated by “|” (instead of just one).
**DC Compatibility:** you can send several Test Execution keys separated by “|” (instead of just one). | | **testPlanTestExecutions** | **Event-based:**
P1 - Test Plan Key or ID of Test Plans (mandatory)
**DC Compatibility:**
P1 - Test Plan Key or Filter Name/ID of Test Plans | Returns a list of Test Executions that are associated with a Test Plan or a saved filter of Test Plans. | ⁽¹⁾
^{issue in testPlanTestExecutions("DEMO-10")}
(2)
^{issue in testPlanTestExecutions("Test Plans saved filter")} | **Event-based: **
- The* Filters* parameter is not available. - You can send several Test Plan keys separated by “|” (instead of just one).
**DC Compatibility:** you can send several Test Plan keys separated by “|” (instead of just one). | ## Xray DC Compatible JQL Functions > ℹ️ DC Compatible JQL functions are currently in Closed **[Beta](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUDDRAFT/pages/44829594)**. A [feature toggle](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565845) is available (Figure 2), allowing you to enable or disable them based on your needs. If you find the current limitations too restrictive, you can choose to turn them off. > ℹ️ > ℹ️ If you are interested in participating in this program, please submit your **[access request here](https://www.getxray.app/lp/xray-jqlfunction-request)****.** Our team will review and provide further guidance. | **JQL Function** | **Parameters** | **Description** | **Example** | **Notes** | | --- | --- | --- | --- | --- | | **testTestSet** | P1 - Test Set Issue Key or Filter Name/ID of Test Sets | Returns a list of Test Set Issues associated with the input Test issue key | ⁽¹⁾
^{issuetype = 'Test' and key in testSetTests('DEMO-5')}
⁽²⁾
^{issuetype = 'Test'}
^{and key in testSetTests('Test sets saved filter')} | N/A | | **testSetTests** | P1 - Test Set Issue Key or Filter Name/ID of Test Sets | Returns a list of Test Issues associated with the input Test Set Issue key | ⁽¹⁾
^{issuetype = 'Test' and key in testSetTests('DEMO-5')}
⁽²⁾
^{issuetype = 'Test'}
^{and key in testSetTests('Test sets saved filter')} | N/A | | **testsWithNoTestSet** | P1 - Saved filter Name/ID | Returns a list of Test issues not associated with a Test Set | ⁽¹⁾
^{issue in testsWithNoTestSet()}
⁽²⁾
^{issue in testsWithNoTestSet("saved_filter")} | N/A | | **testPreConditions** | P1 - Test Issue Key | Returns the Precondition Issues associated with the input Test issue key | ^{issuetype = 'Precondition'}
^{and key in testPreConditions('DEMO-1')} | N/A | | **preConditionTests** | P1 - Pre-Condition Issue Key | Returns the Test issues associated with the input Pre-Condition Issue key | ^{issuetype = 'Test'}
^{and key in preConditionTests('DEMO-1')} | N/A | | **testRequirements** | P1 - Test Issue Key or Filter Name/ID of Tests | Returns a list of Requirement Issues associated with the input Test issue key/Filter of Tests | ⁽¹⁾ ^{issuetype = 'Feature'}
^{and key in testRequirements('DEMO-1')}
(2)
^{issuetype = 'Feature'}
^{and key in testRequirements('Tests saved filter')} | N/A | | **requirementTests** | P1 - Requirement Issue Key or Filter Name/ID of Requirement Issues | Returns a list of Test Issues associated with the input Requirement issue key or saved filter with Requirements | ⁽¹⁾
^{issuetype = 'Test'}
^{and key in requirementTests('DEMO-10')}
⁽²⁾
^{issuetype = 'Test'}
^{and key in requirementTests('Requirements saved filter')} | N/A | | **testsWithReqVersion** | P1 - Project Name/Key/Id
P2 - Fix Version * *
P3 - Fix Version (Optional)
...
Pn - Fix Version (Optional) | Returns a list of Test Issues associated with the Requirement issues of the input Fix Versions of the specified project | ^{issuetype = 'Test'}
^{and issue in}
^{testsWithReqVersion('DEMO',}
^{'v1.0', 'v1.1')} | N/A | | **testExecutionTests** | P1 - Test Execution Issue Key or Filter Name/ID
P2 - Test Run Status list separated by "|"(pipe) *(Optional)*
P3 - User assigned to execute Test Run (Optional)
P4 - Defects Flag with value in true or false (needs to be **true **or **false**).
P5 - User who executed the Test Run (optional).
P6 - Existence of comments (*Optional*)
P7 - Existence of evidence (*Optional*)
*P8 - Started from (symbols ****>****/****<**** are read as bigger, exactly/smaller or exactly, respectively; the ****=**** sign or the full absence of signs is read as exactly)*
P9 - Finished on (symbols **>**/**<** are read as *bigger, exactly*/*smaller, or exactly*, respectively; the **=** sign or the full absence of signs is read as *exactly*) | Returns a List of Test issues associated with the input Test Execution issues from *P1 *optionally filtered by the current Test Run status for each Test Issue.
Parameter *P1* can either be a single Test Execution issue key or a saved filter containing multiple Test Execution Issues.
Possible Test Run Status values are: PASS, FAIL, EXECUTING, ABORTED, TODO, and all custom statuses.
P3 corresponds to the user assigned to execute the Test Run, while P5 corresponds to the one who actually executed it. For analyzing the joint values of all Test Run Assignees, "" should be used. For taking into account the Test Runs without any Assignee, then "__NULL__" should be used.
If you pass true as the value for P4, the query returns all Tests from a particular set of Test Executions where no Defects were created. | ⁽¹⁾
^{issuetype = 'Test'}
^{and issue in testExecutionTests('DEMO-9')}
(2)
^{issuetype = 'Test'}
^{and issue in testExecutionTests('DEMO-9',}
^'PASS')
(3)
^{issuetype = 'Test'}
^{and issue in testExecutionTests('DEMO-9',}
^'PASS',
^{'user A')}
(4)
^{issuetype = 'Test'}
^{and issue in testExecutionTests(}
^{'Saved Test Execution Filter',}
^'PASS')
(5)
^{issuetype = 'Test'}
^{and issue in testExecutionTests(}
^{'Saved Test Execution Filter',}
^'',
^{'user A')}
(6)
^{issue in testExecutionTests(}
^{'Saved Test Execution Filter',}
^'',
^{'user A', 'true')}
(7)
^{issue in testExecutionTests(}
^{'Saved Test Execution Filter',}
'','', 'false', 'admin')
(8)
issuetype = 'Test'
and issue in testExecutionTests(
'CALC-397',
'',
'',
'false',
'',
'true',
'false',
'>2016-05-31',
'<2016-06-30') | N/A | | **testsWithoutTestExecution** | P1 - Saved filter Name/ID | Returns a list of Tests that are not associated with a Test Execution to be executed | ⁽¹⁾
^{issuetype = Test and issue in testsWithoutTestExecution()}
⁽²⁾
^{issuetype = Test and issue in testsWithoutTestExecution("saved_filter")} | N/A | | **requirements** | P1 - Status list separated by "|"(pipe)
P2 - Project (Optional)
P3 - Version to calculate requirement status (Optional)
P4 - Test Environment (Optional)
P5 - Flat (Optional)
P6 - ToDate (Optional)
P7 - Saved Filter (Optional) | Returns a list of Requirement Issues with the provided coverage status.
Please provide *Project* parameter (P2) to restrict the requirements to the specified project.
If analyzing a specific version, then the *Project and* * Version *parameters must be filled.
Optional filters include:
*Test Environment*, for taking into account the Test Executions made for that environment. For analyzing the joint values of all environments, "" should be used. For taking into account the Test Executions without any Test Environment assigned, then "__NULL__" should be used.
*Flat *that indicates whether all Requirements (not only parents) should be searched. If "Flat" is not provided, the default value is 'false'.
*ToDate *considers only those requirements executions before a specific date/time (the date literal must follow the ISO8601 format).
*Saved Filters* considers only requirements from that specific filter. | ⁽¹⁾
^{issue in requirements('OK','Calculator')}
> ⚠️ Although optional, it is highly recommended to specify the *Project* parameter as a means to define the project having the Requirements and thus reduce the number of Issues that will be processed/returned. Otherwise, requirements from *all* JIRA projects will be processed, which possibly is something that you don't want or need at all.
⁽²⁾
^{priority = Major and fixVersion <= 'v3.0' and}
^{issue in requirements('NOK', 'Calculator', 'V4.0')}
⁽³⁾
^{issue in}
^{requirements('NOK', '', '', '', '','2014-01-01')}
⁽⁴⁾
^{issue in}
^{requirements('OK',}
^{'Calculator',}
^'v1.0',
^'chrome'
^'false'
^{'2014-08-30')}
⁽⁵⁾
^{issue in}
^{requirements('NOK',}
^{'Calculator',}
^'v2.0', ^'',
^'true')
⁽⁶⁾ ^{issue in} ^{requirements('NOK',} ^{'Calculator',} ^'v2.0', ^'chrome', ^'false', ^{' ',} ^{'Requirements saved filter')}
| N/A | | **requirementsWithStatusByTestPlan** | P1 - Status list separated by "|"(pipe)
P2 - Test Plan Issue Key
P3 - Test Environment (Optional)
P4 - Flat (Optional)
P5 - ToDate (Optional)
P6 - Project (Optional)
P7 - Saved Filter (Optional) | Returns a list of Requirement Issues with the coverage status calculated for the given Test Plan Issue.
Optional filters include:
*Test Environment*, for taking into account the Test Executions made for that environment. For analyzing the joint values of all environments, "" should be used. For taking into account the Test Executions without any Test Environment assigned, then "__NULL__" should be used.
*Flat *that indicates whether all Requirements (not only parents) should be searched. If "Flat" is not provided, the default value is 'false'.
*ToDate *considers only those requirements executions before a specific date/time (the date literal must follow the ISO8601 format).
*Project* and *Saved Filters* considers only requirements from that specific project or filter. | ⁽¹⁾
^{issue in}
^{requirementsWithStatusByTestPlan('OK', 'TP-123')}
⁽²⁾
^{issue in}
^{requirementsWithStatusByTestPlan('NOK',}
^'TP-123',
^'',
^'true')
(3)
^{issue in}
^{requirementsWithStatusByTestPlan('NOK',}
^'TP-123',
^'Android',
^'false',
^{'2014-01-01')}
⁽⁴⁾ ^{issue in} ^{requirementsWithStatusByTestPlan('NOK',} ^'TP-123', ^'Android', ^'false', ^{' ',} ^{'Calculator',} ^{'Requirements saved filter')} | N/A | | **defectsCreatedDuringTesting** | P1 - Test Issue Key or Filter Name/ID of Test Issues | Return a list of Defects created during the execution of the specified Tests | ⁽¹⁾
^{issue in defectsCreatedDuringTesting()}
⁽²⁾
^{issue in defectsCreatedDuringTesting("TEST-123")}
⁽³⁾
^{issue in defectsCreatedDuringTesting("saved_filter")} | N/A | | **defectsCreatedDuringTestExecution** | P1 - Test Execution issue Key or Filter Name/ID of Test Executions
P2 - List of users separated by "|" (pipe) (Optional) | Returns a list of Defects created during the execution of the specified Test Executions; can optionally be filtered by the Defect Issue Assignee username | ^{(1) issue in}
^{defectsCreatedDuringTestExecution(TEST-123)}
^{(2) issue in}
^{defectsCreatedDuringTestExecution(saved_filter)}
^{(3) issue in}
^{defectsCreatedDuringTestExecution(saved_filter, 'user1|user2')}
^{(4) issue in}
^{defectsCreatedDuringTestExecution(TEST-123, 'user1|user2')} | N/A | | **defectsCreatedForRequirement** | P1 - Requirement key or Filter Name/ID of Requirement Issues | Returns a list of defects created during the execution of Tests covering the specified Requirements | ⁽¹⁾
^{issue in defectsCreatedForRequirement("REQ-123")}
⁽²⁾
^{issue in defectsCreatedForRequirement("saved_filter")} | N/A | | **manualTestsWithoutSteps** | P1 - Filter Name/ID | Returns a list of Manual Tests that have no [Enhanced Querying with JQL](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565225) | ⁽¹⁾
^{issue in manualTestsWithoutSteps()}
⁽²⁾
^{issue in manualTestsWithoutSteps("saved_filter")} | N/A | | **testTestExecutions** | P1 - Test Issue Key or Filter Name/ID of Test issues
P2 - Test Run Status list separated by "|"(pipe) (Optional) | Returns a list of Test Executions associated with the input Test Issues from *P1 *optionally filtered by the current Test status in each Test Execution Issue.
Parameter *P1* can either be a single Test Issue key or a saved filter name or ID containing multiple Test Issues.
Possible Test Run Status values are: PASS, FAIL, EXECUTING, ABORTED, TODO and all custom statuses. | ⁽¹⁾
^{issuetype = 'Test Execution'}
^{and issue in testTestExecutions('DEMO-9')}
(2)
^{issuetype = 'Test Execution'}
^{and issue in testTestExecutions('DEMO-9',}
^'PASS')
(3)
^{issuetype = 'Test Execution'}
^{and issue in testTestExecutions(}
^{'Saved Test Filter',}
^'PASS') | N/A | | **testExecWithTestRunsAssignedToUser** | P1 - Username
P2 - Status (Optional) Username is required in case we use this parameter | Returns a list of Test Executions where a user has at least one test run assigned to him. You must specify a user with P1. The current user will no longer be used automatically, even if you are logged in to Jira. If you are not logged in, specifying a user is also required.
Additionally, if you use a status parameter, the user parameter (P1) is always required. | (1)
^{issuetype = 'Test Execution' and}
^{issue in testExecWithTestRunsAssignedToUser('userDPC')}
(2)
^{issuetype = 'Test Execution' and}
^{issue in testExecWithTestRunsAssignedToUser('userDPC', "FAIL")} | N/A | | **testSetPartiallyIn** | P1 - Test Execution Issue Key or Test Plan Issue Key or Filter Name/ID of Test Executions or Test Plans | Return a list of Test Sets that have at least one test in *P1* | (1)
^{issuetype = 'Test Set' and}
^{issue in testSetPartiallyIn('DEMO-15')}
(2)
^{issuetype = 'Test Set' and}
^{issue in testSetPartiallyIn('testExecList')}
(3)
^{issuetype = 'Test Set' and}
^{issue in testSetPartiallyIn('testPlanList')} | N/A | | **testSetFullyIn** | P1 - Test Execution Issue Key or Test Plan Issue Key or Filter Name/ID of Test Executions or Test Plans | Return a list of Test Sets that have all its Tests in *P1* | (1)
^{issuetype = 'Test Set' and}
^{issue in testSetFullyIn('DEMO-15')}
(2)
^{issuetype = 'Test Set' and}
^{issue in testSetFullyIn('testExecList')}
(3)
^{issuetype = 'Test Set' and}
^{issue in testSetFullyIn('testPlanList')} | N/A | | **testPlanTests** | P1 - Test Plan Key or Filter Name/ID of Test Plans
P2 - Status (Optional)
P3 - Environment (Optional) | Returns a list of Tests that are associated with the Test Plan.
The "status" parameter is optional and allows to filter Test Issues in a specific Plan with the specified execution status. If the "status" parameter is present, users might also pass the "environment" parameter. If this parameter is filled, Xray will provide all Tests in a Test Plan that are in the specified "status" and for the specified "environment". | (1)
^{issue in testPlanTests("DEMO-10")}
⁽²⁾
^{issue in testPlanTests("Test Plans saved filter","TODO")}
(3)
^{issue in testPlanTests("DEMO-10","TODO")}
(4)
issue in testPlanTests("DEMO-10","TODO","IOS") | N/A | | **testPlanTestExecutions** | P1 - Test Plan Key or Filter Name/ID of Test Plans | Returns a list of Test Executions that are associated with a Test Plan or a saved filter of Test Plans. | ⁽¹⁾
^{issue in testPlanTestExecutions("DEMO-10")}
(2)
^{issue in testPlanTestExecutions("Test Plans saved filter")} | **DC compatibility:** you can send several Test Plan keys separated by “|” (instead of just one). | | **testPlanRequirements** | P1 - Test Plan Key or Filter Name/ID of Test Plans | Returns the Requirement issues that are indirectly associated, through Test issues, with a Test Plan or a saved filter of Test Plans | (1)
^{issue in testPlanRequirements("DEMO-20")}
⁽²⁾
^{issue in testPlanRequirements("Test Plans saved filter")}
| N/A | | **testTestPlan** | P1 - Test Issue Key | Returns a List of Test Plan Issues associated with the input Test Issue key | ^{issuetype = 'Test Plan'}
^{and key in testTestPlan('DEMO-1')} | N/A | | **testRepositoryFolderTests** | P1 - Project Key
P2 - Folder Path
P3 - Flatten (Optional) | Returns the list of Tests contained in a folder (P2) of the Test Repository of a Project (P1).
May optionally include the Tests in sub-folders by setting Flatten (P3) to "true". | (1)
issue in testRepositoryFolderTests("CALC", 'Parent/Child')
(2)
issue in testRepositoryFolderTests("CALC", 'Parent/Child', "true") | N/A | | **testPlanFolderTests** | P1 - Test Plan Key
P2 - Folder Path
P3 - Flatten (Optional)
P4 - Test Run Status (Optional)
P5 - Test Environment (Optional) | Returns the list of Tests contained in a folder (P2) of a Test Plan (P1).
May optionally include the Tests in sub-folders by setting Flatten (P3) to "true".
Can also filter by Tests Run Status (P4) for a given Test Environment (P5).
To analyze the joint values of all Test Environments, "" should be used. To analyze the Test Executions without any Test Environment assigned, then "__NULL__" should be used. | (1)
issue in testPlanFolderTests(CALC-10, 'Parent/Child')
(2)
issue in testPlanFolderTests(CALC-10, 'Parent/Child', "true")
(3)
issue in testPlanFolderTests(CALC-10, 'Parent/Child', "true", "TODO|FAIL", "windows") | N/A | | **projectParentRequirements** | P1 - Project Key | Returns the list of Requirement Issues, from a given Project, which are not Sub-requirements | (1) issue in projectParentRequirements("CALC") | N/A | | **testExecutionsWithCompletedTestRunsSince** | P1 - Date
P2 - Filter ID/Name (Optional) | Return the list of Test Execution (belonging to the given filter) that have [Test Runs](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44565109) finished since the given date | (1) issue in testExecutionsWithCompletedTestRunsSince(2022-01-01)
(2) issue in testExecutionsWithCompletedTestRunsSince(2022-01-01 12:00, "Current Sprint TestExecs")
(3) issue in testExecutionsWithCompletedTestRunsSince(-3d, 10101) | N/A | | **testPlansWithCompletedTestRunsSince** | P1 - Date
P2 - Filter ID/Name (Optional) | Return the list of Test Plans (belonging to the given filter) that have Test Runs finished since the given date | (1) issue in testPlansWithCompletedTestRunsSince(2022-01-01)
(2) issue in testPlansWithCompletedTestRunsSince(2022-01-01 12:00, "Current Sprint TestPlans")
(3) issue in testPlansWithCompletedTestRunsSince(-3d, 10101) | N/A | ## Custom Fields and Entity Properties Xray provides several custom fields and entity properties. Jira's entity properties provide the means to store key/value pairs on Jira entities, such as Issues. Xray uses some entity properties that can be queried using JQL. ### Entity Properties | **Entity Property** | **Issue Type** | **Description** | **Example(s)** | | --- | --- | --- | --- | | **testType** | Test | The Test Type that characterizes the nature of the Test | ^{project = DEMO and issuetype = Test and testType = Manual}
^{project = DEMO and testType = Manual} | | **testEnvironments** | Test Execution | The Test Environment(s) assigned to the Test Execution | ^{project = DEMO and issuetype = "Test Execution" and testEnvironments = Chrome}
^{project = DEMO and testEnvironments = Chrome} | # Limitations ## Atlassian Caching Mechanism ### Overview All custom JQL functions on Jira Cloud are required to use Atlassian’s caching mechanism. This improves performance and reduces the time it takes for users to see query results. ### How it works Whenever a JQL function with a specific set of parameters is executed, Atlassian caches the results for seven days. If the exact same function with the same parameters is executed again during that period, Jira retrieves the results from the cache - **not from live data **-** **and displays them instantly. ### Limitations When a JQL function is called with a specific set of arguments, its result is cached for **up to seven days**, regardless of which user made the request. Any user who calls the same function with the same arguments receives the same cached result until the cache is updated. The cache is continuously updated by a background job that refreshes JQL function results for all tenants. Each update cycle can take up to a few hours to complete. As soon as one cycle finishes, the next cycle starts. For example, if you run a JQL query, the result is cached. If you then change or edit work items so that the query should return different results, running the same query again before the background job updates the cache may return the previous, now outdated results. This caching behavior applies to the **DC-compatible JQL functions**, which are a **dark feature** available only upon request through [Xray Support](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28). **Event-based JQL functions** are updated based on relevant events instead and are available when the **DC-compatible JQL functions** toggle is disabled. ## Timeout Period Atlassian enforces a **25-second timeout** for all JQL queries. If a query takes longer than 25 seconds to run, it will return an error. To resolve this, you may need to reduce the scope or complexity of the query. ## 1000 Results Limit JQL queries in Jira Cloud are limited to **1,000 results**. If a query returns more than 1,000 Issues, it will produce an error—instead of returning a truncated list. This is to prevent misleading or incomplete data. > **Example:** > The following function will return an error if more than 1,000 Issues match: > `issue in testsWithoutTestExecution()` > ❌ Most Xray functions get a **saved filter** as an argument to work around Jira's 1,000-result limit. The saved filters used in Xray JQL functions **must not be private**. However, they only need to be shared with the Xray user or configured with a scope that includes Xray. They don’t need to be completely public - though that’s also a valid option. > ❌ > ❌ Go [here](https://developer.atlassian.com/cloud/jira/platform/jql-functions/) to learn more. ### Limit Applies Per Argument Each argument in a JQL query is evaluated independently before the combined result is calculated. This means the 1,000-Issue limit is applied **per argument, not to the final combined result**. > **Example:** > `project = CALC AND issue in testsWithoutTestExecution()` If there are more than 1,000 Tests without Executions across the instance, the enhanced JQL will return an error - due to the limitation explained above. To mitigate this, please use a filter **within the Xray JQL function** to reduce the scope of the search. The Xray team is actively investigating improvements to address these three limitations during the Beta period.

Support/Troubleshooting

If you have questions or technical issues, please [contact the Support team via the Customer Portal (Jira service management)](https://jira.getxray.app/servicedesk/customer/portal/2/user/login?destination=portal%2F2%2Fcreate%2F28) or [send us a message using the in-app chat](https://getxraydocs.atlassian.net/wiki/spaces/XRAYCLOUD/pages/44577312).