FETCH (Transact-SQL)

Artigo
11/19/2024

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Banco de Dados SQL no Microsoft Fabric

Recupera uma linha específica de um cursor de servidor Transact-SQL.

Convenções de sintaxe de 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 é positivo, retorna a linha que está n linhas do início do cursor e torna a linha retornada a nova linha atual. Se n ou @nvar é negativo, retorna a linha que está n linhas antes do final do cursor e torna a linha retornada a nova linha atual. Se n ou @nvar é 0, nenhuma linha é retornada. n deve ser uma constante de inteiro e @nvar deve ser smallint, tinyint ou int.

RELATIVE { n| @nvar}
Se n ou @nvar é positivo, retorna a linha que está n linhas após a linha atual e torna a linha retornada a nova linha atual. Se n ou @nvar é negativo, retorna a linha que está n linhas antes da linha atual e torna a linha retornada a nova linha atual. Se n ou @nvar é 0, retorna a linha atual. Se FETCH RELATIVE é especificado com n ou @nvar definido como números negativos ou 0 na primeira busca feita em um cursor, nenhuma linha é retornada. n deve ser uma constante de inteiro 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 se referirá ao cursor global, caso GLOBAL seja especificado, e ao cursor local, caso GLOBAL não seja 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 de estilo ISO DECLARE CURSOR, NEXT será a única opção FETCH com suporte. Se SCROLL for especificado em um estilo ISO DECLARE CURSOR, todas as opções FETCH terão suporte.

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

Se qualquer um dos FORWARD_ONLY ou FAST_FORWARD for especificado, NEXT será a única opção FETCH com suporte.
Se DYNAMIC, FORWARD_ONLY ou FAST_FORWARD não forem especificados e um de KEYSET, STATIC ou SCROLL forem especificados, todas as opções FETCH terão suporte.
DYNAMIC SCROLL cursores dão suporte a todas as opções FETCH, exceto ABSOLUTE.

A função @@FETCH_STATUS relata 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, confira @@FETCH_STATUS (Transact-SQL).

Permissões

As permissões para FETCH são padronizadas para qualquer usuário válido.

Exemplos

a. Usando FETCH em um cursor simples

O exemplo a seguir declara um cursor simples para as linhas da tabela Person.Person com um sobrenome que inicia com B e usa FETCH NEXT para percorrer as linhas. As instruções FETCH retornam o valor da coluna especificada em DECLARE CURSOR como um conjunto de resultados de uma linha.

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

O exemplo a seguir é semelhante ao exemplo A, com exceção de que a saída das instruções FETCH é armazenada em variáveis locais em vez de ser retornada diretamente para o cliente. A instrução PRINT combina as variáveis em uma única cadeia de caracteres e as retorna ao cliente.

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

O exemplo a seguir cria um cursor SCROLL para permitir recursos de rolagem completos por meio das opções LAST, PRIOR, RELATIVE e ABSOLUTE.

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

CLOSE (Transact-SQL)
DEALLOCATE (Transact-SQL)
DECLARE CURSOR (Transact-SQL)
OPEN (Transact-SQL)

Compartilhar via

FETCH (Transact-SQL)

Sintaxe

Argumentos

Comentários

Permissões

Exemplos

a. Usando FETCH em um cursor simples

B. Usando FETCH para armazenar valores em variáveis

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

Consulte Também

Comentários

Recursos adicionais