Documentation PostgreSQL 14.22 » Référence » Commandes SQL » FETCH

Précédent | Niveau supérieur | Suivant
EXPLAIN | Sommaire | GRANT

## FETCH

FETCH — Récupérer les lignes d'une requête à l'aide d'un curseur

## Synopsis

    FETCH [ direction ] [ FROM | IN ] nom_curseur

    où direction peut être :

        NEXT
        PRIOR
        FIRST
        LAST
        ABSOLUTE nombre
        RELATIVE nombre
        nombre
        ALL
        FORWARD
        FORWARD nombre
        FORWARD ALL
        BACKWARD
        BACKWARD nombre
        BACKWARD ALL

## Description

`FETCH` récupère des lignes en utilisant un curseur précédemment ouvert.

À un curseur est associée une position associée utilisée par `FETCH`. Le curseur peut être positionné avant la première ligne du résultat de la requête, sur une ligne particulière du résultat ou après la dernière ligne du résultat. À sa création, le curseur est positionné avant la première ligne. Après récupération de lignes, le curseur est positionné sur la ligne la plus récemment récupérée. Si `FETCH` atteint la fin des lignes disponibles, il est positionné après la dernière ligne ou avant la première ligne dans le cas d'une récupération remontante. `FETCH ALL` ou `FETCH BACKWARD ALL` positionne toujours le curseur après la dernière ligne ou avant la première ligne.

Les formes `NEXT`, `PRIOR`, `FIRST`, `LAST`, `ABSOLUTE`, `RELATIVE` récupèrent une seule ligne après déplacement approprié du curseur. Si cette ligne n'existe pas, un résultat vide est renvoyé et le curseur est positionné avant la première ligne ou après la dernière ligne, en fonction du sens de la progression.

Les formes utilisant `FORWARD` et `BACKWARD` récupèrent le nombre de lignes indiqué en se déplaçant en avant ou en arrière, laissant le curseur positionné sur la dernière ligne renvoyée (ou après/avant toutes les lignes si `nombre` dépasse le nombre de lignes disponibles).

`RELATIVE 0`, `FORWARD 0` et `BACKWARD 0` récupèrent tous la ligne actuelle sans déplacer le curseur, c'est-à-dire qu'ils effectuent une nouvelle récupération de la ligne dernièrement récupérée. La commande réussit sauf si le curseur est positionné avant la première ligne ou après la dernière ligne ; dans ce cas, aucune ligne n'est renvoyée.

### Note

Cette page décrit l'utilisation des curseurs au niveau de la commande SQL. Si vous voulez utiliser des curseurs dans une fonction PL/pgSQL, les règles sont différentes -- voir Section 43.7.3.

## Paramètres

`direction`

  La direction et le nombre de lignes à récupérer. Ce paramètre peut prendre les valeurs suivantes :

  `NEXT`

    La ligne suivante est récupérée. C'est le comportement par défaut si `direction` est omis.

  `PRIOR`

    La ligne précédente est récupérée.

  `FIRST`

    La première ligne de la requête est récupérée. C'est identique à `ABSOLUTE 1`.

  `LAST`

    La dernière ligne de la requête est récupérée. C'est identique à `ABSOLUTE -1`.

  `ABSOLUTE `nombre``

    La `nombre`-ième ligne de la requête est récupérée, ou la `abs(`nombre`)`-ième ligne à partir de la fin si `nombre` est négatif. Le curseur est positionné avant la première ligne ou après la dernière si `nombre` est en dehors des bornes ; en particulier, `ABSOLUTE 0` le positionne avant la première ligne.

  `RELATIVE `nombre``

    La `nombre`-ième ligne suivante est récupérée, ou la `abs(`nombre`)`-ième ligne précédente si `nombre` est négatif. `RELATIVE 0` récupère de nouveau la ligne courante, si elle existe.

  `nombre`

    Les `nombre` lignes suivantes sont récupérées. C'est identique à `FORWARD `nombre``.

  `ALL`

    Toutes les lignes restantes sont récupérées. C'est identique à `FORWARD ALL`).

  `FORWARD`

    La ligne suivante est récupérée. C'est identique à `NEXT`.

  `FORWARD `nombre``

    Les `nombre` lignes suivantes sont récupérées. `FORWARD 0` récupère de nouveau la ligne courante.

  `FORWARD ALL`

    Toutes les lignes restantes sont récupérées.

  `BACKWARD`

    La ligne précédente est récupérée. C'est identique à `PRIOR`.

  `BACKWARD `nombre``

    Les `nombre` lignes précédentes sont récupérées (parcours inverse). `BACKWARD 0` récupère de nouveau la ligne courante.

  `BACKWARD ALL`

    Toutes les lignes précédentes sont récupérées (parcours inverse).

