Read from a PI Data Archive

This example shows you how to read data from specified tags of an AVEVA® PI Data Archive.

The read capability of Industrial Communication Toolbox™ for PI provides a variety of options and flexible ways to get the data from a PI Data Archive. Running this example assumes a PI Data Archive available for connection. The demo tags used in this example were provided by AVEVA and can be downloaded from the following location:

https://learning.osisoft.com/asset-based-af-example-kits

The PI Data Archive is capable of storing decades of real-time data from hundreds of assets.

Create Client/Server Connection and Retrieve Required Tags

Connect to the PI Data Archive using the piclient function. In this example the Windows computer name is used as the PI Data Archive name. Your situation might vary depending on the PI System configuration.

host = getenv("COMPUTERNAME");
client = piclient(host);

Request a list of tags related to the asset of interest. For more detailed information see Get Started Accessing a PI Data Archive.

tagsTurbine = tags(client, Name = "OSIDemo_GU4 Turbine*")

tagsTurbine=17×1 table
                                               Tags                                            
    ___________________________________________________________________________________________

    "OSIDemo_GU4 Turbine.Bearing Temperature.d5939f09-48f9-5fa9-1c4a-038afc4737d5"             
    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"               
    "OSIDemo_GU4 Turbine.Cooling Water Intake Temperature.02345806-6376-56a1-3520-055aaacf2af5"
    "OSIDemo_GU4 Turbine.Cooling Water Output Temperature.177387e1-d1df-5f8a-24d8-77a89e5d2719"
    "OSIDemo_GU4 Turbine.Cooling Water Pressure Output.80338427-9e4a-5448-3ac6-aa1c4bff0664"   
    "OSIDemo_GU4 Turbine.Hours Since Last Maintenance.5d33218e-5692-55c4-1db8-765aea821b7c"    
    "OSIDemo_GU4 Turbine.Lubricant Oil Intake Temperature.023173cc-9003-58d8-2e95-4d7ad5efcdec"
    "OSIDemo_GU4 Turbine.Lubricant Oil Output Temperature.168bd614-1fc5-5323-0887-77a127fa324c"
    "OSIDemo_GU4 Turbine.Lubricant Oil Pressure Output.2d8015d1-6069-59a4-0ffb-04254bd6054c"   
    "OSIDemo_GU4 Turbine.Oil Level.c051220f-c20e-55bb-2ec4-f9bfb5a9d9e6"                       
    "OSIDemo_GU4 Turbine.Total Hours Running.ace91215-54c4-5a35-1cb1-78248dcb0861"             
    "OSIDemo_GU4 Turbine.Turbine Vibration.63f0a79e-676a-545f-3647-8579685df5f8"               
    "OSIDemo_GU4 Turbine.Vane Angle.7317f353-c8e4-534f-13a9-c557c81f2de5"                      
    "OSIDemo_GU4 Turbine.Water Flow.d8d44160-1b7f-51a9-37e7-00679041f415"                      
    "OSIDemo_GU4 Turbine.Water in Oil.c0265ea0-2233-5149-3ede-44d9c5737833"                    
    "OSIDemo_GU4 Turbine.Water pH Intake.c3355c67-ace0-557b-382e-b670d80b823a"                 
      ⋮

Read Latest Value of Tag

Read the most recent recorded value of a tag using the read function.

vibrationLatestTT = read(client, tagsTurbine.Tags(2))

vibrationLatestTT=1×3 timetable
              Time                                                  Tag                                         Value    Status
    ________________________    ____________________________________________________________________________    _____    ______

    16-Feb-2024 07:34:53 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.91      Good

Read Values over Period of Time

To read values over a period of time, first define the period. For example, to read values of a tag over the last two days, use the DateRange Name-Value pair to specify a starting datetime and ending datetime. Set the start date to two days ago.

startDate = datetime("now") - days(2);

Set the end date to now.

endDate = datetime("now");

Use these to specify the starting datetime and ending datetime in your request.

vibrationTwoDaysTT = read(client, tagsTurbine.Tags(2), DateRange=[startDate,endDate])

