Creating a JSON Query
You can view and define Create Lists queries using JavaScript Object Notation (JSON), a text format used to transmit data objects consisting of name/value pairs. When you build a query in the Enhanced or Classic query builder, click the JSON option button to view the JSON representation of your query. Alternatively, you can build a JSON query directly in the editor or click Load JSON to load a JSON text file. When you build a JSON query in the editor, you can save the query to your local machine as a plain text file.
The JSON editor is not intended for use by Limited Users. The record types drop-down list and range entry fields remain locked for this role.
Refer to the JSON.org website for fundamental information about JSON. The following sections provide an introduction to JSON queries in Create Lists:
Create Lists Query Structure
A Create Lists 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 identify 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 Create Lists query consists of one or more query objects that contain one or more expressions.
A Simple 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. A simple query contains one complete Create Lists search term ("Bibliographic Title equal to "birds of america"). See Example 1 below to view the JSON representation of a simple query.
A Compound Query
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. See Example 2 below to view the JSON representation of a compound query. Note the use and placement of the queries operator on the second line of the compound query.
Target
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 used to determine the record field being searched:
- 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. For MARC field searches, only the marcTag property is required (the ind1/ind2 properties and the subfields property are optional). These values are documented in the 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 topics:
Note that if you use either ind1 or ind2 in your query for marcTag searching, both of these properties must be included in the query syntax. Otherwise the system provides whichever is missing and assigns it a null (" ") value. The ind1/ind2 properties can be used without the subfields property; likewise, the subfields property can be used without the ind1/ind2 properties).
See Create Lists JSON Syntax for Record Field Discriminators for a complete list of the JSON Create Lists field discriminators.
The record property in a target has a type property, which in most cases is the name of the record type in lowercase. See Create Lists JSON Syntax for Record-Type Names for a complete list of the JSON syntax for record-type names.
The type property also might have relationType and relationTag properties, if the record type is a soft-linked record type, such as related resource records for orders. See Example 4 below to view the JSON representation of a soft-linked record.
Expression
The JSON representation of a simple expression is a JSON object with an op property and an operands property. The op property is the name of the expression's operator. See Create Lists JSON Syntax for Relational Operators for a complete list of the JSON syntax for valid Create Lists operators. Note that if you use the In operator, you cannot view or edit queries in the Classic editor.
The operands property is an array of JSON strings representing the operands for the expression. An operand specifies the specific data being searched. For example, "birds of america" would be the operand for a simple query that searches for the bibliographic title "Birds of America".
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 Create Lists queries in JSON.
To learn the element structure, attribute name, or identifying value for any valid Create Lists data, you can use the Classic or Enhanced query builder to specify the data, and then switch to the JSON editor to view the corresponding code.
Example 1: A simple query with a single, simple expression
A simple query for Bibliographic title equal to 'birds of america'
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "t"}
},
"expr": {
"op": "equals",
"operands": ["birds of america"]
}
}
Example 2: A compound query consisting of two simple queries
A compound query for Bibliographic title equal to 'strangers on a train' and Bibliographic author has 'highsmith'
{
"queries": [
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "t"}
},
"expr": {
"op": "equals",
"operands": ["strangers on a train"]
}
},
"and",
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "a"}
},
"expr": {
"op": "has",
"operands": ["highsmith"]
}
}
]
}
Example 3: 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"]
}
]
}
Example 4: A soft-linked record type
A query for Registered Session Summary starts with "gardening lecture"
{
"target": {
"record": {
"type": "section",
"relationType": "soft",
"relationTag": "3"
},
"field": {"tag": "s"}
},
"expr": {
"op": "starts_with",
"operands": ["gardening lecture"]
}
}
Example 5: A compound query illustrating syntax for variable-length, fixed-length, and special fields
A compound query for Bibliographic title has 'mockingbird' and Bibliographic MARC Tag 24501|c has "lee" and Bibliographic material type equal to 'a' and Bibliographic country equal to 'xxu' and Order paid date equals yesterdayIn this query, there are expressions targeting the following field types:
- a variable-length field using a non-MARC field tag (title / field tag "t")
- a variable-length field using a MARC field tag with indicators and a subfield (MARC 24501|c)
- a fixed-length field (material type / ff #30)
- a special field (MARC 008 'country' subfield / special field #268)
- a record property (Order record PAID date / record property #79003)
{
"queries": [
{
"target": {
"record": {"type": "bib"},
"field": {"tag": "t"
}
},
"expr": {
"op": "has",
"operands": ["mockingbird"]
}
},
"and",
{
"target": {
"record": {"type": "bib"},
"field": {"marcTag": "245",
"ind1": "0",
"ind2": "1",
"subfields": "c"
}
},
"expr": {
"op": "has",
"operands": ["lee"]
}
},
"and",
{
"target": {
"record": {"type": "bib"},
"id": 30
},
"expr": {
"op": "equals",
"operands": ["a"]
}
},
"and",
{
"target": {
"record": {"type": "bib"},
"specialField": 268
},
"expr": {
"op": "equals",
"operands": ["xxu"]
}
},
"and",
{
"target": {
"record": {"type": "order"},
"id": 79003
},
"expr": {
"op": "yesterday",
"operands": [""]
}
}
]
}
Example 6: A query targeting data stored in a barcode field
A compound query for Item Barcode in ("23100 10850 0098","23100108500101. ","23100108500114")Note that Create Lists searches record data when searching for barcodes, and does not search the normalized data stored in the barcode index. Create Lists does not find a barcode unless the data is entered exactly as it appears in the record (including all spaces and punctuation that may be stored in the record's barcode field, and that are typically removed during the indexing process).
{
"queries": [
{
"target": {
"record": {"type": "item"},
"field": {"tag": "b"}
},
"expr": [
{
"op": "in",
"operands": [
"23100 10850 0098",
"23100108500101. ",
"23100108500114"
]
}
]
}
]
}