`nombre`

  Constante de type entier éventuellement signé, qui précise l'emplacement ou le nombre de lignes à récupérer. Dans le cas de `FORWARD` et `BACKWARD`, préciser une valeur négative pour `nombre` est équivalent à modifier le sens de `FORWARD` et `BACKWARD`.

`nom_curseur`

  Le nom d'un curseur ouvert.

## Sorties

En cas de succès, une commande `FETCH` renvoie une balise de commande de la forme

    FETCH nombre

Le `nombre` est le nombre de lignes récupérées (éventuellement zéro). Dans psql, la balise de commande n'est pas réellement affichée car psql affiche à la place les lignes récupérées.

## Notes

Le curseur doit être déclaré avec l'option `SCROLL` si les variantes de `FETCH` autres que `FETCH NEXT` ou `FETCH FORWARD` avec un nombre positif sont utilisées. Pour les requêtes simples, PostgreSQL autorise les parcours inverses à partir de curseurs non déclarés avec `SCROLL`. il est toutefois préférable de ne pas se fonder sur ce comportement. Si le curseur est déclaré avec `NO SCROLL`, aucun parcours inverse n'est autorisé.

Les récupérations `ABSOLUTE` ne sont pas plus rapides que la navigation vers la ligne désirée par déplacement relatif : de toute façon, l'implantation sous-jacente doit parcourir toutes les lignes intermédiaires. Les récupérations absolues négatives font même pis : la requête doit être lue jusqu'à la fin pour trouver la dernière ligne, puis relue en sens inverse à partir de là. Néanmoins, remonter vers le début de la requête (comme avec `FETCH ABSOLUTE 0`) est rapide.

`DECLARE` est utilisé pour définir un curseur. `MOVE` est utilisé pour modifier la position du curseur sans récupérer les données.

## Exemples

Parcourir une table à l'aide d'un curseur :

    BEGIN WORK;

    -- Initialiser le curseur :
    DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;

    -- Récupèrer les 5 premières lignes du curseur liahona :
    FETCH FORWARD 5 FROM liahona;

     code  |          titre          | did | date_prod  |   genre  |  longueur
    -------+-------------------------+-----+------------+----------+-----------
     BL101 | The Third Man           | 101 | 1949-12-23 | Drama    | 01:44
     BL102 | The African Queen       | 101 | 1951-08-11 | Romantic | 01:43
     JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25
     P_301 | Vertigo                 | 103 | 1958-11-14 | Action   | 02:08
     P_302 | Becket                  | 103 | 1964-02-03 | Drama    | 02:28

    -- Récupèrer la ligne précédente :
    FETCH PRIOR FROM liahona;

     code  |  titre  | did | date_prod  |  genre |  longueur
    -------+---------+-----+------------+--------+-----------
     P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08

    -- Fermer le curseur et terminer la transaction:
    CLOSE liahona;
    COMMIT WORK;

## Compatibilité

Le standard SQL ne définit `FETCH` que pour une utilisation en SQL embarqué. La variante de `FETCH` décrite ici renvoie les données comme s'il s'agissait du résultat d'un `SELECT` plutôt que de le placer dans des variables hôtes. À part cela, `FETCH` est totalement compatible avec le standard SQL.

Les formes de `FETCH` qui impliquent `FORWARD` et `BACKWARD`, ainsi que les formes `FETCH `nombre`` et `FETCH ALL`, dans lesquelles `FORWARD` est implicite, sont des extensions PostgreSQL.

Le standard SQL n'autorise que `FROM` devant le nom du curseur ; la possibilité d'utiliser `IN`, ou de les laisser, est une extension.

## Voir aussi

CLOSE, DECLARE, MOVE