Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

# Indicateurs de requête SPARQL utilisés avec DESCRIBE
<a name="sparql-query-hints-for-describe"></a>

Une requête SPARQL `DESCRIBE` fournit un mécanisme flexible permettant de demander des descriptions de ressources. Cependant, les spécifications SPARQL ne définissent pas la sémantique précise de `DESCRIBE`.

À partir de la [version 1.2.0.2 du moteur](engine-releases-1.2.0.2.md), Neptune prend en charge plusieurs modes et algorithmes `DESCRIBE` adaptés à différentes situations.

Cet exemple de jeu de données permet d'illustrer les différents modes :

```
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix : <https://example.com/> .

:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JohnDoe :firstName "John" .
:JaneDoe :knows _:b1 .
_:b1 :knows :RichardRoe .

:RichardRoe :knows :JaneDoe .
:RichardRoe :firstName "Richard" .

_:s1 rdf:type rdf:Statement .
_:s1 rdf:subject :JaneDoe .
_:s1 rdf:predicate :knows .
_:s1 rdf:object :JohnDoe .
_:s1 :knowsFrom "Berlin" .

:ref_s2 rdf:type rdf:Statement .
:ref_s2 rdf:subject :JaneDoe .
:ref_s2 rdf:predicate :knows .
:ref_s2 rdf:object :JohnDoe .
:ref_s2 :knowsSince 1988 .
```

Les exemples ci-dessous supposent qu'une description de la ressource `:JaneDoe` est demandée à l'aide d'une requête SPARQL comme celle-ci :

```
DESCRIBE <https://example.com/JaneDoe>
```

## L'indice de `requête SPARQL DescribeMode`
<a name="sparql-query-hints-describeMode"></a>

L'indicateur de requête `hint:describeMode` SPARQL est utilisé pour sélectionner l'un des modes `DESCRIBE` SPARQL suivants pris en charge par Neptune :

### Mode `ForwardOneStep` DESCRIBE
<a name="sparql-query-hints-describeMode-ForwardOneStep"></a>

Vous invoquez le mode `ForwardOneStep` avec l'indicateur de requête `describeMode` comme suit :

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "ForwardOneStep"
}
```

Le mode `ForwardOneStep` renvoie uniquement les attributs et les liens de transfert de la ressource à décrire. Dans le cas de cet exemple, cela signifie qu'il renvoie les triplets dont la ressource à décrire, `:JaneDoe`, est le sujet :

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b301990159 .
```

Notez que la requête DESCRIBE peut renvoyer des triplets avec des nœuds vides (par exemple, `_:b301990159`), qui ont des ID différents à chaque fois par rapport au jeu de données en entrée.

### Mode `SymmetricOneStep` DESCRIBE
<a name="sparql-query-hints-describeMode-SymmetricOneStep"></a>

`SymmetricOneStep` est le mode DESCRIBE par défaut si vous ne fournissez aucun indicateur de requête. Vous pouvez également l'invoquer explicitement avec l'indicateur de requête `describeMode` comme ceci :

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "SymmetricOneStep"
}
```

Sous la sémantique `SymmetricOneStep`, `DESCRIBE` renvoie les attributs, les liens de transfert et les liens inverses de la ressource à décrire :

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b318767375 .

_:b318767631 rdf:subject :JaneDoe .

:RichardRoe :knows :JaneDoe .

:ref_s2 rdf:subject :JaneDoe .
```

### Le mode DESCRIPTION LIMITÉE CONCISE (`CBD`) DESCRIBE
<a name="sparql-query-hints-describeMode-CBD"></a>

Le mode `CBD` (Concise Bounded Description) est invoqué à l'aide de l'indicateur de requête `describeMode` suivant :

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "CBD"
}
```

Sous la sémantique `CBD`, `DESCRIBE` renvoie la description CBD (telle que [définie par le W3C](http://www.w3.org/Submission/CBD)) de la ressource à décrire :

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b285212943 .
_:b285212943 :knows :RichardRoe .

_:b285213199 rdf:subject :JaneDoe .
_:b285213199 rdf:type rdf:Statement .
_:b285213199 rdf:predicate :knows .
_:b285213199 rdf:object :JohnDoe .
_:b285213199 :knowsFrom "Berlin" .

:ref_s2 rdf:subject :JaneDoe .
```

La description CBD d'une ressource RDF (c'est-à-dire un nœud dans un graphe RDF) est le plus petit sous-graphe pouvant être autonome centré sur ce nœud. En pratique, cela signifie que si vous considérez ce graphe comme un arbre, avec le nœud désigné comme racine, il n'y a pas de nœuds vides comme feuilles de cet arbre. Comme les nœuds vides ne peuvent pas être traités de manière externe ni utilisés dans les requêtes ultérieures, il ne suffit pas de parcourir le graphe pour trouver le ou les prochains sauts individuels à partir du nœud actuel. Vous devez également aller assez loin pour trouver ce qui pourra être utilisé dans les requêtes ultérieures (à savoir autre chose qu'un nœud vide).

