Copy Page

You are not logged in. Any changes you make will be marked as anonymous. You may want to Log In if you already have an account. You can also Sign Up for a new account.

<p>This document describes the new query language, called <strong>ECQL</strong>. It is a CQL Like language which offers a more flexible syntax in order to support all filter and expression possibilities.</p>

<h3>ECQL Grammar</h3>

<p>In this section are presented the ECQL's syntax rules. EBNF metalanguage is used to describe the grammar.</p>

<h5>Search conditions</h5>

&lt;sequence of search conditions> ::=
 			&lt;search condition>
 		       |&lt;sequence of search conditions> &lt;semicolon> &lt;search condition>

&lt;search condition> ::= &lt;boolean value expression>

</pre></td></tr></table>

<h5>Boolean Predicate</h5>

&lt;boolean value expression> ::=
    &lt;boolean term>
    | &lt;boolean value expression> OR &lt;boolean term>

&lt;boolean term> ::=
    &lt;boolean factor>
    | &lt;boolean term> "AND" &lt;boolean factor>

&lt;boolean factor> ::= [ "NOT" ] &lt;boolean primary>

</pre></td></tr></table>

<h5>Boolean Primary Predicates</h5>

&lt;boolean primary> ::=
    &lt;predicate>
    | &lt;left parent> &lt;search condition> &lt;right parent>
    | &lt;left bracket> &lt;search condition> &lt;right bracket>

</pre></td></tr></table>

<h5>Comparison Predicate</h5>

&lt;comparison predicate> ::= &lt;expression> &lt;comp op> &lt;expression>

</pre></td></tr></table>

<h5>Like Text Predicate</h5>

&lt;character pattern> ::= &lt;character string literal>

(* pattern examples :
        attribute like '%contains_this%'
        attribute like 'begins_with_this%'
        attribute like '%ends_with_this'
        attribute like 'd_ve' will match 'dave' or 'dove'
        attribute not like '%will_not_contain_this%'
        attribute not like 'will_not_begin_with_this%'
        attribute not like '%will_not_end_with_this' *)

</pre></td></tr></table>

<h5>Null Predicate</h5>

&lt;null predicate> ::= &lt;expression> "IS" [ "NOT" ] "NULL"

</pre></td></tr></table>

<h5>Existence Predicate</h5>

</pre></td></tr></table>

<h5>Between Predicate</h5>

</pre></td></tr></table>

<h5>Temporal Predicate</h5>

&lt;date-time expression ::= &lt;date-time> | &lt;period>

</pre></td></tr></table>

<h5>ID Predicate</h5>

<p>Deprecated Syntax</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;id predicate> ::= [ "NOT" ] "IN" "(" &lt;id> {"," &lt;id> } ")"
&lt;id> ::=  &lt;character string literal>
</pre></td></tr></table>
<p>New Syntax (since 2.7.rc1)</p>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;id predicate> ::= [ "NOT" ] "IN" "(" &lt;id> {"," &lt;id> } ")"
&lt;id> ::=  &lt;character string literal> | &lt;integer literal> 
</pre></td></tr></table>

<h5>IN Predicate</h5>

<h5>INCLUDE/EXCLUDE Predicate</h5>

<h5>Expression</h5>

&lt;term> ::=  &lt;factor> { &lt;multiplication operator> &lt;factor> }
&lt;multiplication operator> ::= &lt;asterisk> | &lt;solidus>

&lt;factor> ::=
	  &lt;function>
	| &lt;literal>
	| &lt;attribute>
	| ( &lt;expression> )
	| [ &lt;expression> ]

&lt;function> ::= &lt;identifier> "(" ( &lt;function arguments> ("," &lt;function arguments> )* )? ")"

&lt;function arguments> ::= &lt;literal> | &lt;attribute> | &lt;expression>

&lt;literal> ::= &lt;signed numeric literal>| &lt;general literal>

&lt;signed numeric literal> ::= [ &lt;sign> ] &lt;unsigned numeric literal>

&lt;general literal> ::=
    &lt;character string literal>
    | &lt;boolean literal>
    | &lt;geography literal

&lt;boolean literal> ::= "TRUE" | "FALSE"

</pre></td></tr></table>

<h5>Spatial Predicate</h5>

&lt;geometry predicate> ::= &lt;geoop name>&lt;georoutine argument list>
	| &lt;expression>&lt;relgeoop name>&lt;relgeoop argument list>
	| BBOX &lt;bbox argument list>

&lt;relgeoop name> ::= "DWITHIN" | "BEYOND"

&lt;relgeoop argument list> ::= "(" &lt;expression> "," &lt;expression> "," &lt;tolerance> ")"

&lt;tolerance> ::=&lt;unsigned numeric literal>&lt;comma>&lt;distance units>

