i2b2 Web Client
Space shortcuts
Space Tools

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.

Example Box
titleTable of Contents

The Query Tool panel is where queries are constructed and run. 

Table of Contents

The Query Tool is the main panel through which users construct, refine, and submit i2b2 queries.

3.1 Layout

Image Removed

3.2 Building a New Query

Initially the Query Tool shows three Groups to the users, but only one (the first one) is active. Users are to add criteria via drag-and-drop to the Groups to construct their queries. A number of potential i2b2 objects can be added to the Groups. They include ontology terms, previous queries, results of previous queries, and items from the Workplace.

    i. Adding i2b2 Objects into Groups

       1) Ontology Terms

The Navigate/Find Terms panel contains all available ontologies. Users can browse or use its search functionalities to find a certain terms. After identifying the terms users wish to query for, they can drag and drop them into the Groups.

       2) Previous Query

The Previous Queries panel lists all previously submitted queries. Users may drag and drop a previous query into a Group. When a new query contains a previous query is executed, i2b2 will run the previous query first. The previous query's results are then used in conjunction with the other terms in the new query to obtain the final results. In this sense, a previous query in a query can be thought of as a sub-query.

       3) Query Result (Patient Set/ Patient)

For each previous query in the Previous Queries panel, its results such as individual patients or patient sets can also be dropped into the Groups.

       4) Including a Folder in Workplace

Workplace is a place where users can put any i2b2 objects such as ontology terms, previous queries, patient sets, etc. they wish to save for later. Users can then drag these saved objects into the query Groups. In addition,

    ii. AND/OR Operators

       Order of Precedents

    iii. How to use a lab test (terms with values)

    iv. Run Query and Clear buttons

3.4 Resetting the Query Tool (Clear)

3.5 What Happens when a query gets queued?

3.6  Rerun a Previous Query

3.7 Advanced Query Options

    i.Output Options

        1) Patient Set
        2) Encounter Set
        3) Number of Patients
        4) Gender Patient Breakdown
        5) Vital Status Patient Breakdown
        6) Race Patient Breakdown
        7) Age Patient Breakdown
        8) Timeline
        9) Length of Stay Breakdown
        10) Top 20 Medications Breakdown
        12) Top 20 diagnoses Breakdown
        13) Inpatient and Outpatient Breakdown

    ii. Managing Groups

        1) Additional Groups
        2) Shifting Group Order
        3) Delete Groups

    iii. Specifying Constraints

        1) Date Constraints  (Panel-level and Term-level)
        2) Negation (Exclude)
        3) Occurrences

    iv. Value Constraints

(e.g. "Find patients who have a systolic blood pressure reading greater than 130 mm Hg")

    v. Modifiers

        1) What are they?
        2) Has Value Constraints like Labs
        3) How are they represented in Navigate/Find Terms
            - Modifier
            - Modifier Container

    vi. Query Timing

        1) Treat all groups independently (default)
        2) Select Groups occur in the same financial encounter
        3) Define sequence of events (Temporal Query)
            - Simple
            - Advanced
            - Some Concepts do not make sense here (Put them in the Population )

3.8 Example Queries

  i. Simple Query: "Finding patients with a diagnosis A or a diagnosis B or has lab test C."

  ii. Running a Previous Query

  iii. Temporal Query (Simple)

  iv.  How to find Patients with >1 diagnosis X OR >1 diagnosis Y  (Using nested queries)

Image Added

  1. Panel Options  Image Added allow users to (1) view the XML exchange between the client and the i2b2 server (if enabled) , (2) set options for the panel, and (3) resize the panel.
  2. Query Name Display shows the name of the current query. Users can also drop a previous query here to load it.
  3. Query Timing Selector enables users to select the appropriate timings for their query, including temporal queries.
  4. Query Groups are where users can drag and drop terms to build queries. There are initially three Groups, but more can be added.
  5. Tool Bar contains buttons to run queries, clear all the panels, add new panels, and navigate between panels.

3.2 Creating a Query

3.2.1 i2b2 Items for Querying

These items may be dragged into Query Groups to construct queries.


leafImage Added

TermsTerms (also called concepts) are the words or phrases that make up vocabularies. Terms are the basic query items.

folderImage Added

Term GroupsRelated terms are grouped into hierarchies. When a term group is used in a query, all terms in the group are searched for.

