Grouping Functions: Difference between revisions

From wiki.jriver.com
Jump to navigation Jump to search
No edit summary
 
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{incomplete}}
{{function type page}}
{{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.
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 used 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).
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]]


=== <span id="GroupCount">GroupCount(&hellip;)</span> ===
=== <span id="GroupCount">GroupCount(&hellip;)</span> ===
Line 24: Line 25:


=== <span id="GroupCountQuery">GroupCountQuery(&hellip;)</span> ===
=== <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.
: Counts the number of items in a specified group


{{function description box
{{function description box
Line 37: Line 38:
: * 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 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.
: * 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 Album Artist /(Auto/) not Album Artist (Auto)
: * 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=
| examples=
Line 66: Line 67:


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


{{function description box
{{function description box
Line 81: Line 82:
{{argument table row|1|Supresses 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=
| examples=
'''{{monospace|GroupSummaryQuery()}}'''
'''{{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.
: '''Coming Soon...'''


'''{{monospace|GroupSummaryQuery()}}'''
'''{{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.
: '''Coming Soon...'''
}}
}}

Latest revision as of 11:25, 19 July 2020

The expression language is largely used to evaluate one file at a time. The grammar implies that something like 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 File Info Panel

GroupCount(…)

Counts the members of a specified group (in a category or field).
Description GroupCount(field)
  • Argument field is optional (defaults to current grouping).

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

Examples Example Threads:
(Back to top)   (Function index)

GroupCountQuery(…)

Globally counts the number of different Field 2 entries for files that share Field 1 with the current file.
Description GroupCountQuery(field 1, Field 2)
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.

Notes:

* 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 Album Artist /(Auto/) not Album Artist (Auto)
Examples [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, Cris Rea (10 Albums)
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.

GroupCountQuery(album artist /(auto/);Camera, album)

This expression will return the number of albums by each artist, per camera used to take the pictures.
(Back to top)   (Function index)

GroupSummary(…)

Summarises the members of a specified group (in a category or field).
Description GroupSummary(field)
  • Argument field is optional (defaults to 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:
Matt introduces Grouping Functions
Use field names, not field values (square bracket notation)
(Back to top)   (Function index)


GroupSummaryQuery(…)

Globally summarises the Field entries for files that share a Match with the current file.
Description GroupSummaryQuery(Match, Field, Mode)
  • Argument mode is optional (defaults to 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.

Available mode values:

0Default. Outputs labels such as Avg or Total
1Supresses labels such as Avg or Total

Notes:

* 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 Album Artist /(Auto/) not Album Artist (Auto)
Examples GroupSummaryQuery(Album, Duration)
Returns the total duration of the album this file is a part of. This differs from 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.

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 Album Rating: 3.6 out of 5
Note the use of mode 1 here to supress output of the "avg" abbrevbiation.
(Back to top)   (Function index)