-
Notifications
You must be signed in to change notification settings - Fork 200
Reference: Filter Syntax
Stephane Daigle edited this page Aug 22, 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 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 latest_by 'REVISION_NUMBER':
Returns the cuts that have the highest revision number.
This is typically used with a query filter that returns
cuts that have the same value for a given field
(e.g. code field). This preset therefore allows to get
the Cut of that group that has the highest
revision_number value.
Version CUT_SHOT_VERSIONS cut_id Valid Cut entity id.
Returns all Version entities associated to the Shot
entity associated to the Cut.
LATEST 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.
'BY_PIPELINE_STEP_NUMBER_AND_ENTITIES_CREATED_AT':
When dealing with multiple versions associated to the
same entity *and* to a task, returns only the last
Version entity created and assocaited to the highest
step.list_order.
This allows to isolate the Version entity that is the
farthest along in the pipeline.