diff -r 4fe4ce7e2544 -r 60faaa480f02 doc/book/en/08-rql.en.txt --- a/doc/book/en/08-rql.en.txt Thu Nov 20 11:51:28 2008 +0100 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,211 +0,0 @@ -.. -*- coding: utf-8 -*- - -RQL language (Relation Query Language) -====================================== - -Introduction ------------- -* RQL language focuses on browsing relations. -* Attributes are considered as particular relations. -* RQL is inspired from SQL but is a high level language. -* A good knowledge of Erudi's schemas defining the application is required. - - -Types of requests ------------------ - -Search (`Any`) - query the repository to extract entities and/or attributes. - -Insertion (`INSERT`) - insert new entities in the database. - -Updates of entities, creation of relations (`SET`) - update existing entities in the database, or create relations between existing - entities - -Deletion of entities or relations (`DELETE`) - delete existing entities and relations from the database. - - -Variables and typing --------------------- - -Entities and values to browse and/or select are set in the query through *variables* -which should be written in capital letters. - -The possible types for each variable can be deducted from the schema depending on -the conditions expressed in the query. - -You can force the possible types for a variable thanks to the special relation `is`. - - - -Built-in types --------------- -* `String` (literal: between double or single quotes). -* `Int`, `Float` (separator is '.'). -* `Date`, `Datetime`, `Time` (literal: pattern YYYY/MM/DD[ hh:mm] or keywords - `TODAY` and `NOW`). -* `Boolean` (keywords `TRUE` et `FALSE`). -* keyword `NULL`. - -Operators ----------- -* Logical operators: `AND`, `OR`, `,`. -* Mathematical operators: `+`, `-`, `*`, `/`. -* Comparison operators: `=`, `<`, `<=`, `>=`, `>`, `~=`, `LIKE`, `IN`. - - * The operator `=` is the default operator. - - * The operator `LIKE` / `~=` allows the use of the character `%` in a string - to indicate that the string should start/end with a prefix/suffix:: - - Any X WHERE X nom ~= 'Th%' - Any X WHERE X nom LIKE '%lt' - - * The operator `IN` allows to provide a list of possible values:: - - Any X WHERE X nom IN ('chauvat', 'fayolle', 'di mascio', 'thenault') - -Search query ------------- - - [`DISTINCT`] V1(, V2)\* - [`GROUPBY` V1(, V2)\*] [`ORDERBY` ] - [`WHERE` ] - [`LIMIT` ] [`OFFSET` ] - -:entity type: - Type of the selected variable - Special type `Any` is equivalent to not specify a type -:condition: - list of relations to browse following the pattern - `V1 relation V2|` -:orderterms: - Setting of the selection order : variable or column number followed by the - sorting method (`ASC`, `DESC`), ASC being the default value. -:note for grouped queries: - For grouped queries (e.g. using function `GROUPBY`), all the selected - variables must be grouped or aggregated. - -Examples - search -~~~~~~~~~~~~~~~~~ -:: - - Any X WHERE X eid 53 - Personne X - Personne X WHERE X travaille_pour S, S nom "logilab" - Any E,COUNT(X) GROUPBY E ORDERBY EN WHERE X is E, E name EN - Any E,COUNT(X) GROUPBY E ORDERBY 2 WHERE X is E - - -Advanced features -~~~~~~~~~~~~~~~~~ -* Aggregate functions: `COUNT`, `MIN`, `MAX`, `SUM`. -* String functions:`UPPER`, `LOWER`. -* Optional relations: - - * They allow to select entities related to others or not. - - * You should use `?` behind the variable to specify the relation to itself is - optional. - - - Project anomalies related to a version or not:: - - Any X,V WHERE X concerns P, P eid 42, X corrected_in V? - - - All the cards and the project they document otherwise :: - - Any C,P WHERE C is Card, P? documented_by C - -Negation -~~~~~~~~ -* A query such as `Document X WHERE NOT X owned_by U` is equivalent to - "the documents which do not have relation `owned_by`". -* Whereas the query `Document X WHERE NOT X owned_by U, U login "syt"` - is equivalent to "the documents which do not have relation `owned_by` - with the user syt". They could have a relation with other users. - - -Identity -~~~~~~~~ - -We could use the special relation `identity` in a query in order to add a -condition of identity between two variables. This is equivalent to ``is`` -in Python. - - Any A WHERE A comments B, A identity B - -returns the set of objects which comment themselves. The relation `identity` -is very usefull while defining security rules with `RQLExpressions`. - -Insertion queries ------------------ - `INSERT` V1(, V2)\* `:` - [`WHERE` ] - -:assignments: - list of relations to assign such as `V1 relation V2|` - -The condition allow to define the variables we would use in assignments. - -Be careful, if a condition is specified, the insertion is done *for each result -returned by the condition*. - -Examples - insertion -~~~~~~~~~~~~~~~~~~~~~ -* Insertion of a new person named 'bidule':: - - INSERT Person X: X name 'bidule' - -* Insertion of a new person named 'bidule', another named - 'chouette' and a relation 'friend' between them:: - - INSERT Person X, Person Y: X name 'bidule', Y name 'chouette', X friend Y - -* Insertion of a new person named 'bidule' and a relation 'friend'with an - existing person 'chouette':: - - INSERT Person X: X name 'bidule', X friend Y WHERE Y name 'chouette' - - -Update queries --------------- - `SET` - [`WHERE` ] - -Be careful, if a condition is specified, the update is done *for each result -returned by the condition*. - -Examples - update -~~~~~~~~~~~~~~~~~ -* Renaming of the person named 'bidule' to 'toto', with change on the first name:: - - SET X name 'toto', X firstname 'original' WHERE X is 'Person', X name 'bidule' - -* Insertion of a relation of type 'know' between two objects linked with the relation - of type 'friend' :: - - SET X know Y WHERE X friend Y - -Deletion queries ----------------- - `DELETE` ( V) | (V1 relation v2),... - [`WHERE` ] - - -Be careful, if a condition is specified, the deletion is done *for each result -returned by the condition*. - - -Examples -~~~~~~~~ -* Deletion of the person named 'toto':: - - DELETE Person X WHERE X name 'toto' - -* Deletion of all the relations of type 'friend' linked to the person named - 'toto':: - - DELETE X friend Y WHERE X is 'Person', X name 'toto'