Catnap Query Language Reference
The Catnap Query Language, CQL, is a simple, url-safe, expression language that can be used to customize the response of a Catnap enabled RESTful web service.
CQL supports simple field selection and more elaborate logic-based selection expressions.
Catnap queries are specially formatted strings supplied to a Catnap enabled service via a query parameter (by default the query parameter name is fields).
Catnap queries are composed of two types of elements:
- Selectors - Tells Catnap the name of the fields to return and in which order.
- Expressions - Allows the user to specify logic that Catnap will evaluate when determining whether or not a selector will return a particular field.
Selectors allow you to tell Catnap what fields you are interested in and Catnap will return only those fields in the response.
For all of the examples below, let's assume that we have a product information service for an e-commerce site that returns the following data for a product we offer for sale.
Url: https://www.catnap.it/products/12345/details
{
"id": "12345",
"name": "Product 1",
"prices": {
"list": "$120.00",
"sale": "89.99"
},
"images": [
{
"sortOrder": 1,
"url": "https://catnap-springboot-sample.herokuapp.com\/12345-primary.png",
"alt": "Product 1",
"size": "primary"
},
{
"sortOrder": 2,
"url": "https://catnap-springboot-sample.herokuapp.com\/12345-thumbnail.png",
"alt": "Product 1",
"size": "thumbnail"
}
],
"inventory": {
"online": {
"storeId": 999,
"storeName": "web",
"sizes": [
{
"size": "S",
"count": 23
},
{
"size": "M",
"count": 0
},
{
"size": "L",
"count": 6
}
]
},
"stores": [
{
"storeId": 1,
"storeName": "store 1",
"sizes": [
{
"size": "S",
"count": 6
},
{
"size": "M",
"count": 10
},
{
"size": "L",
"count": 14
}
]
},
{
"storeId": 2,
"storeName": "store 2",
"sizes": [
{
"size": "S",
"count": 20
},
{
"size": "M",
"count": 8
},
{
"size": "L",
"count": 3
}
]
}
]
}
}
As you can see, the response contains information on the identity of the product as well as pricing information, product imagery, and inventory counts.
Field Selectors are the simplest form of query parameters in CQL, consisting only of a comma-separated list of field names on the response object.
fields={field 1},{field 2},...{field n}
Fields are returned in the order in which they are specified in the query.
In the example below assume that we are only interested in returning the id and the name of the product.
Url: https://www.catnap.it/products/12345/details?fields=id,name
{
"id": "12345",
"name": "Product 1"
}
Sub-Field Selectors allow you to select and return fields nested within objects. Sub-Fields are specified as a comma separated list within parenthesis that immediately follow the field in which they are nested.
fields={field 1}({sub-field 1},{sub-field 2},...{sub-field n})
In the example below assume that we are only interested in returning the name and the list price of the product.
As you can see in the data returned from the service, list price is a field named list nested within the prices object.
Url: https://www.catnap.it/products/12345/details?fields=name,prices(list)
{
"name" : "Product 1",
"prices" : {
"list" : "$120.00"
}
}
Just as you can select Sub-Fields within nested objects, you can select sub-fields within collections of nested objects.
fields={field 1}({sub-field 1},{sub-field 2},...{sub-field n})
In the example below assume that we are only interested in returning the name of the product and the sortOrder and
url of all images within the images collection.
Url: https://www.catnap.it/products/12345/details?fields=name,images(sortOrder,url)
{
"name" : "Product 1",
"images" : [
{
"sortOrder" : 1,
"url" : "https://catnap-springboot-sample.herokuapp.com/12345-primary.png"
},
{
"sortOrder" : 2,
"url" : "https://catnap-springboot-sample.herokuapp.com/12345-thumbnail.png"
}
]
}
Sub-Field selectors support selecting fields at arbitrary depths within an object hierarchy.
fields={field 1}({sub-field 1}({sub-sub-field1},...{sub-sub-fieldn}))
In the example below assume that we are only interested in returning the name of the product and sizes information for online inventory.
Url: https://www.catnap.it/products/12345/details?fields=name,inventory(online(sizes))
{
"name" : "Product 1",
"inventory" : {
"online" : {
"sizes" : [
{
"size" : "S",
"count" : 23
},
{
"size" : "M",
"count" : 0
},
{
"size" : "L",
"count" : 6
}
]
}
}
}
You can use expressions with fields or sub-fields. The condition must evaluate to true for the selected field to be included in the results. If there is no field condition, then all fields of the selected type are included. Expressions are always nested within square brackets.
The equality expressions give you the ability to only select fields in the event that a specified field value is: equal to, not equal to, less than, greater than, less than or equal to, or greater than or equal to a specified value.
| Operator | Example | Description |
|---|---|---|
| = | {field}={value} | Return the selection if field's value is equal to value. |
| != | {field}!={value} | Return the selection if field's value is not equal to value. |
| < | {field}<{value} | Return the selection if field's value is less than value. |
| > | {field}>{value} | Return the selection if field's value is greater than value. |
| <= | {field}<={value} | Return the selection if field's value is less than or equal to value. |
| >= | {field}>={value} | Return the selection if field's value is greater than or equal to value. |
Catnap is smart about types and will attempt to convert the value you supply in an expression to the same type as the field before evaluating the expression.
Special Cases:
- Strings are compared alphabetically
- Valid "true" boolean values are: true, T, and 1
- Valid "false" boolean values are: false, F, and 0
In the example below assume that we are only interested in returning the name of the product and all of the images within the image collection that have a sortOrder equal to 1.
Url: https://www.catnap.it/products/12345/details?fields=name,images[sortOrder=1]
{
"name" : "Product 1",
"images" : [
{
"sortOrder" : 1,
"url" : "https://catnap-springboot-sample.herokuapp.com/12345-primary.png",
"alt" : "Product 1",
"size" : "primary"
}
]
}
In the example below assume that we are only interested in returning the name of the product and the url of all of the images within the image collection that have a sortOrder greater than 1.
Url: https://www.catnap.it/products/12345/details?fields=name,images(url)[sortOrder>1]
{
"name" : "Product 1",
"images" : [
{
"url" : "https://catnap-springboot-sample.herokuapp.com/12345-thumbnail.png"
}
]
}
In the example below assume that we are only interested in returning the name of the product and the url of all of the images within the image collection, but if the image has a sortOrder equal to 1 we would also like to return the alt text.
Url: https://www.catnap.it/products/12345/details?fields=name,images(url,alt[sortOrder=1])
{
"name" : "Product 1",
"images" : [
{
"url" : "https://catnap-springboot-sample.herokuapp.com/12345-primary.png",
"alt" : "Product 1"
},
{
"url" : "https://catnap-springboot-sample.herokuapp.com/12345-thumbnail.png"
}
]
}
The logical operators "and", "or", and "not" will be available in a future release of Catnap.