The Cache data source was specifically designed to enable high-speed analytic processing of real-time data and the comparison of current real-time values against history data, either visually or as input to alert rules that activate automated behavior.

The Cache data source allows for easy definition of a memory resident data cache that can store current scalar values, tabular data with optional filters, as well as time-stamped scalar or tabular data (up to a configurable number of entries), which keeps only the most current information and discards older entries. A cache history can be configured to time-stamp incoming data or to recognize a time-stamp already included in incoming data. You can also optionally pre-load a cache with data from another source, for example if you have historical information stored in a database.

In many real-time situations, data enters the system asynchronously. For example, in a financial trading application a series of data might be delivered that contains multi-dimensional data about a particular trading instrument. You might want to store the current value of a particular market data feed based on the instrument name index (IBM) and the activity index ("buy") and require a time-stamped history of this market data to analyze the trend of a particular instrument over a period of time.

The Cache data source allows for much higher performance than the traditional means of either performing analytics on information stored in a database or querying it back out of the database when it is necessary to make calculations.

A cache history table is kept in memory. The size and time range of the data in the history table is determined by the cache maxNumberOfHistoryRows property and (optionally) its historyTimeSpan property. The cache persistence feature allows a cache definition file to be used as a data configuration file for the Historian, so that the cache history data is stored in a database table. The database and table names are specified by the cache object.

When the cache data source is initialized, it preloads the history tables of all caches that use the cache persistence feature by making appropriate SQL queries. However, the number of rows that can be loaded from the database into the cache in-memory history table is limited by the cache maxNumberOfHistoryRows property and (if specified) historyTimeSpan property values.

When making a data attachment to a cache history table, the Attach to Data dialog Advanced Filter options can be used to specify the time period of interest (Time Range, Begin Time, and End Time fields).

Extend with SQL 
The Extend with SQL option allows you to configure a cache to use a SQL query to retrieve data from an external database. This option provides a convenient way to retrieve and display cache data that is stored in an RTView Historian database. When this option is not enabled the cache data source retrieves data from the in-memory cache only. To use this option, make a data attachment to a cache history table, select Advanced Filter Rows, specify the time period of interest, and select Extend with SQL. For details, see Extend with SQL.

Data Compaction
Primary compaction operates on in-memory cache tables, condensing a cache history table by periodically applying a calculation (for example, average, min, max, etc.) to each column. It then stores a single result row in another cache table. Primary compaction is configured using the Data Compaction: Primary (in-memory) properties. This feature complements the Historian data compaction, or secondary compaction feature, which operates on database tables. Secondary compaction can be configured to compact rows in database tables as the data "ages".  Secondary compaction is configured using the Data Compaction: Secondary (Historian) properties.

Adding Caches
In the Display Builder, select Tools>Caches to open the Caches dialog. When you have finished adding all of your caches and configuring their properties, Save the display (.rtv) file and add this Cache Definition file to the Cache data source configuration.

Cache Definition Files
To create an Cache Definition file, save the display (.rtv) file that contains the cache definition properties you set. See Application Options for details on how to add a Cache Definition file to the Cache data source configuration.

Viewing Caches
See the Attach to Cache Data section for more information on attaching to cache data variables.

Table Cache
The Table Cache allows you to cache your tabular data. Attach your input data to the valueTable property.

Cache Properties

