Filters

Filters are configurable components of GeoEvent Services that filter (remove from the streaming data) GeoEvents that do not satisfy specified criteria. Filters are generally either attribute filters or spatial filters, although Extension GeoEvent product macros such as $DEFINITION_NAME, for example, enable GeoEvent filtering by properties (such as the name of the GeoEvent Definition associated with the current GeoEvent).

Attribute filters

Attribute filters in a GeoEvent Service filter events based on attribute criteria. An attribute filter can be configured with one or more attribute expressions. The logical combination of these expressions represents the criteria a GeoEvent must satisfy to pass through the filter.

The following attribute operators are supported:

• Equal (=)—This operator retains GeoEvents whose attribute values equal a specified value. For example, IdString = 3XAB891
• Not Equal (!=)—This operator retains GeoEvents whose attribute values do not equal a specified value. For example, StatusString != Err.

  Remarque :

  The Equals and Not Equal operators should not be applied to floating point values. For example, do not configure a filter expression like Radius = 3.14159, instead use the Greater Than, Less Than, or other operator.

• Greater Than (>)— This operator retains GeoEvents whose attribute values are greater than a specified value. For example, Speed > 50.
• Greater Or Equal (>=)—This operator retains GeoEvents whose attribute values are greater than or equal to a specified value. For example, Speed >= 50.
• Less Than (<)—This operator retains GeoEvents whose attribute values are less than a specified value. For example, Altitude < 1000.
• Less Or Equal (<=)—This operator retains GeoEvents whose attribute values are less than or equal to a specified value. For example, Altitude <= 1000.

  Remarque :

  The Greater Than, Less Than, and other operators should not be applied to string values. For example do not configure a filter expression like Company > ABC, instead use the Equals or Not Equal operator and incorporate the entire string into the expression.

• IN— This operator retains GeoEvents when a specified field's value exists in a comma-separated list of values. For example, StatusCode IN HK1,HK3,HK5.
• MATCHES—This operator retains GeoEvents when a specified field's value matches a regular expression. For example, StatusCode MATCHES ^HK[135].

  Remarque :

  The specified regular expression is evaluated as either matching or not matching the entire event field value; partial matches are not supported. In the example above, if the StatusCode contained additional characters beyond the single numeric digit, the expression would need to include .* to match any trailing characters in the attribute value.

• EXISTS—This operator retains GeoEvents when a specified field exists in the received event's schema. For example, Geometry EXISTS.
• ISNULL—This operator retains GeoEvents when a specified field contains a null value. For example, Geometry ISNULL.

Remarque :

Checking for NULL strings is not supported. GeoEvent defines a string as empty (a zero-length string) rather than as a null object.

Spatial filters

Spatial filters in a GeoEvent Service filter GeoEvents based on a spatial relationship with a GeoFence. The geometries that specify a GeoFence must be imported into the Extension GeoEvent from a published feature service before a spatial filter can be configured.

The following spatial operators are supported:

• INSIDE—A GeoEvent's geometry is considered to be inside a GeoFence if its geometry is entirely within the area defined by the GeoFence. This operator can determine whether a point associated with a GeoEvent is inside an area of interest.
• OUTSIDE—A GeoEvent's geometry is considered to be outside a GeoFence if its geometry is entirely outside the area defined by the GeoFence. This operator can determine whether a point associated with a GeoEvent is outside an area of interest.

  

• ENTER—A GeoEvent's geometry is considered to have entered a GeoFence if its geometry is now inside the area defined by the GeoFence, when the previous GeoEvent position, from the same track, was outside the GeoFence. After an enter condition is detected and the GeoEvent is allowed to pass through the filter, the tracked object must report at least one event outside the GeoFence before another enter will be recognized.
• EXIT—A GeoEvent's geometry is considered to have exited a GeoFence if its geometry is now outside the area defined by the GeoFence, when the previous GeoEvent position, from the same track, was inside the GeoFence. After an exit condition is detected and the GeoEvent is allowed to pass through the filter, the tracked object must report at least one event inside the GeoFence before another exit will be recognized.

  

Remarque :

The EXISTS and ISNULL attribute operators above are also applicable when a Geometry field is specified as part of a spatial filter's expression.

Typically a set of GeoFences define areas of interest and are imported from a feature service providing polygon features. GeoFences do not always have to represent polygonal areas. They can be imported from point and line features as well.

The spatial operators below are applicable to different types of geometries. These spatial operators return a Boolean, indicating whether or not the described relationship exists between a GeoFence and a GeoEvent's geometry. Some relationships require that a GeoEvent's geometry have the same dimension as the GeoFence to which it is being compared, while others have more flexible dimensional constraints. Many of the spatial operators below are mutually exclusive Clementini operators.

• CONTAINS—A GeoFence is considered to contain a GeoEvent's geometry if its geometry is a subset of the GeoFence's geometry and the intersection of the two geometries is not empty. The Contains operation is the logical opposite of Within; if a GeoFence contains a GeoEvent's geometry, then the GeoEvent's geometry is within the GeoFence.

  

