How to Query the XNAT Search Engine with REST API

Contents

Get All MR Sessions In The OASIS Cross-Sectional Study

The XNAT search engine can be queried via the REST API. Here's a quick demonstration using XNAT Central. First, you will need a sample search xml:

Show XML Code Block

CODE

<?xml version="1.0" encoding="UTF-8"?>
<xdat:search ID="" allow-diff-columns="0" secure="false" brief-description="MR Sessions"
 xmlns:xdat="http://nrg.wustl.edu/security" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <xdat:root_element_name>xnat:mrSessionData</xdat:root_element_name>
    <xdat:search_field>
        <xdat:element_name>xnat:mrSessionData</xdat:element_name>
        <xdat:field_ID>LABEL</xdat:field_ID>
        <xdat:sequence>0</xdat:sequence>
        <xdat:type>string</xdat:type>
        <xdat:header>MR ID</xdat:header>
    </xdat:search_field>
    <xdat:search_field>
        <xdat:element_name>xnat:subjectData</xdat:element_name>
        <xdat:field_ID>LABEL</xdat:field_ID>
        <xdat:sequence>1</xdat:sequence>
        <xdat:type>string</xdat:type>
        <xdat:header>Subject</xdat:header>
    </xdat:search_field>
    <xdat:search_field>
        <xdat:element_name>xnat:mrSessionData</xdat:element_name>
        <xdat:field_ID>AGE</xdat:field_ID>
        <xdat:sequence>2</xdat:sequence>
        <xdat:type>integer</xdat:type>
        <xdat:header>Age</xdat:header>
    </xdat:search_field>
    <xdat:search_field>
        <xdat:element_name>cnda:clinicalAssessmentData</xdat:element_name>
        <xdat:field_ID>NEURO_CDR_RATING</xdat:field_ID>
        <xdat:sequence>3</xdat:sequence>
        <xdat:type>string</xdat:type>
        <xdat:header>CDR</xdat:header>
    </xdat:search_field>
    <xdat:search_field>
        <xdat:element_name>cnda:clinicalAssessmentData</xdat:element_name>
        <xdat:field_ID>NEURO_MMSE</xdat:field_ID>
        <xdat:sequence>4</xdat:sequence>
        <xdat:type>string</xdat:type>
        <xdat:header>MMSE</xdat:header>
    </xdat:search_field>
    <xdat:search_field>
        <xdat:element_name>xnat:subjectData</xdat:element_name>
        <xdat:field_ID>GENDER</xdat:field_ID>
        <xdat:sequence>5</xdat:sequence>
        <xdat:type>string</xdat:type>
        <xdat:header>M/F</xdat:header>
    </xdat:search_field>
    <xdat:search_where method="OR">
        <xdat:criteria override_value_formatting="0">
            <xdat:schema_field>xnat:mrSessionData/sharing/share/project</xdat:schema_field>
            <xdat:comparison_type>=</xdat:comparison_type>
            <xdat:value>CENTRAL_OASIS_CS</xdat:value>
        </xdat:criteria>
        <xdat:criteria override_value_formatting="0">
            <xdat:schema_field>xnat:mrSessionData/PROJECT</xdat:schema_field>
            <xdat:comparison_type>=</xdat:comparison_type>
            <xdat:value>CENTRAL_OASIS_CS</xdat:value>
        </xdat:criteria>
    </xdat:search_where>
</xdat:search>

This search queries for all mrSessionData objects that are owned by the CENTRAL_OASIS_CS project or shared into the CENTRAL_OASIS_CS project.

The <xdat:root_element_name> determines which data type you are returning. There will be one row per matching entry of this type.
You can add fields from other data types using <xdat:search_field> elements. You can put any XNAT xsiTypes into the <xdat:element_name> field. The field_ID must match a <DisplayField> in the display documents for that data-type.
The search criteria can reference either display fields from the display documents, or schema fields themselves using XPATH.

