Skip to main content

Easy query generation for the FTrack API.

Project description


FTrack Query is an object-orientated wrapper over the FTrack API. While the default query syntax is powerful, it is entirely text based so dynamic queries can be difficult to construct. This module supports and/or operators with nested comparisons.

It is recommended to first read for a basic understanding of how the FTrack API works.


pip install ftrack_query


Original Syntax

This will build queries attached to the current session, which allows them to be executed directly.

from ftrack_query import FTrackQuery, entity, or_

with FTrackQuery() as session:
    # Create
    note = session.Note.create(
        content='My new note',
        category=session.NoteLabel.where(entity.color!=None, name='Internal').one(),

    # Query
    task = session.Task.where('Lighting', 'Rendering'),
            entity.parent == session.Episode.first(),
            entity.parent == None,
        name='My Task',
        'name', '', '',


Statement Syntax

In version 1.7, new statement functions were added, to allow queries to be built without an associated session object.

These require a session.execute call in order to work, but the underlying logic is the same as with the original syntax.

from ftrack_query import FTrackQuery, select, create, update, delete

with FTrackQuery() as session:
    # Query
    stmt = (
        select('', '', '')
        .where('Lighting', 'Rendering'))
    task = session.execute(stmt).first()
    print(f'Task found: {task})

    # Create
    stmt = (
        .values(name='My Task', parent=task)
    task = session.execute(stmt)
    print(f'Task created: {task}')

    # Update
    stmt = (
        .where(name='Old Task Name')
        .values(name='New Task Name')
    rows = session.execute(stmt)
    print(f'Tasks updated: {rows}')

    # Delete
    stmt = (
        .where(name='Old Task Name')
    rows = session.execute(stmt)
    print(f'Tasks deleted: {rows}')

Event Syntax

The event system uses a slightly different query language, this has been added for convenience but generally should not be needed.

from ftrack_query import FTrackQuery, event

with FTrackQuery() as session:
   != getuser(),



Main class inherited from ftrack_api.Session.


Every available entity type is an attribute of a session. What was originally session.query('Note') is now session.Note. This results in the Query object, which is used for constructing and executing queries.

.where(*args, **kwargs)

Filter the result.

Using kwargs is the recommended way, with a syntax like .where(first_name='Peter', last_name='Hunt').

Using args is required for complex queries. This uses the Comparison object, which is automatically created when comparing multiple Query objects. An example would be .where(entity.project.metadata.any(entity.key!='disabled')).

.populate(*args) | .select(*args)

Pre-fetch entity attributes.

An an example, in order to iterate through the name of every user, it would be a good idea to prefetch first_name and last_name, as otherwise two queries will be performed for each individual user.


Sort the results by an attribute.

The attribute and order can be given in the format, or as a raw string such as name descending.


Reverse the sorting direction.


Limit the amount of results to a certain value.


In the case of using a limit, this applies an offset to the result that is returned.

.in_(subquery) | .not_in(subquery)

Perform a check to check if an attribute matches any results.

This can accept a subquery such .in_('select id from table where x is y'), or a list of items like .in_('x', 'y').


If an entity has a primary key, by calling the value of that primary key, the entity or None will be returned. Currently only User supports this.


The Comparison object is designed to convert data to a string. It contains a wide array of operators that can be used against any data type, including other Comparison objects.

Any comparison can be reversed with the ~ prefix or the not_ function.

  • String Comparison: entity.attr=='value'
  • Number comparison: entity.attr>5
  • Pattern Comparison:'value%')
  • Time Comparison: entity.attr.after('day'))
  • Scalar Relationship: entity.attr.has(subattr='value')
  • Collection Relationship: entity.attr.any(subattr='value')
  • Subquery Relationship: entity.attr.in_(subquery)

and_(*args, **kwargs) | or_(*args, **kwargs)

Join multiple comparisons. and_ is used by default if nothing is provided.


The statement functions build upon the Query object, but are not attached to any session. Instead of session.Note, it becomes select('Note').


A select statement has access to the Query methods such as .where().

If multiple arguments are given, it will use these in place of .populate() (eg. select('', Task.parent') is the same as select('Task').populate('name', 'parent')).

Calling session.execute(stmt) will execute the query and return FTrack's own QueryResult object, from which .one(), .first() or .all() may be called.


A create statement has a .values() method used to input the data.

Calling session.execute(stmt) will return the created entity.


An update statement has access to all of the Query methods, but also has a .values() method used to input the new data.

Calling session.execute(stmt) will return how many entities were found and updated.


A delete statement has access to most of the Query methods.

Calling session.execute(stmt) will return how many entities were deleted.

A convenience method, .clean_components(), can be used when deleting a Component. Enabling this will remove the component from every location before it is deleted.

Equivalent examples from the API reference:

# Project

# Project where status is active

# Project where status is active and name like "%thrones"
select('Project').where('%thrones'), status='active')

# session.query('Project where status is active and (name like "%thrones" or full_name like "%thrones")')
select('Project').where(or_('%thrones'),'%thrones')), status='active')

# session.query('Task where is "{0}"'.format(project['id']))

# session.query('Task where is "{0}" and is "Done"'.format(project['id']))
select('Task').where( == 'Done', project=project)

# session.query('Task where timelogs.start >= "{0}"'.format('day')))
select('Task').where(entity.timelogs.start >='day'))

# session.query('Note where author has (first_name is "Jane" and last_name is "Doe")')
select('Note').where('Jane', last_name='Doe'))

# session.query('User where not timelogs any ()')

# projects = session.query('select full_name, from Project')
select('Project.full_name', '')
# or
select('Project').populate('full_name', '')

# select name from Project where allocations.resource[Group].memberships any (user.username is "john_doe")
select('Project').select('name').where(entity.allocations.resource['Group'].memberships.any(entity.user.username == 'john_doe'))

# Note where parent_id is "{version_id}" or parent_id in (select id from ReviewSessionObject where version_id is "{version_id}")
select('Note').where(or_(entity.parent_id.in_(select('').where(version_id=version_id)), parent_id=version_id))

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ftrack-query-1.7.0.tar.gz (18.9 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page