List Filter Syntax and Usage

This document describes the list filter syntax and how to use it to filter various resource types.

Some API methods can accept a filter to limit the resources in the response.

Syntax Summary

This section provides a quick overview of the list filter syntax structure.

  • A filter is a string containing an expression, which is a Boolean combination of comparisons:
    expression = ["NOT"] comparison { ("AND" | "OR") ["NOT"] comparison }
    expression = ( expression )
    
  • A comparison matches a field of a resource with a value. All the common comparison operators can be used. The has operator, which is a colon (:), can be used towards strings and repeated fields. Please refer to the Has operator section for details.
    comparison = name OP value
    OP = "<=" | "<" | ">=" | ">"  | "!=" | "=" | ":"
  • Values appearing in filters can be numbers, strings, or parenthesized expressions. Strings are used to represent arbitrary text, plus Boolean, Enum values, and Timestamp.
    value = number| string | "*" | "(" expression ")"

Boolean expressions

expression = ["NOT"|"-"] comparison {["AND" | "OR"] ["NOT"|"-"] comparison}

The NOT operator has the highest precedence, followed by OR and AND in that order. For example, the following two expressions are equivalent:

a OR NOT b AND NOT c OR d
(a OR (NOT b)) AND ((NOT c) OR d)

The AND operator can be omitted between comparisons. For example, the following two filters are the same:

c=d AND e=f
c=d e=f

The hyphen/minus (-) can be used as an alternative for NOT. When using the -, no space is allowed between it and the following comparison. For example, the following two filters are the same:

NOT e=f
-e=f

Comparisons

This section discusses "name OP value" comparisons.

comparison = name OP value
OP = "<=" | "<" | ">=" | ">" | "!=" | "=" | ":"
name = identifier { "." identifier }
identifier = unquoted_text
value = number | string | "*" | "(" expression ")"

The left-hand side of a comparison is the path name of an API resource field. The name consists of a series of resource identifiers connected by period (.). Each field identifier is followed by the next level of names for that field. For example, consider a resource having a complex field "item" containing another complex field "tool", which contains a field named "shape". In a filter for this resource, you would refer to shape with the name "item.tool.shape".

The right-hand side is typically a scalar value that is converted to the field's type and compared against it. See the Value Literal Types section for more details.

Right-hand side of a comparison can also be expressed as a parenthesized Boolean combination of literal values and/or boolean expressions which contains only literal values (preceded with or without “NOT”). The left-hand side name and the comparison operator are applied to each of the values. For example, the following two filters are the same:

deal.name = ("test 1" OR "test 2")
deal.name = "test 1" OR deal.name = "test 2"

Here is another more complex example of two equivalent filters:

deal.name = ("test 1" OR "test 2" AND (NOT “test3” OR “test4”))
(deal.name = "test 1" OR deal.name = "test 2") AND ( (NOT deal.name = ”test3”) OR deal.name = ”test4”)

Value Literal Types

The right-hand side value of a Comparison operator can be categorized into Number and String literals.

Number

This section elaborates on how different types of numeric literals are represented.

  • Double
    Any number that contains a decimal point, with or without a sign (‘-’) is treated as a Double. For example, 1234.567, -789.0123.

  • Integer
    Any number that doesn’t have a decimal point, with or without a sign (‘-’) is treated as an integer. For example, 1234, -789.

String

This section describes a list of types that can be written as a string literal in the filter syntax.

Note: a string literal can be double quoted (“”), or unquoted. Single quote cannot be used to represent a string literal. For example, “ABC DEF” and ABC DEF are equivalent. ‘ABC DEF’ is not allowed by the syntax.

  • Boolean
    "True" or "False" in any letter case. For example, "True", "true", “TRUE”.

  • Enum
    The name of an enumeration type literal, case-sensitive. For example, "FINALIZED".

  • String
    Any string that contains UTF-8 encoded or 7-bit ASCII text. Embedded quotation marks must be escaped with a backslash. For example, name = "test \"double quotes\"".

    Unquoted string containing whitespace will be treated as implicit AND among all the words after splitting the string by whitespace. For example, name=(ABC DEF) is equivalent to name=ABC AND name=DEF.

  • Timestamp
    A string in the ISO8601 standard format. For example, "2014-10-02T15:01:23.045Z".

Comparison Operators

There are 6 comparison operators: "<=", "<", ">=", ">", "!=", "=", ":" (HAS operator). All of the 6 operators apply to Double, Integer, Boolean, Enum and Timestamp value types.

For strings, only "!=", "=", ":" can be applied for comparison. String comparison is case insensitive.

Has operator

