Vivid Trace 1.4 JQL Functions

This document contains definitions of all Vivid Trace JQL functions, along with samples of advanced searches that illustrate how these functions can be applied to common situations. To fully understand the information in this document, you should use this document in conjunction with JIRA's Advanced Searching documentation. This document covers the following topics:

For error & warning messages refer to Messages and Codes.

Searching Issue Relationships

Vivid Trace has a suite of highly-configurable JQL functions for comprehensively tracing issues along their issue link relationships and their parent/sub-task relationships using JIRA's Advanced Searching facilities. The essence of these functions is the identification of issues based on their relationships with other issues, a capability that JIRA lacks off-the-shelf.

Rudimentary queries can be formulated in three stages: indicate seed issues ("where to start"), specify how to conduct the search along issue relationships and other factors ("how to follow"), and finally narrow down results to the desired issues ("what to gather"). Once you have acclimated yourself, queries become a matter of describing the desired issues and their relationships to and characteristics of other issues.

JQL Functions and Seed Issues

Let's start with the relations() JQL function. You indicate which issues to start searching from (the seed issues) by passing certain parameters to the function. relations() will find all issues related to the seed issues by issue links and by parent/sub-task relationships. Seed issues can be specified directly as issue parameters, and as the issues returned from jql query parameters. All JQL functions accept any mix and quantity of seed issue parameters.

Objective & ExplanationJQL Query
Find all issues related to a specific issue. Here, ABC-1 is the lone seed issue. This query returns a list of issues that includes the seed issue plus every issue reachable from the seed issue by issue links and by parent/sub-task relationships. Issues for which the current user doesn't have view permission and any further issues beyond it are not included in the results.

issue IN relations(ABC-1)

Find all issues related to and including several seed issues. Here, three issues are referred to by their issue keys, and one by its issue ID.

issue IN relations(ABC-33, ABC-481, 317289, XYZ-67)

Identify all issues related to the issues returned from a JQL query. Depending on the quantity of issues returned from the JQL query and their connectedness, potential many issues can be found.

issue IN relations('jql = labels IN (support, operations)')

Find all issue relations from a mix of seed issues. This query combines both methods of specifying seed issues. The issues found from executing the JQL queries and the directly specified issues are all merged together into the seed issues.

issue IN relations('jql = filter = "Exceeding SLA"', ABC-98, 'jql = assignee = "Beverly Dubois"', XYZ-10)

You can control whether or not the seed issues are included in the search results using the inclusive parameter. Some particular parameter settings recur often enough that they warrant their own shorthand. The relatesWith() function is useful in the common situation where the seed issues are not wanted in the result set.

Objective & ExplanationJQL Query
Find all issues related to, but not including, several seed issues. The inclusive parameter tells the JQL function to not include the seed issues in the resulting list of issues.

issue IN relations(ABC-33, ABC-481, 'inclusive = no')

Another way to write the above JQL query. It produces identical results, but uses the relatesWith() JQL function to make the query more concise and easier to reason about.

issue IN relatesWith(ABC-33, ABC-481)

Searching Issue Link and Parent/Sub-task Relationships

Vivid Trace provides parameters for searching particular types of issue relationships, along with functions that abbreviate the task of writing such queries. The direction parameter controls the effective directions: which kinds of issue relationships are followed when searching. When following issue link directions, the issueLinkType parameter either limits or prunes which issue link types are followed during the search process, thus controlling the effective issue link types. distance controls how far away from the seed issues to scan while conducting the search. The links() function finds issues that have issue links. Where the parents() function identifies parent issues, issues that have sub-tasks, subtasks() finds sub-task issues, issues that have parents and are of a sub-task issue type.

Objective & ExplanationJQL Query
Find all issues in a project that have issue links.

issue IN relations('jql = project = ABC', 'direction IN (inward, outward)')

Another way to write the above JQL query. It produces identical results, but uses the links() JQL function to make the query more concise and easier to reason about.

issue IN links('jql = project = ABC')

