FETCH (Transact-SQL)

Sintaxe

FETCH 
          [ [ NEXT | PRIOR | FIRST | LAST 
                    | ABSOLUTE { n | @nvar } 
                    | RELATIVE { n | @nvar } 
               ] 
               FROM 
          ] 
{ { [ GLOBAL ] cursor_name } | @cursor_variable_name } 
[ INTO @variable_name [ ,...n ] ] 

Argumentos

• NEXT
  Retorna a linha de resultado imediatamente seguinte à linha atual e adiciona a linha atual à linha retornada. Se FETCH NEXT for a primeira busca de um cursor, a primeira linha do conjunto de resultados será retornada. NEXT é a opção padrão de busca de cursor.

• PRIOR
  Retorna a linha de resultado imediatamente anterior à linha atual e decrementa a linha atual da linha retornada. Se FETCH PRIOR for a primeira busca de um cursor, nenhuma linha será retornada e o cursor será deixado posicionado antes da primeira linha.

• FIRST
  Retorna a primeira linha no cursor e a torna a linha atual.

• LAST
  Retorna a última linha no cursor e a torna a linha atual.

• ABSOLUTE { n| @nvar}
  Se n ou @nvar for positivo, a linha que está n linhas a partir do início do cursor será retornada e a linha retornada se tornará a nova linha atual. Se n ou @nvar for negativo, a linha que está n linhas antes do final do cursor será retornada e a linha retornada se tornará a nova linha atual. Se n ou @nvar for 0, nenhuma linha será retornada. n deve ser uma constante inteira e @nvar deve ser smallint, tinyint ou int.

• RELATIVE { n| @nvar}
  Se n ou @nvar for positivo, a linha que está n linhas após a linha atual será retornada e a linha retornada se tornará a nova linha atual. Se n ou @nvar for negativo, a linha que está n linhas antes da linha atual será retornada e a linha retornada se tornará a nova linha atual. Se n ou @nvar for 0, a linha atual será retornada. Se FETCH RELATIVE for especificado com n ou @nvar definido como números negativos ou 0 na primeira busca feita em um cursor, nenhuma linha será retornada. n deve ser uma constante inteira e @nvar deve ser smallint, tinyint ou int.

• GLOBAL
  Especifica que cursor_name se refere a um cursor global.

• cursor_name
  É o nome do cursor aberto a partir do qual a busca deve ser feita. Se um cursor global e um cursor local existirem com cursor_name como seu nome, cursor_name será o cursor global, se GLOBAL for especificado, e será o cursor local, se GLOBAL não for especificado.

• @cursor_variable_name
  É o nome de uma variável de cursor que faz referência ao cursor aberto a partir do qual a busca deve ser feita.

• INTO @variable_name\[ ,...n]
  Permite que os dados das colunas de uma busca sejam colocados em variáveis locais. Cada variável na lista, da esquerda para a direita, está associada à coluna correspondente no conjunto de resultados do cursor. O tipo de dados de cada variável deve corresponder ou ser uma conversão implícita com suporte do tipo de dados da coluna do conjunto de resultados correspondente. O número de variáveis deve corresponder ao número de colunas na lista de seleção do cursor.

Comentários

Se a opção SCROLL não for especificada em uma instrução DECLARE CURSOR no estilo ISO, NEXT será a única opção de FETCH com suporte. Se SCROLL for especificado em uma instrução DECLARE CURSOR no estilo ISO, haverá suporte para todas as opções de FETCH.

Quando as extensões de cursor DECLARE do Transact-SQL forem usadas, estas regras se aplicarão:

• Se FORWARD_ONLY ou FAST_FORWARD for especificado, NEXT será a única opção de FETCH com suporte.

• Se DYNAMIC, FORWARD_ONLY ou FAST_FORWARD não forem especificados e KEYSET, STATIC ou SCROLL for especificado, haverá suporte para todas as opções de FETCH.

• Cursores DYNAMIC SCROLL oferecem suporte a todas as opções de FETCH, exceto ABSOLUTE.

A função @@FETCH_STATUS informa o status da última instrução FETCH. As mesmas informações são registradas na coluna fetch_status do cursor retornado por sp_describe_cursor. Essas informações de status devem ser usadas para determinar a validade dos dados retornados por uma instrução FETCH antes de tentar qualquer operação nesses dados. Para obter mais informações, consulte @@FETCH_STATUS (Transact-SQL).

Permissões

As permissões FETCH assumem como padrão qualquer usuário válido.

Exemplos

A. Usando FETCH em um cursor simples

USE AdventureWorks2008R2;
GO
DECLARE contact_cursor CURSOR FOR
SELECT LastName FROM Person.Person
WHERE LastName LIKE 'B%'
ORDER BY LastName;

OPEN contact_cursor;

-- Perform the first fetch.
FETCH NEXT FROM contact_cursor;

-- Check @@FETCH_STATUS to see if there are any more rows to fetch.
WHILE @@FETCH_STATUS = 0
BEGIN
   -- This is executed as long as the previous fetch succeeds.
   FETCH NEXT FROM contact_cursor;
END

CLOSE contact_cursor;
DEALLOCATE contact_cursor;
GO

B. Usando FETCH para armazenar valores em variáveis

USE AdventureWorks2008R2;
GO
-- Declare the variables to store the values returned by FETCH.
DECLARE @LastName varchar(50), @FirstName varchar(50);

DECLARE contact_cursor CURSOR FOR
SELECT LastName, FirstName FROM Person.Person
WHERE LastName LIKE 'B%'
ORDER BY LastName, FirstName;

OPEN contact_cursor;

-- Perform the first fetch and store the values in variables.
-- Note: The variables are in the same order as the columns
-- in the SELECT statement. 

FETCH NEXT FROM contact_cursor
INTO @LastName, @FirstName;

-- Check @@FETCH_STATUS to see if there are any more rows to fetch.
WHILE @@FETCH_STATUS = 0
BEGIN

   -- Concatenate and display the current values in the variables.
   PRINT 'Contact Name: ' + @FirstName + ' ' +  @LastName

   -- This is executed as long as the previous fetch succeeds.
   FETCH NEXT FROM contact_cursor
   INTO @LastName, @FirstName;
END

CLOSE contact_cursor;
DEALLOCATE contact_cursor;
GO

C. Declarando um cursor SCROLL e usando as outras opções de FETCH

USE AdventureWorks2008R2;
GO
-- Execute the SELECT statement alone to show the 
-- full result set that is used by the cursor.
SELECT LastName, FirstName FROM Person.Person
ORDER BY LastName, FirstName;

-- Declare the cursor.
DECLARE contact_cursor SCROLL CURSOR FOR
SELECT LastName, FirstName FROM Person.Person
ORDER BY LastName, FirstName;

OPEN contact_cursor;

-- Fetch the last row in the cursor.
FETCH LAST FROM contact_cursor;

-- Fetch the row immediately prior to the current row in the cursor.
FETCH PRIOR FROM contact_cursor;

-- Fetch the second row in the cursor.
FETCH ABSOLUTE 2 FROM contact_cursor;

-- Fetch the row that is three rows after the current row.
FETCH RELATIVE 3 FROM contact_cursor;

-- Fetch the row that is two rows prior to the current row.
FETCH RELATIVE -2 FROM contact_cursor;

CLOSE contact_cursor;
DEALLOCATE contact_cursor;
GO

Consulte também

Referência

Conceitos