-
Notifications
You must be signed in to change notification settings - Fork 200
Reference: Filter Syntax
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 step.list_order value. |