Find all issues that have issue links of a certain type.

issue IN links('issueLinkType = Duplicates')

Requirements satisfaction for a given software release.

issue IN relations('jql = project = ABC AND fixVersion = "1.2.3" AND issueType = Requirement')

Examine requirements coverage for a specific component

issue IN relations('jql = component = TMIC and issueType = Requirement', 'direction = outward') AND issueType IN (Requirement, Task, Bug, Test)

Starting from the issues in a saved filter, all issues reachable by up to 3 issue links away.

issue IN links('jql = filter = RemainingTasks', 'distance = 3')

Find all issues outside of a project that are linked to issues within a project.

issue IN links('jql = project = ABC', 'inclusive = no')

All parents in and of the issues found by a saved filter (referenced by name).

issue IN parents('jql = filter = "Back-support Escalated"')

Issues whose sub-tasks are assigned to specific people.

issue IN parents('jql = assignee IN ("Carlita Mendez", "Funani Mkatshana")')

All sub-tasks in and of the issues found by a saved filter (referenced by ID). Sub-tasks directly found by the filter are included in the results only if their parents were found too.

issue IN subtasks('jql = filter = 10020')

All issues involved in cloning: the clones and the cloned (assuming the issue links are intact).

issue IN links('issueLinkType = Cloners')

Overdue issues in a project of concern and the unresolved issues that feed into them.

issue IN relations('jql = project = ABC AND dueDate < now()', 'direction IN (parents, inward)') AND resolution IS EMPTY

Nearby (and thus shorter list of) upstream issues that feed into a project of concern.

issue IN relatesWith('direction in (parents, inward)', 'jql = project = ABC', 'distance = 2', 'issueLinkType in (Blocks, Requires)')

Narrowing Down Results

Seed issues indicate from where to start searching for issue relations, and have the potential to produce impractically large result sets that can't factor into your decision making. To extract only desired issues or to shorten the results to usable quantities, the resulting issues produced by these JQL functions can be further qualified by specifying the characteristics of the desirable issues.

Objective & ExplanationJQL Query
Describe from where to start searching for issue relations by indicating seed issues.

issue IN relations(...)

Describe the nature of issues to produce by qualifying resulting issues with additional JQL clauses.

issue IN relations(...) AND ...

Narrow down the related issues for a project version to higher-priority items assigned to the current user for an impending release.

priority IN (Blocker, Critical) AND assignee = currentUser() AND issue IN relations('jql = fixVersion = "1.2.3"')

Pinpoint all issues outside of a project blocking a release.

issue in links('jql = project = ABC AND fixVersion = "1.2.3"', 'inclusive = no') AND project != ABC

Identify issues shared by two spheres of responsibility.

(issue IN relations(ABC-55, 'distance = 4')) AND (issue IN relations(MNP-177, 'distance = 3'))

Unresolved parent issues for a version, some of which might be from different projects.

issue IN parents('jql = project = ABC AND fixVersion = "1.2.3"') AND resolution IS EMPTY

Show unresolved sub-tasks for a component.

resolution IS EMPTY AND issue IN subtasks('jql = component = Widget')

Search for all issues blocking Zephyr for JIRA tests. Note that, depending on the version of Zephyr that created the issue links, those issue links might be set backwards, requiring an inversion of direction in your JQL queries or in your interpretation of the results.

issue IN relatesWith('jql = issueType = Test', 'distance = 1', 'direction = inward', 'issueLinkType = Blocks') AND issueType != Test

Research documents attached to resolved duplicates while investigating a regression.

attachments IS NOT EMPTY AND ((issue IN relations('issueLinkType = Duplicates') AND resolution IS NOT EMPTY) OR (resolution = Duplicate))

Searching Based on the Existence of Relationships

relations() and certain other sibling functions can be used to identify issues that have at least one relationship with another issue, be it an issue link or a parent/sub-task relationship. Searching based on the existence of relationships is accomplished by not supplying seed issues to the functions. When no seed issues are supplied but certain other parameters are, all issues that match (using issue IN ...) or do not match (using issue NOT IN ...) those parameters will be found.