&lt;distance units> ::= = "feet" | "meters" | "statute miles" | "nautical miles" | "kilometers"

</pre></td></tr></table>

bbox argument list> ::= "(" &lt;attribute>"," &lt;min X>"," &lt;min Y>"," &lt;max X>"," &lt;max Y> ["," &lt;crs>]")"
	| "(" &lt;expression>"," &lt;min X>"," &lt;min Y>"," &lt;max X>"," &lt;max Y> ["," &lt;crs>] ")"
        | "(" &lt;expression>, &lt;expression> ")"

&lt;min X> ::= &lt;signed numerical literal>
&lt;min Y> ::= &lt;signed numerical literal>
&lt;max X> ::= &lt;signed numerical literal>
&lt;max Y> ::= &lt;signed numerical literal>
&lt;crs> ::=  ... (* default: EPSG:4326. *)

</pre></td></tr></table>

<h5>Geometry Literal</h5>

&lt;Point Tagged Text> ::= POINT &lt;Point Text>

&lt;LineString Tagged Text> ::= LINESTRING &lt;LineString Text>

&lt;Polygon Tagged Text> ::= POLYGON &lt;Polygon Text>

&lt;MultiPoint Tagged Text> ::= MULTIPOINT &lt;Multipoint Text>

&lt;MultiLineString Tagged Text> ::= MULTILINESTRING &lt;MultiLineString Text>

&lt;MultiPolygon Tagged Text> ::= MULTIPOLYGON &lt;MultiPolygon Text>

&lt;GeometryCollection Tagged Text> ::=GEOMETRYCOLLECTION &lt;GeometryCollection Text>

&lt;Point Text> := EMPTY | &lt;left paren> &lt;Point> &lt;right paren>
&lt;Point> := &lt;x>&lt;space>&lt;y>
&lt;x> := numeric literal
&lt;y> := numeric literal
&lt;LineString Text> := EMPTY | &lt;left paren> &lt;Point> \{&lt;comma>&lt;Point >\}...&lt;right paren>
&lt;Polygon Text> := EMPTY | &lt;left paren>&lt;LineString Text>\{&lt;comma>&lt;LineString Text> \}...&lt;right paren&gt;
&lt;Multipoint Text> := EMPTY | &lt;left paren>&lt;Point Text>\{&lt;comma>&lt;Point Text >\}...&lt;right paren>
&lt;MultiLineString Text> := EMPTY | &lt;left paren>&lt;LineString Text>\{&lt;comma>&lt;LineString Text>\}...&lt;right paren>
&lt;MultiPolygon Text> := EMPTY | &lt;left paren>&lt;Polygon Text>\{&lt;comma>&lt;Polygon Text>\}...&lt;right paren>
&lt;GeometryCollection Text> := EMPTY | &lt;left paren>&lt;Geometry Tagged Text>\{&lt;comma>&lt;Geometry Tagged Text>\}...&lt;right paren>
&lt;Envelope Tagged Text> ::= ENVELOPE &lt;Envelope Text>

&lt;Envelope Text> ::= EMPTY |
    &lt;left paren>&lt;WestBoundLongitude>&lt;comma>
        &lt;EastBoundLongitude>&lt;comma>
        &lt;NorthBoundLatitude>&lt;comma>
        &lt;SouthBoundLatitude>&lt; &lt;right paren>

&lt;WestBoundLongitude> ::= &lt;numeric literal>
&lt;EastBoundLongitude> ::= &lt;numeric literal>
&lt;NorthBoundLatitude> ::= &lt;numeric literal>
&lt;SouthBoundLatitude> ::= &lt;numeric literal>
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;date-time> ::= &lt;full-date> T &lt;UTC-time>
&lt;full_date> ::= &lt;date-year> &lt;date-month> &lt;date-day>
&lt;date-year> ::= &lt;digit>&lt;digit>&lt;digit>&lt;digit>
&lt;date-month> ::= &lt;digit>&lt;digit>
&lt;date-day> ::= &lt;digit>&lt;digit>
&lt;UTC-time> ::= &lt;time-hour> : &lt;time-minute> : &lt;time-second> Z
&lt;time-hour> ::= &lt;digit>&lt;digit>
&lt;time-minute> ::= &lt;digit>&lt;digit>
&lt;time-second> ::= &lt;digit>&lt;digit>[.&lt;digit>...]
&lt;duration> ::= P &lt;dur-date> | T&lt;dur-time>
&lt;dur-date> ::= &lt;dur-day> | &lt;dur-month> | &lt;dur-year> [&lt;dur-time>]
&lt;dur-day> ::= &lt;digit>... D
&lt;dur-month> ::= &lt;digit>... M [&lt;dur-day>]
&lt;dur-year> ::= &lt;didit>... Y [&lt;dur-month>]
&lt;dur-time> ::= &lt;dir-hour> | &lt;dur-minute> | &lt;dur-second>
&lt;dur-hour> ::= &lt;digit>... H [&lt;dur-minute>]
&lt;dur-minute> ::= &lt;digit>... M [&lt;dur-second>]
&lt;dur-second> ::= &lt;digit>... S
&lt;period> ::=
    &lt;date-time> / &lt;date-time>
    | &lt;date-time> / &lt;duration>
    | &lt;duration> / &lt;date-time>
