-
Notifications
You must be signed in to change notification settings - Fork 200
Reference: Filter Syntax
Stephane Daigle edited this page Aug 23, 2016
·
27 revisions
Filters are represented as a list of conditions that will be combined using the supplied filter_operator (any or all). Each condition can be either in the simple form:
[ <field>, <relation>, <value(s)> ]
... or in API 3.0.11+, it can be a dictionary that represents a complex sub-condition of the form:
{ "filter_operator": "any", "filters": [ <list of conditions> ] }
Using the default filter_operator "all", the following filters will return all Shots whose status is "ip" AND is linked to either Asset #9 OR Asset #23.
filters = [
["sg_status_list", "is", "ip"],
{
"filter_operator": "any",
"filters": [
[ "assets", "is", { "type": "Asset", "id": 9 } ],
[ "assets", "is", { "type": "Asset", "id": 23 } ]
]
}
]
result = sg.find("Shot", filters)Operator Arguments
-------- ---------
'is' [field_value] | None
'is_not' [field_value] | None
'less_than' [field_value] | None
'greater_than' [field_value] | None
'contains' [field_value] | None
'not_contains' [field_value] | None
'starts_with' [string]
'ends_with' [string]
'between' [[field_value] | None, [field_value] | None]
'not_between' [[field_value] | None, [field_value] | None]
'in_last' [[int], 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR']
# note that brackets are not literal (eg. ['start_date', 'in_last', 1, 'DAY'])
'in_next' [[int], 'HOUR' | 'DAY' | 'WEEK' | 'MONTH' | 'YEAR']
# note that brackets are not literal (eg. ['start_date', 'in_next', 1, 'DAY'])
'in' [[field_value] | None, ...] # Array of field values
'type_is' [string] | None # Shotgun entity type
'type_is_not' [string] | None # Shotgun entity type
'in_calendar_day' [int] # Offset (e.g. 0 = today, 1 = tomorrow,
# -1 = yesterday)
'in_calendar_week' [int] # Offset (e.g. 0 = this week, 1 = next week,
# -1 = last week)
'in_calendar_month' [int] # Offset (e.g. 0 = this month, 1 = next month,
# -1 = last month)
'name_contains' [string]
'name_not_contains' [string]
'name_starts_with' [string]
'name_ends_with' [string]
addressing 'is'
'is_not'
'contains'
'not_contains'
'in'
'type_is'
'type_is_not'
'name_contains'
'name_not_contains'
'name_starts_with'
'name_ends_with'
checkbox 'is'
'is_not'
currency 'is'
'is_not'
'less_than'
'greater_than'
'between'
'not_between'
'in'
'not_in'
date 'is'
'is_not'
'greater_than'
'less_than'
'in_last'
'not_in_last'
'in_next'
'not_in_next'
'in_calendar_day'
'in_calendar_week'
'in_calendar_month'
'in_calendar_year'
'between'
'in'
'not_in'
date_time 'is'
'is_not'
'greater_than'
'less_than'
'in_last'
'not_in_last'
'in_next'
'not_in_next'
'in_calendar_day'
'in_calendar_week'
'in_calendar_month'
'in_calendar_year'
'between'
'in'
'not_in'
duration 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
entity 'is'
'is_not'
'type_is'
'type_is_not'
'name_contains'
'name_not_contains'
'name_is'
'in'
'not_in'
float 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
image 'is' ** Note: For both 'is' and 'is_not', the only supported value is None,
'is_not' ** which supports detecting the presence or lack of a thumbnail.
list 'is'
'is_not'
'in'
'not_in'
multi_entity 'is' ** Note: when used on multi_entity, this functions as
you would expect 'contains' to function
'is_not'
'type_is'
'type_is_not'
'name_contains'
'name_not_contains'
'in'
'not_in'
number 'is'
'is_not'
'less_than'
'greater_than'
'between'
'not_between'
'in'
'not_in'
password ** Filtering by this data type field not supported
percent 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
serializable ** Filtering by this data type field not supported
status_list 'is'
'is_not'
'in'
'not_in'
summary ** Filtering by this data type field not supported
tag_list 'is' ** Note: when used on tag_list, this functions as
you would expect 'contains' to function
'is_not'
'name_contains'
'name_not_contains'
'name_id'
text 'is'
'is_not'
'contains'
'not_contains'
'starts_with'
'ends_with'
'in'
'not_in'
timecode 'is'
'is_not'
'greater_than'
'less_than'
'between'
'in'
'not_in'
url ** Filtering by this data type field is not supported
As of Shotgun version 7.0 it is possible to also use filter presets. These presets provide a simple way to specify powerful query filters that would otherwise be costly and difficult to craft using traditional filters.
Multiple presets can be specified in cases where it makes sense.
Also, these presets can be used alongside normal filters. The result returned is an AND operation between the specified filters.
The following query will return the Version with the name 'ABC' that is linked to the latest entity created.
additional_filter_presets = [
{
"preset_name": "LATEST",
"latest_by": "ENTITIES_CREATED_AT"
}
]
filters = [['code', 'is', 'ABC']]
result = sg.find('Version', filters = filters, additional_filter_presets = additional_filter_presets)The following query will find all CutItems associated to Cut #1 and return all Versions associated to the Shot linked to each of these CutItems.
additional_filter_presets = [
{
"preset_name": "CUT_SHOT_VERSIONS",
"cut_id": 1
}
]
result = sg.find('Version', additional_filter_presets = additional_filter_presets)Allowed filter presets (and preset parameter values) depend on the entity type being searched.
The table bellow gives the details about which filter preset can be used on each entity type and with which parameters.
Entity Type Preset Name Preset Parameters Allowed Preset Parameter Values
----------- ----------- ----------------- -------------------------------
Cut LATEST [string] latest_by 'REVISION_NUMBER':
Returns the cuts that have the highest revision number.
This is typically used with a query filter that returns
cuts with the same value for a given field
(e.g. code field). This preset therefore allows to get
the Cut of that set that has the highest
revision_number value.
Version CUT_SHOT_VERSIONS [int] cut_id Valid Cut entity id.
Returns all Version entities associated to the Shot
entity associated to the CutItems of the given Cut.
This basically allows to find all Versions associated
to the given Cut, via its CutItems.
LATEST [string] latest_by 'ENTITIES_CREATED_AT':
When dealing with multiple Versions associated to a
group of entities, returns only the last Version
created for each entity.
For example, when dealing with a set of Shots, this
preset allows to find the latest Version created
for each of these Shots.
'BY_PIPELINE_STEP_NUMBER_AND_ENTITIES_CREATED_AT':
When dealing with multiple versions associated to the
same entity *and* to Tasks, returns the Version
associated to the Task with highest step.list_order.
If multiple Versions are found for that step.list_order,
only the latest Version is returned.
This allows to isolate the Version entity that is the
farthest along in the pipeline for a given entity.
For example, when dealing with a Shot with multiple
versions, this preset will return the Version
associated to the Task with the highest
step.list_order value.