The HAS operator (:) allows for special operations on certain fields:

  • Substrings. When the HAS operator is used for comparing values on a string column to a string, the operator will act as a substring operation. Example: name:"abcd" will return all instances where name is a string containing "abcd".
  • Existence checking. When the HAS operator is used with the special character "*", the HAS operator will act as if checking for not null values. Example: name:* will return all instances where name is not null/missing/undefined.
  • When the HAS operator is used with non string values, it will behave the same as the EQUALS (=) operator. Example: isCompleted:true will behave in the same way as isCompleted = true.

Repeated Fields

The HAS (:) operator can be used to filter on a repeated API resource field, as long as:

  1. There is only one single repeated component along the field identifier path.
  2. Last identifier of the field path is of scalar type.

Filtering on nested repeated fields is not supported.

For example, item has a “colors” field, which contains string values like “red”, “blue”, “yellow”.

item.colors:(“red”) will return all items that have the value “red” in the colors field.
item.colors:(“red” “yellow”) will return all items that have both the value “red” and “yellow” in the colors field.
item.colors:(“red” OR “yellow”) will return all items that have the value “red” or “yellow” in the colors field.

Here is a second example, item has a repeated “tools” field, which is a complex object that contains a scalar field “shape” (possible values, “square”, “round”).

item.tools.shape:(“square”) will return all items that have “square” shaped tools.
item.tools.shape:(“square” “round”) will return all items that have both a “square” shared tool and a “round” shaped tool.
item.tools.shape:(“square” OR “round”) will return all items that have a “square” shape tool or a “round” shaped tool.

Note: Not all repeated fields can be filtered. For more details about a specific resource, see the reference documentation.

Usage Examples

Example Description

externalDealId = "123456789"

externalDealId that has a string value “123456789”.

advertiserId:93641

advertiserId = 93641

advertiserId that has an integer value 93641.

isSetupComplete = true

isSetupComplete:TRUE

isSetupComplete = (True)

isSetupComplete is equal to TRUE.

updateTime > "2018-02-14T11:09:19.378Z"

updateTime is later than 02/14/2018 11:09:19.378 UTC

displayName = "proposal" AND proposalRevision = 3

displayName = "proposal" proposalRevision = 3

displayName string has an identical value of ”proposal” ANDproposalRevision is equal to 3.

displayName = "proposal" OR proposalRevision = 3

displayName has a string value of “proposal” OR the proposalRevision is equal to 3.

NOT displayName = "proposal"

displayName != “proposal”

displayName is not equal to “proposal”.

proposalState = (PROPOSED OR BUYER_ACCEPTED)

proposalState = PROPOSED OR proposalState = BUYER_ACCEPTED

proposalState has an enum value that is either equal to PROPOSED OR BUYER_ACCEPTED.

proposalState = (PROPOSED AND BUYER_ACCEPTED)

proposalState = (PROPOSED BUYER_ACCEPTED)

proposalState = PROPOSED AND proposalState = BUYER_ACCEPTED

proposalState = PROPOSED proposalState = BUYER_ACCEPTED

proposalState has an enum value that is equal to PROPOSED AND BUYER_ACCEPTED

dealName = Test Deal

INVALID expression

dealName = “Test Deal”

dealName is equal to “Test Deal”.

dealName = (Test Deal)

dealName is equal to “Test” and also equal to “Deal”.

dealName = (“Test1” OR “Test2”)

dealName = “Test1” OR dealName = “Test2”

dealName is either equal to “Test1” or equal to “Test2”.

dealName:*

dealName is not null.

dealName:”test”

dealName:test

dealName contains the substring “test”.

dealName:(“A B”)

dealName:”A B”

dealName contains the substring “A B”.

dealName:(A B)

dealName:”A” AND dealName:”B”

dealName contains the substring “A” and the substring “B”.

dealName:(“A” OR “B” AND “C”)

dealName:(“A” OR “B” “C”)

dealName:“A” OR dealName:“B” AND dealName:“C”

dealName:“A” OR dealName:“B” dealName:“C”

(dealName:“A” OR dealName:“B”) AND dealName:“C”

(dealName:“A” OR dealName:“B”) dealName:“C”

dealName contains either substring “A” OR “B” AND also contains substring “C”

dealName:(“A B” C)

dealName:”A B” AND dealName:”C”

dealName contains substring “A B” and also contains substring “C”.

dealName:(“A B” OR C D)

dealName contains either the substring “A B” or “C”, and also contains substring “D”.

dealName:(NOT “A” B)

NOT dealName:”A” AND dealName:”B”

(NOT dealName:”A”) AND dealName:”B”

(NOT dealName:”A”) dealName:”B”

dealName does not contain any substring “A” and also contains substring “B”.

dealName:(NOT “A” OR “B”)

NOT dealName:”A” OR dealName:”B”
(NOT dealName:”A”) OR dealName:”B”

dealName does not contain any substring “A” or contains substring “B”.

Send feedback about...

Authorized Buyers
Authorized Buyers