Skip to content

Filter Encoding Reference

This is a reference for the Filter Encoding language implemented in GeoServer. The Filter Encoding language uses an XML-based syntax. It is defined by the OGC Filter Encoding standard.

Filters are used to select features or other objects from the context in which they are evaluated. They are similar in functionality to the SQL "WHERE" clause. A filter is specified using a condition.

Condition

A condition is a single Predicate element, or a combination of conditions by Logical operators.

Predicate

Predicates are boolean-valued expressions which compute relationships between values. A predicate is specified by using a comparison operator or a spatial operator. The operators are used to compare properties of the features being filtered to other feature properties or to literal data.

Comparison operators

Comparison operators are used to specify conditions on non-spatial attributes.

Binary Comparison operators

The binary comparison operators are:

  • <PropertyIsEqualTo>
  • <PropertyIsNotEqualTo>
  • <PropertyIsLessThan>
  • <PropertyIsLessThanOrEqualTo>
  • <PropertyIsGreaterThan>
  • <PropertyIsGreaterThanOrEqualTo>

They contain the elements:
Element Required? Description
Expression Yes The first value to compare. Often a <PropertyName>.
Expression Yes The second value to compare

Binary comparison operator elements may include an optional matchCase attribute, with the value true or false. If this attribute is true (the default), string comparisons are case-sensitive. If the attribute is false strings comparisons do not check case.

PropertyIsLike operator

The <PropertyIsLike> operator matches a string property value against a text pattern. It contains the elements:
Element Required? Description
<PropertyName> Yes Contains a string specifying the name of the property to test
<Literal> Yes Contains a pattern string to be matched

The pattern is specified by a sequence of regular characters and three special pattern characters. The pattern characters are defined by the following required attributes of the <PropertyIsLike> element:

  • wildCard specifies the pattern character which matches any sequence of zero or more string characters
  • singleChar specifies the pattern character which matches any single string character
  • escapeChar specifies the escape character which can be used to escape the pattern characters

PropertyIsNull operator

The <PropertyIsNull> operator tests whether a property value is null. It contains the element:
Element Required? Description
<PropertyName> Yes contains a string specifying the name of the property to be tested

PropertyIsBetweeen operator

The <PropertyIsBetween> operator tests whether an expression value lies within a range given by a lower and upper bound (inclusive). It contains the elements:
Element Required? Description
Expression Yes The value to test
<LowerBoundary> Yes Contains an Expression giving the lower bound of the range
<UpperBoundary> Yes Contains an Expression giving the upper bound of the range

Spatial operators

Spatial operators are used to specify conditions on the geometric attributes of a feature. The following spatial operators are available:

Topological operators

These operators test topological spatial relationships using the standard OGC Simple Features predicates:

  • <Intersects> - Tests whether two geometries intersect
  • <Disjoint> - Tests whether two geometries are disjoint (do not interact)
  • <Contains> - Tests whether a geometry contains another one
  • <Within> - Tests whether a geometry is within another one
  • <Touches> - Tests whether two geometries touch
  • <Crosses> - Tests whether two geometries cross
  • <Overlaps> - Tests whether two geometries overlap
  • <Equals> - Tests whether two geometries are topologically equal

These contains the elements:
Element Required? Description
<PropertyName> Yes Contains a string specifying the name of the geometry-valued property to be tested.
GML Geometry Yes A GML literal value specifying the geometry to test against

Distance operators

These operators test distance relationships between a geometry property and a geometry literal:

  • <DWithin>
  • <Beyond>

They contain the elements:
Element Required? Description
<PropertyName> Yes Contains a string specifying the name of the property to be tested. If omitted, the default geometry attribute is assumed.
GML Geometry Yes A literal value specifying a geometry to compute the distance to. This may be either a geometry or an envelope in GML 3 format
<Distance> Yes Contains the numeric value for the distance tolerance. The element may include an optional units attribute.

Bounding Box operator

The <BBOX> operator tests whether a geometry-valued property intersects a fixed bounding box. It contains the elements:
Element Required? Description
<PropertyName> No Contains a string specifying the name of the property to be tested. If omitted, the default geometry attribute is assumed.
<gml:Box> Yes A GML Box literal value specifying the bounding box to test against

Examples

  • This filter selects features with a geometry that intersects the point (1,1).
