.. _rql_intro:

Introduction

------------

Goals of RQL

~~~~~~~~~~~~

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).

Comparison with existing languages

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SQL

```

RQL may remind of SQL but works at a higher abstraction level (the *CubicWeb*

framework generates SQL from RQL to fetch data from relation databases). RQL is

focused on browsing relations. The user needs only to know about the *CubicWeb*

data model he is querying, but not about the underlying SQL model.

Sparql

``````

The query language most similar to RQL is SPARQL_, defined by the W3C to serve

for the semantic web.

Versa

`````

We should look in more detail, but here are already some ideas for the moment

... Versa_ is the language most similar to what we wanted to do, but the model

underlying data being RDF, there are some things such as namespaces or

handling of the RDF types which does not interest us. On the functionality

level, Versa_ is very comprehensive including through many functions of

conversion and basic types manipulation, which we may want to look at one time

or another.  Finally, the syntax is a little esoteric.

Datalog

```````

Datalog_ is a prolog derived query langage which applies to relational

databases. It is more expressive than RQL in that it accepts either

extensional_ and intensional_ predicates (or relations). As of now,

RQL only deals with intensional relations.

The different types of queries

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Search (`Any`)

   Extract entities and attributes of entities.

Insert entities (`INSERT`)

   Insert new entities or relations in the database.

   It can also directly create relationships for the newly created entities.

Update entities, create relations (`SET`)

   Update existing entities in the database,

   or create relations between existing entities.

Delete entities or relationship (`DELETE`)

   Remove entities or relations existing in the database.

RQL relation expressions

~~~~~~~~~~~~~~~~~~~~~~~~

RQL expressions apply to a live database defined by a

:ref:`datamodel_definition`. Apart from the main type, or head, of the

expression (search, insert, etc.) the most common constituent of an

RQL expression is a (set of) relation expression(s).

An RQL relation expression contains three components:

* the subject, which is an entity type

* the predicate, which is a relation definition (an arc of the schema)

* the object, which is either an attribute or a relation to another entity

.. image:: Graph-ex.gif

    :alt: <subject> <predicate> <object>

    :align: center

.. warning::

 A relation is always expressed in the order: ``subject``,

 ``predicate``, ``object``.

 It is important to determine if the entity type is subject or object

 to construct a valid expression. Inverting the subject/object is an

 error since the relation cannot be found in the schema.

 If one does not have access to the code, one can find the order by

 looking at the schema image in manager views (the subject is located

 at the beginning of the arrow).

An example of two related relation expressions::

  P works_for C, P name N

RQL variables represent typed entities. The type of entities is

either automatically inferred (by looking at the possible relation

definitions, see :ref:`RelationDefinition`) or explicitely constrained

using the ``is`` meta relation.

In the example above, we barely need to look at the schema. If

variable names (in the RQL expression) and relation type names (in the

schema) are expresssively designed, the human reader can infer as much

as the |cubicweb| querier.

The ``P`` variable is used twice but it always represent the same set

of entities. Hence ``P works_for C`` and ``P name N`` must be

compatible in the sense that all the Ps (which *can* refer to

different entity types) must accept the ``works_for`` and ``name``

relation types. This does restrict the set of possible values of P.

Adding another relation expression::

  P works_for C, P name N, C name "logilab"

This further restricts the possible values of P through an indirect

constraint on the possible values of ``C``. The RQL-level unification_

happening there is translated to one (or several) joins_ at the

database level.

.. note::

 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`_

RQL Operators

~~~~~~~~~~~~~

An RQL expression's head can be completed using various operators such

as ``ORDERBY``, ``GROUPBY``, ``HAVING``, ``LIMIT`` etc.

RQL relation expressions can be grouped with ``UNION`` or

``WITH``. Predicate oriented keywords such as ``EXISTS``, ``OR``,

``NOT`` are available.

The complete zoo of RQL operators is described extensively in the

following chapter (:ref:`RQL`).

.. _RDF concepts: http://www.w3.org/TR/rdf-concepts/

.. _Versa: http://wiki.xml3k.org/Versa

.. _SPARQL: http://www.w3.org/TR/rdf-sparql-query/

.. _unification: http://en.wikipedia.org/wiki/Unification_(computing)

.. _joins: http://en.wikipedia.org/wiki/Join_(SQL)

.. _Datalog: http://en.wikipedia.org/wiki/Datalog

.. _intensional: http://en.wikipedia.org/wiki/Intensional_definition

.. _extensional: http://en.wikipedia.org/wiki/Extension_(predicate_logic)