#### Calcul de la valeur CBD
<a name="sparql-query-hints-describeMode-CBD-computing"></a>

Avec un nœud particulier (le nœud ou la racine de départ) dans le graphe RDF source, la valeur CBD de ce nœud est calculée comme suit :

1. Incluez dans le sous-graphe toutes les déclarations du graphe source dont le *sujet* de la déclaration est le nœud de départ.

1. De manière récursive, pour toutes les déclarations du sous-graphe contenant jusqu'à présent un *objet* de nœud vide, incluez dans le sous-graphe toutes les déclarations du graphe source dont le *sujet* de la déclaration correspond à ce nœud vide, et qui ne sont pas déjà incluses dans le sous-graphe.

1. De manière récursive, pour toutes les déclarations incluses dans le sous-graphe jusqu'à présent, pour toutes les réifications de ces déclarations dans le graphe source, incluez la valeur CBD en commençant par le nœud `rdf:Statement` de chaque réification.

Il en résulte un sous-graphe où les nœuds de l'*objet* sont soit des références IRI ou des littéraux, soit des nœuds vides ne faisant l'*objet* d'aucune déclaration dans le graphe. Notez que le CBD ne peut pas être calculé à l'aide d'une seule requête SPARQL SELECT ou CONSTRUCT.

### Le mode DESCRIBE de description symétrique concise et bornée (`SCBD`)
<a name="sparql-query-hints-describeMode-SCBD"></a>

Le mode `SCBD` (Symetric Concise Bounded Description) est invoqué à l'aide de l'indicateur de requête `describeMode` suivant :

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE <https://example.com/JaneDoe>
{
  hint:Query hint:describeMode "SCBD"
}
```

Sous la sémantique `SCBD`, `DESCRIBE` renvoie la description SCBD (telle que définie par le W3C dans [Description des jeux de données liés avec le vocabulaire VoID](http://www.w3.org/TR/void/)) :

```
:JaneDoe :firstName "Jane" .
:JaneDoe :knows :JohnDoe .
:JaneDoe :knows _:b335544591 .
_:b335544591 :knows :RichardRoe .

:RichardRoe :knows :JaneDoe .

_:b335544847 rdf:subject :JaneDoe .
_:b335544847 rdf:type rdf:Statement .
_:b335544847 rdf:predicate :knows .
_:b335544847 rdf:object :JohnDoe .
_:b335544847 :knowsFrom "Berlin" .

:ref_s2 rdf:subject :JaneDoe .
```

L'avantage des valeurs CBD et SCBD par rapport aux modes `ForwardOneStep` et `SymmetricOneStep` est que les nœuds vides sont toujours étendus pour inclure leur représentation. Cet avantage est de taille, car vous ne pouvez pas interroger un nœud vide à l'aide de SPARQL. En outre, les modes CBD et SCBD prennent également en compte les réifications.

Notez que l'indicateur de requête `describeMode` peut également faire partie d'une clause `WHERE` :

```
PREFIX hint: <http://aws.amazon.com/neptune/vocab/v01/QueryHints#>
DESCRIBE ?s
WHERE {
  hint:Query hint:describeMode "CBD" .
  ?s rdf:type <https://example.com/Person>
}
```

## L'astuce de `description` de la requête IterationLimit SPARQL
<a name="sparql-query-hints-describeIterationLimit"></a>

L'indicateur de requête `hint:describeIterationLimit` SPARQL fournit une contrainte **facultative** sur le nombre maximum d'extensions itératives à effectuer pour les algorithmes itératifs DESCRIBE tels que CBD et SCBD.

Les limites du mode DESCRIBE doivent s'appliquer simultanément. Par conséquent, si la limite d'itération et la limite de déclarations sont spécifiées, elles doivent toutes deux être respectées avant que la requête DESCRIBE ne soit interrompue.

La valeur par défaut est 5. Vous pouvez la définir sur ZÉRO (0) pour ne pas spécifier de limite du nombre d'extensions itératives.

## L'astuce de `description` de la requête StatementLimit SPARQL
<a name="sparql-query-hints-describeStatementLimit"></a>

L'indicateur de requête SPARQL `hint:describeStatementLimit` fournit une contrainte **facultative** sur le nombre maximum de déclarations pouvant être présentes dans une réponse à une requête DESCRIBE. Il n'est appliqué qu'aux algorithmes itératifs DESCRIBE tels que CBD et SCBD.

Les limites du mode DESCRIBE doivent s'appliquer simultanément. Par conséquent, si la limite d'itération et la limite de déclarations sont spécifiées, elles doivent toutes deux être respectées avant que la requête DESCRIBE ne soit interrompue.

La valeur par défaut est 5 000. Vous pouvez la définir sur ZÉRO (0) pour ne pas limiter le nombre de déclarations renvoyées.