Objective & ExplanationJQL Query
All issues that have one or more issue link or parent/sub-task relations.

issue IN relations()

Orphan issues: All issues that have no such relations whatsoever.

issue NOT IN relations()

Linked issues in certain statuses.

status IN ('In Progress', 10005) AND issue IN links()

Sub-tasks not in a certain issue status.

resolution != Fixed AND issue IN subtasks()

Potential orphans that are not related to other issues in a project.

project = 'ABC' AND issue NOT IN relations()

Changes that occurred anywhere along an entire value delivery chain (following relations) within the last 7 days.

updated <= 1w AND issue IN relations() AND project = ABC

Quoting Function Parameters

JQL function parameters whose values contain quotes, commas, and other punctuation may require escaping and nested quoting, complicating legibility, readability, and problem diagnoses. Almost all of the parameters to these functions need to be quoted, with either single-quotes or double-quotes. Ideally you can copy & paste directly between parameters and other places, such as issue fields, however because such data also often contains punctuation and requires quoting, the parameters can end up having nested quotes and escaping.

Quotes nested within quotes of the same type, either single- or double-quotes, must be escaped using backslash \ characters. Alternatives to nested quoting and escaping include: Refer to source objects by ID instead of by name, split portions of the query into saved filters and reference those filters instead, or eliminating spaces and other JQL punctuation from the source objects' names.

Objective & ExplanationJQL Query
A query with nested quotes that identifies issues linked with the Cross Check issue link type. The issueLinkType parameter is surrounded with quotes, and its parameter value is also quoted because the name contains a space character. Because the inner quotes nested within the outer quotes are of the same type, the inner quotes need to be escaped. Notice how the escaping reduces readability.

issue IN links("issueLinkType = \"Cross Check\"")

Another way to write the above JQL query. The respective quotings are different, and therefore the inner quotes need not be escaped. Note that single and double quotes may be difficult to distinguish when placed adjacently, as is so near the end of this query.

issue IN links("issueLinkType = 'Cross Check'")

Yet another way to write the above queries. It also produces identical results, but references the issueLinkType by its ID, thereby avoiding nested quotes altogether, improving legibility while sacrificing readability.

issue IN links("issueLinkType = 10212")

Accuracy of Results

When the stakes are high and a query's results are being fed into critical decision making processes like Release to Manufacturing or when asking "should this project be funded?", you need to understand the information in this section.

Security and JIRA Permissions

Vivid Trace enforces the JIRA security model but deviates in one aspect for the sake of accurate results: Vivid Trace JQL functions issue warning VTW-7 whenever the search process finds related issues for which the user executing the search doesn't have browse permission. Such issues become dead-ends and are not reported in the results. This warning alerts the viewer to the incompleteness of the results on account of the current user not having the necessary permissions to display all related issues. Whether that incompleteness matters to you depends on your use case. When every last related issue needs to be put under the spotlight, such as when conducting traceability analysis, you need to ensure that the JIRA user account in use has permission to browse all issues in question.

VTW-7: One or more issues have been omitted due to insufficient browse permissions.

Warning message VTW-7 that accompanies incomplete search results when the current user lacks permission to browse one or more of the related issues.

In keeping with JIRA's own JQL functions, Vivid Trace JQL functions will not acknowledge seed issues for which the current user lacks browse permissions, returning error message VTE-1 instead.

The projectConfig Parameter

These JQL functions can apply project configurations (by specifying the projectConfig = apply parameter) to affect the results. Because project configurations can be changed over the course of a project's lifetime, the projectConfig parameter should not be apply'ed wherever results must remain consistent even when project configuration changes, for example in long-serving saved filters.

Stables IDs and Volatile Names: Interpretation of Parameter Values and Trade-offs

For parameter values that can specify JIRA objects by either ID or name, such as for issue link types, the value will be treated as an ID first, and if the ID cannot be resolved, then it will be treated as a name for another try at resolution. With this ordering, your queries will not change their behavior even when an object is created with or renamed to a name that mimics the IDs used in your queries.

