Zerkel Queries

Overview

Zerkel is a querying language used by Kevel to set the custom targeting of a flight, channel or creative.

Zerkel is very flexible and contains operators for:

• String Values - exact match, wildcards, etc
• Numerical Values - exact number match, less than, greater than, etc
• Array Values - targets if element is included in array
• Logic Operators - and, or, not
• True or False
• Regular Expressions - matches, does not match

📘

The keys and string values in a Zerkel query are case-sensitive. Whitespace around the Zerkel operators is optional.

🚧

The maximum character length for Zerkel queries is 1000 characters.

🚧

When passing queries via CustomTargeting field in API, make sure quotation marks are escaped so they don't break JSON. For example:

name = "Kevel" would become name = \"Kevel\"

Operators for String Values

String Examples

• $url contains "kevel" - Targets URLs such as "www.kevel.co", "kevel.net", etc.
• $url like "www.kevel.com*" - Targets any URL that begins with "www.kevel.com", such as "www.kevel.com/about", "www.kevel.com/solutions/", etc.

Operators for Numeric Values

Operators for Array Values

contains

The contains operator targets a placement based on whether an element is present in the array. For example, given numbers = [1,2,3,4] in a placement:

• numbers contains 1 would be true, and the placement will be targeted.
• numbers contains "potato" would be false, and the placement will not be targeted.

📘

Unlike strings, the contains operator for arrays is an exact match for an element. For example:

• numbers contains 23 would be true if 23 is an element in the array.
• numbers contains 23 would not be true if 1234 is an element in the array.

Logic Operators

You can create complex queries by using these Boolean operators:

• and
• or
• not

In addition, you can use parentheses to group logical statements together.

❗️

If you use the not operator, you must use parentheses to enclose what you're querying against. For example:

weather contains "sunny" and not (season = "winter")

If you do not include the parentheses, the Zerkel query will be incorrectly parsed!

True or False

To determine whether a key exists in a request (true) or doesn't exist (false), use the key by itself as your query:

• foo - matches if the foo key is present in the request
• not foo - matches if the foo key is not present in the request

🚧

If the value of a key is 0, "", or null, Zerkel will parse the key as nonexistent.

For instance, given "foo":0 in the request, foo will return false (i.e. not match) and not foo will return true.

To work around this, you can pass an arbitrary value or [] instead of 0, "" or null in your requests.

Operators for Regular Expressions

Zerkel supports two operators for querying against regular expressions:

• =~ (matches)
• !~ (does not match)

For example:

$url =~ "^https?:\/\/([^/:]\.)*foo\.bar\.com([:/].*)?$"

Will target any URL that contains foo.bar.com in the domain, including secure sites and subdomains.

Before using these operators, you should be familiar with how to use regular expressions.

Comments

You can include comments in your queries. Zerkel supports both single-line and multi-line comments. Any text that is commented will be ignored by custom targeting.

A single-line comment starts with // and extends to the end of the line:

weather contains "sunny" // this targets sunny weather

A multi-line comment starts with / and ends with/. All content within the operators will be ignored:

/* The following query
   will target
   sunny weather */
weather contains "sunny"

Example Queries

Simple value comparison:

age > 25

Multiple comparisons. Make sure to use parentheses.

(age > 25 and gender = "male")

Even more complexity:

(age > 25 and gender = "male") or 
   (age > 50 and gender = "female")

With Reserved Keys:

$device.brandName like "*Samsung*"

To target arrays, place BEFORE the key you are comparing:

["27511", "27519", "27701", "27707"] contains $location.postalCode

The Zerkel interpreter in the UI automatically validates queries before you save the flight. If a query is invalid, an alert will appear:

The full Zerkel parser is hosted on Github.