Permalink
Browse files

User Guide - added Filter Encoding reference section

  • Loading branch information...
1 parent 865646c commit 8f5ec57cc52c5c0ccec25b1ab054b5f6cd923173 Martin Davis committed Jan 4, 2013
@@ -0,0 +1,378 @@
+.. _filter_fe_reference:
+
+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 <http://www.opengeospatial.org/standards/filter>`_.
+
+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**.
+
+.. _filter_condition:
+
+Condition
+---------
+
+A condition is a single :ref:`filter_predicate` element,
+or a combination of conditions by :ref:`filter_logical`.
+
+.. _filter_predicate:
+
+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:
+
+.. list-table::
+ :widths: 25 15 60
+
+ * - **Element**
+ - **Required?**
+ - **Description**
+ * - :ref:`filter_expression`
+ - Yes
+ - The first value to compare.
+ Often a ``<PropertyName>``.
+ * - :ref:`filter_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:
+
+.. list-table::
+ :widths: 25 15 60
+
+ * - **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:
+
+.. list-table::
+ :widths: 25 15 60
+
+ * - **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.
+It contains the elements:
+
+.. list-table::
+ :widths: 25 15 60
+
+ * - **Element**
+ - **Required?**
+ - **Description**
+ * - :ref:`filter_expression`
+ - Yes
+ - The value to test
+ * - ``<LowerBoundary>``
+ - Yes
+ - Contains an :ref:`filter_expression` giving the lower bound of the range
+ * - ``<UpperBoundary>``
+ - Yes
+ - Contains an :ref:`filter_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
+ * ``<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:
+
+.. list-table::
+ :widths: 25 15 60
+
+ * - **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:
+
+.. list-table::
+ :widths: 25 15 60
+
+ * - **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:
+
+.. list-table::
+ :widths: 25 15 60
+
+ * - **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).
+
+.. code-block:: xml
+
+ <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.
+
+.. code-block:: xml
+
+ <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].
+
+.. code-block:: xml
+
+ <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>
+
+
+.. _filter_logical:
+
+Logical operators
+-----------------
+
+Logical operators are used to specify
+logical combinations of :ref:`filter_condition` elements
+(which may be either :ref:`filter_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 :ref:`filter_condition` elements.
+
+ * ``<Not>`` - computes the logical negation of the operand
+
+The content for ``<Not>`` is a single operand given by a :ref:`filter_condition` element.
+
+Examples
+^^^^^^^^
+
+* This filter uses ``<And>`` to combine a comparison predicate and a spatial predicate:
+
+.. code-block:: xml
+
+ <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>
+
+
+.. _filter_expression:
+
+Expression
+----------
+
+**Filter expressions** perform computation on 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 :ref:`filter_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
+:ref:`filter_expression` elements providing the values of the function arguments.
+
+See the :ref:`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:
+
+.. list-table::
+ :widths: 25 75
+
+ * - **Type**
+ - **Description**
+ * - Numeric
+ - A string representing a numeric value.
+ * - String
+ - A string value.
+ ``CDATA`` sections may be used to include non-XML compatible text
+ * - Date
+ - A string representing a date.
+ * - Geometry
+ - An element specifying a geometry in GML 3 format.
+
+
+
+
+
+
@@ -14,6 +14,7 @@ Filters can be used in several contexts in GeoServer:
:maxdepth: 1
syntax/
+ filter_reference
ecql_reference
function
function_reference
Oops, something went wrong.

0 comments on commit 8f5ec57

Please sign in to comment.