diff -r 4ac19f288149 -r 3c9dfc6e820b doc/book/en/annexes/rql/language.rst --- a/doc/book/en/annexes/rql/language.rst Thu Jul 07 17:06:50 2011 +0200 +++ b/doc/book/en/annexes/rql/language.rst Thu Jul 07 18:20:23 2011 +0200 @@ -6,6 +6,7 @@ ---------- .. _RQLKeywords: + Reserved keywords ~~~~~~~~~~~~~~~~~ @@ -20,6 +21,7 @@ .. _RQLCase: + Case ~~~~ @@ -33,6 +35,7 @@ .. _RQLVariables: + Variables and typing ~~~~~~~~~~~~~~~~~~~~ @@ -63,11 +66,12 @@ * `identity`: relation to use to tell that a RQL variable is the same as another when you've to use two different variables for querying purpose. On the - opposite it's also useful together with the `NOT`_ operator to tell that two + opposite it's also useful together with the :ref:`NOT` operator to tell that two variables should not identify the same entity .. _RQLLiterals: + Literal expressions ~~~~~~~~~~~~~~~~~~~ @@ -88,10 +92,12 @@ .. _RQLOperators: + Operators ~~~~~~~~~ .. _RQLLogicalOperators: + Logical operators ````````````````` :: @@ -102,6 +108,7 @@ operators (see :ref:`RQLOperatorsPriority`). .. _RQLMathematicalOperators: + Mathematical operators `````````````````````` :: @@ -112,6 +119,7 @@ .. _RQLComparisonOperators: + Comparison operators ```````````````````` :: @@ -138,6 +146,7 @@ .. _RQLStringOperators: + String operators ```````````````` :: @@ -178,6 +187,7 @@ .. _RQLOperatorsPriority: + Operators priority `````````````````` @@ -191,6 +201,7 @@ .. _RQLSearchQuery: + Search Query ~~~~~~~~~~~~ @@ -427,6 +438,7 @@ .. _RQLFunctions: + Available functions ~~~~~~~~~~~~~~~~~~~ @@ -434,89 +446,94 @@ nativly by the framework. Notice that cubes may define additional functions. .. _RQLAggregateFunctions: + Aggregate functions ``````````````````` -+------------------------+----------------------------------------------------------+ -| :function:`COUNT` | return the number of rows | -+------------------------+----------------------------------------------------------+ -| :function:`MIN` | return the minimum value | -+------------------------+----------------------------------------------------------+ -| :function:`MAX` | return the maximum value | -+------------------------+----------------------------------------------------------+ -| :function:`AVG` | return the average value | -+------------------------+----------------------------------------------------------+ -| :function:`SUM` | return the sum of values | -+------------------------+----------------------------------------------------------+ -| :function:`COMMA_JOIN` | return each value separated by a comma (for string only) | -+------------------------+----------------------------------------------------------+ ++--------------------+----------------------------------------------------------+ +| :func:`COUNT` | return the number of rows | ++--------------------+----------------------------------------------------------+ +| :func:`MIN` | return the minimum value | ++--------------------+----------------------------------------------------------+ +| :func:`MAX` | return the maximum value | ++--------------------+----------------------------------------------------------+ +| :func:`AVG` | return the average value | ++--------------------+----------------------------------------------------------+ +| :func:`SUM` | return the sum of values | ++--------------------+----------------------------------------------------------+ +| :func:`COMMA_JOIN` | return each value separated by a comma (for string only) | ++--------------------+----------------------------------------------------------+ All aggregate functions above take a single argument. Take care some aggregate functions (e.g. :keyword:`MAX`, :keyword:`MIN`) may return `None` if there is no result row. .. _RQLStringFunctions: + String transformation functions ``````````````````````````````` -+-----------------------------+-----------------------------------------------------------------+ -| :function:`UPPER(String)` | upper case the string | -+-----------------------------+-----------------------------------------------------------------+ -| :function:`LOWER(String)` | lower case the string | -+-----------------------------+-----------------------------------------------------------------+ -| :function:`LENGTH(String)` | return the length of the string | -+-----------------------------+-----------------------------------------------------------------+ -| :function:`SUBSTRING( | extract from the string a string starting at given index and of | -| String, start, length)` | given length | -+-----------------------------+-----------------------------------------------------------------+ -| :function:`LIMIT_SIZE( | if the length of the string is greater than given max size, | -| String, max size)` | strip it and add ellipsis ("..."). The resulting string will | -| | hence have max size + 3 characters | -+-----------------------------+-----------------------------------------------------------------+ -| :function:`TEXT_LIMIT_SIZE( | similar to the above, but allow to specify the MIME type of the | -| String, format, max size)` | text contained by the string. Supported formats are text/html, | -| | text/xhtml and text/xml. All others will be considered as plain | -| | text. For non plain text format, sgml tags will be first removed| -| | before limiting the string. | -+-----------------------------+-----------------------------------------------------------------+ ++-------------------------+-----------------------------------------------------------------+ +| :func:`UPPER(String)` | upper case the string | ++-------------------------+-----------------------------------------------------------------+ +| :func:`LOWER(String)` | lower case the string | ++-------------------------+-----------------------------------------------------------------+ +| :func:`LENGTH(String)` | return the length of the string | ++-------------------------+-----------------------------------------------------------------+ +| :func:`SUBSTRING( | extract from the string a string starting at given index and of | +| String, start, length)`| given length | ++-------------------------+-----------------------------------------------------------------+ +| :func:`LIMIT_SIZE( | if the length of the string is greater than given max size, | +| String, max size)` | strip it and add ellipsis ("..."). The resulting string will | +| | hence have max size + 3 characters | ++-------------------------+-----------------------------------------------------------------+ +| :func:`TEXT_LIMIT_SIZE( | similar to the above, but allow to specify the MIME type of the | +| String, format, | text contained by the string. Supported formats are text/html, | +| max size)` | text/xhtml and text/xml. All others will be considered as plain | +| | text. For non plain text format, sgml tags will be first removed| +| | before limiting the string. | ++-------------------------+-----------------------------------------------------------------+ .. _RQLDateFunctions: + Date extraction functions ````````````````````````` -+------------------------------+----------------------------------------+ -| :function:`YEAR(Date)` | return the year of a date or datetime | -+------------------------------+----------------------------------------+ -| :function:`MONTH(Date)` | return the year of a date or datetime | -+------------------------------+----------------------------------------+ -| :function:`DAY(Date)` | return the year of a date or datetime | -+------------------------------+----------------------------------------+ -| :function:`HOUR(Datetime)` | return the year of a datetime | -+------------------------------+----------------------------------------+ -| :function:`MINUTE(Datetime)` | return the year of a datetime | -+------------------------------+----------------------------------------+ -| :function:`SECOND(Datetime)` | return the year of a datetime | -+------------------------------+----------------------------------------+ ++--------------------------+----------------------------------------+ +| :func:`YEAR(Date)` | return the year of a date or datetime | ++--------------------------+----------------------------------------+ +| :func:`MONTH(Date)` | return the year of a date or datetime | ++--------------------------+----------------------------------------+ +| :func:`DAY(Date)` | return the year of a date or datetime | ++--------------------------+----------------------------------------+ +| :func:`HOUR(Datetime)` | return the year of a datetime | ++--------------------------+----------------------------------------+ +| :func:`MINUTE(Datetime)` | return the year of a datetime | ++--------------------------+----------------------------------------+ +| :func:`SECOND(Datetime)` | return the year of a datetime | ++--------------------------+----------------------------------------+ .. _RQLOtherFunctions: + Other functions ``````````````` -+---------------------------+--------------------------------------------------------------------+ -| :function:`ABS(num)` | return the absolute value of a number | -+---------------------------+--------------------------------------------------------------------+ -| :function:`RANDOM()` | return a pseudo-random value from 0.0 to 1.0 | -+---------------------------+--------------------------------------------------------------------+ -| :function:`FSPATH(X)` | expect X to be an attribute whose value is stored in a | -| | :ref:`BFSStorage` and return its path on the file system | -+---------------------------+--------------------------------------------------------------------+ -| :function:`FTKIRANK(X)` | expect X to be an entity used in a has_text relation, and return a | -| | number corresponding to the rank order of each resulting entity | -+---------------------------+--------------------------------------------------------------------+ -| :function:`CAST(Type, X)` | expect X to be an attribute and return it casted into the given | -| | final type | -+---------------------------+--------------------------------------------------------------------+ ++-----------------------+--------------------------------------------------------------------+ +| :func:`ABS(num)` | return the absolute value of a number | ++-----------------------+--------------------------------------------------------------------+ +| :func:`RANDOM()` | return a pseudo-random value from 0.0 to 1.0 | ++-----------------------+--------------------------------------------------------------------+ +| :func:`FSPATH(X)` | expect X to be an attribute whose value is stored in a | +| | :class:`BFSStorage` and return its path on the file system | ++-----------------------+--------------------------------------------------------------------+ +| :func:`FTKIRANK(X)` | expect X to be an entity used in a has_text relation, and return a | +| | number corresponding to the rank order of each resulting entity | ++-----------------------+--------------------------------------------------------------------+ +| :func:`CAST(Type, X)` | expect X to be an attribute and return it casted into the given | +| | final type | ++-----------------------+--------------------------------------------------------------------+ .. _RQLExamples: + Examples ~~~~~~~~ @@ -579,6 +596,7 @@ .. _RQLInsertQuery: + Insertion query ~~~~~~~~~~~~~~~ @@ -611,6 +629,7 @@ INSERT Person X: X name 'foo', X friend Y WHERE name 'nice' .. _RQLSetQuery: + Update and relation creation queries ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -633,6 +652,7 @@ .. _RQLDeleteQuery: + Deletion query ~~~~~~~~~~~~~~