• CROSSES—A GeoFence is considered to cross a GeoEvent's geometry if any portion of their geometries is coincident. Two polylines cross if they share interior points (at least one of which is not an endpoint). A polyline and a polygon cross if they share a polyline or a point on the interior of the polygon that is not equivalent to the entire polyline.

  

• INTERSECTS—A GeoFence intersects a GeoEvent's geometry if the two geometries are not disjointed. The Intersects operator is the logical opposite of the Disjoint operator.
• DISJOINT—A GeoFence and a GeoEvent's geometry are considered disjointed if they do not intersect.

  

• EQUALS—Two geometries are considered equal when their symmetric difference is the empty set. If you were to iterate over each segment in each geometry to compare the segment's type and coordinates, and found they were the same (using the spatial reference's cluster tolerances to determine equality of coordinates), the two geometries would be considered equal.

  

• OVERLAPS—A GeoFence is considered to overlap a GeoEvent's geometry if the two geometries intersect, the intersection is the same dimension of the geometries being compared, and the geometries are not equal.

  

• TOUCHES—A GeoFence is considered to touch a GeoEvent's geometry when the geometries intersect but the intersection of their interiors is empty.

  

• WITHIN—A GeoFence is considered to be within a GeoEvent's geometry if the two geometries intersect and the intersection of their interiors is not empty. The Within operator is the logical opposite of Contains.

  

See IRelationalOperator Interface in the ArcObjects API Reference for .NET for more information on relational operators.

See Managing GeoFences to learn more about working with GeoFences in the Extension GeoEvent.

GeoEvent property filters

Every GeoEvent within the Extension GeoEvent has an associated set of properties such as the GeoEvent Definition used to construct the GeoEvent. Recall that a GeoEvent Definition is a schema that identifies the attribute fields and data types—date, string, integer, and so forth—for the GeoEvent's data. A filter can be configured to filter GeoEvents based on their properties such as their GeoEvent Definition.

When configuring a filter expression, the drop-down for the Field parameter displays a list of field names from available GeoEvent Definitions. At the top of this list are several Extension GeoEvent properties including:

• $OWNER_ID
• $OWNER_URI
• $DEFINITION_NAME
• $DEFINITION_GUID
• $RECEIVED_TIME

Constructing a filter with the following expression would discard any GeoEvents that do not contain the Flights-TcpTextIn GeoEvent Definition name: $DEFINITION_NAME = Flights-TcpTextIn. A filter like this one that is based on a GeoEvent Definition property could be used to filter any GeoEvents that do not adhere to a required schema.

Configuring filters using tags

A tag is a label placed on a particular field of a GeoEvent Definition. Tags are similar to field aliases; they support consistency in expressions when different GeoEvent Definitions associate similar data with different field names. Certain built-in tags identify important Extension GeoEvent fields that contain information such as a TRACK_ID or GEOMETRY.

Once a tag has been created and applied to a particular field of a GeoEvent Definition, filters can reference a field by its tag rather than by the field’s name. This is particularly useful when configuring an attribute filter because it allows a single attribute filter to apply the exact same attribute-based criteria to multiple types of events.

See Managing tags to learn more about using tags in the Extension GeoEvent.

Configuring filters using regular expressions

The MATCHES operator—available when configuring an attribute filter—supports the use of regular expressions to find a pattern within a target field. Regular expression pattern matching can be a powerful tool for data validation. The full scope and syntax of regular expressions cannot be covered within this topic, but the examples below help illustrate their use in GeoEvent filters.

Remarque :

Regular expressions can only be applied to attribute fields of type string.

Remarque :

The specified pattern is matched against the entire string. You cannot enter California to match strings that contain that substring. Specifying a pattern .*California.* accounts for zero or more characters both before and after the substring the filter is supposed to find.

Field value	RegEx pattern	Result
SWA2382	^SWA[0-9]+$	The carat sign (^) anchors the pattern to the beginning of the string, and a dollar sign ($) anchors the pattern to the end of the string. The [0-9]+ portion of the pattern specifies that one or more digits 0 through 9 should be found at the end of the string. Any values in the target field that do not begin with SWA, followed by some number of digits representing a flight number, will be discarded by the filter.
02/15/1973	[0-1][0-9][/][0-3][0-9][/][0-1][0-9][0-9][0-9]	The use of numeric ranges such as 0 through 1, 0 through 3, and 0 through 9 specifies the expected values for a mm/dd/yy date string. Values that do not have a two-digit month followed by a two-digit day and a four-digit year, separated by a slash (/), will be discarded by the filter.
3.14159	^[-+]?[0-9]*\.?[0-9]+$	This pattern verifies that the string in the target field can be interpreted as a numeric value. An asterisk (*) in the RegEx pattern matches zero or more instances of the preceding character; a question mark (?) matches zero or one instances. The backslash means that the '.' is a literal decimal point, not a wildcard (*). The pattern makes a plus (+) or minus (-) sign the integer portion of a floating point value and the literal decimal optional (may occur zero times).

Regular expression examples