DECLARE

Définit un nouveau curseur. Utilisez un curseur pour récupérer en même temps quelques lignes du jeu de résultats d’une requête plus grande.

Lorsque la première ligne d’un curseur est extraite, le jeu complet de résultats est matérialisé sur le nœud principal, en mémoire ou sur disque, si nécessaire. En raison de l’impact négatif potentiel de l’utilisation de curseurs avec des ensembles de résultats volumineux sur les performances, nous recommandons autant que possible l’utilisation d’approches alternatives. Pour plus d'informations, consultez Considérations relatives aux performances lors de l’utilisation de curseurs.

Vous devez déclarer un curseur au sein d’un bloc de transaction. Un seul curseur à la fois peut être ouvert par séance.

Pour plus d’informations, consultez FETCH, CLOSE.

Syntaxe

DECLARE cursor_name CURSOR FOR query

Paramètres

nom_curseur

Nom du nouveau schéma.

query

Instruction SELECT qui remplit le curseur.

Notes d’utilisation sur DECLARE CURSOR

Si votre application cliente utilise une connexion ODBC et que votre requête crée un ensemble de résultats trop volumineux pour contenir en mémoire, vous pouvez diffuser l’ensemble de résultats sur votre application cliente à l’aide d’un curseur. Lorsque vous utilisez un curseur, l’ensemble de résultats est matérialisé sur le nœud principal et le client peut ensuite extraire les résultats de façon incrémentielle.

Note

Pour activer les curseurs dans ODBC pour Microsoft Windows, activez l’option Use Declare/Fetch (Utiliser Declare/Fetch) dans le DSN ODBC que vous utilisez pour Amazon Redshift. Nous recommandons de définir la taille du cache ODBC, à l’aide du champ Cache Size (Taille du cache) de la boîte de dialogue ODBC DSN, avec la valeur 4 000 ou plus sur les clusters à plusieurs nœuds afin de réduire les allers et retours. Sur un cluster à un seul nœud, définissez Cache Size sur 1 000.

En raison de l’impact négatif potentiel de l’utilisation de curseurs sur les performances, nous recommandons d’utiliser les autres approches autant que possible. Pour plus d'informations, consultez Considérations relatives aux performances lors de l’utilisation de curseurs.

Les curseurs Amazon Redshift sont pris en charge avec les limitations suivantes :

• Un seul curseur à la fois peut être ouvert par séance.

• Les curseurs doivent être utilisés au sein d’une transaction (BEGIN … END).

• La taille maximale cumulée du jeu de résultats pour tous les curseurs est limitée en fonction du type de nœud du cluster. Si vous avez besoin de jeux de résultats plus larges, vous pouvez redimensionner avec une configuration de nœud XL ou 8XL.

  Pour plus d'informations, consultez Contraintes de curseur.

Contraintes de curseur

Lorsque la première ligne d’un curseur est extraite, le jeu complet de résultats est matérialisé sur le nœud principal. Si le jeu de résultats ne contient pas en mémoire, il est écrit sur le disque en fonction des besoins. Pour protéger l’intégrité du nœud principal, Amazon Redshift applique les contraintes sur la taille de tous les jeux de résultats du curseur, en fonction du type de nœud du cluster.

Le tableau suivant illustre la taille maximale du jeu de résultats pour chaque type de nœud de cluster. Les tailles maximales des jeux de résultats sont exprimés en mégaoctets.

Type de nœud	Ensemble de résultats maximal par cluster (Mo)
Nœuds multiples RA3 16XL	14400000
Nœud simple DC2 Large	8000
Nœuds multiples DC2 Large	192000
Nœuds multiples DC2 8XL	3200000
Nœuds multiples RA3 4XL	3200000
Nœuds multiples RA3 XLPLUS	1000000
Nœud unique RA3 XLPLUS	64000
Amazon Redshift sans serveur	150000