</pre></td></tr></table>

<h5>Lexical Rules </h5>

&lt;SQL terminal character> ::= &lt;SQL language character>
&lt;SQL language character> ::= &lt;simple Latin letter>

| &lt;digit>
| &lt;SQL special character>
&lt;simple Latin letter> ::= &lt;simple Latin upper case letter>
                           | &lt;simple Latin lower case letter>
&lt;simple Latin upper case letter> ::=
       A | B | C | D | E | F | G | H | I | J | K | L | M | N | O
       | P | Q | R | S | T | U | V | W | X | Y | Z
&lt;simple Latin lower case letter> ::=
       a | b | c | d | e | f | g | h | i | j | k | l | m | n | o
       | p | q | r | s | t | u | v | w | x | y | z
&lt;digit> ::=
       0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;SQL special character> ::= &lt;space>
                           | &lt;double quote>
                           | &lt;percent>
                           | &lt;ampersand>
                           | &lt;quote>
                           | &lt;left paren>
                           | &lt;right paren>
                           | &lt;asterisk>
                           | &lt;plus sign>
                           | &lt;comma>
                           | &lt;minus sign>
                           | &lt;period>
                           | &lt;solidus>
                           | &lt;colon>
                           | &lt;semicolon>
                           | &lt;less than operator>
                           | &lt;equals operator>
                           | &lt;greater than operator>
                           | &lt;question mark>
                           | &lt;left bracket>
                           | &lt;right bracket>
                           | &lt;circumflex>
                           | &lt;underscore>
                           | &lt;vertical bar>
                           | &lt;left brace>
                           | &lt;right brace>
&lt;space> ::= /*space character in character set in use
              In ASCII it would be 40*/
&lt;double quote> ::= "
&lt;percent> ::= %
&lt;ampersand> ::= &amp;
&lt;quote> ::= '
&lt;left paren> ::= (
&lt;right paren> ::= )
&lt;asterisk> ::= *
&lt;plus sign> ::= +
&lt;comma> ::= ,
&lt;minus sign> ::= -
&lt;period> ::= .
&lt;solidus> ::= /
&lt;colon> ::= :
&lt;semicolon> ::= ;
&lt;less than operator> ::= &lt;
&lt;equals operator> ::= =
&lt;greater than operator> ::= >
&lt;question mark> ::= ?
&lt;left bracket> ::= [
&lt;right bracket> ::= ]
&lt;circumflex> ::= ^
&lt;underscore> ::= _
&lt;vertical bar> ::= |
&lt;left brace> ::={
&lt;right brace> ::=}
&lt;separator> ::= { &lt;comment> | &lt;space> | &lt;newline> }...
/* The next section of the BNF defines the tokens available to the
   language. I have deleted the concepts of bit string, hex string and
   national character string literal. Keywords have been added to support the
   geo literals. */
&lt;token> ::= &lt;nondelimiter token>
            | &lt;delimiter token>
&lt;nondelimiter token> ::= &lt;regular identifier>
                        | &lt;key word>
                        | &lt;unsigned numeric literal>

</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;regular identifier> ::= &lt;identifier body>
                        | &lt;double quote> {"any character"} &lt;double quote>
&lt;identifier body> ::= &lt;identifier start> [ { &lt;underscore> | &lt;identifier part> }... ]
&lt;identifier start> ::= &lt;simple latin letter>
&lt;identifier part> ::= &lt;identifier start>
                     | &lt;digit>
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;key word> ::= &lt;reserved word>
&lt;reserved word> ::= NOT | AND | OR | LIKE |
                    IS | NULL |
                    EXISTS | DOES-NOT-EXIST |
                    DURING | AFTER | BEFORE
                    IN | INCLUDE | EXCLUDE |
                    TRUE | FALSE |
                    EQUALS | DISJOINT | INTERSECTS | TOUCHES | CROSSES | WITHIN | CONTAINS| OVERLAPS | RELATE | DWITHIN | BEYOND |
                    POINT | LINESTRING | POLYGON | 
                    MULTIPOINT | MULTILINESTRING | MULTIPOLYGON | GEOMETRYCOLLECTION
</pre></td></tr></table>

<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;unsigned numeric literal> ::= &lt;exact numeric literal>
                              | &lt;approximate numeric literal>
