TimeZest Query Language (TQL)

The TimeZest Query Language (TQL) is a flexible and powerful way to filter the results which are returned from the TimeZest API.

You could use TQL to ask TimeZest for all scheduling requests sent to a particular email domain:

TQL Example

scheduling_requests.end_user_email LIKE @example.com

Or obtain a list of all agents in your system who don't have 2-factor authentication enabled:

TQL Example

agents.two_factor_enabled EQ false

Or retrieve a list of all scheduling requests where the end user has selected an appointment in a particular date range:

TQL Example

scheduling_requests.selected_start_time GTE 2023-07-01 AND scheduling_requests.selected_start_time LTE 2023-08-01

To use TQL as part of an API request, simply pass the TQL as the filter parameter:

Request

  curl https://api.timezest.com/v1/agents?filter=agent.name~LIKE~john \
  -H "Authorization: Bearer <Your API Token>"

Predicates

TQL is formed of predicates, which are always formed of three parts:

  • The attribute, which specifies the attribute that TimeZest should use to filter records. In the first example above, the attribute is scheduling_requests.end_user_email.
  • The operator, which specifies how the attribute is to be compared to the value in the predicate to determine if a particular record is to be filtered in to the result set. In the first example above, the operator is LIKE.
  • The value, which is the value to which the record is to be compared to. In the example above, the value is @example.com.

Each of these three parts are required exactly once in a valid predicate, and they need to be separated by one or more space characters, or the tilde ~ character.

Attributes

The attribute part of a TQL predicate specifies which property on the record TimeZest should consider when filtering records.

Attributes are always in the form of object.property to allow for TimeZest to distinguish between attributes like name which can be otherwise ambiguous.

The available attributes for filtering the results for a particular endpoint are specified in the documentation of the endpoint. For performance reasons, not all attributes are available to be filtered on. Each attribute also has a type, which determines which operators and values are valid to be used with it.

Operators

TimeZest supports the following operators:

OperatorsDescriptionCompatibility
EQ — equals value
NOT_EQ — does not equal value		Equality comparisons to compare if a value is exactly equal to the value in the record.Valid for string, timestamp and number attributes.
GT — greater than value
GTE — greater than or equals value
LT — less than value
LTE — less than or equals value		Inequality comparisons between the value and the value in the record.Valid for timestamp and number attributes.
LIKE — contains value
NOT_LIKE — does not contain value		These operators can be used to determine if the text in the record contains or doesn't contain the value as a substring.

This operator is not case sensitive.		Valid for string attributes.
IN — array contains value
NOT_IN — array does not contain value		These operators select records which have the exact value of one of the values in the value array. They can be thought of as an EQ combined with an OR operator.Valid for string, timestamp and number attributes.

Values

Each operator can compare the attribute on a record to a value to decide if a particular record belongs to the set of filtered results. TimeZest supports the following values:

Value TypeDescriptionExamples
StringA string of characters. TimeZest will interpret any value which it cannot recognize as another type of value as a string
Strings do not need to be quoted unless they contain the ", ,, ~ or space characters.		John, "[email protected]"
NumberA number, with or without a fractional part.100, 23.25
TimestampA specific point in time. This can be expressed as a Unix timestamp (e.g. 1692172402) or an RFC3666 time (e.g. 2023-08-01T09:00:00Z) or a RFC3666 date (e.g. 2023-08-01).
A RFC3666 date will be interpreted as being the time at 00:00 UTC on that date.		1692172402,
2023-08-01T09:00:00Z, 2023-08-01
String ArrayAn array of one or more strings, separated by commas (but not spaces). Where a string in an array contains a comma or a space, it will need to be quoted.john,"john smith"

TimeZest can perform some conversions between values automatically - for example, agent.email LIKE 123 will work, and be interpreted as "agent.email contains the string '123'".