Pour afficher la configuration de curseur active pour un cluster, interrogez la table système STV_CURSOR_CONFIGURATION en tant que super-utilisateur. Pour afficher l’état des curseurs actifs, interrogez la table système STV_ACTIVE_CURSORS. Seules les lignes des curseurs d’un utilisateur sont visibles de l’utilisateur, mais un super-utilisateur peut afficher tous les curseurs.

Considérations relatives aux performances lors de l’utilisation de curseurs

Comme les curseurs matérialisent la totalité de l’ensemble de résultats sur le nœud principal avant de commencer à renvoyer les résultats au client, l’utilisation de curseurs avec des ensembles de résultats très volumineux peut avoir un impact négatif sur les performances. Nous vous déconseillons vivement l’utilisation de curseurs avec des jeux de résultats très volumineux. Dans certains cas, comme lorsque votre application utilise une connexion ODBC, les curseurs peuvent être la seule solution possible. Si possible, nous recommandons d’utiliser ces alternatives :

• Utilisez UNLOAD pour exporter une grande table. Lorsque vous utilisez UNLOAD, les nœuds de calcul fonctionnent en parallèle pour transférer directement les données vers les fichiers de données sur Amazon Simple Storage Service. Pour plus d'informations, consultez Déchargement des données.

• Définissez le paramètre JDBC de taille d’extraction dans votre application cliente. Si vous utilisez une connexion JDBC et que vous rencontrez des out-of-memory erreurs côté client, vous pouvez permettre à votre client de récupérer des ensembles de résultats par lots plus petits en définissant le paramètre JDBC fetch size. Pour plus d’informations, consultez Définition du paramètre de taille d’extraction JDBC.

Exemples DECLARE CURSOR

L’exemple suivant déclare un curseur nommé LOLLAPALOOZA pour sélectionner les informations sur les ventes pour l’événement Lollapalooza, puis récupère les lignes de l’ensemble de résultats à l’aide du curseur :

-- Begin a transaction

begin;

-- Declare a cursor

declare lollapalooza cursor for
select eventname, starttime, pricepaid/qtysold as costperticket, qtysold
from sales, event
where sales.eventid = event.eventid
and eventname='Lollapalooza';

-- Fetch the first 5 rows in the cursor lollapalooza:

fetch forward 5 from lollapalooza;

  eventname   |      starttime      | costperticket | qtysold
--------------+---------------------+---------------+---------
 Lollapalooza | 2008-05-01 19:00:00 |   92.00000000 |       3
 Lollapalooza | 2008-11-15 15:00:00 |  222.00000000 |       2
 Lollapalooza | 2008-04-17 15:00:00 |  239.00000000 |       3
 Lollapalooza | 2008-04-17 15:00:00 |  239.00000000 |       4
 Lollapalooza | 2008-04-17 15:00:00 |  239.00000000 |       1
(5 rows)

-- Fetch the next row:

fetch next from lollapalooza;

  eventname   |      starttime      | costperticket | qtysold
--------------+---------------------+---------------+---------
 Lollapalooza | 2008-10-06 14:00:00 |  114.00000000 |       2

-- Close the cursor and end the transaction:

close lollapalooza;
commit;

L’exemple suivant passe en boucle sur un curseur contenant tous les résultats d’une table :

CREATE TABLE tbl_1 (a int, b int);
INSERT INTO tbl_1 values (1, 2),(3, 4);

CREATE OR REPLACE PROCEDURE sp_cursor_loop() AS $$
DECLARE
    target record;
    curs1 cursor for select * from tbl_1;
BEGIN
    OPEN curs1;
    LOOP
        fetch curs1 into target;
        exit when not found;
        RAISE INFO 'a %', target.a;
    END LOOP;
    CLOSE curs1;
END;
$$ LANGUAGE plpgsql;

CALL sp_cursor_loop();
         
SELECT message 
   from svl_stored_proc_messages 
   where querytxt like 'CALL sp_cursor_loop()%';
         
  message
----------
      a 1
      a 3