Zerkel is a querying language used by Adzerk 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
CustomTargetingfield in API, make sure quotation marks are escaped so they don't break JSON. For example:
name = "Adzerk"would become
name = \"Adzerk\"
exact string match
strings do not match exactly
wildcard match allows
$url contains "zerk"- Targets URLs such as "adzerk.com", "adzerk.net", "berzerk.com", "foozerkbar.com", etc.
$url like "adzerk.com*"- Targets any URL that begins with "adzerk.com", such as "adzerk.com/about", "adzerk.com/api", etc.
exact number match
numbers do not match exactly
less than or equal to
greater than or equal to
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 1would 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 23would be true if 23 is an element in the array.
numbers contains 23would not be true if 1234 is an element in the array.
You can create complex queries by using these Boolean operators:
In addition, you can use parentheses to group logical statements together.
If you use the
notoperator, 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!
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
fookey is present in the request
not foo- matches if the
fookey is not present in the request
If the value of a key is
null, Zerkel will parse the key as nonexistent.
For instance, given
"foo":0in the request,
foowill return false (i.e. not match) and
not foowill return true.
To work around this, you can pass an arbitrary value or
nullin your requests.
Zerkel supports two operators for querying against regular expressions:
!~(does not match)
$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.
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"
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.
Updated about a year ago