FETCH

Descrição

O comando FETCH traz linhas utilizando um cursor previamente criado.

O cursor possui uma posição associada, a qual é 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 trazer algumas linhas, o cursor fica posicionado na linha trazida mais recentemente. Se o comando FETCH ultrapassar o final das linhas disponíveis, então o cursor fica posicionado após a última linha, ou antes da primeira linha se estiver trazendo 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 trazem uma única linha após mover o cursor de forma apropriada. Se a linha não existir, um resultado vazio é retornado, e o cursor é deixado posicionado antes da primeira linha ou após a última linha, conforme seja apropriado.

As formas que utilizam FORWARD e BACKWARD trazem 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 trazida a linha corrente sem mover o cursor, ou seja, traz novamente a linha trazida mais recentemente. Sempre é bem-sucedido, a menos que o cursor esteja posicionado antes da primeira linha ou após a última linha; nestes casos, nenhuma linha é retornada.

Parâmetros

Saídas

Ao terminar 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 trazidas 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 trazer para trás usando cursores não declarados com SCROLL, mas é bom não confiar neste comportamento. Se o cursor for declarado com NO SCROLL, então trazer para trás não é permitido.

Trazer com 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. Buscas absolutas negativas são piores 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.

A atualização dos dados através de cursores não é permitida atualmente pelo PostgreSQL.

O comando DECLARE é utilizado para definir o cursor. Deve ser utilizado o comando MOVE para mudar a posição do cursor sem trazer dados.

Exemplos

O exemplo a seguir percorre uma tabela usando um cursor.

=> BEGIN WORK;

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

=> -- Trazer 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

=> -- Trazer 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 do hospedeiro. Fora este ponto, o comando FETCH possui total compatibilidade ascendente [1] com o padrão SQL.

As formas do comando FETCH envolvendo FORWARD e BACKWARD, assim bem como todas as formas de FETCH contador e FETCH ALL, na qual o 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.