Optimization: Combining Related Queries

Reducing round-trips for data via the API can significantly improve the speed of your application.

Much like "Bubble Fields" / "Field Hopping" in the UI, we can poll Shotgun for data on the fields of entities linked to our main query, both as a part of the query parameters as well as in the data returned.

Starting with a simple and common example, many queries require knowing what project your data is associated with. Without using "field hopping" in an API call, you would first get the project and then use that data for your follow up query, like so:

# Get the project
projectName = 'Big Buck Bunny'
sgProject = sg.find("Project", [['name','is',projectName]])

# Use project result to get associated shots
sgShots = sg.find("Shot", [['project','is',sgProject]], ['code'])

With "field hopping" you can combine these queries into:

# Get all shots on 'Big Buck Bunny' project
projectName = 'Big Buck Bunny'
sgShots = sg.find("Shot", [['project.Project.name','is',projectName]], ['code'])

As you can see above, the syntax is to use "." dot notation, joining field names to entity types in a chain. In this example we start with the field "project" on the Shot entity, then specify we're looking for the "name" field on the Project entity by specifying "Project.name".

Now that we've demonstrated querying using dot notation, let's take a look at returning linked data by adding the status of each Sequence entity associted with each Shot in our previous query:

# Get shot codes and sequence status all in one query
projectName = 'Big Buck Bunny'
sgShots = sg.find("Shot", [['project.Project.name','is',projectName]],
                          ['code','sg_sequence.Sequence.sg_status_list'])