cacheName	A unique name for the cache. An entry for this property is required. Caches that do not specify a cacheName, as well as caches with duplicate cacheName properties, will not be created and an error will print to the console. Substitutions defined in a Cache Definition File allow the same file to be specified multiple times with different sets of substitutions. Note that each cacheName defined in that file should contain a substitution, since cache names must be unique. Substitutions must use the following syntax: $subname:subvalue $subname2:subvalue2 If a substitution value contains a single quote, it must be escaped using a / : $filter:Plant=/'Dallas/' If a substitution value contains a space, it must be enclosed in single quotes. Do not escape these single quotes: $subname:subvalue $subname2:'sub value 2' A substitution string cannot contain the following: : | . tab space , ; = < > ' " & / \ { } [ ] ( )
description	Enter descriptive text which is displayed in the Description column of the Caches table.
indexColumnNames	Enter a semicolon (;) separated list of column names from the attached valueTable to be used as index columns.
timestampColumnName	Specify the name of a timestamp column. If the specified timestampColumnName is not found in the incoming data, a column will be inserted and each row will contain the time that row was received.
queryServerName	Specifies the name of the Data Server to use to perform the initial SQL query to preload the cache's tables, and also to perform any Extend-by-SQL queries for data attachments to the cache. By default, the value of the property is blank, which means that the SQL queries are performed by the local application. NOTE: SQL queries are only performed if the cache's historyTableName or currentTableName properties specify a database table name.
updateListenersImmedFlag	If selected, then each time new data is stored in the cache the updated contents of the cache's tables are immediately applied to any listeners attached to those tables. This is the default setting and is appropriate for most caches. If deselected, the updated contents of the cache's tables are not applied to the listeners immediately after new data is stored in the cache. Instead the listeners are updated on the next RTView update cycle; default is 2 seconds. In very specific conditions, this can improve the performance of the Data Server. For example, in a case where the cache is maintained in a Data Server and raw event-driven data (e.g. high-frequency event data from a JMS, RV, or RTVAgent data attachment) is frequently stored in the cache and the cache's current table or history table can grow to more than 25,000 rows.

Cache Current Table Properties

maxNumberOfCurrentRows	Specifies the maximum number of rows in a cache current table. The oldest rows in the current table are removed if necessary to maintain this limit. The default value is blank, indicating no limit on the number of rows. A value of zero can also be used to specify no limit. The cache data source checks the maxNumberOfCurrentRows limit at approximately 10 second intervals, therefore the limit might be exceeded if new data is applied to the cache between those intervals. NOTE: In many cases it is not necessary to place a numerical limit on the rows in the current table, since the rows are limited by the number of unique combinations of index column values, or rows are removed via other properties. In the case of a cache with no index columns, each update replaces the entire current table.
rowExpirationMode	Specifies whether to expire rows in the current table and, if so, the mode for doing so. Possible values are: Off Row expiration is disabled. Mark An Expired column is added to the current table and its value is set to true in each expired row. Delete Expired rows are deleted from the current table. Mark & Delete An Expired column is added to the current table, its value is set to true in each expired row. Eventually, expired rows are deleted from the current table. The default value is Off. If this property is set to Mark, Delete or Mark & Delete, the following additional properties are available in the property sheet: rowExpirationTime, rowExpiredIndexColumns and rowExpiredColumnName. If this property is set to Mark & Delete, the rowExpirationTimeForDelete property is available in the property sheet.
rowExpirationTime	This property is available when the rowExpirationMode property is set to Mark or Delete, or Mark & Delete. If row expiration is enabled on a cache (rowExpirationMode is not Off), the current table is periodically checked for expired rows. A row is expired if the difference between the current time and the timestamp in the row timestamp column is greater than the interval specified by the rowExpirationTime property. This check is performed once every 10 seconds, approximately. Specify the duration in seconds, or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows: y years (365 days) M months (31 days) w weeks (7 days) d days h hours m minutes s seconds The default value is blank, which specifies no expiration time. A row in the current table is considered expired when it is not updated per the time interval specified by the rowExpirationTime property. NOTE: The cache data source checks the expiration time limit at approximately 10 second intervals, therefore the limit might be exceeded by up to 10 seconds.
rowExpirationTimeForDelete	This property is available only when the rowExpirationMode property is set to Mark & Delete. A row is deleted if the difference between the current time and the timestamp in the row timestamp column is greater than the interval specified by this property. The value of this property should specify a longer time interval than that specified for the rowExpirationTime property. The default value is blank, which specifies no deletion time. Specify the duration in seconds, or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows: y years (365 days) M months (31 days) w weeks (7 days) d days h hours m minutes s seconds This property is useful in cases where a row in the cache current table should be marked as expired after the time period indicated by the rowExpirationTime has passed and the row has not been updated, and then later the row should be deleted after the time indicated by rowExpirationTimeForDelete has passed. For example, if a cache has the following property settings: rowExpirationMode: Mark & Delete rowExpirationTime: 30m rowExpirationTimeForDelete: 4h and a row in the cache current table is not updated for 30 minutes, the value of the Expired column for that row will be set to true. If a row is not updated for 4 hours, it will be deleted from the current table.
rowExpiredColumnName	This property is available when the rowExpirationMode property is set to Mark, or Mark & Delete. Specifies the name of the boolean column that is added to the cache current table to indicate if a row is expired. The default value is Expired.
rowExpiredIndexColumns	Previously named indexColumnNamesForDelete, this property is available when the rowExpirationMode property is set to Mark or Delete, or Mark & Delete. Enter a semicolon (;) separated list of column names. The list must contain some or all of the column names specified in the cache indexColumnNames Property. The default value is blank. On each update to the cache, the set of values contained in the update for the columns specified in this property is recorded. A row in the current table is considered expired when it has a matching value for those columns but was not updated.
rowsToDeleteTable	Previously named deleteTable, this property is intended to be attached to a data table that specifies the rows to be deleted from the cache current table. The data table attached to the rowsToDeleteTable is expected to contain the columns specified in the indexColumnNames property. If a row in the rowsToDeleteTable has the same values in each of the index columns as does a row in the cache current table, that row will be deleted from the current table. The history table is not affected.

