Creating queries

Use a query to retrieve a set of work items that meet specific conditions.

About this task

When you create a query, you specify the conditions and the work item properties to display in the results table. You can create the query for your own use or to share among team members.


  1. In the Work Items perspective, in the Team Artifacts view, expand the project area.
  2. Right-click Work Items and select New > Query. Alternatively, you can create a query in the Work Items view by clicking the Create New Query icon.
  3. In the query editor, enter a name for the query in the Name field. Depending on the type of query you want to create, click one of the following links:
    • Start from scratch: This query is based on a unique set of conditions. To create this type of query, after you click Start from scratch, follow these steps:
      1. Click the Add Conditions icon.
      2. In the Condition Selection window, select the attributes to use as query conditions and click OK.
        Tip: By default, only the built-in attributes are displayed. To include custom attributes, links, and archived attributes in the list, select the corresponding check box in the lower portion of the window: Show custom, Show links, Include archived. For example, to query on all work items without a Parent link, first select the Show links check box. Then, from the attributes list, select Parent, and click OK. Finally, in Step 2.c., set the attribute condition.
      3. For each attribute, specify the value or condition that must be met. For example, for the Due Date attribute you can use a specific date or a relative date, such as 15 days from now. As another example, to query on all work items without a Parent, set the Parent attribute condition to do not exist.
      4. To nest conditions and groups of conditions, click the arrow icon next to the Add Condition icon and select the type of condition to add. For each group, click All must match and select AND or OR. Use AND when all of the conditions you specify must be met for the query to return a work item. Use OR when any one of the conditions must be met.
      5. Optional: To specify input variables for an attribute condition, in the upper-right corner of the attribute condition area, click the Enable Input of Condition Values when Query is Run icon. When you run the query, the Assign Parameter Values wizard opens. In the wizard, select the values for every input variable and run the query.
    • Simple Query: This query uses the Status, Category, Owner, and optional text conditions. To create this type of query, after you click Simple Query, follow these steps:
      1. Select one or more values for the Status, Category, and Owner attributes.
      2. Optional: Enter a text string. The query searches fields of the work items for matching occurrences of the text string. Queries for string-based fields, such as Summary and Description, are not case-sensitive. Add and remove conditions as necessary.
    • Full Text Query: This query searches all fields of work items for a text string. To create this type of query, after you click Full Text Query, follow these steps:
      1. Enter the text string.
      2. Add and remove conditions as necessary. Queries for string-based fields, such as Summary and Description, are not case-sensitive.
  4. Click the Details tab. Enter a description of the query so that other users can understand which work items the query returns without reading the Conditions tab.
  5. By default, new queries are private. To share a query with members of a team, click Share > Team or Project Area and select a team. To share a query with a specific user, click Share > User and select the user.
    Tip: If you change a shared query, the changes apply to the other users with whom you share the query. If you delete a shared query, that query is no longer available to users with whom you shared the query.
  6. Click the Column Display tab. In the Columns section, double-click each attribute that you want to display as a column heading in the query results grid. Scroll to the Sorting area. Double-click the attribute to use for sorting the work items in the query results grid. In the Selected sort columns table, you can set the sort direction to Ascending or Descending. The first attribute that you select is the primary sorting attribute. You can specify additional sorting attributes.
    Note: You are able to create a query that includes empty fields: for example, text fields without content can be included in your query.
  7. To save the query, click Save.

    Another way to create a query is to edit an existing query. When you finish editing, click Save Copy and provide a different name for the query.

  8. To run the query, click the Run icon.
  9. To create a feed for this query, click the Create RSS Subscription for this Query icon. When any work items that are selected by this query change, you will receive notifications in the Team Dashboard view.


If you do not share the query, it appears in your My Queries list. If you share the query with an individual user (rather than a whole team), it appears in your My Queries list and it is also displayed in the Shared Queries > Individually Shared folder when that user accesses it. If you share the query with a team, the query is displayed in the team area folder in the Shared Queries folder.

video icon Video channel
Software Education channel

learn icon Courses

IoT Academy
Skills Gateway

ask icon Community forums library

support icon Support

IBM Support Community
Deployment wiki