Mercurial Mercurial > pub > hg > cubicweb / comparison
summary | shortlog | changelog | graph | tags | bookmarks | branches | files | changeset | file | latest | revisions | annotate | diff | comparison | raw | help
Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc/book/en/annexes/rql/language.rst
changeset 7632 3c9dfc6e820b
parent 7578 49be8619b745
child 7738 e0c86caf5c48
equal deleted inserted replaced
7631:4ac19f288149 7632:3c9dfc6e820b 
     4 
     4 
     5 RQL syntax
 
     5 RQL syntax
 
     6 ----------
 
     6 ----------
 
     7 
     7 
     8 .. _RQLKeywords:
 
     8 .. _RQLKeywords:
 
       
     9 
     9 Reserved keywords
 
    10 Reserved keywords
 
    10 ~~~~~~~~~~~~~~~~~
 
    11 ~~~~~~~~~~~~~~~~~
 
    11 
    12 
    12 ::
 
    13 ::
 
    13 
    14 
    18 The keywords are not case sensitive. You should not use them when defining your
 
    19 The keywords are not case sensitive. You should not use them when defining your
 
    19 schema, or as RQL variable names.
 
    20 schema, or as RQL variable names.
 
    20 
    21 
    21 
    22 
    22 .. _RQLCase:
 
    23 .. _RQLCase:
 
       
    24 
    23 Case
 
    25 Case
 
    24 ~~~~
 
    26 ~~~~
 
    25 
    27 
    26 * Variables should be all upper-cased.
 
    28 * Variables should be all upper-cased.
 
    27 
    29 
    31 * Entity types should start with an upper cased letter and be followed by at least
 
    33 * Entity types should start with an upper cased letter and be followed by at least
 
    32   a lower cased latter.
 
    34   a lower cased latter.
 
    33 
    35 
    34 
    36 
    35 .. _RQLVariables:
 
    37 .. _RQLVariables:
 
       
    38 
    36 Variables and typing
 
    39 Variables and typing
 
    37 ~~~~~~~~~~~~~~~~~~~~
 
    40 ~~~~~~~~~~~~~~~~~~~~
 
    38 
    41 
    39 Entities and values to browse and/or select are represented in the query by
 
    42 Entities and values to browse and/or select are represented in the query by
 
    40 *variables* that must be written in capital letters.
 
    43 *variables* that must be written in capital letters.
 
    61 * `has_text`: relation to use to query the full text index (only for entities
 
    64 * `has_text`: relation to use to query the full text index (only for entities
 
    62   having fulltextindexed attributes).
 
    65   having fulltextindexed attributes).
 
    63 
    66 
    64 * `identity`: relation to use to tell that a RQL variable is the same as another
 
    67 * `identity`: relation to use to tell that a RQL variable is the same as another
 
    65   when you've to use two different variables for querying purpose. On the
 
    68   when you've to use two different variables for querying purpose. On the
 
    66   opposite it's also useful together with the `NOT`_ operator to tell that two
 
    69   opposite it's also useful together with the :ref:`NOT` operator to tell that two
 
    67   variables should not identify the same entity
 
    70   variables should not identify the same entity
 
    68 
    71 
    69 
    72 
    70 .. _RQLLiterals:
 
    73 .. _RQLLiterals:
 
       
    74 
    71 Literal expressions
 
    75 Literal expressions
 
    72 ~~~~~~~~~~~~~~~~~~~
 
    76 ~~~~~~~~~~~~~~~~~~~
 
    73 
    77 
    74 Bases types supported by RQL are those supported by yams schema. Literal values
 
    78 Bases types supported by RQL are those supported by yams schema. Literal values
 
    75 are expressed as explained below:
 
    79 are expressed as explained below:
 
    86 
    90 
    87 You may also use the :keyword:`NULL` keyword, meaning 'unspecified'.
 
    91 You may also use the :keyword:`NULL` keyword, meaning 'unspecified'.
 
    88 
    92 
    89 
    93 
    90 .. _RQLOperators:
 
    94 .. _RQLOperators:
 
       
    95 
    91 Operators
 
    96 Operators
 
    92 ~~~~~~~~~
 
    97 ~~~~~~~~~
 
    93 
    98 
    94 .. _RQLLogicalOperators:
 
    99 .. _RQLLogicalOperators:
 
       
   100 
    95 Logical operators
 
   101 Logical operators
 
    96 `````````````````
 
   102 `````````````````
 
    97 ::
 
   103 ::
 
    98 
   104 
    99      AND, OR, NOT, ','
 
   105      AND, OR, NOT, ','
 
   100 
   106 
   101 ',' is equivalent to 'AND' but with the smallest among the priority of logical
 
   107 ',' is equivalent to 'AND' but with the smallest among the priority of logical
 
   102 operators (see :ref:`RQLOperatorsPriority`).
 
   108 operators (see :ref:`RQLOperatorsPriority`).
 
   103 
   109 
   104 .. _RQLMathematicalOperators:
 
   110 .. _RQLMathematicalOperators:
 
       
   111 
   105 Mathematical operators
 
   112 Mathematical operators
 
   106 ``````````````````````
 
   113 ``````````````````````
 
   107 ::
 
   114 ::
 
   108 
   115 
   109      +, -, *, /
 
   116      +, -, *, /
 
   110 
   117 
   111 Those should behave as you expect.
 
   118 Those should behave as you expect.
 
   112 
   119 
   113 
   120 
   114 .. _RQLComparisonOperators:
 
   121 .. _RQLComparisonOperators:
 
       
   122 
   115 Comparison operators
 
   123 Comparison operators
 
   116 ````````````````````
 
   124 ````````````````````
 
   117  ::
 
   125  ::
 
   118 
   126 
   119      =, !=, <, <=, >=, >, IN
 
   127      =, !=, <, <=, >=, >, IN
 
   136 
   144 
   137     Any X WHERE X name IN ('chauvat', 'fayolle', 'di mascio', 'thenault')
 
   145     Any X WHERE X name IN ('chauvat', 'fayolle', 'di mascio', 'thenault')
 
   138 
   146 
   139 
   147 
   140 .. _RQLStringOperators:
 
   148 .. _RQLStringOperators:
 
       
   149 
   141 String operators
 
   150 String operators
 
   142 ````````````````
 
   151 ````````````````
 
   143 ::
 
   152 ::
 
   144 
   153 
   145   LIKE, ILIKE, ~=, REGEXP
 
   154   LIKE, ILIKE, ~=, REGEXP
 
   176 
   185 
   177 Other back-ends are not supported yet.
 
   186 Other back-ends are not supported yet.
 
   178 
   187 
   179 
   188 
   180 .. _RQLOperatorsPriority:
 
   189 .. _RQLOperatorsPriority:
 
       
   190 
   181 Operators priority
 
   191 Operators priority
 
   182 ``````````````````
 
   192 ``````````````````
 
   183 
   193 
   184 #. "(", ")"
 
   194 #. "(", ")"
 
   185 #. '*', '/'
 
   195 #. '*', '/'
 
   189 #. 'OR'
 
   199 #. 'OR'
 
   190 #. ','
 
   200 #. ','
 
   191 
   201 
   192 
   202 
   193 .. _RQLSearchQuery:
 
   203 .. _RQLSearchQuery:
 
       
   204 
   194 Search Query
 
   205 Search Query
 
   195 ~~~~~~~~~~~~
 
   206 ~~~~~~~~~~~~
 
   196 
   207 
   197 Simplified grammar of search query: ::
 
   208 Simplified grammar of search query: ::
 
   198 
   209 
   425 
   436 
   426     (Any X, XN WHERE X is Person, X surname XN) UNION (Any X,XN WHERE X is Company, X name XN)
 
   437     (Any X, XN WHERE X is Person, X surname XN) UNION (Any X,XN WHERE X is Company, X name XN)
 
   427 
   438 
   428 
   439 
   429 .. _RQLFunctions:
 
   440 .. _RQLFunctions:
 
       
   441 
   430 Available functions
 
   442 Available functions
 
   431 ~~~~~~~~~~~~~~~~~~~
 
   443 ~~~~~~~~~~~~~~~~~~~
 
   432 
   444 
   433 Below is the list of aggregate and transformation functions that are supported
 
   445 Below is the list of aggregate and transformation functions that are supported
 
   434 nativly by the framework. Notice that cubes may define additional functions.
 
   446 nativly by the framework. Notice that cubes may define additional functions.
 
   435 
   447 
   436 .. _RQLAggregateFunctions:
 
   448 .. _RQLAggregateFunctions:
 
       
   449 
   437 Aggregate functions
 
   450 Aggregate functions
 
   438 ```````````````````
 
   451 ```````````````````
 
   439 +------------------------+----------------------------------------------------------+
 
   452 +--------------------+----------------------------------------------------------+
 
   440 | :function:`COUNT`      | return the number of rows                                |
 
   453 | :func:`COUNT`      | return the number of rows                                |
 
   441 +------------------------+----------------------------------------------------------+
 
   454 +--------------------+----------------------------------------------------------+
 
   442 | :function:`MIN`        | return the minimum value                                 |
 
   455 | :func:`MIN`        | return the minimum value                                 |
 
   443 +------------------------+----------------------------------------------------------+
 
   456 +--------------------+----------------------------------------------------------+
 
   444 | :function:`MAX`        | return the maximum value                                 |
 
   457 | :func:`MAX`        | return the maximum value                                 |
 
   445 +------------------------+----------------------------------------------------------+
 
   458 +--------------------+----------------------------------------------------------+
 
   446 | :function:`AVG`        | return the average value                                 |
 
   459 | :func:`AVG`        | return the average value                                 |
 
   447 +------------------------+----------------------------------------------------------+
 
   460 +--------------------+----------------------------------------------------------+
 
   448 | :function:`SUM`        | return the sum of values                                 |
 
   461 | :func:`SUM`        | return the sum of values                                 |
 
   449 +------------------------+----------------------------------------------------------+
 
   462 +--------------------+----------------------------------------------------------+
 
   450 | :function:`COMMA_JOIN` | return each value separated by a comma (for string only) |
 
   463 | :func:`COMMA_JOIN` | return each value separated by a comma (for string only) |
 
   451 +------------------------+----------------------------------------------------------+
 
   464 +--------------------+----------------------------------------------------------+
 
   452 
   465 
   453 All aggregate functions above take a single argument. Take care some aggregate
 
   466 All aggregate functions above take a single argument. Take care some aggregate
 
   454 functions (e.g. :keyword:`MAX`, :keyword:`MIN`) may return `None` if there is no
 
   467 functions (e.g. :keyword:`MAX`, :keyword:`MIN`) may return `None` if there is no
 
   455 result row.
 
   468 result row.
 
   456 
   469 
   457 .. _RQLStringFunctions:
 
   470 .. _RQLStringFunctions:
 
       
   471 
   458 String transformation functions
 
   472 String transformation functions
 
   459 ```````````````````````````````
 
   473 ```````````````````````````````
 
   460 
   474 
   461 +-----------------------------+-----------------------------------------------------------------+
 
   475 +-------------------------+-----------------------------------------------------------------+
 
   462 | :function:`UPPER(String)`   | upper case the string                                           |
 
   476 | :func:`UPPER(String)`   | upper case the string                                           |
 
   463 +-----------------------------+-----------------------------------------------------------------+
 
   477 +-------------------------+-----------------------------------------------------------------+
 
   464 | :function:`LOWER(String)`   | lower case the string                                           |
 
   478 | :func:`LOWER(String)`   | lower case the string                                           |
 
   465 +-----------------------------+-----------------------------------------------------------------+
 
   479 +-------------------------+-----------------------------------------------------------------+
 
   466 | :function:`LENGTH(String)`  | return the length of the string                                 |
 
   480 | :func:`LENGTH(String)`  | return the length of the string                                 |
 
   467 +-----------------------------+-----------------------------------------------------------------+
 
   481 +-------------------------+-----------------------------------------------------------------+
 
   468 | :function:`SUBSTRING(       | extract from the string a string starting at given index and of |
 
   482 | :func:`SUBSTRING(       | extract from the string a string starting at given index and of |
 
   469 |    String, start, length)`  | given length                                                    |
 
   483 |  String, start, length)`| given length                                                    |
 
   470 +-----------------------------+-----------------------------------------------------------------+
 
   484 +-------------------------+-----------------------------------------------------------------+
 
   471 | :function:`LIMIT_SIZE(      | if the length of the string is greater than given max size,     |
 
   485 | :func:`LIMIT_SIZE(      | if the length of the string is greater than given max size,     |
 
   472 |  String, max size)`         | strip it and add ellipsis ("..."). The resulting string will    |
 
   486 |  String, max size)`     | strip it and add ellipsis ("..."). The resulting string will    |
 
   473 |                             | hence have max size + 3 characters                              |
 
   487 |                         | hence have max size + 3 characters                              |
 
   474 +-----------------------------+-----------------------------------------------------------------+
 
   488 +-------------------------+-----------------------------------------------------------------+
 
   475 | :function:`TEXT_LIMIT_SIZE( | similar to the above, but allow to specify the MIME type of the |
 
   489 | :func:`TEXT_LIMIT_SIZE( | similar to the above, but allow to specify the MIME type of the |
 
   476 |  String, format, max size)` | text contained by the string. Supported formats are text/html,  |
 
   490 |  String, format,        | text contained by the string. Supported formats are text/html,  |
 
   477 |                             | text/xhtml and text/xml. All others will be considered as plain |
 
   491 |  max size)`             | text/xhtml and text/xml. All others will be considered as plain |
 
   478 |                             | text. For non plain text format, sgml tags will be first removed|
 
   492 |                         | text. For non plain text format, sgml tags will be first removed|
 
   479 |                             | before limiting the string.                                     |
 
   493 |                         | before limiting the string.                                     |
 
   480 +-----------------------------+-----------------------------------------------------------------+
 
   494 +-------------------------+-----------------------------------------------------------------+
 
   481 
   495 
   482 .. _RQLDateFunctions:
 
   496 .. _RQLDateFunctions:
 
       
   497 
   483 Date extraction functions
 
   498 Date extraction functions
 
   484 `````````````````````````
 
   499 `````````````````````````
 
   485 
   500 
   486 +------------------------------+----------------------------------------+
 
   501 +--------------------------+----------------------------------------+
 
   487 | :function:`YEAR(Date)`       | return the year of a date or datetime  |
 
   502 | :func:`YEAR(Date)`       | return the year of a date or datetime  |
 
   488 +------------------------------+----------------------------------------+
 
   503 +--------------------------+----------------------------------------+
 
   489 | :function:`MONTH(Date)`      | return the year of a date or datetime  |
 
   504 | :func:`MONTH(Date)`      | return the year of a date or datetime  |
 
   490 +------------------------------+----------------------------------------+
 
   505 +--------------------------+----------------------------------------+
 
   491 | :function:`DAY(Date)`        | return the year of a date or datetime  |
 
   506 | :func:`DAY(Date)`        | return the year of a date or datetime  |
 
   492 +------------------------------+----------------------------------------+
 
   507 +--------------------------+----------------------------------------+
 
   493 | :function:`HOUR(Datetime)`   | return the year of a datetime          |
 
   508 | :func:`HOUR(Datetime)`   | return the year of a datetime          |
 
   494 +------------------------------+----------------------------------------+
 
   509 +--------------------------+----------------------------------------+
 
   495 | :function:`MINUTE(Datetime)` | return the year of a datetime          |
 
   510 | :func:`MINUTE(Datetime)` | return the year of a datetime          |
 
   496 +------------------------------+----------------------------------------+
 
   511 +--------------------------+----------------------------------------+
 
   497 | :function:`SECOND(Datetime)` | return the year of a datetime          |
 
   512 | :func:`SECOND(Datetime)` | return the year of a datetime          |
 
   498 +------------------------------+----------------------------------------+
 
   513 +--------------------------+----------------------------------------+
 
   499 
   514 
   500 .. _RQLOtherFunctions:
 
   515 .. _RQLOtherFunctions:
 
       
   516 
   501 Other functions
 
   517 Other functions
 
   502 ```````````````
 
   518 ```````````````
 
   503 +---------------------------+--------------------------------------------------------------------+
 
   519 +-----------------------+--------------------------------------------------------------------+
 
   504 | :function:`ABS(num)`       | return the absolute value of a number                             |
 
   520 | :func:`ABS(num)`      |  return the absolute value of a number                             |
 
   505 +---------------------------+--------------------------------------------------------------------+
 
   521 +-----------------------+--------------------------------------------------------------------+
 
   506 | :function:`RANDOM()`      | return a pseudo-random value from 0.0 to 1.0                       |
 
   522 | :func:`RANDOM()`      | return a pseudo-random value from 0.0 to 1.0                       |
 
   507 +---------------------------+--------------------------------------------------------------------+
 
   523 +-----------------------+--------------------------------------------------------------------+
 
   508 | :function:`FSPATH(X)`     | expect X to be an attribute whose value is stored in a             |
 
   524 | :func:`FSPATH(X)`     | expect X to be an attribute whose value is stored in a             |
 
   509 |                           | :ref:`BFSStorage` and return its path on the file system           |
 
   525 |                       | :class:`BFSStorage` and return its path on the file system         |
 
   510 +---------------------------+--------------------------------------------------------------------+
 
   526 +-----------------------+--------------------------------------------------------------------+
 
   511 | :function:`FTKIRANK(X)`   | expect X to be an entity used in a has_text relation, and return a |
 
   527 | :func:`FTKIRANK(X)`   | expect X to be an entity used in a has_text relation, and return a |
 
   512 |                           | number corresponding to the rank order of each resulting entity    |
 
   528 |                       | number corresponding to the rank order of each resulting entity    |
 
   513 +---------------------------+--------------------------------------------------------------------+
 
   529 +-----------------------+--------------------------------------------------------------------+
 
   514 | :function:`CAST(Type, X)` | expect X to be an attribute and return it casted into the given    |
 
   530 | :func:`CAST(Type, X)` | expect X to be an attribute and return it casted into the given    |
 
   515 |                           | final type                                                         |
 
   531 |                       | final type                                                         |
 
   516 +---------------------------+--------------------------------------------------------------------+
 
   532 +-----------------------+--------------------------------------------------------------------+
 
   517 
   533 
   518 
   534 
   519 .. _RQLExamples:
 
   535 .. _RQLExamples:
 
       
   536 
   520 Examples
 
   537 Examples
 
   521 ~~~~~~~~
 
   538 ~~~~~~~~
 
   522 
   539 
   523 - *Search for the object of identifier 53*
 
   540 - *Search for the object of identifier 53*
 
   524   ::
 
   541   ::
 
   577 
   594 
   578         Any X where X is in (FirstType, SecondType)
 
   595         Any X where X is in (FirstType, SecondType)
 
   579 
   596 
   580 
   597 
   581 .. _RQLInsertQuery:
 
   598 .. _RQLInsertQuery:
 
       
   599 
   582 Insertion query
 
   600 Insertion query
 
   583 ~~~~~~~~~~~~~~~
 
   601 ~~~~~~~~~~~~~~~
 
   584 
   602 
   585     `INSERT` <entity type> V1 (, <entity type> V2) \ * `:` <assignments>
 
   603     `INSERT` <entity type> V1 (, <entity type> V2) \ * `:` <assignments>
 
   586     [ `WHERE` <restriction>]
 
   604     [ `WHERE` <restriction>]
 
   609   ::
 
   627   ::
 
   610 
   628 
   611         INSERT Person X: X name 'foo', X friend  Y WHERE name 'nice'
 
   629         INSERT Person X: X name 'foo', X friend  Y WHERE name 'nice'
 
   612 
   630 
   613 .. _RQLSetQuery:
 
   631 .. _RQLSetQuery:
 
       
   632 
   614 Update and relation creation queries
 
   633 Update and relation creation queries
 
   615 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
   634 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
   616 
   635 
   617     `SET` <assignements>
 
   636     `SET` <assignements>
 
   618     [ `WHERE` <restriction>]
 
   637     [ `WHERE` <restriction>]
 
   631 
   650 
   632         SET X know Y  WHERE X friend Y
 
   651         SET X know Y  WHERE X friend Y
 
   633 
   652 
   634 
   653 
   635 .. _RQLDeleteQuery:
 
   654 .. _RQLDeleteQuery:
 
       
   655 
   636 Deletion query
 
   656 Deletion query
 
   637 ~~~~~~~~~~~~~~
 
   657 ~~~~~~~~~~~~~~
 
   638 
   658 
   639     `DELETE` (<entity type> V) | (V1 relation v2 ),...
 
   659     `DELETE` (<entity type> V) | (V1 relation v2 ),...
 
   640     [ `WHERE` <restriction>]
 
   660     [ `WHERE` <restriction>]
cubicweb