Cache History Table Properties

allowDuplicatesInHistoryFlag	If this property is deselected, then before adding a new row to the History table the cache data source will first check if an existing row has the identical timestamp and index column values. If a duplicate does exist, the existing row will be replaced with the new row. NOTE: If duplicate history rows are acceptable or unlikely to occur, then it is recommended that this property remain selected to maintain optimum performance.
historyColumnNames	Enter a semicolon (;) separated list of column names from the cache current table to be stored in the cache history. The order in which the column names are specified does not affect the order in which they appear in the history table, they appear in the same order as they do in the current table. By default, the cache current table and cache history table store the same columns. In many cases this is desirable. Data sources may supply data tables containing columns whose values are static (for example, units, version number, description, etc). It can be useful to store these values in the cache current table, but they can take up memory and database space when storing data in the history tables at every update. The columns specified by historyColumnNames must be a subset of the columns in the cache current table. If a specified column does not appear in the current table, it is ignored. If a column is not specified in historyColumnNames but the column is specified in either indexColumnNames or timestampColumnName, the column is still included in the history table. This is because the index column and the timestamp column are needed for use and maintenance of the history table.  Changing the names specified in historyColumnNames could lead to incompatibility with data previously stored by the Historian. Note that this is also an issue with changes made to the cache schemaTable or the cache valueTable attachment. The default value is blank, which specifies that all columns from the current table be stored in the history table.
historyTimeSpan	Previously named timeSpan, this property specifies the amount of time that rows will be kept in the History table according to their timestamp. Specify the duration in seconds or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows: y years (365 days) M months (31 days) w weeks (7 days) d days h hours m minutes s seconds The historyTimeSpan property only determines the duration of rows kept in the History table by the cache data source. It does not affect database storage, if any, associated with the cache. NOTE: The maxNumberOfHistoryRows property will limit the total number of rows in the History table regardless of the specified historyTimeSpan.
initialTable	Attach this property to a table to pre-populate initial data for a cache. Specify the initialTable property to ensure that data is available for viewing when the cache is accessed for the first time. To properly populate the initial data for the cache using the initialTable property: Specify the index columns for queries using the indexColumnNames property. The SQL query that populates the initialTable must have the same index column(s) specified as those used to setup the cache. The table must contain the same column(s) as the input table attached to the valueTable property. The table must contain a timestamp column if timestampColumnName is specified. If the specified timestampColumnName is not found in the incoming data, a column is inserted. Data attached to this property works best if it is only updated once at the startup of RTView. NOTE: A table attached the initialTable property will be modified if you did not include a column with the timestampColumnName and/or if the rowsToDeleteTable property is updated. If other objects in your RTView application are attached to this same table, those objects might also be affected.
maxNumberOfHistorytRows	The number of rows in the History table. Default is 0. If set to 0, no History table is created and only the Current table is available in the Table drop down menu in the Attach to Cache Data dialog. The Extend with SQL option requires this property to have a value greater than 0.

Data Properties

