FETCH

Name

FETCH  --  busca linhas de uma tabela usando um cursor

Synopsis

FETCH [ direção ] [ contador ] { IN | FROM } cursor
FETCH [ FORWARD | BACKWARD | RELATIVE ] [ # | ALL | NEXT | PRIOR ] { IN | FROM } cursor
  

Entradas

direção

Um seletor definindo a direção da busca. Pode ser um dos seguintes:

FORWARD

busca a(s) próxima(s) linha(s). Este é o padrão quando o seletor for omitido.

BACKWARD

busca a(s) linha(s) anterior(es).

RELATIVE

Somente por compatibilidade com o SQL92.

contador

O contador determina quantas linhas serão buscadas. Pode ser um dos seguintes:

#

Um número inteiro com sinal que especifica quantas linhas serão buscadas. Observe que um número negativo é equivalente a mudar o sentido de FORWARD e de BACKWARD.

ALL

Busca todas as linhas remanescentes.

NEXT

Equivalente a especificar um contador igual a 1.

PRIOR

Equivalente a especificar um contador igual a -1.

cursor

O nome de um cursor aberto.

Saídas

O comando FETCH retorna o resultado da consulta definida pelo cursor especificado. As seguintes mensagens retornam quando a consulta falha:

NOTICE: PerformPortalFetch: portal "cursor" not found

Se o cursor não tiver sido previamente declarado. O cursor deve ser declarado dentro do bloco da transação.

NOTICE: FETCH/ABSOLUTE not supported, using RELATIVE

O PostgreSQL não suporta o posicionamento absoluto do cursor.

ERROR: FETCH/RELATIVE at current position is not supported

O SQL92 permite buscar repetitivamente o cursor em sua "posição corrente" usando a sintaxe

FETCH RELATIVE 0 FROM cursor.
	

O PostgreSQL atualmente não suporta esta noção; na verdade o valor zero é reservado para indicar que todas as linhas devem ser buscadas, equivalendo a especificar a palavra chave ALL. Se a palavra chave RELATIVE for usada, o PostgreSQL assume que o usuário deseja o comportamento do SQL92 e retorna esta mensagem de erro.

Descrição

O comando FETCH permite o usuário buscar linhas usando um cursor. O número de linhas buscadas é especificado pelo #. Se o número de linhas remanescentes no cursor for menor do que #, então somente as linhas disponíveis são buscadas. Colocando-se a palavra chave ALL no lugar do número faz com que todas as linhas restantes no cursor sejam buscadas. As instâncias podem ser buscadas para frente (FORWARD) e para trás (BACKWARD) O padrão é para frente.

Tip: É permitido especificar números negativos para o contador de linhas. Um número negativo equivale a inverter o sentido das palavras chave FORWARD e BACKWARD. Por exemplo, FORWARD -1 é o mesmo que BACKWARD 1.

Notas

Observe que as palavras chave FORWARD e BACKWARD são extensões do PostgreSQL. A sintaxe do SQL92 também é suportada, especificando-se a segunda forma do comando. Veja abaixo para obter detalhes sobre questões de compatibilidade.

A atualização de dados pelo cursor não é suportada pelo PostgreSQL, porque mapear as atualizações do cursor de volta para as tabelas base geralmente não é possível, como no caso das atualizações nas visões. Conseqüentemente, os usuários devem executar um comando UPDATE explícito para atualizar os dados.

Os cursores somente podem ser usados dentro de transações, porque os dados por eles armazenados estendem-se por muitas consultas dos usuários.

Use o comando MOVE para mudar a posição do cursor. O comando DECLARE define um cursor. Consulte os comando BEGIN, COMMIT, e ROLLBACK para obter mais detalhes sobre transações.

Utilização

O exemplo a seguir acessa uma tabela usando um cursor.

-- Definir e usar o cursor:

BEGIN WORK;
DECLARE liahona CURSOR FOR SELECT * FROM filmes;

-- Buscar as 5 primeiras linhas do cursor liahona:
FETCH FORWARD 5 IN 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

-- Buscar a linha anterior:
FETCH BACKWARD 1 IN liahona;

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

-- fechar a consulta e efetivar o trabalho:

CLOSE liahona;
COMMIT WORK;

Compatibilidade

SQL92

Note: O uso não embutido de cursores é uma extensão do PostgreSQL. A sintaxe e a utilização dos cursores está sendo comparada com relação à forma embutida dos cursores definida no SQL92.

O SQL92 permite o posicionamento absoluto de cursores para a busca (FETCH), e permite armazenar os resultados em variáveis explicitadas:

FETCH ABSOLUTE #
    FROM cursor
    INTO :variável [, ...]
    

ABSOLUTE

O cursor deve ser posicionado na linha especificada pelo número absoluto. Todos os números de linhas no PostgreSQL são números relativos, portanto esta funcionalidade não é suportada.

:variável

Variável do programa.