AF SDK Reference

AFSearch.BinnedSummaryAsync(TBin) Method

Save PDF

TABLE OF CONTENTS

AFSearch.BinnedSummaryAsync(TBin) Method

Save PDF

Last UpdatedNov 18, 2025
4 minute read

Generates a summary broken down by the specified bins for items matching the search criteria asynchronously.

Namespace: OSIsoft.AF.Search
Assembly: OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 3.1.1.1182

Syntax

public Task<AFBinnedResult<TBin>> BinnedSummaryAsync<TBin>(
	string field,
	IEnumerable<TBin> bins,
	UOM binUOM,
	string summaryField,
	AFSummaryTypes summaryTypes,
	CancellationToken cancellationToken
)
where TBin : Object, IComparable<TBin>

Public Function BinnedSummaryAsync(Of TBin As {Object, IComparable(Of TBin)}) ( 
	field As String,
	bins As IEnumerable(Of TBin),
	binUOM As UOM,
	summaryField As String,
	summaryTypes As AFSummaryTypes,
	cancellationToken As CancellationToken
) As Task(Of AFBinnedResult(Of TBin))

Dim instance As AFSearch
Dim field As String
Dim bins As IEnumerable(Of TBin)
Dim binUOM As UOM
Dim summaryField As String
Dim summaryTypes As AFSummaryTypes
Dim cancellationToken As CancellationToken
Dim returnValue As Task(Of AFBinnedResult(Of TBin))

returnValue = instance.BinnedSummaryAsync(field, 
	bins, binUOM, summaryField, summaryTypes, 
	cancellationToken)

public:
generic<typename TBin>
where TBin : Object, IComparable<TBin>
Task<AFBinnedResult<TBin>^>^ BinnedSummaryAsync(
	String^ field, 
	IEnumerable<TBin>^ bins, 
	UOM^ binUOM, 
	String^ summaryField, 
	AFSummaryTypes summaryTypes, 
	CancellationToken cancellationToken
)

member BinnedSummaryAsync : 
        field : string * 
        bins : IEnumerable<'TBin> * 
        binUOM : UOM * 
        summaryField : string * 
        summaryTypes : AFSummaryTypes * 
        cancellationToken : CancellationToken -> Task<AFBinnedResult<'TBin>>  when 'TBin : Object and IComparable<'TBin>

Parameters

field: Type: SystemString
The field whose value should be binned.
bins: Type: System.Collections.GenericIEnumerableTBin
The bins the field should be sorted into.
binUOM: Type: OSIsoft.AF.UnitsOfMeasureUOM
The unit of measure associated with bin values.
summaryField: Type: SystemString
The field that should be summarized for each group.
summaryTypes: Type: OSIsoft.AF.DataAFSummaryTypes
The types of summaries to perform for each group.
cancellationToken: Type: System.ThreadingCancellationToken
A token to control cancellation of the aggregation request.

Type Parameters

TBin: The type of bins the summary is broken into.

Return Value

Type: TaskAFBinnedResultTBin
A result containing the requested summaries broken down by bin or an error if the summaries could not be performed.

Remarks

Notes to Callers
This call might use a background task to complete some of its work. See the Threading Overview for some matters to consider when execution transitions to another thread.

Examples

// Get the Database
PISystems myPISystems = new PISystems();
PISystem myPISystem = myPISystems.DefaultPISystem;
if (myPISystem == null)
    throw new InvalidOperationException("Default PISystem was not found.");
AFDatabase myDB = myPISystem.Databases[dbName];
if (myDB == null)
    throw new InvalidOperationException("Database was not found.");

// Create a search to find all the event frames created from the 'Event'
// template in the last year.
using (AFEventFrameSearch eventSearch = new AFEventFrameSearch(myDB, "EventFrameSearch", @"Template:'Event' Start:>'t-1y'"))
{
    eventSearch.CacheTimeout = TimeSpan.FromMinutes(10);
    // Get the average duration binned by start month
    AFBinnedResult<AFTime> binnedSummary = await eventSearch.BinnedSummaryAsync("StartTime",
        new AFTimeSpan(months: 1).GetIntervalTimes(new AFTimeRange("1-1y", "1+1mo")), binUOM: null,
        summaryField: "Duration", summaryTypes: AFSummaryTypes.Average, cancellationToken: CancellationToken.None);
    foreach (var bin in binnedSummary.BinnedResults)
    {
        Console.WriteLine("Month: {0}, Average: {1}",
            bin.Key, bin.Value[AFSummaryTypes.Average]);
    }
}

' Get the Database
Dim myPISystems As New PISystems()
Dim myPISystem As PISystem = myPISystems.DefaultPISystem
If myPISystem Is Nothing Then
    Throw New InvalidOperationException("Default PISystem was not found.")
End If
Dim myDB As AFDatabase = myPISystem.Databases(dbName)
If myDB Is Nothing Then
    Throw New InvalidOperationException("Database was not found.")
End If

' Create a search to find all the event frames created from the 'Event'
' template in the last year.
Using eventSearch As New AFEventFrameSearch(myDB, "EventFrameSearch", "Template:'Event' Start:>'t-1y'")
    eventSearch.CacheTimeout = TimeSpan.FromMinutes(10)


    ' Get the average duration binned by start month
    Dim binnedSummary As AFBinnedResult(Of AFTime) = Await eventSearch.BinnedSummaryAsync("StartTime", New AFTimeSpan(months:=1).GetIntervalTimes(New AFTimeRange("1-1y", "1+1mo")), binUOM:=Nothing, summaryField:="Duration", summaryTypes:=AFSummaryTypes.Average, cancellationToken:=CancellationToken.None)
    For Each bin As KeyValuePair(Of AFRange(Of AFTime), IReadOnlyDictionary(Of AFSummaryTypes, AFValue)) In binnedSummary.BinnedResults
        Console.WriteLine("Month: {0}, Average: {1}", bin.Key, bin.Value(AFSummaryTypes.Average))
    Next

    Return True
End Using

No code example is currently available or this language may not be supported.

Version Information

AFSDK

Supported in: 3.1.1, 3.1.0, 3.0.2, 3.0.1, 3.0.0, 2.10.11, 2.10.5, 2.10.0, 2.10, 2.9.5, 2.9

AF SDK Reference