resetTrigger	When data values attached to this property receive an update the cache will be cleared.
schemaTable	Optionally attach this property to any tabular data source (e.g. SQL query, XML file, etc.) to provide the structure of a table you would like the Table Cache object to use. Only the table's structure will be used from this data attachment, any row data will be ignored. Once a schemaTable is specified, Current and History tables will be initialized accordingly and the Attach to Cache Data dialog will show the columns found in that table structure. Once data becomes available, Table Cache objects will contain the columns found in the specified schemaTable, in addition to columns found in the data. NOTE: If the data types of columns defined in the schemaTable differ from data types found in the actual data attachment, then the schema types will be used and incoming data will be converted. If the specified timestampColumnName is not found in the incoming data, a column will be inserted.
schemaTableStrictFlag	If selected, then the schemaTable will be applied to all incoming data tables before they are stored in the cache even when the data table and the schema table have the same number of columns. If deselected, the schema is applied only when the data table and schema table have different numbers of columns. NOTE: This option should only be selected if it is possible for a data table to have the expected number of columns, but those columns may be in the wrong order. If incoming data tables have a large number of columns and a high update frequency, then applying the schema in all cases will incur additional CPU overhead when updating a cache.
valueTable	Attach your input data to this property if it is tabular. For scalar input data, select the Double Cache object and attach your input data to the value property.
valueTableCount	Allows the Table Cache object to support multiple data attachments. Default is 1, which results in a single valueTable property. If valueTableCount is increased to 2, then valueTable02 will be added to the Object Property list and so on. Maximum value is 99.

Data Compaction: Primary (in-memory) Properties
The Data Compaction: Primary (in-memory) category of properties is available when a tabular cache object is selected in the Builder.   

condenseRowsCombineHistoryFlag	If selected, the history_combo table is made available. This property is available when the condenseRowsFlag property is selected. The history_combo table stores rows of recent raw data followed by rows of older condensed data. The raw data rows extend from the current time back for the number of seconds specified by the condenseRowsRawDataTimeSpan property. The condensed rows are limited by the historyTimeSpan and/or maxNumberOfHistoryRows properties.
condenseRowsFlag	If selected, enables the primary compaction feature for the cache. This property makes the following tables available (in addition to the tables available by default, the Current and History tables.): current_condensed: This table stores the most recent row of condensed data for each unique index column value combination. history_condensed: This table stores condensed data history, limited by the cache historyTimeSpan and/or maxNumberOfHistoryRows properties. If you also select the condenseRowsCombineHistoryFlag property, the history_combo table is made available: history_combo: This table stores rows of recent raw data followed by rows of older condensed data. The raw data rows extend from the current time back for the number of seconds specified by the condenseRowsRawDataTimeSpan property. The condensed rows are limited by the historyTimeSpan and/or maxNumberOfHistoryRows properties. This property affects RTView behavior when persisting a cache to, or restoring it from, a database. For example, if condenseRowsFlag is selected on cache C1: If the cache definition file is used as an Historian configuration file, the Historian stores only the condensed rows for C1 in the database table specified by C1's historyTableName property. When the cache definition file is loaded by an RTView application (other than the Historian) the database table specified by C1's historyTableName is queried to get the initial rows for C1.history_condensed and, if enabled, C1.history_combo. This is useful in cases where the Historian should only store data that has already undergone primary compaction, rather than storing raw data which arrives in high volumes. When condenseRowsFlag is selected, the following additional properties are available in the property sheet: condenseRowsInterval, condenseRowsGroupBy, condenseRowsRawDataTimeSpan and condenseRowsCombineHistoryFlag.
condenseRowsGroupBy	A string that specifies the calculation to be performed on each data column in the cache table. This property is available when the condenseRowsFlag property is selected. Specify the string using the following format: name1:calc1;name2;calc2... where nameN is the name of data column N, and calcN is the calculation to be performed on the values in the column for each time interval. The supported calculations are average, min, max, and sum. The value for this property is configured from a dialog which allows the user to pick a column name and the calculation for that column. If a calculation is not specified for a data column, sum is used. Calculations are not applied to the data table index columns, nor to the timestamp column.
condenseRowsInterval	The time interval at which the cache history is condensed. This property is available when the condenseRowsFlag property is selected. Specify a value using the following format: NNu where NN is a number and u is a single character. Valid characters are as follows: w weeks (7 days) d days h hours m minutes s seconds For example, to specify a ten minute interval: 10m If only a number is entered, it is assumed to be seconds.
condenseRowsRawDataTimeSpan	The time span of raw data kept in the cache history table and, if enabled, its history_combo table. This property is available when the condenseRowsFlag property is selected.