vibrationTwoDaysTT=7×3 timetable
              Time                                                  Tag                                         Value    Status
    ________________________    ____________________________________________________________________________    _____    ______

    15-Feb-2024 05:34:53 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.88     Good 
    15-Feb-2024 09:34:53 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.912     Good 
    15-Feb-2024 11:34:53 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.86     Good 
    15-Feb-2024 15:08:29 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.89     Good 
    15-Feb-2024 19:34:53 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.87     Good 
    16-Feb-2024 01:27:41 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.99     Good 
    16-Feb-2024 07:34:53 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.91     Good

Read All Recorded Values of a Tag

To read all recorded values of a tag, it is useful to know when data recording began. You can use the Earliest Name-Value pair to determine this.

vibrationEarliestTT = read(client, tagsTurbine.Tags(2), Earliest=true)

vibrationEarliestTT=1×3 timetable
              Time                                                  Tag                                         Value    Status
    ________________________    ____________________________________________________________________________    _____    ______

    05-Nov-2023 22:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     NaN      Bad

Notice the value of this tag at the earliest recorded time is a NaN. This is often the case for the first data point in a series as the PI Data Archive indicates a status of Bad for this data point upon creation. You can exclude this from your data set if desired.

This earliest data point identifies the time of the first recorded value. You can now use this information to establish a starting datetime for your request.

startDate = datetime(vibrationEarliestTT.Time(1));

Set the ending datetime to now.

endDate = datetime("now", TimeZone="local");

Depending on your system, this query may return a large amount of data. If you have an extensive history of data that makes this too slow or impractical, you may want to skip this step.

vibrationAllTT = read(client, tagsTurbine.Tags(2), DateRange=[startDate,endDate])

vibrationAllTT=3759×3 timetable
              Time                                                  Tag                                         Value    Status
    ________________________    ____________________________________________________________________________    _____    ______

    05-Nov-2023 22:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     NaN      Bad  
    05-Nov-2023 22:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.75      Good 
    05-Nov-2023 22:50:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.89      Good 
    05-Nov-2023 22:53:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.88      Good 
    05-Nov-2023 22:59:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.85      Good 
    05-Nov-2023 23:00:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.84      Good 
    05-Nov-2023 23:05:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.86      Good 
    05-Nov-2023 23:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.8      Good 
    05-Nov-2023 23:11:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.88      Good 
    05-Nov-2023 23:14:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.88      Good 
    05-Nov-2023 23:25:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"     0.9      Good 
    05-Nov-2023 23:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.81      Good 
    05-Nov-2023 23:42:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.99      Good 
    05-Nov-2023 23:50:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.98      Good 
    06-Nov-2023 00:04:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.96      Good 
    06-Nov-2023 00:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.78      Good 
      ⋮

Reduce Data Set Using Linear Interpolation Provided by PI Server

Notice the large number of datapoints in the result of the previous step. You can reduce the data set by using the Interval Name-Value pair. For example the following read requests data with an interval of 30 minutes. The Interval Name-Value pair requests the PI Server to perform linear interpolation on recorded values and provide results at the specified interval.

vibrationInterpolatedTT = read(client, tagsTurbine.Tags(2), DateRange=[startDate,endDate], Interval=minutes(30))

vibrationInterpolatedTT=4919×3 timetable
              Time                                                  Tag                                          Value     Status
    ________________________    ____________________________________________________________________________    _______    ______

    05-Nov-2023 22:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"        NaN     Bad  
    05-Nov-2023 22:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.75     Good 
    05-Nov-2023 23:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"        0.8     Good 
    05-Nov-2023 23:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.81     Good 
    06-Nov-2023 00:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.78     Good 
    06-Nov-2023 00:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.96     Good 
    06-Nov-2023 01:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.91     Good 
    06-Nov-2023 01:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.67     Good 
    06-Nov-2023 02:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.88     Good 
    06-Nov-2023 02:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.82     Good 
    06-Nov-2023 03:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"       0.99     Good 
    06-Nov-2023 03:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.67902     Good 
    06-Nov-2023 04:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.63579     Good 
    06-Nov-2023 04:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.94517     Good 
    06-Nov-2023 05:10:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.20893     Good 
    06-Nov-2023 05:40:42 UTC    "OSIDemo_GU4 Turbine.Bearing Vibration.f60c59bb-f918-5421-12f0-40939fa38b0b"    0.70928     Good 
      ⋮

Clean Up

When you are finished working with the PI Data Archive, disconnect and remove the client by clearing its variable from the workspace.

clear client;