Managing the Historian (version 23)

Managing DataSets

A DataSet is a logical grouping of tags and is the basic building block of the Historian database. A DataSet houses the HDB files (historic database files) that contain tags and all the TVQ updates and properties for those tags. 

You may view all your DataSets by opening the Canary Admin application and then selecting the Historian tile. The first screen of the Historian user interface displays every DataSet. 

HISTORIAN Window

In the upper left-hand corner you can view information about the Canary Historian.

DATASET Window

In the lower left-hand corner you can view information about the currently selected DataSet.  To select a DataSet, click on it once.  It will be highlighted yellow once selected.

DataSet Options

When a DataSet is selected, the 'DATASET' window has an additional set of options which can be displayed by selecting the down arrow icon. These options include:

If more DataSets exist than can be displayed, a scroll bar at the top of the screen appears. This bar can be used to navigate throughout the collection of DataSets and can be adjusted.  Either grip can be positioned along the range to start or end at a particular DataSet instance. Dragging the yellow bar between the grips will vary the DataSets displayed but not the number of DataSets displayed.

Managing HDB Files

An HDB file contains all of the tags, TVQs, and metadata properties written to a DataSet for a specific period of time, usually one day.  Within an HDB file, TVQs are grouped into blocks of records called vectors.  Vector size and the number of TVQs segmented within a vector are dependent on data type.

You may view all your HDB files by opening the Canary Admin application and then selecting the 'Historian' tile. The first screen of the Historian user interface displays every DataSet.  Double-click on a DataSet tile to browse all the available HDB files. 

When data begins to get logged to the DataSet, a new HDB file is automatically created and displayed.  When an HDB file is finished having data written to it, it is rolled over, then validated and closed.  A new HDB file is then automatically created. Anytime a Logging Session is stopped, an HDB file is closed, and eventually validated by the background validation process.  When the Logging Session is restarted, the current file is reopened for writing or a new HDB file is generated.

Additionally, HDB files will automatically roll over if they exceed 512 MB in size. To maximize historian efficiency, size DataSets to maintain only a single HDB file per day.

Each HDB file is represented by a tile with the date of the contained timestamps.  If there are more than one HDB files per day, the time the file was opened will also be displayed.

HDB File States and Indicators

HDB files have several states.  These include:

• Open - An HDB file is actively being written to and has not yet been validated or compressed.  Represented with a black clock in the upper left hand corner.
• Closed - An HDB file has been validated and is no longer open to have data written. Represented with the tile colored dark blue.
• Online - An HDB file is available to client queries. May or may not have been validated. Represented with the tile colored dark blue. If it is has not been validated, will contain a black clock in the upper left hand corner.
• Offline - An HDB file is not available for client queries. May or may not have been validated. Represented with the tile colored grey.

When an HDB tile is selected it will turn yellow if it is an online file or light grey if it is an offline file.  More than one HDB file may be selected using SHIFT or CTRL.

HDB File Validation

Validation is an internal Canary process that is generally executed automatically.  During HDB file validation, all file structure and data links are checked. If a file does not pass validation, it is automatically moved to an offline status.

Caution, this process can create large files and may require an extended length of time to complete.

HDB File Recovery

If an HDB file fails validation, the file must be recovered in order to be part of the available historical record.  Once manually initiated, file recovery is an automated process that involves the following steps:

• The file is disassembled and all readable components are placed into text files
• An import file is created by reformatting the text files into the proper time sequence
• The new import file is then converted into an HDB file and brought online and revalidated
• The original corrupted HDB file is preserved and marked with a .old extension but remains outside the available historical record

The admin has the choice to delete the old corrupted HDB file once they have verified the newly recovered HDB file is correct.

HDB FILE Window

Double click a DataSet to access the 'HDB' file window for that DataSet. Select a single HDB file to access the FILE window on the lower left hand side of the screen. 

Based on the status indicator an admin should take the following action: 

HDB File Options

When an HDB tile is selected, the 'FILE' window has an additional set of options which can be displayed by selecting the down arrow icon. These options are different based on the status of the HDB file.

Online HDB FILE OPTIONS 

Online HDB Files are represented by a blue tile. This is the default state of HDB files. Select a single HDB file or multiple HDB files using either Shift or the CTRL key.  Then select the down arrow icon in the 'FILE' window to access the HDB file options.

How to Rename Tags in Bulk

1. Double-click the DataSet that houses the tag names that need changed. Double click the current HDB file (or the file that houses the tag names that must be changed).
2. When looking at the full list of tags within the HDB file, select the white drop down arrow. Uncheck the 'Include Parent Path' checkbox.
3. Select 'ok'. Save the CSV file.
4. Open up the CSV file in Excel and copy and paste the tag names into column B. Change all tag names in column B as needed. Save the CSV file.
5. Open the Canary Admin. Select the 'Historian' tab. Select the 'Database' tab.
6. Double-click the same DataSet in step 2. Single click the HDB2 file that houses the tags that need changed.
7. Select the yellow drop down menu. Select 'RENAME TAGS'. This dialog appears.  You will not need to adjust 'Header Count' or 'Source tag paths column' or 'Destination tag paths column'.
8. Select 'browse' to find the CSV file saved in step 6.
9. Decide whether you wish to change the tag name in the entire DataSet, only this HDB file, this HDB file and later, or this HDB file and earlier.
10. Select 'ok'.

You may receive an error message that references a text file.  You can find the text file in the same directory as the CSV file you tried to upload.  Sometimes an error will occur but the tags will also be successfully renamed.  Verify the tag names have or have not been updated prior to troubleshooting the error file.

Should you choose to use an existing CSV file to accomplish the rename other than the file described above, you will need to format the 'Header Count', 'Source tag paths column', and 'Destination tag paths column' accordingly.

Offline HDB FILE OPTIONS

Offline files are represented by gray tiles and have a different 'FILE OPTIONS' menu.  An HDB File is in an offline state when manually taken offline, or if the validation process has found errors or corrupt values within an HDB file.  Select a single HDB file or multiple HDB files using either Shift or the CTRL key.  Then select the down arrow icon in the 'FILE' window to access the HDB file options.

If more HDB files exist than can be displayed, a scroll bar at the top of the screen appears. This bar can be used to navigate throughout the collection of HDB files and can be adjusted.  Either grip can be positioned along the range to start or end at a particular HDB instance. Dragging the yellow bar between the grips will vary the HDB files displayed but not the number of HDB files displayed.

Managing Tags

TAGS Window

From the Database tab of the Historian tile, double click an active DataSet, then double-click an HDB file. The 'TAGS' window is on the left side of the screen. 

1. Select a tag. Timestamps, Values, and Tag Qualities populate on the right side of the screen.

Select 'Trend' to view the selected tag's TVQ updates on a quick trend chart.

Exporting a Tag List

The tag list can be exported as a CSV file by:

1. Select the down arrow icon beside the search bar in the 'TAGS' window. 
2. Select 'Include Parent Path' to list entire tag names, with the DataSet included, or unselect to have just the tag name.
3. Select 'ok'.

PROPERTIES Window

The 'PROPERTIES' Window on the bottom left side of the screen, displays  additional tag information.  Tags that have metadata properties will have those properties displayed here.  (If metadata is configured to be stored in an external SQL database, they will not appear here, but they will appear in the Views tile.) Calculated tags, tags created using the Canary Calculation Server, will also display information. 

TAG OPTIONS

Select the drop down arrow in the 'PROPERTIES' window.