Data Compaction: Secondary (Historian) Properties

compactionType

Select from the following options: None - No compaction. Aggregate - Compact via data aggregation. Displace - Compact via table displacement. You must specify at least one index column via the indexColumnNames property and, where possible, quoteColumnNamesFlag should be selected to preserve column name case. NOTE: Based on your specified compactionRules, use the -smoothcompaction command line option to perform compaction on old data which currently exists in your database from prior executions of the Historian. compactionGroupBy This property applies only if the selected compactionType is Aggregate. Click on the  button to specify the methods used to perform compaction (i.e. sum, count, average, min or max). compactionRules Specify compaction rules. NOTE: If the selected compactionType is Displace, then currently this property only supports the use of one displacement rule. NOTE: These object properties apply to Advanced Historian users only.

Historian Properties
You must specify your Cache definition (.rtv) file as an Historian data configuration (,rtv) file in order use the following object properties.

Property Name	Description
currentTableName	Enter the name of a table in your Historian database in which to store the cache's current data table. If you specify a currentTableName and no table by that name exists in your database, then one will be created for you the first time you run the Historian. On each update of the data attached to the valueTable property, the Historian will create or update corresponding rows in the specified currentTableName in the Historian database. The indexColumnNames property will be used to locate rows to update otherwise, if no indexColumnNames are defined, the Historian will replace the entire table on each update. If the rowsToDeleteTable property is used to delete rows from the cache's current table, then Historian will also delete those rows from the specified currentTableName table in the Historian database. On startup of an RTView application, the specified currentTableName will be queried from the Historian database for initial rows to be loaded into the cache's current table. To prevent this initial data from being loaded, you can run the Display Builder or Display Viewer from a command window and use the -nohistory command line option. NOTE: The currentTableName property is not supported in combination with the Historian's -kdbformat command line option.
databaseName	Name of your Historian database that contains history and/or current tables for this cache. If left blank, the database name RTVHISTORY is assumed. The Extend with SQL option requires that the database specified in this property have a SQL database connection. Or, if this property is blank, there must be a database connection to the default RTVHISTORY database.
historyTableName	Enter the name of a table in your Historian database in which to store the cache history data table. If you specify a historyTableName and no table by that name exists in your database, one is created for you the first time you run the Historian. When rows are appended to the cache history table, the Historian also appends those rows to the specified historyTableName in the Historian database. If you specify a timestampColumnName, the Historian assumes that column is to be used for sorting and purging rows in chronological order and does not append its own timestamp columns to the specified historyTableName table. Before data is stored in the database, the cache schemaTable, if any, is applied. If you specify a historyTableName, RTView applications automatically query the Historian database table for the initial rows to be loaded into the cache history table, provided that: The initialTable property is not attached to data (indicating an explicit query has been configured to load cache history data), and A timestampColumnName is specified (so that it can be used to sort the SQL query result by time). The number of rows loaded by this initial query is limited by the maxNumberOfHistoryRows property. To prevent this initial data from being loaded, you can run the Display Builder or Display Viewer from a command window and use the -nohistory command line option. The Extend with SQL option requires that this property specify the cache database table name. The table specified in this property is used for queries.
quoteColumnNamesFlag	If selected, column names will be quoted in all SQL queries and commands for this cache.

Object Properties

Property Name	Description
anchor	Specifies where to anchor an object in the display.
objName	Name given to facilitate object management via the Object List dialog. Select Tools>Object List.
objX	Plot x-axis position of object.
objY	Plot y-axis position of object.
styleClass	Enables you to apply distinct styles to different instances of the same object class. The  value entered for styleClass must not contain spaces and must not start with rtv.

Double Cache
The Double Cache allows you to cache your scalar (double) data. Attach your input data to the value property.

Cache Properties

