DECLARE

Definisce un nuovo cursore. Utilizza un cursore per recuperare poche righe alla volta dal set di risultati di una query più grande.

Quando viene recuperata la prima riga di un cursore, l'intero set di risultati si materializza sul nodo principale, in memoria o sul disco, se necessario. A causa del potenziale impatto negativo sulle prestazioni dell'utilizzo dei cursori con set di risultati di grandi dimensioni, si consiglia di utilizzare approcci alternativi laddove possibile. Per ulteriori informazioni, consulta Considerazioni sulle prestazioni quando si utilizzano i cursori.

Devi dichiarare un cursore all'interno di un blocco di transazione. È possibile aprire un solo cursore alla volta per sessione.

Per ulteriori informazioni, consultare FETCH, CLOSE.

Sintassi

DECLARE cursor_name CURSOR FOR query

Parametri

cursor_name

Nome del nuovo cursore.

query

Istruzione SELECT che popola il cursore.

Note per l'utilizzo di DECLARE CURSOR

Se l'applicazione client utilizza una connessione ODBC e la query crea un set di risultati che è troppo grande per rientrare nella memoria, puoi eseguire il flusso del set di risultati all'applicazione client utilizzando un cursore. Quando usi un cursore, l'intero set di risultati si materializza sul nodo principale e il client può recuperare i risultati in modo incrementale.

Nota

Per abilitare i cursori in ODBC per Microsoft Windows, abilitare l'opzione Usa dichiara/recupera nel DSN ODBC utilizzato per Amazon Redshift. Si consiglia di impostare la dimensione della cache ODBC, utilizzando il campo Cache Size (Dimensione cache) nella finestra di dialogo delle opzioni del DSN ODBC su 4.000 o un valore superiore sui cluster a più nodi per ridurre al minimo i round trip. Su un cluster a nodo singolo, imposta la dimensione della cache su 1.000.

A causa del potenziale impatto negativo sulle prestazioni dell'utilizzo dei cursori, si consiglia di utilizzare approcci alternativi laddove possibile. Per ulteriori informazioni, consulta Considerazioni sulle prestazioni quando si utilizzano i cursori.

I cursori Amazon Redshift sono supportati con le seguenti limitazioni:

• È possibile aprire un solo cursore alla volta per sessione.

• I cursori devono essere utilizzati all'interno di una transazione (BEGIN … END).

• La dimensione massima dei set di risultati cumulativi per tutti i cursori è vincolata in base al tipo di nodo del cluster. Se sono necessari set di risultati più grandi, puoi ridimensionare una configurazione di nodo XL o 8XL.

  Per ulteriori informazioni, consulta Vincoli del cursore.

Vincoli del cursore

Quando viene recuperata la prima riga di un cursore, l'intero set di risultati si materializza sul nodo principale. Se il set di risultati non rientra in memoria, viene scritto sul disco in base alle necessità. Per proteggere l'integrità del nodo principale, Amazon Redshift applica i vincoli sulla dimensione di tutti i set di risultati del cursore, in base al tipo di nodo del cluster.

La tabella seguente mostra le dimensioni massime del set di risultati totali per ciascun tipo di nodo del cluster. Le dimensioni massime del set di risultati sono espresse in megabyte.

Tipo di nodo	Dimensioni massime del set di risultati per cluster (MB)
Più nodi RA3 16XL	14400000
Nodo singolo DC1 Large	16000
Più nodi DC1 Large	384000
Più nodi DC1 8XL	3000000
Nodo singolo DC2 Large	8000
Più nodi DC2 Large	192000
Più nodi DC2 8XL	3200000
Più nodi RA3 4XL	3200000
Nodi multipli RA3 XLPLUS	1000000
Nodo singolo RA3 XLPLUS	64000
Amazon Redshift Serverless	150000

Per visualizzare la configurazione del cursore attivo per un cluster, eseguire una query sulla tabella di sistema STV_CURSOR_CONFIGURATION come utente con privilegi avanzati. Per visualizzare lo stato dei cursori attivi, esegui la query sulla tabella di sistema STV_ACTIVE_CURSORS. Un utente può vedere solo le righe dei propri cursori, ma un utente con privilegi avanzati può visualizzare tutti i cursori.

Considerazioni sulle prestazioni quando si utilizzano i cursori

Poiché i cursori materializzano l'intero set di risultati sul nodo principale prima di iniziare a restituire i risultati al client, l'utilizzo di cursori con set di risultati molto grandi può avere un impatto negativo sulle prestazioni. Ti consigliamo pertanto di non utilizzare i cursori con set di risultati molto grandi. In alcuni casi, ad esempio quando l'applicazione utilizza una connessione ODBC, i cursori potrebbero essere l'unica soluzione attuabile. Se possibile, consigliamo di utilizzare queste alternative:

• Usa UNLOAD per esportare una tabella di grandi dimensioni. Quando si utilizza UNLOAD, i nodi di calcolo lavorano in parallelo per trasferire i dati direttamente nei file di dati in Amazon Simple Storage Service. Per ulteriori informazioni, consulta Scaricamento dei dati.

• Imposta il parametro relativo alle dimensioni di recupero JDBC nell'applicazione client. Se utilizzi una connessione JDBC e riscontri out-of-memory errori sul lato client, puoi consentire al client di recuperare i set di risultati in batch più piccoli impostando il parametro JDBC fetch size. Per ulteriori informazioni, consulta Impostazione del parametro delle dimensioni del recupero JDBC.

Esempi di DECLARE CURSOR

L'esempio seguente dichiara un cursore denominato LOLLAPALOOZA per selezionare le informazioni di vendita per l'evento Lollapalooza e quindi recupera le righe dal set di risultati utilizzando il cursore:

-- 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'esempio seguente esegue un loop su un refcursor con tutti i risultati di una tabella:

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