User Guide - added Filter Encoding reference section

jericks · Jan 4, 2013 · 8f5ec57 · 8f5ec57
1 parent 865646c
commit 8f5ec57
Show file tree

Hide file tree

Showing 3 changed files with 383 additions and 3 deletions.
diff --git a/doc/en/user/source/filter/filter_reference.rst b/doc/en/user/source/filter/filter_reference.rst
@@ -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.
+
+
+
+
+
+
diff --git a/doc/en/user/source/filter/index.rst b/doc/en/user/source/filter/index.rst
@@ -14,6 +14,7 @@ Filters can be used in several contexts in GeoServer:
    :maxdepth: 1
 
    syntax/
+   filter_reference
    ecql_reference
    function
    function_reference