Click or drag to resize
OSIsoft, LLC

AFSearchFilter Enumeration

This enumeration specifies the valid search filters that are available for an AFSearch based query string.

Namespace:  OSIsoft.AF.Search
Assembly:  OSIsoft.AFSDK (in OSIsoft.AFSDK.dll) Version: 2.10.6.195
Syntax
public enum AFSearchFilter
Members
  Member nameValueDescription
None0 Indicates that no filter is specified.
AllDescendants1

This filter specifies that all descendants including children should be searched. Enabling this filter will make the search slower if the Root filter is also specified. The filter value must be a Boolean value of either or . If not specified, this filter is enabled by default.

This filter was added in PI AF 2016 (2.8.0).

Analysis19

This filter specifies the analysis field search criteria. The filter value is the path to the AFAnalysis.

This filter was added in PI AF 2016 (2.8.0).

AnalysisName34

This filter specifies the analysis name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2016 R2 (2.8.5).

CanBeAcknowledged16

This filter specifies the CanBeAcknowledged field search criteria. The filter value must be a Boolean value of either or .

This filter was added in PI AF 2016 (2.8.0).

Category7

This filter specifies the category field search criteria. The filter value is the path to the AFCategory.

This filter was added in PI AF 2016 (2.8.0).

CategoryName22

This filter specifies the category name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2016 (2.8.0).

Contact26

This filter specifies the contact field search criteria. The filter value is the path to the AFContact.

This filter was added in PI AF 2016 (2.8.0).

ContactName27

This filter specifies the contact name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2016 (2.8.0).

CreationDate36

This filter specifies the CreationDate field search criteria. The filter value must be in a format that can be parsed by the Parse Overload method.

This filter was added in PI AF 2017 (2.9.0).

Description5

This filter specifies the description field search criteria. The filter value is a query string that will accept wildcard characters. Only the first 440 characters of the description will be searched.

This filter was added in PI AF 2016 (2.8.0).

Destination33

This filter specifies the destination field search criteria. The filter value is the path to an AFBaseElement.

This filter was added in PI AF 2016 R2 (2.8.5).

Duration10

This filter specifies the Duration field search criteria. The filter value must be in a format that can be parsed by the Parse Overload method.

This filter was added in PI AF 2016 (2.8.0).

Element20

This filter specifies the element field search criteria. The filter value is the path to the AFElement or a nested query.

This filter was added in PI AF 2016 (2.8.0). Support for nested queries with this filter was added in PI AF 2017 R2 (2.9.5).

ElementName11

This filter specifies the element name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2016 (2.8.0).

ElementReferenceTemplate18

This filter specifies the element reference template field search criteria. The filter value is the path to the AFElementTemplate.

This filter was added in PI AF 2016 (2.8.0).

End9

This filter specifies the end time field search criteria. The filter value must be in a format that can be parsed by the Parse Overload method.

This filter was added in PI AF 2016 (2.8.0).

EventFrame41

This filter specifies the event frame field search criteria. The filter value is a nested query.

This filter was added in PI AF 2017 R2 (2.9.5).

GroupID31

This filter specifies the Group ID search criteria. The filter value must be a Int16 value. This filter was added in version PI AF 2016 R2 (2.8.5).

This filter was added in PI AF 2016 (2.8.0).

ID45

This filter specifies the ID search criteria. The filter value must be a Guid value. This filter was added in version PI AF 2018 (2.10.0).

This filter was added in PI AF 2018 (2.10.0).

InProgress2

This filter specifies the in progress search criteria. The filter value must be a Boolean value of either or .

This filter was added in PI AF 2016 (2.8.0).

IsAcknowledged15

This filter specifies the IsAcknowledged field search criteria. The filter value must be a Boolean value of either or .

This filter was added in PI AF 2016 (2.8.0).

IsAnnotated17

This filter specifies the IsAnnotated field search criteria. The filter value must be a Boolean value of either or .

This filter was added in PI AF 2016 (2.8.0).

IsInternal40

This filter specifies the IsInternal field search criteria. The filter value must be a Boolean value of either or .

This filter was added in PI AF 2017 R2 (2.9.5).

ModifyDate37

