FETCH

Descrição

O comando FETCH retorna linhas utilizando um cursor previamente criado. [1] [2] [3]

O cursor possui uma posição associada, que é utilizada pelo comando FETCH. A posição do cursor pode ser: antes da primeira linha, em uma determinada linha, ou após a última linha do resultado da consulta. Ao ser criado, o cursor fica posicionado antes da primeira linha. Após retornar algumas linhas, o cursor fica posicionado na linha retornada mais recentemente. Se o comando FETCH ultrapassar o final das linhas disponíveis, então o cursor ficará posicionado após a última linha, ou antes da primeira linha se estiver retornando linhas para trás. Os comandos FETCH ALL e FETCH BACKWARD ALL sempre deixam o cursor posicionado após a última linha ou antes da primeira linha, respectivamente.

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

As formas que utilizam FORWARD e BACKWARD retornam o número indicado de linhas movendo o cursor para frente ou para trás, deixando o cursor posicionado na última linha retornada; ou após/antes de todas as linhas se o contador exceder o número de linhas disponíveis.

RELATIVE 0, FORWARD 0 e BACKWARD 0 requerem que seja retornada a linha corrente sem mover o cursor, ou seja, retorna novamente a linha retornada mais recentemente. Sempre é bem-sucedido, a menos que o cursor esteja posicionado antes da primeira linha ou após a última linha; nestes casos, não é retornada nenhuma linha.

Parâmetros

Saídas

Ao término bem-sucedido, o comando FETCH retorna uma linha de fim de comando na forma

FETCH contador

O contador é o número de linhas trazidas (possivelmente zero). Deve ser observado que no psql a linha de fim de comando não é exibida, uma vez que o psql mostra as linhas retornadas em seu lugar.

Observações

O cursor deve ser declarado com a opção SCROLL se houver intenção de utilizar qualquer variante do comando FETCH que não seja FETCH NEXT ou FETCH FORWARD com um contador positivo. Para consultas simples o PostgreSQL permite retornar linhas rolando para trás a partir de cursores não declarados com a opção SCROLL, mas é melhor não confiar neste comportamento. Se o cursor for declarado com a opção NO SCROLL, então não será permitido retornar linhas rolando para trás.

Retornar linhas com a opção ABSOLUTE não é nem um pouco mais rápido que navegar para a linha desejada usando um movimento relativo: a implementação subjacente necessita de qualquer maneira percorrer todas as linhas intermediárias. Retorno de linha absoluta negativa é pior ainda: a consulta precisa ser lida até o fim para encontrar a última linha, e depois percorrida para trás a partir deste ponto. Entretanto, voltar para o início da consulta (como com FETCH ABSOLUTE 0) é rápido.

Atualmente o PostgreSQL não permite a atualização dos dados através de cursores.

Para definir o cursor é utilizado o comando DECLARE. Para mudar a posição do cursor sem trazer dados é utilizado o comando MOVE.

Exemplos

O exemplo a seguir percorre uma tabela usando um cursor.

BEGIN WORK;

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

-- Retornar as 5 primeiras linhas do cursor liahona:
FETCH FORWARD 5 FROM liahona;

 cod   |          titulo         | did | data_prod  |   tipo   | duracao
-------+-------------------------+-----+------------+----------+---------
 BL101 | The Third Man           | 101 | 1949-12-23 | Drama    | 01:44
 BL102 | The African Queen       | 101 | 1951-08-11 | Romance  | 01:43
 JL201 | Une Femme est une Femme | 102 | 1961-03-12 | Romance  | 01:25
 P_301 | Vertigo                 | 103 | 1958-11-14 | Ação     | 02:08
 P_302 | Becket                  | 103 | 1964-02-03 | Drama    | 02:28

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

 cod   |  titulo | did | data_prod  |  tipo  | duracao
-------+---------+-----+------------+--------+---------
 P_301 | Vertigo | 103 | 1958-11-14 |  Ação  | 02:08

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

Compatibilidade

O padrão SQL define o comando FETCH apenas para uso na linguagem SQL incorporada (embedded). Esta variante do FETCH descrita aqui retorna os dados como se fossem o resultado de um comando SELECT, em vez de colocar nas variáveis hospedeiras. Fora este ponto, o comando FETCH possui total compatibilidade ascendente [4] com o padrão SQL.

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

O padrão SQL permite apenas o FROM precedendo o nome do cursor; a opção para utilizar IN é uma extensão.

Consulte também