Creating a JSON Query
You create queries using JavaScript Object Notation (JSON), a text format used to transmit data objects consisting of name/value pairs. Refer to the JSON.org website for fundamental information about JSON.
The queries accepted by the Sierra API use the same structure as JSON queries used by Sierra's Create Lists function. The API operation determines the record type to return, which is equivalent to the "record type to store" in Create Lists.
To learn the element structure, attribute name, or identifying value for any valid data, you can use either the Classic or Enhanced Create Lists query builder in the Sierra Desktop application to specify the data, and then switch to the Create Lists JSON editor to view the corresponding code.
The following sections provide an introduction to JSON queries for the Sierra API.
Query Structure
A query can be one of two types:
- A simple query that applies to a single target.
- A compound query consisting of multiple queries connected with Boolean AND or OR operators. The queries that make up a compound query can themselves be simple or compound, which means that there is an arbitrary level of query nesting.
A simple query consists of a target that defines where to find the data and an expression that evaluates to true or false when supplied with data.
- A set of name/value pairs identifies the target.
- An expression can be one of two types:
- A simple expression that consists of an operator and zero or more operands.
- A compound expression that consists of multiple expressions connected with Boolean AND or OR operators. Like a compound query, the expressions that make up a compound expression can themselves be simple or compound, which means that there is an arbitrary level of expression nesting.
JSON Representation
The JSON representation of a query consists of one or more query objects that contain one or more expressions.
Query
The JSON representation of a simple query is a JSON object with target and expr properties representing the query's target and expression, respectively.
The JSON representation of a compound query is a JSON object with a single queries property for which the value is an array of one or more JSON objects joined by a literal string AND or OR. Each JSON object in the queries array is a representation of a query, which can itself be simple or compound.
Within a simple query, the target property has a record property identifying the target record type, and an additional property representing one of the following discriminators:
- id - a number identifying a fixed-length field (three or fewer digits) or a record property (four or more digits).
- field - a JSON object representing a non-MARC variable-length field, in which case there is a single string/value tag property, or a MARC field, in which case there are marcTag, ind1, ind2, and subfields properties, all of which are strings. These values are documented in the Sierra WebHelp reference topics that describe the variable-length fields found in Innovative record types.
- specialField - a number identifying a MARC leader or control field element (the @ Num). These numbers are documented in the following Sierra WebHelp topics:
The record property in a target has a type property, which is the name of the record type in lowercase. It also might have relationType and relationTag properties, if the record type is a soft-linked record type, such as related resource records for orders.
Expression
The JSON representation of a simple expression is a JSON object with op and operands properties. The op property is the name of the expression's operator in lowercase. (See Using Relational Operators in the Sierra WebHelp for a complete description of recognized operators.) The operands property is an array of JSON strings representing the operands for the expression.
The JSON representation of a compound expression is an array of simple expressions connected with Boolean AND or OR operators.
Examples
The following examples illustrate basic patterns for representing API queries in JSON.
A simple query with a single, simple expression
A simple query for Bibliographic title equal to 'moby dick'
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "t"}
},
"expr": {
"op": "equals",
"operands": ["moby dick"]
}
}
A compound query consisting of two simple queries
A compound query for Bibliographic title equal to 'moby dick' and Bibliographic author has 'melville'
{
"queries": [
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "t"}
},
"expr": {
"op": "equals",
"operands": ["moby dick"]
}
},
"and",
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "a"}
},
"expr": {
"op": "has",
"operands": ["melville"]
}
}
]
}
A simple query with a compound expression
A simple query for Bibliographic title equal to 'moby dick' and has 'whale'
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "t"}
},
"expr": [
{
"op": "equals",
"operands": ["moby dick"]
},
"and",
{
"op": "has",
"operands": ["whale"]
}
]
}
A soft-linked record type
A query for Related resource name has 'test'
{
"target": {
"record": {
"type": "resource",
"relationType": "soft"
},
"field": {"tag": "t"}
},
"expr": {
"op": "has",
"operands": ["test"]
}
}
The only valid value for the relationType parameter is "soft". Standard record links do not require the relationType parameter.