leafImage Added

ModifiersModifiers are descriptors that can be attached to terms to make small changes to them. For example, a Diagnosis concept may be additionally described by Modifiers "Principal Diagnosis" or "Secondary diagnosis."

folderImage Added

Modifier GroupsGroups of Modifiers, similar to Term Groups.

prevQueryImage Added/Image Added

Previous QueriesPrevious Queries are queries that have been run before and are stored in the 'Previous Queries' panel.

Image Added

Individual PatientsIf selected when running a query, a query can return a Patient Set,which is a set of patient numbers that satisfy the query criteria. The Patient Set is stored with the query in the Previous Queries panel. The Patient Set can be expanded, and individual subjects dragged into query groups to be used in a new query.

Image Added

Patient SetsIf selected when running a query, a query can return a Patient Set, which is a set of patient numbers that satisfy the query criteria. The Patient Set is stored with the query in the Previous Queries panel and can be dragged into query groups to be used in a new query.

Image Added

Encounter SetsIf selected when running a query, a query can return an Encounter Set, which is a set of encounter numbers that satisfy the query criteria. The Encounter Set is stored with the query in the Previous Queries panel and can be dragged into query groups to be used in a new query.

3.2.1 Operators and Order of Precedence

 i2b2 items are combined using Boolean operators AND and OR.

Items within each Group are first ORed together. The Groups are then ANDed together. 

Example 1 (AND): This query finds patients with Acute Myocardial Infarction AND Angina Pectoris.

Image Added

Example 2 (OR): This query finds patients with Acute Myocardial Infarction OR Angina Pectoris.

Image Added

Example 3 (AND of ORs): This query finds patients with (Acute Myocardial Infarction OR Angina Pectoris) AND who are male.

     *Note that the OR expression in the parentheses is evaluated first.

Image Added

3.2.2 Constraints

Constraints are used to narrow down the search criteria to a particular time frame, number of occurrences or a specific value or range of values. In i2b2, there are several types of constraints that can be defined in the Query Tool view. 

  1. Group Constraints
    1. Date Constraint
      1. Setting Date Constraint for the entire Group
        Image Added

        Clicking on 'Dates' will display a dialog box in which a date range can be selected to restrict the occurrences of the items in the Group to within that range. Check one or both of the check boxes to indicate whether there is a begin date (From) or an end date (To) or both.

        Image Added

        Then type the date directly in the text box or click on the drop-down arrow to open the calendar below to select a date. This will set the date range for all items in this Group. 

        Image Added

      2. Setting Date Constraint on individual items.
        Sometimes only some items in the Group need date constraints or different items in one group require different date constraints. In this case, right click on an item and select Set Date Constraint  to set the date constraint for that item specifically.
        Image Added

      3. Once a date constraint is applied, Dates will now be underlined to indicate a date constraint has been set.

        Image Added

    2. Occurrence Constraint

      Users can define the number of times an item must occur for each subject. 

      Click on 'Occurs>0x'

      Image Added

      A new window will open

      Image Added

      Click on the drop-down arrow to display a list of numbers.
      Select a number from the list.

      qtConstOccurSelectionImage Added

       Click on the OK button.

       Occurs > 0x will now be underlined to indicate a constraint has been set and the 0 will be replaced with the selected number.

      qtConstOccurSetImage Added

      Note that if there are multiple items in the panel, patients are counted if any single item has more than the number of occurrences selected. The logic is: Term A (2+ occurrences) OR Term B (2+ occurrences) OR Term C (2+ occurrences).

    3. ExclusionImage Added
      Constraint will not include patients with the concepts listed in the panel. 

      Click on the Exclude button located in the selection criteria section of the panel.

      The text in the information box will change to "none of these" and the background color will change to pink.

    4. Value Constraints (eg. labs)
      Constraint is by the value associated to a concept or modifier. Not all items have values. The value constraint window will open automatically when you drop a concept into a panel in the Query Tool view. To set the constraint at a later time, right click on the item in the panel and select Set Value.
      Image Added
      1. Numeric

        The numeric value is defined in the source system when the result is entered. Enter a numerical value at the Please enter a value field.

        Image Added

        Unlike flag and text values, numeric values use operators, such as greater than or less than when setting the constraints. 

        Image Added

        The Units will default to the normal units defined for the item.  Click on the drop-down arrow to change the units.

        Image Added
        (In order for unit conversion to work a parameter called CRC_ENABLE_UNITCD_CONVERSION must be defined for the project. If this is not defined you need to contact your system administrator.)

      2. Categorical

      3. Text
        Image Added

      1. Flags (high, low, etc.)

      2. Modifier Value Constraints
        Image Added

