XNAT API Documentation
XNAT API Documentation
Breadcrumbs

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 


<?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:

$ 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 


<?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:

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

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