And this is the trade-off: When reading JQL queries, names are helpful because they convey meaning, while as simple numbers IDs are inherently opaque. On the other hand, while IDs cannot be changed, names can be edited by owners or administrators at any time, and distinct objects can bear identical names leading to ambiguity. Renaming objects can cause saved JQL queries whose function parameters refer to such objects by name to return incorrect results or start returning errors instead. In short, use of IDs in function parameters earns you queries that are more resistant to renaming and thus stable but at the cost of legibility, whereas names are readable but potentially hazardous, especially when a query's results are being fed into critical decision making processes like Release to Manufacturing or when asking "should this project be funded?" A correct approach is to select for readability versus sure-fire correctness of results. Queries written in an unstable manner can produce nearly imperceptible differences, wildly different results, or errors. Errors are perhaps the best outcome, because they alert you to the changes while not producing poisonous results.

To help eliminate ambiguity and maligned query results, Vivid recommends clearly avoiding naming objects in a way that can be interpreted as IDs. For example, avoid naming a saved filter as "10001", as that name is interpretable as an ID and likely overlaps an existing, different saved filter whose ID actually is 10001.

Objective & ExplanationJQL Query
As version 1.2.3 can be renamed or exist in several projects, this query is susceptible to producing different results should the names of the referenced objects change.

issue IN relations('jql = project = ABC AND fixVersion = "1.2.3"')

Even if the same version string is registered in several projects, version IDs uniquely identify a singular version in one project. Even if the version is renamed, this query will continue producing reliable results.

issue IN relations('jql = fixVersion = 11806')

JQL Function Reference

Vivid Trace comes equipped with a suite of JQL functions for identifying related issues according to a variety of criteria, specified as parameters. Function parameters are detailed in the next section. In addition to the general relations() JQL function, there are several specializations at your disposal for writing more concise JQL queries that are easier to reason about. The ordering of issues produced by these JQL functions is unspecified.

None of these functions observe or are affected by the Issue Count Soft Maximum, a setting that limits the size of the results, or by the Graph Traversal Time Limit, a setting that caps the amount of time JIRA spends computing results. Functions that are asked to make use of issue linking and/or sub-task features that are disabled in your JIRA system will issue warning messages VTW-8 and VTW-9, respectively.

The functions are:

Usage

links( [optional PARAMETER] [, more PARAMETERs] )

where PARAMETER is one of distance, inclusive, issue, issueLinkType, jql, or projectConfig.

Description

Identifies issues reachable from the seed issues by following along issue links, according to parameters. Without seed issues, identifies all issues that have issue links. Equivalent to relations() with direction IN (inward, outward).

Returns List of issues.
Availability Since Vivid Trace 1.2.

parents()

Usage

parents( PARAMETER [, more PARAMETERs] )

where PARAMETER is one of distance, inclusive, issue, issueLinkType, jql, or projectConfig.

Description

In terms of parent/sub-task relationships, parent issues are issues that have sub-tasks. This function identifies those seed issues that are parent issues plus all issues that are parents of the seed issues, according to parameters. When used without seed issues, this function identifies all parent issues.

JIRA's own JQL function standardIssueTypes() returns a list of issues types that are able to have sub-tasks. In contrast, parents() finds parent issues that actually have sub-tasks.

Returns List of issues.
Availability Since Vivid Trace 1.2.

relatesWith()

Usage

relatesWith( PARAMETER [, more PARAMETERs] )

where PARAMETER is one of direction, distance, issue, issueLinkType, jql, or projectConfig.

Description

Identifies issues that relate with, but do not include, the seed issues, according to parameters. Issue link and parent/sub-task relationships are all considered. This function requires seed issues. Equivalent to relations() with inclusive = no.

Returns List of issues.
Availability Since Vivid Trace 1.2.

relations()

Usage

relations( [optional PARAMETER] [, more PARAMETERs] )

