--- a/doc/book/en/annexes/rql/intro.rst	Wed Jul 07 13:50:55 2010 +0200
+++ b/doc/book/en/annexes/rql/intro.rst	Wed Jul 07 10:53:03 2010 +0200
@@ -7,8 +7,13 @@
 Goals of RQL
 ~~~~~~~~~~~~
 
-The goal is to have a language making relations browsing easy. As
-such, attributes will be regarded as cases of special relations (in
+The goal is to have a semantic language in order to:
+
+- query relations in a clear syntax
+- empowers access to data repository manipulation
+- making attributes/relations browsing easy
+
+As such, attributes will be regarded as cases of special relations (in
 terms of usage, the user should see no syntactic difference between an
 attribute and a relation).
 
@@ -59,7 +64,78 @@
    Remove entities or relations existing in the database.
 
 
+Concepts
+~~~~~~~~
+
+Entity type
+```````````
+
+RQL manipulates variables that are instances of entities.
+Each entity has its own type which are used in backend to improve the query
+execution plan.
+
+Restrictions
+````````````
+
+They are conditions used to limit the perimeter of the result set.
+
+Relations
+`````````
+A relation is a `3-expression` defined as follows:
+
+.. image:: Graph-ex.gif
+    :alt: <subject> <predicate> <object>
+    :align: center
+
+A RQL relation contains three components:
+
+* the subject, which is an entity type
+* the predicate, which is an oriented graph
+* the object, which is either an attribute or a relation to another entity
+
+In cubicweb, the term `relation` is often found without ambiguity instead of `predicate`.
+This predicate is also known as the `property` of the triple in `RDF concepts`_
+
+A relation is always expressed in the order: subject, predicate, object.
+
+It's important to determine if entity type is subject or object to construct a
+valid expression. An inversion subject/object is equivalent to an RQL error
+since the supposed relation cannot be found in schema. If you don't have access
+to the code, you could find the order by looking at the schema image in manager
+views (the subject is located at the beginning of the arrow).
+
+.. _SQL: http://www.firstsql.com/tutor5.htm
+.. _RDF concepts: http://www.w3.org/TR/rdf-concepts/
+
+Cardinality
+```````````
+XXX
+
+Cardinality is an important concept to model your business rules.
+They determine nu./tutorials/advanced/index.rst
+
+Please refer to the `datamodel definitions`_ for a deep understanding.
+
+`Relations`_ are always expressed by cardinality rules (`**` by default)
+
+.. _datamodel definitions: ./devrepo/datamodel/definition.rst
+
+Transaction
+```````````
+
+RQL supports notion of **transactions**; i.e. sequences of RQL statements
+without invoking security hooks of the instance's schema.
+
+When you're ready to make persistent the changes, you have to *commit* the
+modification in calling `commit()`.
+
+If an error is found (typically in raising a ValidationError), you have the
+possibility to roll back the transaction in invoking `rollback()` function; i.e
+to come back to the initial state of the transaction.
+
+Please, refer to the :ref:`Migration` chapter if you want more details.
 
 
-.. _Versa: http://uche.ogbuji.net/tech/rdf/versa/
+
+.. _Versa: http://wiki.xml3k.org/Versa
 .. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/