Here is a cURL search request that can be sent to MoNA. MoNA utilizes the Spring Filter library to create dynamic queries. Let's dissect the following cURL command.
curl -G -H "Content-Type: application/json" --data-urlencode "query=exists(metaData.name:'ionization mode' and metaData.value:'positive')" --data-urlencode "size=10" --data-urlencode "page=1" http://mona.fiehnlab.ucdavis.edu/rest/spectra/search
1) -G ensures the cURL call is GET
2) -H "Content-Type: application/json" tells cURL to return a JSON payload.
3) --data-urlencode "query=exists(metaData.name:'ionization mode' and metaData.value:'positive')" will encode the query parameter to ensure all values of the text are passed to the backend. The query itself will be further explained later.
4) --data-urlencode "size=10" sets the JSON result size to 10 spectra. Please use size is possible! Large result sets can cause strain on the database and extend query times.
5) --data-urlencode "page=1" accesses the first page of the above size of a given result set. If the above query results in 200 total results, and you designate a size of 10 like above, you'll have 20 available pages of results.
6) http://mona.fiehnlab.ucdavis.edu/rest/spectra/search is the REST endpoint you'll contact for your searches.
Please take some time to read the README.md from the Spring Filter project! The MoNA team has decided to use Spring Filter for all of its querying. The library allows for nested querying and provides an extensive amount of functions and operations to create custom queries.
Spring Filter uses dot notation to reference nested objects. Let's a simplified Spectrum object for example:
{
"id": "MoNA000001",
"compound": [
{
"metaData": {"name": "InChIKey", value: "BRMWTNUJHUMWMS-LURJTMIESA-N"}
}
],
"metaData": {"name": "ionization mode", value: "positive"},
}
If we want to check the id value, then we reference: id
If we want to check compound metadata name, then we reference: compound.metaData.name
Or if we want to check spectrum metadata value, then we reference: metaData.value
There will be a spectrum data object on the bottom of this page for you to reference when creating queries. Simply put, you can use Javascript like dot notation to reference fields within a spectrum object for searching.
| Literal | Description | Example |
|---|---|---|
| and | AND Condition Between Two Expressions | id : 'MoNA000001' and metaData.name : 'positive' |
| or | OR Condition Between Two Expressions | id : 'MoNA000001' or metaData.name : 'positive' |
| not | NOT Condition For Given Expressions | not (metaData.name : 'positive') |
| Literal | Description | Example |
|---|---|---|
| ~ | checks if the left (string) expression is similar to the right (string) expression | metaData.name ~ '*ionization' |
| : | checks if the left expression is equal to the right expression | id : MoNA000001 |
| ! | checks if the left expression is not equal to the right expression | compound.metaData.value ! 'BRMWTNUJHUMWMS-LURJTMIESA-N' |
| > | checks if the left expression is greater than the right expression | metaData.value > 100 |
| >: | checks if the left expression is greater or equal to the right expression | metaData.value >: 100 |
| < | checks if the left expression is smaller than the right expression | metaData.value < 100 |
| <: | checks if the left expression is smaller or equal to the right expression | metaData.value <: 100 |
| is null | checks if an expression is null | metaData.value is null |
| is not null | checks if an expression is not null | metaData.value is not null |
| is empty | checks if the (collection) expression is empty | compound is empty |
| is not empty | checks if the (collection) expression is not empty | compound is not empty |
| in | checks if an expression is present in the right expressions | metaData.value in ('positive', 'negative') |
| Name | Description | Example | Explanation |
|---|---|---|---|
| exists | returns the existence of a subquery result | exists(metaData.value: 'positive' and metaData.name: 'ionization mode') | returns true if metadata name is ionization mode and the value is positive |
Subquries are the most important function as they allow of to query a given table multiple times. Normally, we are limited to searching each field a single time such as only being able to visit metaData.name once in a given query statement. But, with subqueries, we are able to join the metaData table multiple times and check various field values.
Subqueries allow us to perform custom queries like the following that searches for dirty spectra:
exists(metaData.name:'normalized entropy' and metaData.value>'0.8') and exists(metaData.name:'spectral entropy' and metaData.value>'3.0')
The queries that you construct for cURL commands work exactly the same as they do in the Spectrum Browser. Simply do the following:
1) Look at the top of the page and click on Display Generated Query
2) Next to Generated Query you will see the button
3) Type or copy your query into the field and then click on Update Query. This will execute the query and provide you results! In addition you'll be provided a cURL command that you can then execute on the command line.