This filter specifies the ModifyDate field search criteria. The filter value must be in a format that can be parsed by the Parse Overload method.

Important note Important
The object's ModifyDate is only updated when a change to its configuration is checked in. Most template changes do not update the modify date of the object. An update to an attribute value that is not a configuration item (i.e. its IsConfigurationItem is set to ) will also not update the object's modify date.

This filter was added in PI AF 2017 (2.9.0).

Name4

This filter specifies the name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2016 (2.8.0).

OwnerName46

This filter specifies the owner name field search criteria.

This filter was added in PI AF 2018 R2 (2.10.5).

Parent44

This filter specifies the parent field search criteria. It only searches the primary parent. The filter value is a nested query.

This filter was added in PI AF 2017 R2 (2.9.5).

PlugIn42

This filter specifies the PlugIn field search criteria. The filter value must either be blank or the path to the AFPlugIn. The type of AFPlugIn required will depend on the type of AFSearch:

This filter was added in PI AF 2017 R2 (2.9.5).

PlugInName43

This filter specifies the PlugIn name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2017 R2 (2.9.5).

ReferenceType23

This filter specifies the reference type field search criteria between the specified Root filter object and the returned object. If the Root filter object is not specified, then the AFDatabase is used. The filter value is the path to the AFReferenceType.

This filter was added in PI AF 2016 (2.8.0).

Root3

This filter specifies the root (or any parent) to begin the search on. The filter value is the path to the AFObject. Specifying this filter with the AllDescendants filter enabled will cause the search to be slower.

This filter was added in PI AF 2016 (2.8.0).

Sandbox24

This filter specifies that the sandbox should be searched in the server for changes that the user has saved but not checked in. Including this filter will make the search slower. The filter value must be a Boolean value of either or .

This filter was added in PI AF 2016 (2.8.0).

Severity14

This filter specifies the severity field search criteria. The filter value must be one of the Severity enumeration values.

This filter was added in PI AF 2016 (2.8.0).

SortField29

This filter specifies the field that is used to sort the returned search results. The filter value must be one of the AFSortField enumeration values. If not specified, the default sort order for the object type is used (e.g. StartTime for AFEventFrame and Name for most other types).

This filter was added in PI AF 2016 (2.8.0).

SortOrder30

This filter specifies the order of the returned search results. The filter value must be one of the AFSortOrder enumeration values. If not specified, the default sort order of Ascending is used.

This filter was added in PI AF 2016 (2.8.0).

Source32

This filter specifies the source field search criteria. The filter value is the path to an AFBaseElement.

This filter was added in PI AF 2016 R2 (2.8.5).

Start8

This filter specifies the start time field search criteria. The filter value must be in a format that can be parsed by the Parse Overload method.

This filter was added in PI AF 2016 (2.8.0).

Status28

This filter specifies the status field search criteria. The filter value must be one of the AFStatus enumeration values.

This filter was added in PI AF 2016 (2.8.0).

Target25

This filter specifies the target field search criteria. The filter value is the path to the AFObject.

This filter was added in PI AF 2016 (2.8.0).

TargetName35

This filter specifies the target name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2017 (2.9.0).

Template6

This filter specifies the template field search criteria. The filter value is the path to the AFElementTemplate or the AFAnalysisTemplate.

This filter was added in PI AF 2016 (2.8.0).

TemplateName21

This filter specifies the template name field search criteria. The filter value is a query string that will accept wildcard characters.

This filter was added in PI AF 2017 (2.9.0).

TimeContext38

This filter specifies an AFTime context or the start of an AFTimeRange context to be used when evaluating attribute value filters. The filter value must be in a format that can be parsed by the Parse Overload method.

When the time context filter is not specified, then the database's QueryDate will be used when evaluating the attribute value filters if it is not MaxValue. When the database's QueryDate is set to MaxValue, then the current time will be used as the time context.

This filter was added in PI AF 2017 (2.9.0).

TimeContextEnd39

This filter specifies the end of an AFTimeRange context to be used when evaluating attribute value filters. The TimeContext filter specifies the start of the time context range. The filter value must be in a format that can be parsed by the Parse Overload method.

