Filtering using API like queries

To use the filter with API like syntax:

  1. Go to your project. (In our example, we use the filter in Tasks Spreadsheet)
  2. Open the Add filter drop-down menu.
  3. Choose what you want to filter on, for instance, Task.
  4. Click Query, opening the Query (Task) filter window.


Image: Example of how to open the API query filter in the Tasks Spreadsheet.


The query syntax is identical to the filter part of the query. So anything after the where keyword can be used:

select id from Task where .

Let us now have a look at a few examples of what can be done in the Tasks Spreadsheet  > Add filter > Task > Query.

  • Let us start with something easy and find all Tasks named Animation:
name is Animation
  • Here, we use a relation to filter out all Tasks that have a status that is Approved: is Approved

Now let us try finding all Shots that have notes from our colleague John.

Use Add filter > Shot > Query to add the query field for Shot:

notes any (author.first_name is John)

If we use the query filter in the Versions page  Add filter > Version > Query, we can find Versions that have some metadata attached to them:

metadata any (key is foo and value is bar)
  • Or Versions that have components in our custom Location named is ""

Any issues with syntax, usage of relations, or attributes in the Query will be presented as feedback below the query input field.

Please note: (Only necessary if you are on ftrack Studio 4.4 and below) In Configuring Advanced Settings, it is possible to enable advanced filter query to get access to API like filters in the Versions / Tasks Spreadsheet and the Latest versions widget.


Take care when filtering based on relations. There are currently no restrictions on what relations are available, and certain queries on nested data might cause performance problems.

Using variables

Filters also support a set of predefined variables for dynamic usage:

CURRENT_USER_ID - User id of the current user.
CURRENT_USERNAME - Username of the current user.
LAST_MONTH - First date of last month.
LAST_WEEK - First date of last week.
THIS_MONTH - First date of this month.
THIS_WEEK - First date of this week. The first day of this week can be set to either Monday or Sunday. You can adjust this setting by navigating to System Settings > Scheduling > Settings > First day of the week.
NEXT_MONTH - First date of next month.
NEXT_WEEK - First date of next week.
YESTERDAY - Yesterday's date.
TOMORROW - Tomorrow’s date.
TODAY - Today’s date.
NOW - Date and time right now.
DAYS(N) - Date relative to today. N can be a positive or negative integer. E.g. DAYS(14) or DAYS(-14)


Example of how to filter out all tasks that has notes added this week:  "{THIS_WEEK}" and notes.user_id != "{CURRENT_USER_ID}"

Please note: A variable must be inside quotation marks, see the example above. If a variable is misspelled or does not exist, it will be silently ignored.

  • Known limitations: The date comparison will be in UTC, which can cause confusion. This limitation applies if timezone support is enabled (enabled on all hosted instances).

Tip: For more complex examples, check the Query Examples article.



Was this article helpful?
0 out of 0 found this helpful

Articles in this section