AF SDK Reference

AFListData.Summary Method

Save PDF

TABLE OF CONTENTS

AFListData.Summary Method

Save PDF

Last UpdatedNov 18, 2025
7 minute read

Returns several summaries for a list of attributes over a single time range.

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

Syntax

public IEnumerable<IDictionary<AFSummaryTypes, AFValue>> Summary(
	AFTimeRange timeRange,
	AFSummaryTypes summaryTypes,
	AFCalculationBasis calculationBasis,
	AFTimestampCalculation timeType,
	PIPagingConfiguration pagingConfig
)

Public Function Summary ( 
	timeRange As AFTimeRange,
	summaryTypes As AFSummaryTypes,
	calculationBasis As AFCalculationBasis,
	timeType As AFTimestampCalculation,
	pagingConfig As PIPagingConfiguration
) As IEnumerable(Of IDictionary(Of AFSummaryTypes, AFValue))

Dim instance As AFListData
Dim timeRange As AFTimeRange
Dim summaryTypes As AFSummaryTypes
Dim calculationBasis As AFCalculationBasis
Dim timeType As AFTimestampCalculation
Dim pagingConfig As PIPagingConfiguration
Dim returnValue As IEnumerable(Of IDictionary(Of AFSummaryTypes, AFValue))

returnValue = instance.Summary(timeRange, 
	summaryTypes, calculationBasis, 
	timeType, pagingConfig)

public:
IEnumerable<IDictionary<AFSummaryTypes, AFValue^>^>^ Summary(
	AFTimeRange timeRange, 
	AFSummaryTypes summaryTypes, 
	AFCalculationBasis calculationBasis, 
	AFTimestampCalculation timeType, 
	PIPagingConfiguration^ pagingConfig
)

member Summary : 
        timeRange : AFTimeRange * 
        summaryTypes : AFSummaryTypes * 
        calculationBasis : AFCalculationBasis * 
        timeType : AFTimestampCalculation * 
        pagingConfig : PIPagingConfiguration -> IEnumerable<IDictionary<AFSummaryTypes, AFValue>>

Parameters

timeRange: Type: OSIsoft.AF.TimeAFTimeRange
The time range over which to compute the summary.
summaryTypes: Type: OSIsoft.AF.DataAFSummaryTypes
A flag which specifies one or more summaries to compute over the time range.
calculationBasis: Type: OSIsoft.AF.DataAFCalculationBasis
Specifies the method of evaluating the data over the time range.
timeType: Type: OSIsoft.AF.DataAFTimestampCalculation
A flag indicating what how to calculate a timestamp for each interval.
pagingConfig: Type: OSIsoft.AF.PIPIPagingConfiguration
Contains the paging configuration parameters for the request.

Return Value

Type: IEnumerableIDictionaryAFSummaryTypes, AFValue

An enumerable of IDictionaryTKey, TValue for each AFAttribute in the list. The results are not guaranteed to match the order of the AFAttributeList, and duplicate attributes in the list will not produce a duplicate result. The results can be mapped back to the corresponding attribute using the Attribute property on each result.

The order of the results are predictable; however, if you need the results in the same order as the attribute list, then consider using a dictionary keyed by attribute to construct a list in the same order.

The attributes in the list are broken up by data reference. If the data reference supports bulk calls, then the bulk call is used to improve performance and reduce roundtrips to the server. PI Point attributes are then broken up a second time by their corresponding PI Data Archive. A bulk call is made against each PI Data Archive in parallel. The results are made available as they are returned from the PI Data Archive in the order that the bulk calls were made.

The following example shows a list of attributes including duplicates from three different PI Data Archives, and two table lookups:

Attribute	PI Data Archive	Data Reference
Lobby Room Temperature	Contoso	PI Point
Lobby Room Temperature	Northwind	PI Point
Target Lobby Room Temperature	N/A	Table Lookup
Lobby Room Temperature	Contoso	PI Point
Lobby Room Temperature	AdventureWorks	PI Point
Maximum Lobby Room Temperature	N/A	Table Lookup
Kitchen Room Temperature	Contoso	PI Point

This table shows the order that the results would be returned:

Attribute	PI Data Archive	Data Reference
Lobby Room Temperature	Contoso	PI Point
Kitchen Room Temperature	Contoso	PI Point
Lobby Room Temperature	Northwind	PI Point
Lobby Room Temperature	AdventureWorks	PI Point
Target Lobby Room Temperature	N/A	Table Lookup
Maximum Lobby Room Temperature	N/A	Table Lookup

Since the first attribute is on the Contoso PI Data Archive, it is the first PI Data Archive to receive a bulk call; therefore, all Contoso attributes will be returned first. Duplicate attributes do not produce a duplicate result, so the duplicate Contoso Lobby Room Temperature does not produce a second return value. After the Contoso attributes have been returned, the Northwind attributes are returned followed by the AdventureWorks attributes.

