Building Queries in i2b2

Owned by Maryam Abdallah
Last updated: Sept 12, 2022
5 min read

On this page:

Overview of the i2b2 Workspace

This is the default view of the i2b2 workspace once you log in:

1. The Terms tab lists out all variables available in i2b2 using a hierarchical structure. You can click through each folder to expand and drill down to locate specific variables

2. The Find Terms tab allows you to search for variables by keyword or by the standardized code (i.e., ICD, CPT, LOINC code)

3. Workplace contains your personal i2b2 folder, where you can store previously run queries. It also has the SHARED i2b2 folder; queries placed in the SHARED folder are accessible by all i2b2 users

4. Queries lists all of your previously run queries

5. Find Queries allows you to search for previously run queries by query name

6. To build queries, you drag and drop variables into Groups

7. Click Run Query to run your query once it is built

8. Clicking Clear resets your workspace by clearing all variables you have placed in the Groups

9. Once you run your query, Show Query Status indicates how long the query has been running for

10. Graph Results displays graphs of your query results

11. Query Report allows you to view and export a summary of your query and results in PDF format

 

 

Pro Tip: Resize Workspace

The Resize Workspace icon will toggle between the default tabbed pane size and a vertically expanded view of the pane. This can help minimize the amount of vertical scrolling. Any tabbed pane that includes this Resize Workspace icon will allow you to expand the tab vertically to the full available height of the browser window. This is a very useful option!

 

Building a Query

 

Adding Terms

  1. Locate your variables of interest using the Terms tab or Find Terms tab on the left side of the workspace.

  2. Click, drag and drop your variables of interest into a group on the right side of the screen.

 

 

 

AND vs OR Functions

  • Multiple variables added into the same group will be connected with an OR function

    • In the query on the right, patients that are either White OR Asian will be included in the query

 

  • Different groups are connected with an AND function

    • In the query on the right, patients will be included if they are:

1. Female

AND

2. White OR Asian

 

Query Functions

Date Restrictions

There are two ways to add date restrictions to a query.

Date restrict all variables within a single group

  1. Click on Dates on the upper left corner of a group

2. A pop-up window will appear. Set a start date, end date, or both and click 'OK'

 

3. The specified date restriction will now be applied to all variables within the group

 

Add a date restriction to a single variable within a group

  1. Right click on a single variable within the group and select ‘Set Date Constraint’

2. A pop-up window will appear. Set a start date, end date, or both and click 'OK'

 

3. The date restriction is now applied only to the single variable within the group (Type 2 diabetes mellitus in the example below)

 

 

Exclusion

You can exclude variables within a group by clicking ‘Exclude’ on the upper right corner of a group. Note that doing so will exclude all variables included in that group.

 

Occurrences

By default, variables in each group must occur at least once for a patient to be included in the query results. To change the number of occurrences for events in a particular group:

1. Click ‘Occurs >0x’ at the top of one of the groups. A pop-up will appear where you can specify the number of occurrences

 

2. Use the dropdown menu to select a number between 0 to 19. Click OK to apply the changes

 

 

Running a Query

1. Once you have built a query and you are ready to run the query, click on ‘Run Query’

 

 

 

 

 

 

2. A pop-up will appear and ask you to specify the following:

a. Name of query: It is recommended to specify a name that you will recognize, as i2b2 allows you to search for previously run queries by query name.

b. Query result type(s): 'Number of patients’ provides the total patient count and is selected by default. The other options are:

  • Patient set: Provides a set of patients who met the search criteria. Note: this is required if you submit an i2b2 data request using the patients from this query.

  • Encounter set: Provides a set of encounters for those patients who met the search criteria.

  • Number of patients: Provides the total number of patients who met the search criteria.

  • Gender patient breakdown: Provides the total patient count broken down by gender

  • Vital status patient breakdown: Provides the total patient count broken down by vital status

  • Race patient breakdown: Provides the total patient count broken down by race

  • Age patient breakdown: Provides the total patient count broken down by age

  • Timeline: Provides a set of patients who met the defined criteria and automatically generates a timeline in the timeline view.

 

Note: A query can take anywhere from a few seconds to several hours depending on the complexity of your query, and how many queries are currently in the queue. If a query takes over 180 seconds, the system may time out, but your query will continue to run in the background. You can view the status of a running query under the ‘Queries’ tab