Skip to content

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 an SQL-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.

Quick Start

To use Advanced Search:

  1. Click the search bar and select Advanced Search
  2. Choose your approach:
    • Visual Editor: Use dropdowns and forms for guided query building
    • FlyQL Editor: Write SQL-like queries for precise control
  3. Click Run Query to see results
  4. Save your query for reuse (FlyQL only)

Common FlyQL patterns:

  • Exact match: field.name = value
  • Range: field.name >= 18 AND field.name <= 65
  • Field exists: field.name EXISTS
  • Contains: field.name CONTAINS "text"

Prefer videos?

See our videos on using Advanced Search:

Getting Started

  1. Sign in to Flywheel.

  2. Click the search bar.

    If nothing appears, hit enter on the empty search bar.

  3. Click Advanced Search.

    advancedsearch1.png

  4. Build a search query using either the Visual Editor or FlyQL Editor.

    advancedsearch2.png

Choosing an Editor

Advanced Search provides two ways to build queries:

What's the difference between the visual editor and FlyQL queries?

  • Visual Editor: User-friendly interface with dropdowns and form fields. Best for simple to moderate complexity queries.
  • FlyQL Editor: Text-based query language similar to SQL. Best for complex queries with precise control over logic and operators.
  • Note: Saved Queries can only be edited in FlyQL

The available operations are slightly different between the visual editor and the FlyQL editor. See the sections below for details on each approach.

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

SearchingforSubjects.png

Expected Results:

This query will return subjects that match either of the following conditions:

  • Condition 1: Male subjects aged 14-34 years
  • Condition 2: Subject labels containing MXC OR subjects labeled as phantom

Because the term groups are connected with OR, subjects only need to meet one condition to appear in the results. For example:

  • A 25-year-old male subject would appear (matches Condition 1)
  • A 40-year-old female subject with label MXC_baseline would appear (matches Condition 2)
  • A phantom subject would appear regardless of other attributes (matches Condition 2)
  • A 40-year-old male subject without MXC in the label would NOT appear (meets neither condition)

The results will appear in the Sessions or Subjects view, showing all sessions or subjects that meet the criteria.

Steps

Video Tutorial

Watch how to use the Visual Editor: Construct Advanced Search Queries (33:23)

To build a query in the visual editor:

  1. 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.

  2. 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.

  3. Enter one or more values to search on. Start typing to see a list of all the possible values for your chosen field.

  4. Choose AND/OR for the comparison value within the term. This AND/OR applies within this term group.

  5. 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.

    AddingaTermGroup.png

  6. 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 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.
1
2
3
(file.info.AcquisitionDateTime <= 2020-01-01T06:00:00) AND
(session.info.IQ EXISTS AND session.info.Education >= 12 AND subject.race != White) AND
(file.classification.Intent = Structural) AND (file.type = nifti OR file.type = dicom)

Expected Results:

This query returns files that satisfy all conditions simultaneously. The search will:

  1. First filter to acquisitions before 2020-01-01
  2. Then filter to sessions where IQ data exists AND education level is 12 or higher
  3. Then exclude any subjects with race listed as White
  4. Finally, filter to only Structural classification files in NIFTI or DICOM format

The results will include only files where every condition is true. If a file meets some but not all criteria, it will not appear in the results.

For example, if you have:

  • 1000 total files in your accessible projects
  • 500 files acquired before 2020-01-01
  • 200 of those have complete IQ data and education >= 12
  • 150 of those are from non-White subjects
  • 100 of those are Structural NIFTI or DICOM files

You would see approximately 100 files in your final results.

Steps

Video Tutorial

Watch how to use FlyQL: Data Curation with FlyQL (3:17)

To build a FlyQL query:

  1. 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

  2. Enter an operator. See the table below for the possible operators.

  3. Enter one or more values. Start typing to see a list of all the possible values for your chosen field.
  4. 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)