Filter syntax

This page explains the syntax you must use to filter accounts.

Syntax

All values other than integers must be enclosed in double quotations ("). To learn what values a specific field accepts, see the reference documentation for that field.

You can use AND to filter for multiple fields in the same query. You can also use AND to combine multiple relationship(...) and service(...) filters. Here's an example that combines multiple relationship(...) and service(...) filters:

(relationship(service(type = "ACCOUNT_MANAGEMENT") AND service(handshakeState = "PENDING"))) OR (accountName = "store" AND relationship(...))

This example returns the following accounts:

  • All accounts with an account management relationship to another account, and an additional relationship that's pending acceptance.

  • All accounts with the display name "store", who have relationships to other accounts.

You can't use AND to filter for multiple values in the same field. For example, you can't use accountName = "*A*" AND accountName = "*B*".

You can use OR to filter for two fields in the same query. Enclose the filter criteria on each side of the OR operator with parentheses. For example, (accountName = "storeA") OR (accountName = "storeB").

You can only use OR to combine two fields. For example, you can't use (accountName = "storeA") OR (accountName = "storeB") OR (accountName = "storeC").

Parentheses aren't allowed other than with the AND and OR operators, and in function invocations, like relationship(...) and service(...).

For string fields like accountName and accountIdAlias, you can filter for values that contain a certain word or sequence of characters by enclosing the sequence in asterisks (*). For example, accountName = "*foo*" returns all accounts with an accountName containing foo, like "storeFoo".

You can filter for values that don't contain a certain sequence by using != and *. For example, accountName != "*foo*" returns all accounts with an accountName that doesn't contain foo.

Extra white spaces are ignored. For example, foo AND bar is the same as foo AND bar.

Specification

The filters follow a subset of the AIP filter specification, and its formal EBNF grammar:

filter
    : accountFilterDisj
    | accountFilterConj
    ;
accountFilterDisj
    : "(" accountFilterConj " OR " accountFilterConj ")"
    ;
accountFilterConj
    : accountFilter {" AND " accountFilter}
    ;
accountFilter
    : displayNameFilter | relationshipFn
    ;
displayNameFilter
    : "displayName" comparator value
    ;
relationshipFn
    : "relationship(" relationshipConj ")"
    ;
relationshipConj
    : relationshipFilter {" AND " relationshipFilter}
    ;
relationshipFilter
    : "providerId = " numValue
    | "callerHasAccessToProviderFilter()"
    | "externalAccountId" comparator value
    | "accountIdAlias" comparator value
    | serviceFn
    ;
serviceFn
    : "service(" serviceConj ")"
    ;
serviceConj
    : serviceFilter {" AND " serviceFilter}
    ;
serviceFilter
    : handshakeStateFilter
    | typeFilter
    ;
handshakeStateFilter
    : "handshakeState = " value
    ;
typeFilter
    : "type = " value
    ;
comparator
    : " = " | " != "
    ;