<Intersects>
  <PropertyName>GEOMETRY</PropertyName>
  <gml:Point>
    <gml:coordinates>1 1</gml:coordinates>
  </gml:Point>
</Intersects>
  • This filter selects features with a geometry that overlaps a polygon.
<Overlaps>
  <PropertyName>Geometry</PropertyName>
  <gml:Polygon srsName="http://www.opengis.net/gml/srs/epsg.xml#63266405">
    <gml:outerBoundaryIs>
      <gml:LinearRing>
         <gml:posList> ... </gml:posList>
      </gml:LinearRing>
    </gml:outerBoundaryIs>
  </gml:Polygon>
 </Overlaps>
  • This filter selects features with a geometry that intersects the geographic extent [-10,0 : 10,10].
<BBOX>
  <PropertyName>GEOMETRY</PropertyName>
  <gml:Box srsName="urn:x-ogc:def:crs:EPSG:4326">
    <gml:coord>
      <gml:X>-10</gml:X> <gml:Y>0</gml:Y>
    </gml:coord>
    <gml:coord>
      <gml:X>10</gml:X> <gml:Y>10</gml:Y>
    </gml:coord>
  </gml:Box>
</BBOX>

Logical operators

Logical operators are used to specify logical combinations of Condition elements (which may be either Predicate elements or other logical operators). They may be nested to any depth.

The following logical operators are available:

  • <And> - computes the logical conjunction of the operands
  • <Or> - computes the logical disjunction of the operands

The content for <And> and <Or> is two operands given by Condition elements.

  • <Not> - computes the logical negation of the operand

The content for <Not> is a single operand given by a Condition element.

Examples

  • This filter uses <And> to combine a comparison predicate and a spatial predicate:
<And>
   <PropertyIsEqualTo>
      <PropertyName>NAME</PropertyName>
      <Literal>New York</Literal>
   </PropertyIsEqualTo>
   <Intersects>
      <PropertyName>GEOMETRY</PropertyName>
      <Literal>
         <gml:Point>
             <gml:coordinates>1 1</gml:coordinates>
         </gml:Point>
      </Literal>
   </Intersects>
</And>

Expression

Filter expressions specify constant, variable or computed data values. An expression is formed from one of the following elements (some of which contain sub-expressions, meaning that expressions may be of arbitrary depth):

Arithmetic operators

The arithmetic operator elements compute arithmetic operations on numeric values.

  • <Add> - adds the two operands
  • <Sub> - subtracts the second operand from the first
  • <Mul> - multiplies the two operands
  • <Div> - divides the first operand by the second

Each arithmetic operator element contains two Expression elements providing the operands.

Function

The <Function> element specifies a filter function to be evaluated. The required name attribute gives the function name. The element contains a sequence of zero or more Expression elements providing the values of the function arguments.

See the Filter Function Reference for details of the functions provided by GeoServer.

Property Value

The <PropertyName> element refers to the value of a feature attribute. It contains a string or an XPath expression specifying the attribute name.

Literal

The <Literal> element specifies a constant value. It contains data of one of the following types:
Type Description
Numeric A string representing a numeric value (integer or decimal).
Boolean A boolean value of true or false.
String A string value. XML-incompatible text may be included by using character entities or <![CDATA[ ]]> delimiters.
Date A string representing a date.
Geometry An element specifying a geometry in GML3 format.

WFS 2.0 namespaces

WFS 2.0 does not depend on any one GML version and thus requires an explicit namespace and schemaLocation for GML. In a GET request, namespaces can be placed on a Filter element (that is, filter= the block below, URL-encoded):

<fes:Filter
        xmlns:fes="http://www.opengis.net/fes/2.0"
        xmlns:gml="http://www.opengis.net/gml/3.2">
    <fes:Not>
        <fes:Disjoint>
            <fes:ValueReference>sf:the_geom</fes:ValueReference>
            <gml:Polygon
                    gml:id="polygon.1"
                    srsName='http://www.opengis.net/def/crs/EPSG/0/26713'>
                <gml:exterior>
                    <gml:LinearRing>
                        <gml:posList>590431 4915204 590430
                            4915205 590429 4915204 590430
                            4915203 590431 4915204</gml:posList>
                    </gml:LinearRing>
                </gml:exterior>
            </gml:Polygon>
        </fes:Disjoint>
    </fes:Not>
</fes:Filter>