Query Filters

Query filters are used to select matching interactions in an index ready for analysis.

Query filters are written in CSDL, but the level of complexity and range of operators available is less than when writing interaction filters.

Supported operators

You can use the full set of CSDL operators in your interaction filters but only a subset of the CSDL operators in your query filters.

Operator or feature Availability in query filters
contains Works on tokenized targets only.
Case insensitive for all supported targets.
contains_any Works on tokenized targets only.
Case insensitive for all supported targets.
Limited to 100 items in the argument list.
contains_all Works on tokenized targets only.
Case insensitive for all supported targets.
Limited to 100 items in the argument list.
contains_near Works on tokenized targets only.
Case insensitive for all supported targets.
Limited to 100 items in the argument list.
exists Works on any target (tokenized and non-tokenized).
in Works on string and numeric targets; for example:
"red, white, blue"
[1,2,3]

Limited to 100 items in the argument list.
==
!=

Work on all targets.
Case sensitive for all string and array(string) type targets.

>
>=
 Work on numeric targets only.
wildcard You can use either version of wildcards (? or \*).
Works on any target (tokenized and non-tokenized).
An argument cannot start with a wildcard character.
Limited to 100 items in the argument list.
You can only use alphanumeric characters in your arguments.
url_in Not available.
substr Not available.
regex_partial Not available.
regex_exact Not available.
geo_box
geo_radius
geo_polygon		 Not available.
The cs modifier for case sensitivity. Not available.

Case sensitivity

Targets that are tokenized support the contains, contains_any, contains_near, and contains_all operators. These operators are case insensitive.

For targets of type string the in, ==, and != operators are case sensitive.

Therefore when filtering for a country in LinkedIn Engagement Insights, the following filter will work as expected:

li.user.member.country == "argentina"

However, the following filter will not match any interactions:

li.user.member.country == "ARGENTINA"

Equals and not equal

When using == and != in an interaction filter, the following expressions are not equivalent:

not li.all.articles.domain == "linkedin.com"

li.all.articles.domain != "linkedin.com"

The first example states that linkedin.com is not in the list of values in links.domain. The second example states that there is something in the list of values that is not linkedin.com.

However, when using == and != in a Query Filter, they behave differently.

not li.all.articles.domain == "linkedin.com"

li.all.articles.domain != "linkedin.com"

The first example matches all interactions which don't have linkedin.com in the list of domain values, or have linkedin.com as one of the values as long as it is with other values which are not linkedin.com. The second example states that linkedin.com must not appear in the list of values.

Wildcard operator

When using the wildcard operator it is important to note that only the following characters are supported:

  • Western alphabet letters, a to z (upper and lower case).
  • Numbers 0 to 9.

Accented letters, punctuation and characters from other alphabets are not currently supported.

For instance if you're looking to filter to content mentioning carparks, car parking, and other variations of the term, the following filter would not compile because of the - character:

li.content wildcard "carpark*, car-park*"

You could instead replace the - with a ?. This would then match the - in content and allow the filter to compile:

li.content wildcard "carpark*, car?park*"

Logical operators

You can use up to 30 logical operators (and, or, not) in a query filter. For example, this query filter uses two logical operators:

li.user.member.gender == "female" and li.user.member.country == "United States" and li.content contains "coffee"

Precedence of logical operators

In query filtering OR takes precedence over AND so:

A and B or C and D

is the same as:

(((B or C) and A) and D)

Note: this is not the same as the operator precedence for interaction filters. We recommend that you use parentheses to indicate exactly the precedence you require.

Character escaping

You need to escape double-quote (") characters if they are contained within parameter values you want to use with operators in query filters.

To illustrate this idea, let's look at an example:

  1. You want to filter for a topic name containing quotes, such as 'Mike "Coach K" Krzyzewski'.

  2. The string parameter required by the CSDL parser would read:

    Mike \"Coach K\" Krzyzewski

    This is because the CSDL parser requires a backslash before each double quote to interpret the double quote character correctly.

  3. The CSDL for your query filter including the target name would be:

    fb.topics.name == "Mike \\"Coach K\\" Krzyzewski"

    The additional backslash has been added to escape the double quote within the string value for the condition.

  4. Finally you would encode your filter parameter in JSON for your analysis call:

    "filter": "fb.topics.name == \"Mike \\\\\"Coach K\\\\\" Krzyzewski\""

    Note that encoding the filter CSDL in JSON introduces JSON's own escaping syntax.