-
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.