cacheName	A unique name for the cache. An entry for this property is required. Caches that do not specify a cacheName, as well as caches with duplicate cacheName properties, will not be created and an error will print to the console. Substitutions defined in a Cache Definition File allow the same file to be specified multiple times with different sets of substitutions. Note that each cacheName defined in that file should contain a substitution, since cache names must be unique. Substitutions must use the following syntax: $subname:subvalue $subname2:subvalue2 If a substitution value contains a single quote, it must be escaped using a / : $filter:Plant=/'Dallas/' If a substitution value contains a space, it must be enclosed in single quotes. Do not escape these single quotes: $subname:subvalue $subname2:'sub value 2'
description	Enter descriptive text which is displayed in the Description column of the Caches table.
timestampColumnName	Specify the name of a timestamp column. If the specified timestampColumnName is not found in the incoming data, a column will be inserted and each row will contain the time that row was received

Cache History Table Properties

historyTimeSpan	Previously named timeSpan, this property specifies the amount of time that rows will be kept in the History table according to their timestamp. Specify the duration in seconds or specify a number followed by a single character indicating the desired time interval (e.g. 15m for 15 minutes). Valid characters are as follows: y years (365 days) M months (31 days) w weeks (7 days) d days h hours m minutes s seconds The historyTimeSpan property only determines the duration of rows kept in the History table by the cache data source. It does not affect database storage, if any, associated with the cache. NOTE: The maxNumberOfHistoryRows property will limit the total number of rows in the History table regardless of the specified historyTimeSpan.
initialTable	Attach this property to a table containing initial values for the cache. This attachment must result in a table with a single column of type double, as well as a timestamp column if timestampColumnName is specified. NOTE: If the specified timestampColumnName is not found in the incoming data, a column will be inserted. Data attached to this property works best if it is only updated once at the startup of RTView. NOTE: A table attached the initialTable property will be modified if you did not include a column with the timestampColumnName and/or if the rowsToDeleteTable property is updated. If other objects in your RTView application are attached to this same table, those objects may also be affected.
maxNumberOfHistoryRows	Previously named maxNumberOfRows, this property specifies the number of rows in the History table. Default is 100. If set to 0, no History table is created and only the Current table will be available in the Table drop down menu in the Attach to Cache Data dialog. The Extend with SQL option requires this property to have a value greater than 0.

Data Properties

resetTrigger	When data values attached to this property receive an update the cache will be cleared.
value	Attach your input data to this property if it is scalar. For tabular input data, select the Table Cache object and attach your input data to the valueTable property.

Historian Properties

Property Name	Description
databaseName	Name of your Historian database that contains history and/or current tables for this cache. If left blank, the database name RTVHISTORY is assumed. The Extend with SQL option requires that the database specified in this property have a SQL database connection. Or, if this property is blank, there must be a database connection to the default RTVHISTORY database.
historyTableName	Enter the name of a table in your Historian database in which to store the cache's history data table. If you specify a historyTableName and no table by that name exists in your database, then one will be created for you the first time you run the Historian. When rows are appended to the cache's history table, the Historian will also append those rows to the specified historyTableName in the Historian database. If you specify a timestampColumnName, the Historian assumes that column will be used for sorting and purging rows in chronological order and will not append its own timestamp columns to the specified historyTableName table. Before data is stored in the database, the cache's schemaTable, if any, is applied. If you specify a historyTableName, RTView applications will automatically query the Historian database table for the initial rows to be loaded into the cache's history table, provided that: The initialTable property is not attached to data (indicating an explicit query has been configured to load cache history data), and A timestampColumnName is specified (so that it can be used to sort the SQL query result by time). The number of rows loaded by this initial query is limited by the maxNumberOfHistoryRows property. To prevent this initial data from being loaded, you can run the Display Builder or Display Viewer from a command window and use the -nohistory command line option. The Extend with SQL option requires that this property specify the cache database table name. The table specified in this property is used for queries.
quoteColumnNamesFlag	If selected, column names will be quoted in all SQL queries and commands for this cache.

Object Properties

Property Name	Description
anchor	Specifies where to anchor an object in the display.
objName	Name given to facilitate object management via the Object List dialog. Select Tools>Object List.
objX	Plot x-axis position of object.
objY	Plot y-axis position of object.
styleClass	Enables you to apply distinct styles to different instances of the same object class. The  value entered for styleClass must not contain spaces and must not start with rtv.