where PARAMETER is one of direction, distance, inclusive, issue, issueLinkType, jql, or projectConfig.

Description

Identifies issues that are related to the seed issues by following along issue link and parent/sub-task relationships, according to parameters. By default, this function will search for all issues related to the seed issues in all directions at any distance, and include the seed issues in the results.

Searches are performed by first determining which issues to start searching from (the seed issues). Issues directly specified as issue parameters, and issues resulting from executing the supplied jql query parameters are all aggregated into a single set of seed issues. The order in which seed issues are aggregated is unspecified. Note that if seed issue parameters are supplied but no seed issues were found, warning message VTW-4 is returned without performing a search.

Next, the search begins for related issues. The search is conducted on each seed issue, and no further than specified by the distance parameter. Relationships are followed according to the direction and issueLinkType parameters. According to the projectConfig parameter, certain parameters are overridden by the project configuration corresponding to each individual seed issue. Issues for which the current user doesn't have browse permission and any further issues beyond are not included in the results. Finally, all of the discovered issues are merged together and returned, with or without the seed issues according to the inclusive parameter.

When no seed issues are supplied, the search identifies all issues in the JIRA system that have any relations at all and for which the current user has browse permission. The results can be narrowed down with the direction parameter to find only those issues that have issue relationships in any of the effective directions. Likewise, results can be further narrowed down with issueLinkType to issues that have issue links in any of the effective issue link types. Issues that match (using issue IN ...) or do not match (using issue NOT IN ...) the parameters will be returned.

Relationships with JIRA Agile Epic issues are treated as issue links.

Returns List of issues.
Availability Since Vivid Trace 1.2.
See also links() parents() relatesWith() subtasks()

subtasks()

Usage

subtasks( PARAMETER [, more PARAMETERs] )

where PARAMETER is one of distance, inclusive, issue, issueLinkType, jql, or projectConfig.

Description

In terms of parent/sub-task relationships, this function identifies those seed issues that are sub-task issues plus all issues that are sub-tasks of the seed issues, according to parameters. When used without seed issues, this function identifies all sub-task issues.

JIRA's own JQL function subtaskIssueTypes() returns a list of all sub-task issue types. In contrast, subtasks() finds issues that actually are sub-tasks. Note that issueType in subtaskIssueTypes() is equivalent to issue in subtasks().

Returns List of issues.
Availability Since Vivid Trace 1.2.

JQL Function Parameter Reference

This section describes all of the parameters for the JQL functions. While JIRA's Auto-complete is available for the JQL functions, it is not available for these parameters. Either single quotes or double quotes can be used to quote parameters. Parameters, including values, are case-insensitive wherever possible. Parameters are not positional; they can appear in any order. Duplicate values within parameters are silently ignored.

Parameters that can appear in any quantity:

Parameters that can be supplied at most once:

direction

Usage

'direction = DIRECTION'
'direction != DIRECTION'
'direction IN ( DIRECTION [, more DIRECTIONs] )'
'direction NOT IN ( DIRECTION [, more DIRECTIONs] )'

where DIRECTION is one of: inward, outward, parents, or subtasks

Default value All directions
Description

With seed issues, direction is used to calculate the effective directions, controlling which issue relationships are followed during the search process. At any given issue, relationships in the effective directions will be followed; other relationships will not. All directions are followed by default, but the search can be constrained to follow only certain relationships according to the supplied direction(s), or in the case of the negative forms (!= and NOT IN) all relationships except the supplied direction(s). The = and != are used to specify a single direction, and the IN and NOT IN forms are used to specify one or more directions. The negative forms of this parameter can be useful for pruning results.

inward and outward denote following along inward issue links and outward issue links, respectively. parents denotes following along parent issue relationships, and likewise subtasks denotes following along sub-task issue relationships.

When used without seed issues, only those issues that have relationships in any of the effective directions will be identified.

This parameter is blind to particular issue link types and parent- or sub-task- issue types. To restrict the search to particular issue link types, see the issueLinkType parameter.

