O Amazon Redshift deixará de oferecer suporte ao uso de UDFs em Python após 30 de junho de 2026. Começaremos a aplicar essa alteração em fases. Consulte mais informações sobre os detalhes do fim da vida útil do Python e as opções de migração na publicação do blog publicada em 30 de junho de 2025.

DECLARE

Define um novo cursor. Use um cursor para recuperar algumas linhas de cada vez do conjunto de resultados de uma consulta maior.

Quando a primeira linha do cursor é buscada, o conjunto inteiro de resultados é materializado no nó líder, na memória ou em disco, se necessário. Devido ao impacto da performance negativa potencial de usar cursores com grandes conjuntos de resultado, recomendamos abordagens alternativas sempre que possível. Para obter mais informações, consulte Considerações sobre a performance ao usar cursores.

Você deve declarar um cursor em um bloco de transação. Apenas um cursor pode ser aberto por sessão.

Para obter mais informações, consulte FETCHCLOSE.

Sintaxe

DECLARE cursor_name CURSOR FOR query

Parâmetros

Observações de uso de DECLARE CURSOR

Se seu aplicativo cliente usa uma conexão ODBC e sua consulta cria um conjunto de resultados que é muito grande para caber na memória, você pode transmitir o conjunto de resultados para seu aplicativo cliente usando um cursor. Quando você usa um cursor, o conjunto inteiro de resultados é materializado no nó líder, e a partir de então seu cliente pode buscar os resultados adicionais.

Devido ao impacto da performance negativa potencial do uso de cursores, recomendamos abordagens alternativas sempre que possível. Para obter mais informações, consulte Considerações sobre a performance ao usar cursores.

Os cursores do Amazon Redshift são compatíveis com as seguintes restrições:

Restrições de cursor

Quando a primeira linha de um cursor é buscada, o conjunto inteiro de resultados é materializado no nó líder. Se o resultado não couber na memória, ele será gravado em disco conforme necessário. Para proteger a integridade do nó líder, o Amazon Redshift aplica restrições de tamanho a todos os conjuntos de resultados de cursor com base no tipo de nó do cluster.

A tabela a seguir mostra o tamanho total máximo do conjunto de resultados para cada tipo de nó do cluster. O tamanho máximo do conjunto de resultados é fornecido em megabytes.

Para visualizar a configuração de cursor ativa para um cluster, consulte a tabela de sistema STV_CURSOR_CONFIGURATION como superusuário. Para exibir o estado de cursores ativos, consulte a tabela de sistema STV_ACTIVE_CURSORS. Somente as linhas dos cursores do próprio usuário são visíveis para ele, mas um superusuário pode visualizar todos os cursores.

Considerações sobre a performance ao usar cursores

Como os cursores materializam o conjunto de resultados inteiro no nó líder antes de começar a retornar resultados para o cliente, usar cursores com conjuntos muito grandes de resultados pode ter um impacto negativo na performance. É altamente recomendável não usar cursores com conjuntos muito grandes de resultados. Em alguns casos, como quando seu aplicativo usa uma conexão ODBC, os cursores podem ser a única solução viável. Se possível, recomendamos o uso destas alternativas:

Os nós RG têm tamanhos máximos de conjunto de resultados de cursor menores do que os nós RA3 com capacidade de computação semelhante. Se as workloads que utilizam cursores se aproximarem ou excederem o limite do seu tipo de nó RG, considere as seguintes opções:

Para determinar o tamanho atual do conjunto de resultados do cursor, consulte a visualização SYS_QUERY_HISTORY para obter o valor returned_bytes associado à primeira instrução FETCH executada no cursor. Consulte mais informações em SYS_QUERY_HISTORY.

Exemplo de DECLARE CURSOR

O exemplo a seguir declara um cursor denominado LOLLAPALOOZA para selecionar informações de vendas para o evento Lollapalooza e busca linhas do conjunto de resultados usando o cursor:

-- 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;

O exemplo a seguir percorre um refcursor com todos os resultados de uma tabela:

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