- Comma-Separated Lists for Multiple Associations
- Nested Parentheses for Association Paths
- Square Brackets for Filters
- Double Colon for Axis
Use the RMA path syntax to describe a path connecting associated models in the schema. It is used in the include= and criteria= URL parameters. Please note that the path syntax does not support spaces between operators and values, but values enclosed in single quotes can include them (i.e. name$eq’value with spaces’).
Comma-Separated Lists for Multiple Associations
The RMA Path specifies a set of associations from a resource. The simplest form is a comma-separated list of association names. Association names are lower case and may be singular or plural depending on the type of association.
probes,organism,chromosome
Nested Parentheses for Association Paths
Indicate multiple levels of association with nested parentheses. Follow multiple associations from a model by using commas.
probes(orientation,predicted_sequence)
Square Brackets for Filters
Filter the resources that are included in the query results using square brackets following an association. Operators include equal ($eq), not equal ($ne), like ($li), greater than ($gt), less than ($lt), greater or equal ($ge) less or equal ($le) in ($in) and case-insensitive like ($il).
genes[acromym$eq'ABAT']
The left hand side of the filter is an attribute name. It may be qualified with a lower case plural table name to resolve ambiguity using the form table.attribute. At times the model name in a filter may not match the association name due to inheritance.
predicted_sequence[sequences.sequence_length$eq948]
The right hand side may be a number, a string or a qualified attribute or association name. Strings should be enclosed in single quotes, but the quotes may be omitted when there is no ambiguity. The asterisk (*) is treated as a wildcard for the like and ilike string comparison operators.
genes[chromosome.name$eq'X'] ontologies[name$il'*human*']
A filter without an operator or a right hand side is treated as an existence test. It removes records with null values for an attribute. In many cases an _id attribute can be used to test whether any associated resources exist.
probes[orientation_id]
Apply multiple filters to a set of resources using extra filter clauses in square brackets. The effect is a boolean ‘and’.
chromosome[organism_id$eq1][name$ne'X'][name$ne'Y']
Use filters without any association at the start of the criteria field of a query URL to filter resources from the model in the URL.
http://api.brain-map.org/api/v2/data/Organism/query.xml?criteria=[name$il'*human*'][id$ne15] http://api.brain-map.org/api/v2/data/Gene/query.xml?criteria=[acronym$il'abat']&include=organism
Double Colon for Axis
The double colon (:
operator can be used to change the axis of an RMA query. The five defined axes are attribute::, model::, service::, pipe:: and rma::. The double colon axis operator is combined with an id to create a single step along the axis. Examples include service::differential, pipe::list, model::Gene, and rma::options. Each axis behaves slightly differently. They can be used in combination to form a service pipeline.
The model axis begins an API data query. The right hand side of a model step is a model name. Use the model axis is used in combination with steps along the attribute axis and filters to form a complete model stage.
model::Gene,probes(orientation,predicted_sequence)
Use the rma axis to modify the RMA query. The right hand side of an rma step is the name of the option. An rma::criteria step will cause following attribute steps to specify what associations are used in retrieving the data. An rma::include step will cause following attribute steps to specify what associations are displayed in the message response body. Use an rma::options step to specify sorting, paging and ordering options.
model::Gene,rma::criteria,organism[name$il'Homo Sapiens'],rma::include,probes,chromosome,rma::options[num_rows$eq10]
The above request will find human genes (the criteria), display the genes along with the probes and chromosome (the includes) ten genes at a time (the options). Options specified on the URL as described above are treated as steps on the rma axis.
The service and pipe axes are discussed in depth in the following section. They are used in combination with the other axes to create multiple stage service pipelines.
The attribute:: axis is the assumed axis used for the RMA path syntax, but it is almost never used explicitly.