Main Content

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.c73204fa-e8f2-5513-1bc9-b5f097831d16"             
    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"               
    "OSIDemo_GU4 Turbine.Cooling Water Intake Temperature.f987e786-7a17-5027-1492-0482f0ae04b9"
    "OSIDemo_GU4 Turbine.Cooling Water Output Temperature.62d8d7be-2b82-53bc-09f1-660ffa00aa70"
    "OSIDemo_GU4 Turbine.Cooling Water Pressure Output.7c04f479-ae18-5207-0690-514252308c5b"   
    "OSIDemo_GU4 Turbine.Hours Since Last Maintenance.ec8ae125-0ae5-5d45-1de6-0643ffac4983"    
    "OSIDemo_GU4 Turbine.Lubricant Oil Intake Temperature.7fc3f299-b6ee-5e2e-3e7b-ca4ca59a9d9c"
    "OSIDemo_GU4 Turbine.Lubricant Oil Output Temperature.03c2ec47-7719-5f48-32b5-6c961d1a7912"
    "OSIDemo_GU4 Turbine.Lubricant Oil Pressure Output.9dd81865-26b3-57fb-0791-bf7a3cfea158"   
    "OSIDemo_GU4 Turbine.Oil Level.201c4312-8852-50be-1d8b-297c216712ec"                       
    "OSIDemo_GU4 Turbine.Total Hours Running.4438ad34-9e54-5075-1c76-19e3ac3fb728"             
    "OSIDemo_GU4 Turbine.Turbine Vibration.e4c9f243-d5c9-5f5c-3b82-ed8076592ff9"               
    "OSIDemo_GU4 Turbine.Vane Angle.3ddc1860-a9cc-54ee-2d41-595eb92fc677"                      
    "OSIDemo_GU4 Turbine.Water Flow.cf5b9b79-af11-5637-2317-f518e59b0c9f"                      
    "OSIDemo_GU4 Turbine.Water in Oil.562f483e-a814-5b11-3dd7-44b9735068ca"                    
    "OSIDemo_GU4 Turbine.Water pH Intake.2f31c444-6f9a-5005-083c-db8531de4d07"                 
      ⋮

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
    _________________________    ____________________________________________________________________________    _____    ______

    21-December-2021 15:40:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     0.8      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=559×3 timetable
              Time                                                   Tag                                         Value    Status
    _________________________    ____________________________________________________________________________    _____    ______

    19-December-2021 10:45:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.83      Good 
    19-December-2021 10:50:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.86      Good 
    19-December-2021 10:55:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    1.03      Good 
    19-December-2021 11:00:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.85      Good 
    19-December-2021 11:05:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     0.8      Good 
    19-December-2021 11:10:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.88      Good 
    19-December-2021 11:15:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.89      Good 
    19-December-2021 11:20:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.89      Good 
    19-December-2021 11:25:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.79      Good 
    19-December-2021 11:30:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.88      Good 
    19-December-2021 11:35:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.84      Good 
    19-December-2021 11:40:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     0.7      Good 
    19-December-2021 11:45:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    1.04      Good 
    19-December-2021 11:50:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.83      Good 
    19-December-2021 11:55:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.82      Good 
    19-December-2021 12:00:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.74      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
    _________________________    ____________________________________________________________________________    _____    ______

    04-November-2021 20:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     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=13171×3 timetable
              Time                                                   Tag                                         Value    Status
    _________________________    ____________________________________________________________________________    _____    ______

    04-November-2021 20:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     NaN      Bad  
    04-November-2021 20:30:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.72      Good 
    04-November-2021 20:35:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.73      Good 
    04-November-2021 20:40:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.86      Good 
    04-November-2021 20:45:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.75      Good 
    04-November-2021 20:50:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.73      Good 
    04-November-2021 20:55:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.85      Good 
    04-November-2021 21:00:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.83      Good 
    04-November-2021 21:05:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.97      Good 
    04-November-2021 21:10:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.77      Good 
    04-November-2021 21:15:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.72      Good 
    04-November-2021 21:20:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    1.02      Good 
    04-November-2021 21:25:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.83      Good 
    04-November-2021 21:30:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.89      Good 
    04-November-2021 21:35:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.88      Good 
    04-November-2021 21:40:00    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.95      Good 
      ⋮

Reduce Dataset Using Linear Interpolation Provided by PI Server

Notice the large number of datapoints in the result of the previous step. You can reduce the dataset 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=2247×3 timetable
              Time                                                   Tag                                          Value     Status
    _________________________    ____________________________________________________________________________    _______    ______

    04-November-2021 20:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"        NaN     Bad  
    04-November-2021 20:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.84713     Good 
    04-November-2021 21:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     0.8386     Good 
    04-November-2021 21:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.80423     Good 
    04-November-2021 22:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.86857     Good 
    04-November-2021 22:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.80717     Good 
    04-November-2021 23:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.71863     Good 
    04-November-2021 23:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.96133     Good 
    05-November-2021 00:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     0.8542     Good 
    05-November-2021 00:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"        0.8     Good 
    05-November-2021 01:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.74573     Good 
    05-November-2021 01:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.72857     Good 
    05-November-2021 02:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.79997     Good 
    05-November-2021 02:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"     0.8385     Good 
    05-November-2021 03:25:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.79857     Good 
    05-November-2021 03:55:43    "OSIDemo_GU4 Turbine.Bearing Vibration.64a3ce99-f31e-593c-3e29-595f32095ce7"    0.74147     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;