Advanced Search
Introduction
Advanced Search is a powerful tool that allows you to search on any field in your Flywheel data, including metadata and custom data. Advanced Search includes both a visual query editor as well as the ability to build a query using FlyQL, which is a sequel-like language.
This article explains how to access Advanced Search and perform a visual or FlyQL search.
Try basic search if you do not have complex search criteria.
Prefer videos?
See our videos on using Advanced Search:
Instruction Steps
Navigate to Advanced Search
- Sign in to Flywheel.
-
Click the search bar.
If nothing appears, hit enter on the empty search bar.
-
Click Advanced Search.
-
Build a search query using either the visual editor or in FlyQL.
Build a Query
See below for information on how to use the visual editor and the FlyQL editor. Note that the available operations are slightly different between the visual editor and the FlyQL editor.
What's the difference between the visual editor and FlyQL queries?
- FlyQL queries allow you to have more control over how Flywheel compares multiple terms and term groups
- Saved Queries can only be edited in FlyQL
Visual Editor
The visual editor allows you to create a search with multiple criteria. To create a complex search query, the visual editor uses Terms and Term Groups .
A Term consists of a Field
+ Operator
+ Values
.
Term Groups are multiple Terms connected with the AND/OR toggle. Flywheel evaluates queries within a Term first. Then Term Groups are evaluated.
Example
The example below shows a search for all subjects between the ages of 14 and 34 who are male AND all subject labels containing MXC
OR phantom subjects
Steps
To build a query in the visual editor:
-
In Field, enter any metadata field from your Flywheel data. To see a list of possible options, begin typing and a list of fields appears.
Note
Flywheel must index new data before the fields and values appear in these lists. It may take a few minutes for fields and values from new data to appear in Advanced Search.
-
Select an operator:
- is
- is not
- contains
- does not contain
- exists (true/false)
- range (including open ended ranges)
The available operators appear in a drop down menu once you enter a field. See the reference table below for more information on which operators are available for certain fields.
-
Enter one or more values to search on. Start typing to see a list of all the possible values for your chosen field.
- Choose AND/OR for the comparison value within the term. This AND/OR applies within this term group.
-
Click Add Term Group or Add Term to continue building your query.
If you add another Term Group, use the AND/OR toggle at the top to connect your term groups.
-
Click Run Query once you are finished building your query.
Visual Query Operator Reference
The table below describes the operators for the visual query building in Advanced Search.
Operator | Description | Example | Available for these field types |
---|---|---|---|
is | Returns exact match of specified value. If there are multiple values in the term, IS returns data for each of the values. | file.type is dicom Returns all DICOM data | - Text - Boolean (true/false) |
is not | Returns fields that are not an exact match of the specified value or values. If there are multiple values in the same term, IS NOT returns data for each of the values. | session.notes.user IS NOT john.smith@example.com Returns all sessions that includes notes where the author is not John Smith. | - Text - Boolean (true/false) |
contains | Returns fields containing partial match of specified value | collection.notes.text contains longitudinal Returns collections with notes that include the word "longitudinal" | Text |
does not contain | Returns fields not containing partial match of specified value | NOT acquisition.tags CONTAINS exam Returns all acquisitions that do not include the tag "exam" | Text |
exists (True/False) | Returns fields containing any value (True) or fields with NULL value (False) | analysis.job EXISTS false Returns all sessions where there has not been analysis gear run. | - Text - Boolean(true/false) - Numeric - Date/Time |
range | Returns fields with values between and including max and min values of specified range. You can also do an open ended range by entering only a min or max. | session.age RANGE 55 Returns all sessions where the subject is 55 or older session.timestamp RANGE <blank> 3/30/2020 Returns all sessions that were performed before March 30th 2020. | - Numeric - Date/Time |
FlyQL Editor
FlyQL is a simplified querying language similar to SQL. To build a query in FlyQL create Terms and Term Groups:
A Term consists of a Field
+ Operator
+ Values
.
Term Groups are multiple Terms connected with the AND/OR toggle. Flywheel evaluates queries within a Term first. Then Term Groups are evaluated.
Example
The example below shows a query with multiple criteria. This FlyQL query returns data where all of the following are true:
- Acquisitions that were obtained before January 1st 2020
- The IQ field is complete for the subject
- Subject's education is greater than 12th grade
- Subject's race is not white
- The acquisition is classified as Structural and is in either the NIFTI or DICOM format.
Steps
To build a FlyQL query:
-
Enter a field from your Flywheel data. To see a list of possible field options, begin typing and a list of possible fields appears
Fields with Spaces
If the field includes a space, wrap the entire name in quotes. For example:
"subject.info.Clinical Information" = bravo
-
Enter an operator. See the table below for the possible operators.
- Enter one or more values. Start typing to see a list of all the possible values for your chosen field.
- Enter another query, and connect the two using AND or OR.
FlyQL Operator Reference
Operator | Description | Example |
---|---|---|
=, == | Equals, compares terms for an exact match | user:session.notes.user=johndoe@flywheel.io Returns all sessions with notes from John Doe acquisition.label = FLAIR AND subject.label IN [baseline, week-32] Returns a specific series |
!=, <> | Not Equals, matches any document where the term is NOT an exact match | subject.cohort != Test Returns all subjects that are not in the Test cohort |
< | Less than, matches any document where the term is less than the specified value. | file.info.SeriesDate < 20150107 Returns files with a series date from before January 7th 2015 (not including January 7th) |
<= | Less than or equal to, matches any document where the term is less than or equal to the specified value | file.info.SeriesDate <= 20150107 Returns files with a series date from before January 7th 2015 (including January 7th) |
> | Greater than, matches any document where the term is greater than the specified value | analysis.created > 2020-04-10T05:00:00.000Z Displays analysis created before April 10th 2020 |
>= | Greater than or equal to, matches any document where the term is greater than or equal to the specified value | session.age >= 18 Returns sessions where the subject was 18 years or older at the time of the session. |
=~ | Regular expression match against the term. | session.label =~ “[1-2][0-9]{3}-[0-9]{2}-[0-9]{2}” Returns sessions where the session label is a timestamp date in the yyyy-mm-dd format. This would return: - 2015-07-13 - 1998-01-01 This would not return 2015/07/13 or 01-01-2011 For more information on regular expressions (regex), see regex 101's online guide and validator. |
!~ | Negated regular expression match against the term | session.label !~ "ses-[0-9]{2}" Returns all session labels that are not in the ses-XX format. For example, the above query would return: - ses-1 - session-01 - ses-111 But it would not return ses-01, ses-99. For more information on regular expressions (regex), see regex 101's online guide and validator. |
IN | Returns any data where the term matches any of the values in the provided list | file.info.Anatomy IN [Brain, Neck] Returns files that match a specific anatomy |
LIKE | Uses wildcard matching against a term. Permitted wildcards are: - _ - ? (Single character) - % - * (Multiple characters) | subject.label LIKE "anx*" This returns subject.labels like: - anx_s1 - anx_s2 - anx001 |
CONTAINS | Returns fields containing partial match of specified value | session.notes.text CONTAINS "error on the following" Returns all sessions where the session notes contain the phrase "error on the following". |
NOT CONTAINS | Returns fields that do not contain a partial match of specified value | session.notes.text EXISTS AND NOT session.notes.text CONTAINS summary* Returns all sessions that includes a note, but the note does not contain "summary" or "summaries" |
EXISTS | Returns any document where the field value is not null or empty. | EXISTS subject.info.IQ Returns results where the key exists and has a value. |
NOT EXISTS | Returns any document where the field value does not exist or is empty. | NOT subject.species EXISTS Returns all subjects where the species field is empty |
Parentheses Enforce Order of Operations
Parentheses are used in FlyQL to enforce order of operations. For example, if you wanted to search for all files associated with male subjects between the ages of 18 and 34 or sessions containing the label MXC
:
(subject.sex = male AND subject.age >= 18 AND subject.age <= 34) OR (session.label CONTAINS MXC)