Skip to content

Searching Custom Metadata Fields

Flywheel indexes all custom metadata, making it searchable across your data. This allows you to find data based on project-specific information like scanner parameters, clinical scores, experimental conditions, or any other custom metadata you have added to your data.

This article explains how to search for custom metadata fields using both Basic Search and Advanced Search.

Understanding Custom Metadata Field Paths

Custom metadata fields use a hierarchical structure with dot notation to specify their location. The format is:

1
level.info.FieldName

Where:

  • level: The hierarchy level where the metadata is stored (file, acquisition, session, subject, project, or analysis)
  • info: The standard container for custom metadata
  • FieldName: The name of your custom field

Common Field Path Examples

  • file.info.RepetitionTime - Custom field on a file
  • acquisition.info.SequenceName - Custom field on an acquisition
  • session.info.ClinicalScore - Custom field on a session
  • subject.info.Diagnosis - Custom field on a subject
  • project.info.StudyPhase - Custom field on a project
  • analysis.info.QualityScore - Custom field on an analysis

Nested Fields

If your custom metadata has nested structure, continue the dot notation:

1
2
session.info.Assessment.CognitiveScore
subject.info.Demographics.AgeAtScan

In Basic Search, you can filter by custom metadata fields using the Custom Fields section at the bottom of the search sidebar.

Screen_Shot_2019-03-08_at_1.29.20_PM.png

Steps

  1. Scroll to the Custom Fields section at the bottom of the search filters.

  2. Start typing in the text box. Flywheel will suggest available custom metadata fields as you type.

    Screen_Shot_2019-03-08_at_1.31.19_PM.png

  3. Select the field you want to search on.

  4. A new search box appears below Custom Fields with the selected field name. Enter the value you want to search for.

    Screen_Shot_2019-03-08_at_1.58.34_PM.png

  5. Your search results update to show only data with that custom field value.

Example: Finding Files by Scanner Parameter

To find all files where the RepetitionTime is 2000:

  1. Type file.info.RepetitionTime in the Custom Fields box
  2. Select file.info.RepetitionTime from the suggestions
  3. Enter 2000 in the field value box
  4. Results show only files with RepetitionTime = 2000

Viewing Custom Metadata

The file.info object in search corresponds to the Custom Information section in the file details. You can view this by clicking on a file and looking at the Custom Information section.

Screen_Shot_2019-03-08_at_1.53.22_PM.png

Advanced Search provides more control when searching custom metadata fields. You can use exact matching, ranges, and complex logic.

Using Custom Fields in FlyQL

To search custom metadata in FlyQL, use the full field path:

1
level.info.FieldName operator value

Common Search Scenarios

Exact Match

Find sessions where a specific clinical score equals a value:

1
session.info.ClinicalScore = 75

Range Query

Find subjects where IQ is between 90 and 120:

1
subject.info.IQ >= 90 AND subject.info.IQ <= 120

Field Exists

Find all files that have a specific custom field populated:

1
file.info.QualityControl EXISTS

Contains Text

Find sessions where notes contain a specific term:

1
session.info.Notes CONTAINS "baseline"

Multiple Conditions

Find files with specific scanner parameters:

1
file.info.RepetitionTime = 2000 AND file.info.EchoTime = 30

Field Names with Spaces

If your custom field name contains spaces, wrap the entire field path in quotes:

1
"subject.info.Clinical Assessment" = "Normal"

Example: Finding Subjects by Diagnosis

To find all subjects diagnosed with a specific condition:

  1. Open Advanced Search

  2. Enter the FlyQL query:

    1
    subject.info.Diagnosis = "Alzheimer's Disease"

  3. Click Run Query

Expected Results: All sessions belonging to subjects with the Diagnosis field set to "Alzheimer's Disease".

Example: Finding High-Quality Scans

To find files that passed quality control with high scores:

  1. Open Advanced Search

  2. Enter the FlyQL query:

    1
    file.info.QualityScore >= 90 AND file.info.QualityControl = "Pass"

  3. Click Run Query

Expected Results: Only files with quality scores of 90 or higher that also have a QualityControl status of "Pass".

Tips for Searching Custom Metadata

  • Use autocomplete: Start typing a field name and Flywheel will suggest available fields
  • Check exact field names: Custom field names are case-sensitive in Advanced Search
  • Verify field location: Ensure you are searching at the correct hierarchy level (file vs session vs subject)
  • Use EXISTS first: If unsure what values exist, search for fields that exist, then examine the results
  • Test incrementally: Build complex queries step by step, testing each condition separately