API summary method

---

The summarize() method was added to the Python API after v3.0.7 and is available as a beta feature in the summary grouping branch. It requires Shotgun server version v2.4.0+.

Please submit any bugs directly to Shotgun support, or if you are on the shotgun-dev list, you can send any feedback or comments through there.

summarize()

Description

dict summarize(string entity_type, list filters, list summary_fields, string filter_operator, list grouping)

Summarize and optionally group entities based on the given filter and grouping values

Parameters

• string entity_type (required)
  The entity type to summarize on (in CamelCase format). Example: TimeLog.
• list filters (required)
  An array of array conditions used to filter the summarize query. You can find the reference for filter values here.
  • Each condition should be in the format [ column_name, operator, value1(, value2) ] defined as the following:
  • column_name (string): The system name of the column (not the display name) Examples: “code”, “sg_asset_type”.
  • operator (string): the operator as it appears in the query builder. Examples: “is”, “is_not”, "between", “in_last”.
  • value (mixed): The value to compare the column on.
  • value2 (optional for some operators) (int): The second value for column comparison. This value is specified for operators such as ”between”.
• list summary_fields (required) A list of dictionaries defining the field names to summarize, the summary type, and if required, the summary value
  • string field: The internal field name to summarize
  • string type: The type of summary to perform on the field
  • string value: If the summary type requires an assocated value, provide this here, otherwise it is ignored.
• string filter_operator (default="all")
  Controls how the filters are matched. There are only two valid options: all and any. You cannot currently combine the two options in the same query.
• list grouping (default=None)
  A list of dictionaries defining how to group the returned summaries. Each grouping dict requires the three key values below. You may specify multiple groupings which are performed in the order specified. Summaries will be calculated for each individual group level as well as the parent group and is meant to mimic the same behavior given in the Shotgun UI when you have column summaries turned on.
  • string field: The internal field name to group by
  • string direction (default="asc"): Sorting direction for the returned groups. Valid options are "asc" and "desc".
  • string type: Type of grouping to perform on this field.

Returns

• dict object containing a 'groups' and 'summaries' key. If a grouping value was provided, the results will be nested in the same pattern within the value of the 'groups' key.
  • list groups: Dictionary of group values and their summary values
    • string group_name: Display name of the group
    • string group_value: Internal value of the group. This is often the same as the group_name but not always. For example, in cases where the field you are grouping on is an entity field, the group_value will contain the Shotgun entity hash where the group_name will simply contain the name of the entity. The group_value can be easily used in subsequent Shotgun queries.
    • dict summaries: key value pairs of each summary field name and its corresponding summary value
    • list groups: Dictionary of group values and their summary values
  • dict summaries: key value pairs of each summary field name and its corresponding summary value

Usage Example

# ----------------------------------------------
# Summarize all Time Logs for Shot 100_0010
# return the total duration and number of Time Logs
# group the results by Pipeline Step
# (remember duration values are returned as minutes)
# ----------------------------------------------
    filters = [
        ['project', 'is', {'type':'Project', 'id':65}],
        ['entity.Task.entity', 'is', {'type':'Shot', 'id':860}],
        ]
    summaries = [
        { "field": "duration", "type": "sum"},
        { "field": "id", "type": "count"},
        ]
    grouping = [ { "field": "entity.Task.step", "direction": "asc", "type": "exact" } ]

    result = sg.summarize(
                entity_type="TimeLog",
                filters=filters,
                summary_fields=summaries,
                filter_operator="all",
                grouping=grouping
                )
    

example output:

{'groups': [{'group_name': 'Anm',
             'group_value': {'id': 5,
                             'name': 'Anm',
                             'type': 'Step',
                             'valid': 'valid'},
             'summaries': {'duration': 1800, 'id': 1}},
            {'group_name': 'Comp',
             'group_value': {'id': 8,
                             'name': 'Comp',
                             'type': 'Step',
                             'valid': 'valid'},
             'summaries': {'duration': 840, 'id': 2}},
            {'group_name': 'FX',
             'group_value': {'id': 6,
                             'name': 'FX',
                             'type': 'Step',
                             'valid': 'valid'},
             'summaries': {'duration': 2880, 'id': 4}},
            {'group_name': 'Layout',
             'group_value': {'id': 13,
                             'name': 'Layout',
                             'type': 'Step',
                             'valid': 'valid'},
             'summaries': {'duration': 1980, 'id': 3}},
            {'group_name': 'Light',
             'group_value': {'id': 7,
                             'name': 'Light',
                             'type': 'Step',
                             'valid': 'valid'},
             'summaries': {'duration': 3480, 'id': 5}}],
 'summaries': {'duration': 10980, 'id': 15}}

Valid summary operators by field data type

date | datetime
count, record_count, earliest, latest

number | timecode
count, record_count, sum, minimum, maximum, average

status list
status, status_percentage (requires value key in the summary_fields dict)

checkbox
record_count, checked, unchecked

text
count, record_count

list
count, record_count, percentage (requires value key in the summary_fields dict)

duration
count, record_count, sum, minimum, maximum, average

entity | multi-entity
count, record_count

Valid grouping options by field data type

date | datetime
exact, day, week, month, year

number | timecode
exact, tens, hundreds, thousands, tensofthousands, hundredsofthousands, millions

status list | checkbox
exact

text | list
exact, firstletter

duration
exact, oneday, fivedays

entity | multi-entity
exact, entitytype, firstletter