Note that this parameter must be enclosed in single or double quotes.

Limitations
  • This parameter can appear at most once.
  • At least one direction must be effective.

distance

Usage

'distance = d'

where d is an integer 0 <= d <= 2147483647 (a whole number, zero or larger, not exceeding Java's Integer.MAX_VALUE)

Default value Unlimited distance
Description

Search for issues within up to a maximum distance of d hops away in any direction from the seed issues. A value of 0 will prevent searching beyond the seed issues. A value of d >= 1 or more will search along issue relationships and gather up issues at a distance of up to d issues away from the seed issues.

Note that this parameter must be enclosed in single or double quotes.

Limitations
  • This parameter can appear at most once.
  • This parameter is ignored when used without seed issues.

inclusive

Usage 'inclusive = yes'
'inclusive = true'
'inclusive = no'
'inclusive = false'
Default value yes, include seed issues in results
Description

Determines whether the seed issues are included in the results. yes and true are aliases for each other, and likewise no and false are aliases for each other.

Note that this parameter must be enclosed in single or double quotes.

Limitations
  • This parameter can appear at most once.
  • This parameter is ignored when used without seed issues.

issue

Usage ISSUE_ID
ISSUE_KEY
Description

The supplied issue can be specified by either a valid ID or key, and is added directly to the seed issues, from which the search is started. When an issue key identifies more than one issue, one of those issues is chosen arbitrarily.

An attempt is made to interpret the issue first as an issue ID, and failing that as an issue key.

Limitations
  • This parameter can appear any number of times.
  • The user performing the JQL query must have permission to browse the issue; a permissions violation will return error message VTE-1.
  • JIRA's Quick Search feature will accept just the numeric portion that follows the hyphen of issue keys valid for the current project. For example, if the current project is set to ABC, Quick Search will jump to issue ABC-345 even if just given 345. Quick Search's short form of identifying issues cannot be used here.

issueLinkType

Usage

'issueLinkType = ISSUE_LINK_TYPE'
'issueLinkType != ISSUE_LINK_TYPE'
'issueLinkType IN (ISSUE_LINK_TYPE [, more ISSUE_LINK_TYPEs])'
'issueLinkType NOT IN (ISSUE_LINK_TYPE [, more ISSUE_LINK_TYPEs])'

where ISSUE_LINK_TYPE is the unambiguous ID, name, inward description, or outward description of an issue link type

Default value All issue link types
Description

issueLinkType is used when the effective directions includes the issue link directions inward and/or outward. This parameter is overridden when projectConfig = apply.

With seed issues, issueLinkType is used to calculate the effective issue link types, controlling which issue link types are followed during the search process. At any given issue, issue link relationships in the effective issue link types will be followed; other issue link types will not. All issue link types are followed by default, but the search can be constrained to follow only certain issue link types according to types supplied in this parameter, or in the case of the negative forms (!= and NOT IN) all issue link types except the supplied types. After calculating this parameter, the issue link types that will be followed are referred to as the effective issue link types.

An attempt is made to match each ISSUE_LINK_TYPE as an issue link type ID. Failing that, the function attempts to unambiguously match the complete name, inward description, or outward description of exactly one issue link type. Individual values must be quoted if they contain spaces or JQL punctuation such as single- & double-quotes, parentheses, and commas. Specifying an issue link type by its inward or outward description has exactly the same effect as by ID or name and will not change the effective directions.

When used without seed issues, only those issues that have issue link relationships of any of the effective issue link types will be identified.

Note that this parameter must be enclosed in single or double quotes.

Limitations
  • This parameter can appear at most once.
  • This parameter is only meaningful when the effective direction parameter value includes one or more issue link directions.
  • At least one issue link type must be effective.
  • Ambiguous parameter values that match multiple issue link types will result in error message VTE-8.

jql

Usage

'jql = JQL_QUERY'

where JQL_QUERY is a valid JQL query

Description

Starts the search from issues returned by the supplied JQL query. Issues returned from the JQL query are added to the seed issues, from which the search is started. Form this parameter by adding jql = to the front of your JQL query, and single- or double-quoting the result. Single- and double-quotes within your JQL query might need to be adjusted.

The JQL query issue IN relations(ABC-73, DEF-99) yields the same results as issue IN relations('jql = issue IN (ABC-73, DEF-99)'). This is because relations() will first gather seed issues from the inner jql parameter, which directly produces the mentioned issues.

JQL parsing and permissions problems are reported back as error message VTE-6. If an error is reported for a given JQL query, try using the JQL query by itself to isolate the problem.

Note that this parameter must be enclosed in single or double quotes.

Limitations
  • This parameter can appear any number of times.
  • The JQL query will performed by the current user; any permissions violations will be reported as error message VTE-6.
  • JQL queries that refer to other saved filters in a way that causes cycles, where a filter is somehow called endlessly, cannot be used.

projectConfig

Usage 'projectConfig = apply'
'projectConfig = ignore'
Default value ignore project configuration
Description

Instructs the JQL function to apply the project configuration to each seed issue during search. All available settings in the project configurations will override any corresponding parameters supplied to the JQL function. Concretely, if issueLinkType is specified as a function parameter, it will be overridden by the project configuration on each seed issue.

Alternatively, when set to ignore the function will completely ignore project configurations.

Note that this parameter must be enclosed in single or double quotes.

Limitations
  • This parameter can appear at most once.

Performance

Performance of the JQL functions relies mainly on the performance of JIRA and its Lucene index. In addition to the information published in the JIRA Performance Tuning Knowledge Base article at Atlassian, Vivid recommends ensuring that the Lucene index resides completely in memory on all nodes during routine operation. Accommodating the full Lucene index in-memory is accomplished by vigilantly securing a margin of free JVM memory as measured during routine peak traffic periods. Even with Solid-State Disk (SSD) technology, the performance penalty of loading from disk instead of being in-JVM or cached by the host OS is measured in orders of magnitude.

You can judge baseline JIRA query performance and relative Vivid Trace JQL function performance by issuing and timing the following JQL queries.

Objective & ExplanationJQL Query
Cause a scan of all documents in JIRA's Lucene index, strictly using JIRA's own JQL functionality.

issueType IS NOT EMPTY

Again, cause a full scan of the index, but this time using Vivid Trace's JQL functions.

issue IN relations()

Troubleshooting

Characters Outside Unicode Basic Multilingual Plane (BMP): The use of Unicode characters outside of the Basic Multilingual Plane (BMP) with Vivid Trace has not been verified for correct operation and may lead to undefined & unsupported behavior.

JQL Function Name Collisions Between JIRA Add-ons: The JQL function names in Vivid Trace were carefully chosen to avoid overlapping with those of other add-ons known at the time of their naming. In the event that two or more add-ons register JQL functions with identical function names, JIRA will enable only the first of the overlapping functions it encounters, which might lead to loss of functionality. To resolve this situation, determine the affected add-ons, and then notify Vivid and the other vendors about the collision. While waiting for an up-stream solution, your JIRA Administrator can manually disable the colliding JQL function modules in each of the affected add-ons, and then re-enable just one of the conflicting JQL functions in the add-on of your choice. Note that the functions will be unavailable to users during this administrative operation.

JQL Query is Too Long: The Advanced Search query input field appears to be limited in the number of ASCII characters it can accept in JQL queries. An example of this limit is approximately 8000 ASCII characters using the Advanced Query web-based user interface in JIRA Server version 6.3.11. Queries that exceed this length may cause JIRA to report an error with the message "Error occurred communicating with the server. Please reload the page and try again." One way to resolve this situation is to shorten the JQL query to within the length limit by splitting portions of the query into saved filters and then referencing those saved filters from the shortened query.

Translations and Localisations of JQL Function Parameter Values: The use of values and of user-provided name translations of JIRA objects or values using localisations unsupported by Vivid Trace has not been verified for correct operation and may lead to undefined & unsupported behavior.