read

Read data from PI Data Archive

Since R2022a

collapse all in page

Syntax

piValues = read(piClientObj,tagName)
piValues = read(piClientObj,tagName,Name=Value)

Description

piValues = read(piClientObj,tagName) reads the latest data value from each of the specified tags of the AVEVA® PI Data Archive that the PI client piClientObj is connected to. tagName can be a string or vector of strings. The data is returned to piValues as a timetable.

example

piValues = read(piClientObj,tagName,Name=Value) specifies options for the read operation using name-value arguments. Options include reading earliest value of the specified tag, returning averaged or aggregated data, specifying a date range, and sampling at a specified time interval.

Note

You must install the AF SDK library to connect to a PI server from MATLAB®. For more information, see AF SDK Overview.

example

Examples

collapse all

Read the latest data point of a single tag from an archive represented by the PI client object piClientObj.

piValues = read(piClientObj,"Plant1_generator1_voltage");

Read the earliest data point of a single tag. 

piValues = read(piClientObj,"Plant1_generator1_voltage",Earliest=true);

Read data points of multiple tags over a 6-hour period, interpolating every 5 minutes.

startDate = datetime(2021,6,12,14,10,30); % 12-Jun-2021 14:10:30
endDate = startDate + hours(6);
piValues = read(piClientObj,["Plant1_generator1_voltage","Plant1_generator1_current"], ...
           DateRange=[startDate,endDate], Interval=minutes(5));

Read time-weighted average voltage data over the past day in 4-hour intervals. This example returns the average values of Plant1_generator1_voltage data aggregated over an interval of four hours between the specified startDate and endDate.

startDate = datetime("now") - days(1);
endDate = datetime("now");
piValues = read(piClientObj,"Plant1_generator1_voltage",DateRange=[startDate,endDate], ...
          Interval=hours(4),AggregateFcn="average",CalculationMode="time")
piValues=

  5×3 timetable

              Time                        Tag                  Value    Status
    ________________________    ___________________________    _____    ______

    15-Feb-2026 10:34:53 UTC    "Plant1_generator1_voltage"     0.88     Good 
    15-Feb-2026 14:34:53 UTC    "Plant1_generator1_voltage"    0.912     Good 
    15-Feb-2026 18:34:53 UTC    "Plant1_generator1_voltage"     0.86     Good 
    15-Feb-2026 22:08:29 UTC    "Plant1_generator1_voltage"     0.89     Good 
    15-Feb-2026 02:34:53 UTC    "Plant1_generator1_voltage"     0.87     Good

Input Arguments

collapse all

Client connected to AVEVA PI Data Archive, specified as an icomm.pi.Client object. You create the object with the piclient function.

Example: piClientObj = piclient("pi-host-55")

Data Types: object

Tag names to read from, specified as a string, string array, character vector, or cell array of character vectors. You can also specify tags with a table, in the format returned by the tags function.

Example: piCurrent = read(piClientObj,"Power_ckt2")

Data Types: char | string | table | cell

Name-Value Arguments

collapse all

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: averagedData = read(piClientObj,"Power_ckt2",DateRange=[startTime,endTime],Interval=hours(4),AggregateFcn="average") returns the average values of Power_ckt2 data aggregated over four-hour intervals between startTime and endTime.

Option to read earliest value of PI tag, specified as logical true or false. If this argument is true, the function returns the earliest value of the tags specified in the input argument tagName.

Example: piValues = read(piClientObj,"Plant1_generator1_voltage",Earliest=true)

Data Types: logical

Date and time range to read data, specified as a two-element vector of datetime values returned by the datetime function. You can also specify a time zone in the datetime values. By default, the function uses the time zone of the local system.

Example: [datetime("1-Jan-2020"),datetime("31-Jan-2020")]

Example: [datetime("today",TimeZone="America/New_York"),datetime("now",TimeZone="America/New_York")]

Data Types: datetime

Time interval of sampling to extract interpolated data, specified as a duration.

Example: piValues = read(piClientObj,"Power_ckt2",DateRange=[startTime,endTime],Interval=hours(4)) returns the raw interpolated values of Power_ckt2 data with 4-hour intervals between startTime and endTime.

Data Types: duration

Aggregate function used to process the data, specified as one of these listed values.

  • "none" — Raw interpolated data

  • "total" — Sum of all data points within the interval in the time range

  • "average" — Average of all data points within the interval in the time range

  • "minimum" — Smallest value within the interval

  • "maximum" — Largest value within the interval

  • "range" — Difference between the maximum and minimum values within the interval in the time range

  • "standard-deviation" — Standard deviation of the data within the interval in the time range

  • "population-standard-deviation" — Population standard deviation over the time range

  • "count" — Number of data points within the interval in the time range

  • "percent-good" — Percentage of data points with good values within the interval in the time range

Example: piValues = read(piClientObj,"Power_ckt2",DateRange=[startTime,endTime],Interval=hours(4),AggregateFcn="average") returns the average values of Power_ckt2 data aggregated over 4-hour intervals between startTime and endTime.

Data Types: char | string

Calculation mode used to process the data, specified as one of these listed values.

  • "event" — Gives equal weight to each event (a timestamped data point). Requires at least one event (two for standard deviation). May exclude one or both ends of the interval, depending on interval count and order.

  • "time" — Weights each value by the time it spans within the interval. Interpolates boundary values if needed.

  • "time-continuous" — Same as time, but treats data as continuous for interpolation.

  • "time-discrete" — Same as time, but treats data as discrete steps for interpolation.

  • "event-exclude-recent" — Same as event, but ignores the most recent event at interval boundaries.

  • "event-exclude-earliest" — Same as event, but ignores the earliest event at interval boundaries.

  • "event-include-ends" — Includes events at both ends of the interval in the calculation.

Example: piValues = read(piClientObj,"Power_ckt2",DateRange=[startTime,endTime],Interval=hours(4),AggregateFcn="average",CalculationMode="event-exclude-recent") returns the average of Power_ckt2 data aggregated over 4-hour intervals between startTime and endTime, excluding the most recent data point in each interval.

Data Types: char | string

Output Arguments

collapse all

Data point values read from the PI Data Archive, returned as a timetable. The timetable includes data values for the specified date range in UTC time.

Version History

Introduced in R2022a

expand all

See Also

Functions