FETCH (Transact-SQL)FETCH (Transact-SQL)

APLICA-SE A: simSQL Server (a partir do 2008) simBanco de Dados SQL do Azure nãoSQL Data Warehouse do Azure nãoParallel Data Warehouse APPLIES TO: yesSQL Server (starting with 2008) yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Recupera uma linha específica de um cursor de servidor Transact-SQLTransact-SQL.Retrieves a specific row from a Transact-SQLTransact-SQL server cursor.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

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

ArgumentosArguments

NEXTNEXT
Retorna a linha de resultado imediatamente seguinte à linha atual e adiciona a linha atual à linha retornada.Returns the result row immediately following the current row and increments the current row to the row returned. Se FETCH NEXT for a primeira busca de um cursor, a primeira linha do conjunto de resultados será retornada.If FETCH NEXT is the first fetch against a cursor, it returns the first row in the result set. NEXT é a opção padrão de busca de cursor.NEXT is the default cursor fetch option.

PRIORPRIOR
Retorna a linha de resultado imediatamente anterior à linha atual e decrementa a linha atual da linha retornada.Returns the result row immediately preceding the current row, and decrements the current row to the row returned. Se FETCH PRIOR for a primeira busca de um cursor, nenhuma linha será retornada e o cursor será deixado posicionado antes da primeira linha.If FETCH PRIOR is the first fetch against a cursor, no row is returned and the cursor is left positioned before the first row.

FIRSTFIRST
Retorna a primeira linha no cursor e a torna a linha atual.Returns the first row in the cursor and makes it the current row.

LASTLAST
Retorna a última linha no cursor e a torna a linha atual.Returns the last row in the cursor and makes it the current row.

ABSOLUTE { n| @nvar}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.If n or @nvar is positive, returns the row n rows from the front of the cursor and makes the returned row the new current row. 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.If n or @nvar is negative, returns the row n rows before the end of the cursor and makes the returned row the new current row. Se n ou @nvar é 0, nenhuma linha é retornada.If n or @nvar is 0, no rows are returned. n deve ser uma constante de inteiro e @nvar deve ser smallint, tinyint ou int.n must be an integer constant and @nvar must be smallint, tinyint, or int.

RELATIVE { n| @nvar}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.If n or @nvar is positive, returns the row n rows beyond the current row and makes the returned row the new current row. 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.If n or @nvar is negative, returns the row n rows prior to the current row and makes the returned row the new current row. Se n ou @nvar é 0, retorna a linha atual.If n or @nvar is 0, returns the current row. 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.If FETCH RELATIVE is specified with n or @nvar set to negative numbers or 0 on the first fetch done against a cursor, no rows are returned. n deve ser uma constante de inteiro e @nvar deve ser smallint, tinyint ou int.n must be an integer constant and @nvar must be smallint, tinyint, or int.

GLOBALGLOBAL
Especifica que cursor_name se refere a um cursor global.Specifies that cursor_name refers to a global cursor.

cursor_namecursor_name
É o nome do cursor aberto a partir do qual a busca deve ser feita.Is the name of the open cursor from which the fetch should be made. 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.If both a global and a local cursor exist with cursor_name as their name, cursor_name to the global cursor if GLOBAL is specified and to the local cursor if GLOBAL is not specified.

@cursor_variable_name@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.Is the name of a cursor variable referencing the open cursor from which the fetch should be made.

INTO @variable_name[ ,...n]INTO @variable_name[ ,...n]
Permite que os dados das colunas de uma busca sejam colocados em variáveis locais.Allows data from the columns of a fetch to be placed into local variables. Cada variável na lista, da esquerda para a direita, está associada à coluna correspondente no conjunto de resultados do cursor.Each variable in the list, from left to right, is associated with the corresponding column in the cursor result set. 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.The data type of each variable must either match or be a supported implicit conversion of the data type of the corresponding result set column. O número de variáveis deve corresponder ao número de colunas na lista de seleção do cursor.The number of variables must match the number of columns in the cursor select list.

RemarksRemarks

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.If the SCROLL option is not specified in an ISO style DECLARE CURSOR statement, NEXT is the only FETCH option supported. Se SCROLL for especificado em um estilo ISO DECLARE CURSOR, todas as opções FETCH terão suporte.If SCROLL is specified in an ISO style DECLARE CURSOR, all FETCH options are supported.

Quando as extensões de cursor DECLARE do Transact-SQLTransact-SQL forem usadas, estas regras se aplicarão:When the Transact-SQLTransact-SQL DECLARE cursor extensions are used, these rules apply:

  • Se qualquer um dos FORWARD_ONLY ou FAST_FORWARD for especificado, NEXT será a única opção FETCH com suporte.If either FORWARD_ONLY or FAST_FORWARD is specified, NEXT is the only FETCH option supported.

  • 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.If DYNAMIC, FORWARD_ONLY or FAST_FORWARD are not specified, and one of KEYSET, STATIC, or SCROLL are specified, all FETCH options are supported.

  • DYNAMIC SCROLL cursores dão suporte a todas as opções FETCH, exceto ABSOLUTE.DYNAMIC SCROLL cursors support all the FETCH options except ABSOLUTE.

A função @@FETCH_STATUS relata o status da última instrução FETCH.The @@FETCH_STATUS function reports the status of the last FETCH statement. As mesmas informações são registradas na coluna fetch_status do cursor retornado por sp_describe_cursor.The same information is recorded in the fetch_status column in the cursor returned by 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.This status information should be used to determine the validity of the data returned by a FETCH statement prior to attempting any operation against that data. Para obter mais informações, consulte @@FETCH_STATUS (Transact-SQL).For more information, see @@FETCH_STATUS (Transact-SQL).

PermissõesPermissions

As permissões para FETCH são padronizadas para qualquer usuário válido.Permissions for FETCH default to any valid user.

ExemplosExamples

A.A. Usando FETCH em um cursor simplesUsing FETCH in a simple cursor

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.The following example declares a simple cursor for the rows in the Person.Person table with a last name that starts with B, and uses FETCH NEXT to step through the rows. As instruções FETCH retornam o valor da coluna especificada em DECLARE CURSOR como um conjunto de resultados de uma linha.The FETCH statements return the value for the column specified in DECLARE CURSOR as a single-row result set.

USE AdventureWorks2012;  
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.B. Usando FETCH para armazenar valores em variáveisUsing FETCH to store values in variables

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.The following example is similar to example A, except the output of the FETCH statements is stored in local variables instead of being returned directly to the client. A instrução PRINT combina as variáveis em uma única cadeia de caracteres e as retorna ao cliente.The PRINT statement combines the variables into a single string and returns them to the client.

USE AdventureWorks2012;  
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.C. Declarando um cursor SCROLL e usando as outras opções de FETCHDeclaring a SCROLL cursor and using the other FETCH options

O exemplo a seguir cria um cursor SCROLL para permitir recursos de rolagem completos por meio das opções LAST, PRIOR, RELATIVE e ABSOLUTE.The following example creates a SCROLL cursor to allow full scrolling capabilities through the LAST, PRIOR, RELATIVE, and ABSOLUTE options.

USE AdventureWorks2012;  
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émSee Also

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