&lt;exact numeric literal> ::=
                &lt;unsigned integer> [&lt;period>[&lt;unsigned integer> ] ]
                | &lt;period> &lt;unsigned integer>
&lt;unsigned integer> ::= &lt;digit>...
&lt;approximate numeric literal> ::= &lt;mantissa> E &lt;exponent>
&lt;mantissa> ::= &lt;exact numeric literal>
&lt;exponent> ::= &lt;signed integer>
&lt;signed integer> ::= [ &lt;sign> ] &lt;unsigned integer>
&lt;sign> ::= &lt;plus sign> | &lt;minus sign>
&lt;character string literal> ::=
      &lt;quote> [ &lt;character representation>... ] &lt;quote>
&lt;character representation> ::= &lt;nonquote character> | &lt;quote symbol>
&lt;quote symbol> ::= &lt;quote>&lt;quote>
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>

/*End of non delimiter tokens*/
/* I have limited the delimiter tokens by eliminating, interval strings
and delimited identifiers BNF and simplifying the legal character set to
the characters to a single set so no identification of character set would
be needed decision. */

&lt;delimiter token> ::= &lt;character string literal>
                     | &lt;SQL special character>
                     | &lt;not equals operator>
                     | &lt;greater than or equals operator>
                     | &lt;less than or equals operator>
                     | &lt;concatenation operator>
                     | &lt;double greater than operator>
                     | &lt;right arrow>
                     | &lt;left bracket>
                     | &lt;right bracket>
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>
&lt;character string literal> ::=
                &lt;quote> [ &lt;character representation>... ] &lt;quote>
&lt;character representation> ::= &lt;nonquote character> | &lt;quote symbol>
&lt;quote symbol> ::= &lt;quote>&lt;quote>
&lt;not equals operator> ::= &lt;&gt;
&lt;greater than or equals operator> ::= >=
&lt;less than or equals operator> ::= &lt;=
</pre></td></tr></table>
<table class="wysiwyg-macro" data-macro-name="noformat" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e25vZm9ybWF0fQ&amp;locale=en_GB&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre>

/*The following section is intended to give context for identifier and
namespaces. It assumes that the default namespace is specified in the
query request and does not allow any overrides of the namepace */
&lt;identifier> ::=
&lt;identifier start [ { &lt;colon> | &lt;identifier part> }... ]
&lt;identifier start> ::= &lt;simple Latin letter>
&lt;identifier part> ::= &lt;simple Latin letter> | &lt;digit>
&lt;attribute name> ::= &lt;simple attribute name> | &lt;compound attribute name>
&lt;simple attribute name> ::= &lt;identifier>
&lt;compound attribute name> ::= &lt;identifier>&lt;period>
                              [{&lt;identifier>&lt;period>}...]
                              &lt;simple attribute name>

</pre></td></tr></table>

&lt;integer literal> ::= ...

&lt;floating literal> ::= ...

&lt;boolean literal> ::= TRUE | FALSE

</pre></td></tr></table>

<h3>ECQL Model</h3>

<p>This section presents the UML model which describe the interface and implementation of ECQL parser.</p>

<h5>Interface</h5>
<p>This diagram presents the package interface. The parser's methods perform the parsing of ECQL predicates and expressions and builds the filter.</p>

<p><img class="confluence-embedded-image" src="/download/attachments/230400678/org.geotools.filter.text.ecql-interface+details.jpg?version=1&amp;modificationDate=1368934558048" data-image-src="/download/attachments/230400678/org.geotools.filter.text.ecql-interface+details.jpg?version=1&amp;modificationDate=1368934558048" data-linked-resource-id="230565068" data-linked-resource-type="attachment" data-linked-resource-default-alias="org.geotools.filter.text.ecql-interface details.jpg" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="230400678" title="null > org.geotools.filter.text.ecql-interface details.jpg"></p>

<h5>Implementation</h5>

<p>Below, the figure shows the principal class of the parser and build process implementation. ECQLParser does a top down analysis of the input string and makes the parsing tree. Each time ECQLParser builds a node, it calls the ECQLCompiler, which implements the semantic actions related and builds the product or subproduct required to make the Filters and Expressions at the end of the parsing process.</p>

<p><img class="confluence-embedded-image confluence-thumbnail" src="/download/thumbnails/230400678/org.geotools.filter.text.ecql-implementation.jpg?version=1&amp;modificationDate=1368934558071" data-image-src="/download/attachments/230400678/org.geotools.filter.text.ecql-implementation.jpg?version=1&amp;modificationDate=1368934558071" data-linked-resource-id="230565069" data-linked-resource-type="attachment" data-linked-resource-default-alias="org.geotools.filter.text.ecql-implementation.jpg" data-base-url="http://docs.codehaus.org" data-linked-resource-container-id="230400678" title="null > org.geotools.filter.text.ecql-implementation.jpg"></p>