3.2.3 Query Timing

Image Added

Choose the relationship between the query panels. The default is independent.

  1. Independent

    • The items (facts) can occur at any time in the patient's history.

      Example Box

      Patient has a medication with a dose greater than 500 mg and a medication that is taken once a day documented at any time in their history.

  2. Same Financial Encounter

    1. The items (facts) occur during the same visit (financial encounter).

    2. When this is selected, individual panels can be included in the "same encounter" query, or they can be treated independently.

Image Added

Example Box

Patient has a diagnosis of Acute MI documented at any time in their history and they have a medication with a dose greater than 500 mg and a medication that is taken once a day documented during the same visit

  1. Temporal Query 

In this mode, a sequence of events are defined that are anchored by a constraining population. The constraining population is defined exactly like other query types. The process of building a sequence of events is explained by a a tutorial that is viewable by clicking 'Turn On Tutorial' in the upper-right corner of the query tool.

Image Added

This example finds patients who were diagnosed with diabetes prior to the first observation of an antidiabetic medication (top panel). The population is constrained to patients over 64 years of age (bottom panel).

3.2.4 Reloading a Previous Query 

Saved queries (either from Previous Queries or the Workplace) can be reloaded by dragging them to the Query Name bar at the top of the Query Tool. They can be used within a query by dragging them into a query panel. See the Previous Query section.

Image AddedImage Added

Left: reload a previous query. Right: Use a previous query within a new query.

3.2.5 Resetting the Query Tool

There are three options for resetting the Query Tool view. Users can (1) reset all the groups, (2) clear all items in a panel, or (3) delete an individual item from the group.

A. Reset All Groups: Click on the Clear button located on the toolbar at the bottom of the Query Tool view.

qtToolbarClearImage Added

B. Clear Items in a Panel / Group: Click on the Delete button (deleteImage Added) located in the top right corner of the panel (next to the Group name)

C. Delete Single Item: Using the right mouse button, click on the name of the item to be removed and select Delete from the list.

deleteItemImage Added

3.3 Running a Query 

3.3.1 Run Query

Once the query criterion has been defined, the final steps are to click on the Run Query button, select the result type(s), and click on the OK button to run the query.

Once you have defined the search criteria click on the Run Query button located on the toolbar at the bottom of the Query Tool view.  A new window will open.

    • A name for the query will default at the query name field.  Either change the name of the query or accept the default.
    • In the query result type section, click on the checkboxes for those result types you want to include when the query is run.
    • Click on the OK button.
    • The Run Query window will close and the querying process will begin

Once you begin the process of running the query the Query Status view will display "Running Query", the name of the query, and the time that has elapsed.

Image Added

3.3.2 Query Result Options

There are three categories of query type: counts, sets, and breakdowns. (Note that the Timeline type is not used in the Web Client. If selected it will work the same as patient set.)

1) Number of Patients

This option will return a total count for those patients who meet the defined criteria. This is the most common and fastest query type.

Image Added

2) Patient/Encounter Set

These options return a set of patients or encounters that meet the defined criteria. The set is visible in the Previous Query view and can be used in future queries, the workspace, and by plugins.

 Image Added

Only information on the query's completion is shown in the Query Status panel.

Image Added

4) Patient Breakdowns

The following query types will return patient counts stratified by the selected breakdown category (e.g., Gender or Age).

Breakdown type
Gender patient breakdown
Vital Status patient breakdown
Race patient breakdown
Age patient breakdown
Length of Stay breakdown

Top 20 Medications Breakdown

Top 20 diagnoses Breakdown

Inpatient and Outpatient Breakdown

3.3.3. Query Status 

When a query is running, the query status panel will show its status.

RunningThe query is currently running on the server and the client is waiting for results.
FinishedThe query has completed. Results will be shown below this message.
QueuedThe query took longer than the configured timeout. (Defaults to 180 seconds.) It is still running in the background and the results will appear in Previous Queries when it completes.
ErrorAn error occurred running the query. More information might be available in the XML Message Log.