Descrição

O comando FETCH recupera linhas usando um cursor criado anteriormente.

O cursor tem uma posição associada, usada pelo comando FETCH. A posição do cursor pode ser antes da primeira linha, em qualquer linha específica, ou depois da última linha do resultado da consulta. Ao ser criado, o cursor é posicionado antes da primeira linha. Após buscar algumas linhas, o cursor estará posicionado na linha recuperada mais recentemente. Se o comando FETCH for executado no final das linhas disponíveis, o cursor ficará posicionado após a última linha, ou antes da primeira linha, se a busca for para trás. Os comandos FETCH ALL e FETCH BACKWARD ALL sempre deixarão o cursor posicionado após a última linha, ou antes da primeira linha.

As formas NEXT, PRIOR, FIRST, LAST, ABSOLUTE, e RELATIVE, buscam uma única linha após mover o cursor da forma apropriada. Se esta linha não existir, será retornado um resultado vazio, e o cursor será posicionado antes da primeira linha, ou após a última linha, conforme seja apropriado.

As formas usando FORWARD e BACKWARD recuperam o número indicado de linhas, movendo para frente ou para trás, deixando o cursor posicionado na última linha retornada (ou depois/antes de todas as linhas, se o contador exceder o número de linhas disponíveis).

Todas as formas RELATIVE 0, FORWARD 0, e BACKWARD 0, solicitam a busca da linha corrente sem mover o cursor, ou seja, buscam novamente a linha buscada mais recentemente. Serão bem-sucedidas, a menos que o cursor seja posicionado antes da primeira linha, ou após a última linha; nesses casos, nenhuma linha será retornada.

Parâmetros

Saídas

Após a conclusão bem-sucedida, o comando FETCH retorna uma etiqueta de comando no formato

FETCH contador

O contador é o número de linhas buscadas (possivelmente zero). Note que no psql a etiqueta do comando não será mostrada, porque o psql mostra as linhas buscadas.

Notas

O cursor deverá ser declarado com a opção SCROLL, caso se pretenda usar qualquer variante de FETCH diferente de FETCH NEXT ou FETCH FORWARD com um contador positivo. Para consultas simples, o PostgreSQL permite a busca reversa para cursores não declarados com SCROLL, mas é melhor não confiar neste comportamento. Se o cursor for declarado com NO SCROLL, nenhuma busca para trás será permitida.

As buscas ABSOLUTE não são mais rápidas do que navegar para a linha desejada com um movimento relativo: a implementação subjacente deverá percorrer todas as linhas intermediárias de qualquer maneira. As buscas absolutas negativas são ainda piores: a consulta deverá ser lida até o final para encontrar a última linha e, em seguida, percorrida de volta a partir daí. Entretanto, voltar ao início da consulta (como em FETCH ABSOLUTE 0) é rápido.

Deve-se usar o comando DECLARE para definir o cursor, e o comando MOVE para alterar a posição do cursor sem recuperar os dados.

Exemplo

O exemplo a seguir percorre uma tabela usando um cursor:

BEGIN WORK;

-- Definir o cursor:
DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;

-- Buscar as 5 primeiras linhas no cursor liahona:
FETCH FORWARD 5 FROM liahona;

 code  |          title          | did | date_prod  |   kind   |  len
-------+-------------------------+-----+------------+----------+-------
 BL101 | The Third Man           | 101 | 1949-12-23 | Drama    | 01:44
 BL102 | The African Queen       | 101 | 1951-08-11 | Romantic | 01:43
 JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romantic | 01:25
 P_301 | Vertigo                 | 103 | 1958-11-14 | Action   | 02:08
 P_302 | Becket                  | 103 | 1964-02-03 | Drama    | 02:28

-- Buscar a linha anterior:
FETCH PRIOR FROM liahona;

 code  |  title  | did | date_prod  |  kind  |  len
-------+---------+-----+------------+--------+-------
 P_301 | Vertigo | 103 | 1958-11-14 | Action | 02:08

-- Fechar o cursor e finalizar a transação:
CLOSE liahona;
COMMIT WORK;

Conformidade

O padrão SQL define o comando FETCH para uso somente no SQL incorporado. A variante do comando FETCH descrita aqui retorna os dados como se fosse o resultado de um comando SELECT, em vez de colocá-los em variáveis do hospedeiro. Fora isto, o comando FETCH é totalmente compatível com o padrão SQL.

As formas do comando FETCH envolvendo FORWARD e BACKWARD, assim como a forma FETCH contador e FETCH ALL, onde FORWARD está implícito, são extensões PostgreSQL.

O padrão SQL permite que apenas FROM preceda o nome do cursor; a opção de usar IN, ou deixá-los de fora, é uma extensão.

Veja também