You can retrieve the search results for this search by perfoming a POST of this document to /data/archive/search. You can customize the format of the results using the format=xml,csv,html,json querystring variable. The xml can be posted in the BODY of your HTML message, or attached as a separate file.

To test this:

Download this XML file: central_all_OASIS_MRS.xml
Open a terminal window and type this command:

Terminal

TEXT

$ curl -X POST -u user:password https://central.xnat.org/data/search?format=xml -F "file=@central_all_OASIS_MRS.xml"

Get A Filtered List Of MR Scans From XNAT Central

Here is a second, more interesting search, which gets all of the MR sessions which your account has access to WHERE the DERIVED_AGE is > 90 and the session contains at least one MPRAGE scan.

Download XML Search File: central_all_sessions_with_MPRAGE_by_type.xml

Show XML Code Block

CODE

<?xml version="1.0" encoding="UTF-8"?>
<xdat:search ID="" allow-diff-columns="0" secure="false" brief-description="MR Sessions" xmlns:cnda="http://nrg.wustl.edu/cnda" xmlns:arc="http://nrg.wustl.edu/arc" xmlns:pipe="http://nrg.wustl.edu/pipe" xmlns:fs="http://nrg.wustl.edu/fs" xmlns:wrk="http://nrg.wustl.edu/workflow" xmlns:xdat="http://nrg.wustl.edu/security" xmlns:cat="http://nrg.wustl.edu/catalog" xmlns:prov="http://www.nbirn.net/prov" xmlns:xnat="http://nrg.wustl.edu/xnat" xmlns:xnat_a="http://nrg.wustl.edu/xnat_assessments" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
    <xdat:root_element_name>xnat:mrSessionData</xdat:root_element_name>
    <xdat:search_field>
        <xdat:element_name>xnat:mrSessionData</xdat:element_name>
        <xdat:field_ID>LABEL</xdat:field_ID>
        <xdat:sequence>0</xdat:sequence>
        <xdat:type>string</xdat:type>
        <xdat:header>MR ID</xdat:header>
    </xdat:search_field>
    <xdat:search_field>
        <xdat:element_name>xnat:subjectData</xdat:element_name>
        <xdat:field_ID>LABEL</xdat:field_ID>
        <xdat:sequence>2</xdat:sequence>
        <xdat:type>string</xdat:type>
        <xdat:header>Subject</xdat:header>
    </xdat:search_field>
    <xdat:search_field>
        <xdat:element_name>xnat:mrSessionData</xdat:element_name>
        <xdat:field_ID>AGE</xdat:field_ID>
        <xdat:sequence>3</xdat:sequence>
        <xdat:type>integer</xdat:type>
        <xdat:header>Age</xdat:header>
    </xdat:search_field>
    <xdat:search_where method="AND">
        <xdat:criteria override_value_formatting="0">
            <xdat:schema_field>xnat:mrSessionData/GEN_AGE</xdat:schema_field>
            <xdat:comparison_type>></xdat:comparison_type>
            <xdat:value>90</xdat:value>
        </xdat:criteria>
        <xdat:criteria override_value_formatting="0">
            <xdat:schema_field>xnat:mrSessionData/scans/scan/type</xdat:schema_field>
            <xdat:comparison_type>=</xdat:comparison_type>
            <xdat:value>MPRAGE</xdat:value>
        </xdat:criteria>
    </xdat:search_where>
</xdat:search>

Build Your Own Search Filter With Element Queries

You can use either example XML file as a starting point for your search. For a list of the available data types you can use in your searches, use this query:

Terminal Window

TEXT

$ curl -u user:password http://central.xnat.org/data/search/elements?format=csv

This will return a CSV formatted list of xsiTypes that can be queried in XNAT Central. Using the returned xsiType names, you can retrieve the fields for the data types of interest.

Terminal Window

TEXT

$ curl -u user:password http://central.xnat.org/data/search/elements/xnat:mrSessionData?format=csv