The Query Tool is the main component through which users construct, refine, and submit i2b2 queries. Query construction is primarily based on drag-and-drop and selecting the appropriate options. This page details the various 'Query Tool' operations and options and how to use 'Query Tool' in conjunction with other components. The Table of Content offers links to quickly jump to relevant topics. In addition, a quick start video show the query process and to demonstrate the basic query-building features.





3.1 Quick Start Video

This video introduces the basic functionalities of the Query Tool through building a series of simple queries.

3.2 What is a Query?

An i2b2 query is a request that contains users' search criteria for patients stored in an i2b2 database. A query can be sent to an i2b2 server, where it is evaluated and the results are returned to the users after some time. A query typically contains one or more ontology terms users are interested in. For example, users may select ontology terms to query for patients with certain medications, diagnoses, and demographic information. Users can apply constraints to the terms to be more specific about the criteria. When a query is submitted, it will will take some time for i2b2 to process. Query Status will keep track of how long the query takes to run, and show the results when the query completes. When a query completes, the query itself along with all its results are stored in Previous Queries. Some results such as patient sets can also be used in a new query.

  i. Definition of a Query

  ii. Life Cycle of a Query

  iii. Results of a Query

      1) Patient Number is the default result
      2) Other Options are available (see ... )
      3) Detailed medical data are not part of the results the Query Tool can provide. Other steps are required.

3.3 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 component 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 component 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 component, 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)