After attributes supporting bulk calls have been returned, the remaining attributes are iterated and evaluated, so the table lookups are returned last in the order they were in the original list.

Important
Several factors can cause the values to come back in a different order, so a dictionary should be used to restructure the results if order is important. If an error occurs or the request range spans multiple element versions, the SDK will fall back to an iterative approach. This would cause the PI Point attributes to be returned in the same order as they were in the list. Finally, calls that include a filter expression that resolve differently for each attribute such as "'.' > 1" will also cause the SDK to fall back to an iterative approach.

Important

Several factors can cause the values to come back in a different order, so a dictionary should be used to restructure the results if order is important. If an error occurs or the request range spans multiple element versions, the SDK will fall back to an iterative approach. This would cause the PI Point attributes to be returned in the same order as they were in the list. Finally, calls that include a filter expression that resolve differently for each attribute such as "'.' > 1" will also cause the SDK to fall back to an iterative approach.

Exceptions

Exception	Condition
ArgumentOutOfRangeException	The summaryTypes cannot be None.
OperationCanceledException	When an error occurs that prevents the operation from proceeding. Check the Error property on the pagingConfig object for more specific error information.
ArgumentNullException	When pagingConfig is .

Remarks

Count is the only summary type supported on non-numeric attributes. Requesting a summary for any other type will generate an error.

Time-weighted totals are computed by integrating the rate tag values over the requested time range. If some of the data are bad in the time range, the calculated total is divided by the fraction of the time period for which there are good values. Mathematically, this approach is equivalent to assuming that during the period of bad data, the tag takes on the average values for the entire calculation time range. The use can use the PercentGood summary to determine if the calculation results are suitable for the application's purposes.

For time-weight totals, if the time unit rate of the attribute cannot be determined, then the value will be totaled assuming a unit of "per day" and no unit of measure will be assigned to the value. If the measured time component of the tag is not based on a day, the user of the data must convert the totalized value to the correct units. For example, if the rate tag was gallons/minute, the conversion can be accomplished using UOMDatabase.UOMs["minute"].Convert(value, UOMDatabase.UOMs["day"].

Tip
Results are available for enumeration as they are returned from the data source for better performance.

Important
The returned enumerable collection can be enumerated one time. As the collection is enumerated, the internal data structures are disposed. Any attempt to reset or enumerate a second time will result in an exception.

Notes to Callers
This method, property, or class is not available in the legacy .NET 3.5 version of the SDK.

Security Note
You must have ReadData security rights to read a data value.

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

// Holds the results keyed on the associated attribute
var resultsMap = new Dictionary<AFAttribute, AFValue>();

// Results should be sent back for 100 tags in each page.
PIPagingConfiguration config = new PIPagingConfiguration(PIPageType.TagCount, 100);

try
{
    var listResults = attributeList.Data.Summary(timeRange, AFSummaryTypes.Average,
        AFCalculationBasis.TimeWeighted, AFTimestampCalculation.Auto, config);

    foreach (IDictionary<AFSummaryTypes, AFValue> attributeResults in listResults)
    {
        // Get average values from the result dictionary
        AFValue attributeValue = attributeResults[AFSummaryTypes.Average];
        AFAttribute attr = attributeValue.Attribute;

        // Map the results back to the attribute
        resultsMap[attr] = attributeValue;
    }
}
catch (OperationCanceledException)
{
    // Errors that occur during bulk calls get trapped here
    // The actual error is stored on the PIPagingConfiguration object
    Console.WriteLine(config.Error.Message);
}
catch (Exception otherEx)
{
    // Errors that occur in an iterative fallback method get trapped here
    Console.WriteLine(otherEx.Message);
}

' Holds the results keyed on the associated attribute
Dim resultsMap As New Dictionary(Of AFAttribute, AFValue)

' Results should be sent back for 100 tags in each page.
Dim config As New PIPagingConfiguration(PIPageType.TagCount, 100)

Try

    Dim listResults As IEnumerable(Of IDictionary(Of AFSummaryTypes, AFValue)) =
        attributeList.Data.Summary(timeRange, AFSummaryTypes.Average,
        AFCalculationBasis.TimeWeighted, AFTimestampCalculation.Auto, config)

    For Each attributeResults As IDictionary(Of AFSummaryTypes, AFValue) In listResults

        ' Get average values from result dictionary
        Dim attributeValue As AFValue = attributeResults(AFSummaryTypes.Average)
        Dim attr As AFAttribute = attributeValue.Attribute

        ' Map the results back to the attribute
        resultsMap(attr) = attributeValue
    Next

Catch canceledEx As OperationCanceledException

    ' Errors that occur during bulk calls get trapped here
    ' The actual error is stored on the PIPagingConfiguration object
    Console.WriteLine(config.Error.Message)

Catch otherEx As Exception

    ' Errors that occur in an iterative fallback method get trapped here
    Console.WriteLine(otherEx.Message)
End Try

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, 2.8.5, 2.8, 2.7.5, 2.7, 2.6

AF SDK Reference