FETCH

Nom

FETCH -- récupère des lignes d'une requête en utilisant un curseur

Synopsis

FETCH [ direction { FROM | IN } ]
nomcurseurdirection peut être vide ou
faire partie de :

    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 déjà ouvert.

Un curseur a une position associée qui est utilisée par FETCH. La position du curseur peut être avant la première ligne du résultat d'une requête, une ligne particulière du résultat ou après la dernière ligne du résultat. Une fois créé, un curseur est positionné sur la ligne la plus récemment récupérée. Si FETCH arrive à la fin des lignes disponibles, alors le curseur est positionné après la dernière ligne ou avant la première ligne au cas où la récupération se fait en marche arrière. FETCH ALL ou FETCH BACKWARD ALL laisse toujours le curseur positionné 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 avoir déplacé le curseur de façon appropriée. 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 suivant le 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 demandent la récupération de la ligne actuelle sans déplacer le curseur, c'est-à-dire une nouvelle récupération de la ligne récemment 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 ; auquel cas, aucune ligne n'est renvoyée.

Paramètres

direction

direction définit la direction de la récupération et le nombre de lignes à récupérer. Elle peut prendre les valeurs suivantes :

NEXT

Récupère la prochaine ligne. Ceci est la valeur par défaut si direction est omis.

PRIOR

Récupère la ligne précédente.

FIRST

Récupère la première ligne de la requête (identique à ABSOLUTE 1).

LAST

Récupère la dernière ligne de la requête (identique à ABSOLUTE -1).

ABSOLUTE nombre

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

RELATIVE nombre

Récupère la nombre-ième ligne ou la abs(nombre)-ième ligne précédente si nombre est négatif. RELATIVE 0 récupère de nouveau la ligne actuelle si elle existe.

nombre

Récupère les nombre lignes suivantes (identique à FORWARD nombre).

ALL

Récupère toutes les lignes restantes (identique à FORWARD ALL).

FORWARD

Récupère la ligne suivante (identique à NEXT).

FORWARD nombre

Récupère les nombre lignes suivantes. FORWARD 0 récupère de nouveau la ligne actuelle.

FORWARD ALL

Récupère toutes les lignes restantes.

BACKWARD

Récupère la ligne précédente (identique à PRIOR).

BACKWARD nombre

Récupère les nombre lignes précédentes (parcours inverse). BACKWARD 0 récupère de nouveau la ligne actuelle.

BACKWARD ALL

Récupère toutes les lignes précédentes (parcours inverse).

nombre

nombre est une constante de type entier pouvant être signée, déterminant l'emplacement ou le nombre de lignes à récupérer. Pour les cas FORWARD et BACKWARD, spécifier une valeur négative pour nombre est équivalent à modifier le sens de FORWARD et BACKWARD.

nomcurseur

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 (zéro étant possible). Notez que 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 vous avez l'intention d'utiliser une variante de FETCH autre que FETCH NEXT ou FETCH FORWARD avec un nombre positif. Pour les requêtes simples, PostgreSQL autorise les parcours inverses à partir de curseurs non déclarés avec SCROLL, mais ce comportement n'est pas sûr. 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 de naviguer vers la ligne désirée avec un déplacement relatif : de toute façon, l'implémentation sous-jacente doit parcourir toutes les lignes intermédiaires. Les récupérations absolues négatives sont même pires : la requête doit être lue jusqu'à la fin pour trouver la dernière ligne relue en sens inverse. Néanmoins, remonter vers le début de la requête (comme avec FETCH ABSOLUTE 0) est rapide.

Mettre à jour des données via un curseur n'est pas supporté actuellement par PostgreSQL.

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

Exemples

L'exemple suivant parcourt une table en utilisant un curseur.

BEGIN WORK;

-- Initialise un curseur :
DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;

-- Récupère 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ère 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

-- Ferme le curseur et termine la transaction:
CLOSE liahona;
COMMIT WORK;

Compatibilité

Le standard SQL définit FETCH comme étant à utiliser uniquement dans le 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. A part ce point, FETCH est totalement compatible avec le standard SQL.

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

Le standard SQL autorise seulement FROM précédant le nom du curseur ; La possibilité d'utiliser IN est une extension.

Voir aussi

CLOSE, DECLARE, MOVE