PostgreSQLLa base de données la plus sophistiquée au monde.
Documentation PostgreSQL 14.11 » Référence » Commandes SQL » FETCH

FETCH

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

Synopsis

FETCH [ direction ] [ FROM | IN ] nom_curseur

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