When the time context filter is not specified, then the database's QueryDate will be used when evaluating the attribute value filters if it is not MaxValue. When the database's QueryDate is set to MaxValue, then the current time will be used as the time context.

This filter was added in PI AF 2017 (2.9.0).

Type12

This filter specifies the element, notification contact, or attribute value type field search criteria. The filter's value must be one of the AFElementType, AFNotificationContactType, or TypeCode enumeration values.

This filter was added in PI AF 2016 (2.8.0).

Value13

This filter specifies the attribute value search criteria for the previously specified Template filter object. The filter value will define an AFAttributeValueQuery to be used in the search. If the attribute's are configured to use a data reference and the values are not captured, then including this filter will make the search slower.

The TimeContext and TimeContextEnd filters can be used to specify a time context to be used when evaluating the attribute values.

This filter was added in PI AF 2016 (2.8.0).

Remarks

This enumeration is used to specify the search token's Filter. Several of the filter values are a query string.

The string value of a filter can be enclosed in single quotes ('), double quotes ("), or without quotes. The filter string value can include regular characters and wildcard characters. Regular characters must match exactly the characters specified in the filter value. Wildcard characters can be matched with arbitrary fragments of the filter value. Wildcard characters can be escaped using the single backslash (\) character.

When the filter value is specified within either single or double quotes, the single backslash (\) character is treated as a literal character unless followed by a wildcard character, a single quote ('), or a double quote ("). When specified within quotes, two quote characters that match the starting quote character are treated as a single quote character (e.g. '' is treated as a one single quote character ' if the filter value starts with a single quote). When the filter value is specified without quotes, the backslash character is always used to escape the next character. Therefore you must use a double backslash (\\) to match a single backslash when not using quotes around the filter value.

The wildcard characters used in the string value of a filter have the following rules:

  • If an empty string is specified as part of a Name search filter, then everything will be matched. Otherwise, an exact match on empty string or default value for the filter is performed if an empty string is specified.
  • If no wildcards, then an exact match on the query string is performed.
  • Wildcard * can be placed anywhere in the query string and matches zero or more characters.
  • Wildcard ? can be placed anywhere in the query string and matches exactly one character.
  • One character in a set of characters are matched by placing them within [ ]. For example, a[bc] would match 'ab' or 'ac', but it would not match 'ad' or 'abd'.
  • One character in a set of characters are not matched by placing them within [! ]. For example, a[!bc] would match 'ad', but it would not match 'ab', 'ac', or 'abd'.
  • A character in a range of characters from first to last are matched using the following syntax: [first - last]. For example, a[a-c] would match 'aa', 'ab', or 'ac', but it would not match 'ad' or 'abc'.

The following chart shows which filters are supported by each AFSearch class.

The Type property of the attribute template determines the type of value to be queried, therefore the type must be defined and not set to a type of Object. Any AFAttributeTemplate with a DefaultUOM specified must be of type Single or Double. If a DefaultUOM is not specified in the template for one of these types, then the search will be performed using the specified attribute value as being in the canonical units-of-measure which could cause unexpected results to be returned. The following table shows which AFSearchOperator is supported for each type of value being queried:

TypeEqualNotEqualLessThanGreaterThanLessThanOrEqualGreaterThanOrEqualIn
BooleanYesYesNoNoNoNoYes
UInt64YesYesNoNoNoNoYes
StringYesYesNoNoNoNoYes
GuidYesYesNoNoNoNoYes
SingleYesYesYesYesYesYesNo
DoubleYesYesYesYesYesYesNo
All OthersYesYesYesYesYesYesYes

When the Type property of the AFAttributeTemplate is String, search performance can be improved by marking the AFAttributeTemplate as being indexed by setting the IsIndexed property. Also, the following restrictions are placed on the string length of the attribute value used in the query:

IsIndexedOperatorLength Limit
Equal or NotEqual40 characters
In40 characters
Equal or NotEqualNo limit
In4096 characters when using PI AF Server 2.6 or greater; otherwise 40 characters

Version Information

AFSDK

Supported in: 2.10.5, 2.10, 2.9.5, 2.9, 2.8.5, 2.8, 2.7.5
See Also
Enabling Operational Intelligence