Cross-filter

This section provides information about filtering by referenced fields that are filtered by other reference fields.

Overview

You can cross-filter to filter values of a different entity's fields. That is, you can filter by a referenced field that is filtered by another reference field.

You can filter defects by any defect attributes (reference fields), such as listing defects that are detected in a specific release:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="detected_in_release EQ {id EQ 1004}"

The following cross-filter will correctly list defects whose Severity matches ID number 1003.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="Severity EQ {id EQ 1003}"

The following cross-filter does not work. It attempts to list defects whose Severity matches name High, but you can reference only the ID field when cross-filtering list value fields.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="Severity EQ 'High'"

Note: Defects, user stories, epics, and features are subtypes of work items (work_item). Work item IDs are unique across all workspaces in a space. You do not need to explicitly state which work item subtype you are looking for when querying or query with a cross-filter.

Back to top

Nested cross-filtering

There is no limit to the number of cross-filters you can nest in a query.

Example: You can create a cross-filter to filter defects by any of its field, such as listing defects that are in a specific sprint of a specific release: 

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="detected_in_release EQ {sprints EQ {id EQ 1006}}"

Back to top

Cross-filter on lists

You can use the REST API to filter on lists, phases, and metaphases. For example, you may want to display all defects with a High or Very High severity.

There are two methods for filtering for lists: Query by logical name and Query by label name.

Query by logical name

To use this method, you must first look up the logical name for the value you want to query by. You can do this using the Settings UI or by getting list_node values.

To see all lists and their values:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="logical_name EQ ^*high^}"

To see all defects whose severity matches high

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?query="subtype EQ ^defect^; severity EQ {logical_name EQ ^list_node.severity.high^}"

Query by label name

To see all lists that have a value that exactly matches the value high

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^high^"

To see all defects whose severity is high

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?query="subtype EQ ^defect^;severity EQ {name EQ ^high^}"

To see all lists that have a value that contains the value high, using wildcards: 

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/list_nodes?query="name EQ ^*high^"

To see all defects whose severity contains the value high, using wildcards. This will return defects whose severity is high, very high, or, for example, extremely high.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/work_items?query="subtype EQ ^defect^; severity EQ {name EQ ^*high^}"

Tip: Querying by label name is only supported in English. However, you can specify your query in English, and the results are displayed in your language.

Back to top

Cross-filter on user fields

When creating cross-filters on user-type entity fields, you can only reference the ID field.

The following table shows some examples of user-type fields by entity.

Entity User-type fields in the entity
Defects

author

detected_by

owner

qa_owner

Tests

designer

author

owner

Runs

run_by

author

The following cross-filter will correctly list defects whose QA owner field matches ID number 1003.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="qa_owner EQ {id EQ 1003}"

The following cross-filter does not work. It attempts to list defects whose QA owner field matches the name Ann. However, you can only reference the ID field when using cross-filtering user-type fields.

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/defects?query="qa_owner EQ {name EQ 'Ann*'}"


Back to top

See also: