# Specifications SQL Driver

###### tags: `specification`

## Objectif du document

Creer un format d'entrée et de sortie pour communiquer entre le driver sql et la librairie asklibmanager

## Demande intiale

Demonstrateur à installer chez le client pour connecter directement une base relationnelle au moteur de recherche askelys. Ce demonstrateur peut prendre la forme d'un petit serveur Web de type Endpoint (definissant une API). La reception des données en entrée

1. un arbre representant la requete utilisateur
2. un focus (noeud de l'arbre)
3. une action.

Ce serveur doit renvoyer une liste d'élément au format JSON.

## Description de l'arbre de requête

### définition d'un noeud

Chaque noeud est définit par les attributs suivants:

- *value* (URI si c'est un objet ou Literal si c'est une valeur feuille)
- *focusId* (identifiant du noeud)
- *type* : entity, forward, backward, value
- *not* : booléen (négation du noeud)
- *identifier* : variable (? *obsolete* on pourait utiliser le focusId)
- *optional* (booleen si la valeur demandé est optionnelle)
- *children* : noeuds fils

#### label

En RDF, celui ci est definit par rdfs:label, pref:label, skos:label,etc...

#### Value

contient des URIs ou des valeurs de la bases (contenu des colonnes).

Dans ce projet, Les URIs sont definit avec cette normalisation

* sql:table:*[nom table]*
correspond à un concept de la base

* sql:column:*[nom colonne]*
correspond à une relation de la base

* sql:join:*[nom table de jointure]*
correspond à une relation de la base

#### focusId

Identifiant du noeud

#### type

Définit les noeuds décrit dans les specs de AsklibManager.

* entity : noeud concept. correspond à une table
* forward/backward : noeud relation correspondant à une jointure ou une colonne
* value : correspond à une valeur de la base. assimilé à un xsd:type
* filter : noeud filtre

#### not

négation du noeud

* entité : toutes les entités sauf celle définit par l'URI (attribut valeur).

* donne moi tout ce qui n'est pas un acteur : Le système doit rendre les uris/identifiants de toutes les tables autres que acteurs

* forward/backward : toutes les entités qui ne sont pas déinit par cette propriété

* Donne moi tous les acteurs qui n'ont pas de prénom.
* Donne moi tout ce qui n'a pas de prénom.

* valeur : toutes les entités qui ne correspondent pas à cette valeur

* Donne moi toutes les entités qui n'est pas <sql:table:1>
* Donne moi tout les acteur qui ne s apelle pas john.

#### identifier

Identifiant de variable designant le noeud.

#### optional

rend optionel le résultat attendu .

* entité : pas d'effet (*à confirmer, cela n'a pas de sens de demander un typage optionnel à priori*)
* relation : renvoi une valeur vide si il n'existe pas de valeur (ou d'entité) dans la base correspondant à cette relation.
* valeur : pas d'effet (*à confirmer, cela n'a pas de sens d'affecter une valeur optionnelle à priori*)

#### children

list des noeufs fils.

### Listes des actions

Il existe 4 actions dépendant d'un **focus** :

- **entity** Liste des entités (question portant sur l'ontologie)
- **forward** liste des relations "avant" (question portant sur l'ontologie)
- **backward** liste des relations "arrière" (question portant sur l'ontologie)
- **value** liste des valeurs (question portant sur les données)

Il existe une action retournant l'ensemble des solutions possibles d'un arbre de requête (question portant sur les données)

- **results**

### arbre de requête

#### Spécificté du noeud *racine*

Un arbre est composé d'un **noeud racine** et de noeuds fils.

 tree {
 "focusId": 0,
 "type": "root",
 "not" : false,
 "optional" : "false",
 "children":
 }

Si le noeud racine est vide, les actions

- **entity** donne la liste des concepts de la base.
- **forward** donne la liste des relations disponibles
- **backward** équivalent à **bwd**
- **value** liste de toute les valeurs de la base
- **results** vide

#### requête envoyé au endpoint

Exemple de demande sur les entités disponibles dans la base.

{
    "tree": {
        "focusId": 0,
        "type": "root",
        "not" : false,
        "optional" : false,
        "children": []
    },
    "focusId" : 0,
    "action" : "entity"
}

### résultats attendus

https://www.w3.org/TR/sparql11-results-json/

- **entity** : liste d'URI
- **forward** : liste d'URI
- **backward** : liste d'URI
- **value** : liste de valeurs
- **results** : JSON

### Exemple de requête

####

{
    "tree": {
        "focusId": 0,
        "type": "root",
        "not" : false,
        "optional" : "false",
        "children":
        [
            {
                "value": "sql:table:actor",
                "focusId": 95,
                "type": "entity",
                "not" : false,
                "identifier" : "actor0",
                "optional" : "false",
                "children": []
            }
        ]
    },
    "focusId" : 95,
    "action" : "entity"
}

### focus