View source for Grouping Functions

{{function type page}}

The [[expression language]] is largely used to evaluate one file at a time.  The grammar implies that something like {{monospace|Field(Artist)}} should get the Artist value for the current file being evaluated. Grouping Functions are a special class of functions that operate on a group of files, instead of on individual files.  A simple example would be a function to count the number of artists in the current group.

Grouping Functions may only be useful in relevant areas where Media Center displays groups of files (most notably in Categories and the Tag Action Window), and not to individual file listings, such as an expression column in a File Details View, where they can be used, but will not be all that useful.

The [[GroupCountQuery()]] and [[GroupSummaryQuery()]] functions detailed below are special functions that work '''globally''', returning results from the '''''entire'' library''', regardless of Media Type, or any other filters currently in action. This makes them especially useful for presenting information in Theater View, where typically, 1 file is represented, pertaining to given fields shared with this single file, such as number of tracks in an album, or total duration of the album this track is a part of. For use in Theater View, these would be entered by editing the Theater View [[TV_Episodes#Tweaks_to_Theater_View File Info Panel|File Info Panel]]

=== <span id="GroupCount">GroupCount(&hellip;)</span> ===
: Counts the members of a specified group (in a category or field). 

{{function description box
| name=GroupCount
| arguments=field
| description=
{{argument optional|field|current grouping}}

GroupCount() can be used to count the members of a group of files.

| examples=
'''Example Threads:'''
* [http://yabb.jriver.com/interact/index.php?topic=81766.msg564453#msg564453 Matt introduces Grouping Functions]
* [http://yabb.jriver.com/interact/index.php?topic=94848.msg663421#msg663421 Use field names, not field values (square bracket notation)]
}}

=== <span id="GroupCountQuery">GroupCountQuery(&hellip;)</span> ===
: Globally counts the number of different {{monospace|Field 2}} entries for files that share {{monospace|Field 1}} with the current file.

{{function description box
| name=GroupCountQuery
| arguments=field 1, Field 2
| description=
: '''''Field 1''''' is the name of the field to group by. More than one field can be specified, use a semi colon to separate field names.
: '''''Field 2''''' is the name of the field to count.

<u>'''Notes:'''</u><br>
: * GroupCountQuery is special because it returns counts from the entire library, not just the currently filtered subset.
: * GroupCountQuery can only do what it does by using a cache of the library data. The cache is rebuilt every 60 seconds, so, when testing these, changes may not be immediately noticeable.
: * GroupCountQuery uses field names only, the usual square brackets should not be used.
: * Special characters are required to be escaped, otherwise, they will break the expression. For example, use {{monospace|Album Artist /(Auto/)}} not {{monospace|Album Artist (Auto)}}

| examples=
'''{{monospace|[album artist (auto), 1] (GroupCountQuery(album artist /(auto/), album) albums)}}'''
: When used in the "Expression to display" field of a view pane or theater view category, returns, for example, where [Album Artist (Auto)] is Chris Rea, {{monospace|Cris Rea (10 Albums)}}<br>
: Remember, if there are 10 Chris Rea albums in the library, but due to other filters, only five are displayed,  the expression will still report 10 albums as it works on the entire library.

'''{{monospace|GroupCountQuery(album artist /(auto/);Camera, album)}}'''
: This expression will return the number of albums by each artist, per camera used to take the pictures.
}}

=== <span id="GroupSummary">GroupSummary(&hellip;)</span> ===
: Summarises the members of a specified group (in a category or field). 

{{function description box
| name=GroupSummary
| arguments=field
| description=
{{argument optional|field|current grouping}}

Smartly summarizes the members of a specified group (mode, mean, min, max, etc as is most logical for that grouping).
| examples=
'''Example Threads:'''
: [http://yabb.jriver.com/interact/index.php?topic=81766.msg564453#msg564453 Matt introduces Grouping Functions]
: [http://yabb.jriver.com/interact/index.php?topic=94848.msg663421#msg663421 Use field names, not field values (square bracket notation)]
}}


=== <span id="GroupSummaryQuery">GroupSummaryQuery(&hellip;)</span> ===
: Globally summarises the {{monospace|Field}} entries for files that share a {{monospace|Match}} with the current file.

{{function description box
| name=GroupSummaryQuery
| arguments=Match, Field, Mode
| description=
{{argument optional|mode|0}}
: '''''Match''''' is the name of the field to match. More than one field can be specified, use a semi colon to separate field names.
: '''''Field''''' is the name of the field to summarise.
{{argument table
| name=mode
| contents=
{{argument table row|0|Default. Outputs labels such as Avg or Total}}
{{argument table row|1|Supresses labels  such as Avg or Total}}
}}

<u>'''Notes:'''</u><br>
: * GroupSummaryQuery is special because it summarises matches from the entire library, not just the currently filtered subset.
: * GroupSummaryQuery can only do what it does by using a cache of the library data. The cache is rebuilt every 60 seconds, so, when testing these, changes may not be immediately noticeable.
: * GroupSummaryQuery uses field names only, the usual square brackets should not be used.
: * Special characters are required to be escaped, otherwise, they will break the expression. For example, use {{monospace|Album Artist /(Auto/)}} not {{monospace|Album Artist (Auto)}}

| examples=
'''{{monospace|GroupSummaryQuery(Album, Duration)}}'''
: Returns the total duration of the album this file is a part of. This differs from [[GroupSummary()|GroupSummary]] by returning the total duration of the album from a single file. GroupSummary would only return the duration of the single file currently being viewed.

'''{{monospace|Album Rating: GroupSummaryQuery(Album,Rating,1) out of 5}}'''
: From a single file, this would retrieve the average [Rating] field for the entire album, and output {{monospace|Album Rating: 3.6 out of 5}}<br>Note the use of mode 1 here to supress output of the "avg" abbrevbiation.
}}