Specifies filtering criteria on a data item. A filter limits the scope of collected data for a single data item in a view. Filters are optional.
hs_create_filter view_name, data_item_name, data_item_stat, filter_type, value_spec
name of the view that contains the data item to filter.
the data item to which the filter applies. If the data item contains embedded spaces, surround it with quotation marks.
statistic type for data_item_name. The data_item_name and data_item_stat combination must exist in the view definition. Surround the statistic type with quotation marks.
type of filter to use. Valid values are:
eq – passes values that match any of a list of values. That is, a value passes the filter if it equals the first filter value, or the second filter value, or any other value in the list. Specify the list of values in the value_spec parameter.
neq – passes values that are not equal to any value in a list of values. That is, a value passes the filter if it is not equal to the first filter value, not equal to the second filter value, and not equal to any other value in the list. Specify the list of values in the value_spec parameter.
range – passes values that fall inside a range of values. Specify the ranges in the value_spec parameter.
top – passes a specified number of values that are the highest values received for the data item during a sample interval. For example, a top 10 filter passes the 10 rows of a sample that have the highest values for the data item.
specifies values for the filter tests. The syntax depends on the value of filter_type:
If filter_type is |
value_spec syntax is |
|---|---|
eq or neq |
value1[, value2]... See “Using wildcards” for information about using a wildcard character (%) when valuen is a character string. See “Specifying filters on object name and procedure name” for information on specifying a value for the Object Name and Procedure Name data items. |
range |
To specify values greater than or equal to to a low bound: low,value To specify values less than or equal to a high bound: high,value To specify values greater than or equal to a low bound and less than or equal to a high bound: low,value1,high,value2 See “Specifying filters on object name and procedure name” for information on specifying a value for the Object Name and Procedure Name data items. If you are specifying both an upper and lower bound for either of these data items, each bound must have the same number of subcomponents. |
top |
value where value is the number of items to be passed. It must be greater than zero. |
This example creates a filter for a view named Page I/O. The view contains the Page I/O data item with a “Value for Session” statistic type. The example limits the rows recorded for a sample to the 20 rows that have the highest total number of Page I/Os for the recording session to date.
hs_create_filter PageIO,"Page I/O","Value for Session",top,20
This section contains more information on:
Filters limit the amount of data that Historical Server records. Each filter applies to one data item in the view. Each data item can have only one filter applied to it.
If multiple data items in a view have filters, Historical Server records data that satisfies all of the individual filters. Effectively, the Boolean AND operation is applied to the values of the various filters.
If the top filter is in effect for a data item and another filter is in effect for a second data item, some of the values passed by the top filter may be eliminated by the other filter. The result is that less that specified top n values are returned.
The wildcard character is the percent sign (%). When filter_type is eq or neq, you can use the wildcard in value_spec for data items that return character strings.The wildcard matches any string of zero or more characters. The wildcard can appear anywhere within the filter value (beginning, end, or anywhere in between). Only a single instance of the wildcard can appear in value_spec.
An exception to the single instance rule for the wildcard pertains to the Object Name and Procedure Name data items. In those multi-component data items, you can use a single instance of the wildcard in each component. See “Specifying filters on object name and procedure name” for more information.
When filter_type is range, you cannot use the wildcard character in value_spec.
The Object Name and Procedure Name data items accept multi-component values in value_spec when filter_type is eq, neq, and range. These composite filter values can use the following name forms, where object_name is either a table name or a stored procedure name:
object_name
owner_name.object_name
database_name.owner_name.object_name
If filter_type is eq or neq,
each component can contain a single instance of the wildcard character
(%). The wildcard can be used in place of the entire component.
For example, a value_spec of %.%.authors for
the data_item Object Name sets a filter
that returns the authors table in all databases,
regardless of owner. See “Using wildcards” for more information about the
wildcard character.
If filter_type is range with both upper and lower bounds, the two bounds must have the same number of subcomponents.
Some specific considerations for designing filters using these component data items follow:
If database_name is a component of a composite filter value for an “Object Name” data item, a “Database Name” data item also must be present in the view.
If owner_name is a subcomponent of any composite filter value for an “Object Name” data item, an “Owner Name” data item also must be present in the view.
If database_name is a subcomponent of any composite filter value for a “Procedure Name” data item, a “Procedure Name” data item also must be present in the view.
If owner_name is a component of any composite filter value for a “Procedure Name” data item, a “Procedure Owner Name” data item also must be present in the view.
