FETCH

примечание

Эта страница переведена при помощи нейросети GigaChat.

FETCH - получение результата запроса через курсор.

Синтаксис

FETCH [ direction ] [ FROM | IN ] cursor_name

where direction can be one of:

    NEXT
    PRIOR
    FIRST
    LAST
    ABSOLUTE count
    RELATIVE count
    count
    ALL
    FORWARD
    FORWARD count
    FORWARD ALL
    BACKWARD
    BACKWARD count
    BACKWARD ALL

Описание

FETCH получает строки через ранее созданный курсор.

Курсор связан с определенным положением, которая используется командой FETCH. Позиция курсора может находиться:

• до первой строки результата запроса;
• на любой конкретной строке результата;
• после последней строки.

При создании курсор устанавливается до первой строки. После извлечения некоторых строк курсор будет установлен на последнюю извлеченную строку. Если FETCH доходит до конца доступных строк, курсор будет установлен после последней строки, либо до первой строки, если происходит обратное извлечение. Команды FETCH ALL или FETCH BACKWARD ALL всегда оставляют курсор установленным после последней строки или до первой строки, соответственно.

Формы NEXT, PRIOR, FIRST, LAST, ABSOLUTE, RELATIVE извлекают одну строку, при этом курсор передвигается соответствующим образом. Если такой строки не существует, возвращается пустой результат, а курсор устанавливается до первой строки или после последней строки, как это уместно.

Формы с использованием FORWARD и BACKWARD извлекают указанное количество строк, перемещаясь вперед или назад, и оставляют курсор установленным на последней возвращенной строке (или после/до всех строк, если количество превышает доступное).

RELATIVE 0, FORWARD 0 и BACKWARD 0 запрашивают извлечение текущей строки без перемещения курсора, то есть повторное извлечение самой недавно извлеченной строки. Это будет успешно выполнено, если только курсор не установлен перед первой строкой или после последней строки. В этом случае строка не возвращается.

Примечание

Эта страница описывает использование курсоров на уровне SQL-команд. Если используются курсоры внутри функции PL/pgSQL, действуют другие правила — смотрите раздел «Использование курсоров» документации PostgreSQL.

Параметры

direction

Определяет направление перемещения курсора и количество строк для извлечения. Может принимать следующие значения:

NEXT : Извлекает следующую строку. Это поведение по умолчанию, если параметр direction опущен.

PRIOR : Извлекает предыдущую строку.

FIRST : Извлекает первую строку запроса (то же самое, что ABSOLUTE 1).

LAST : Извлекает последнюю строку запроса (то же самое, что ABSOLUTE -1).

ABSOLUTE count : Извлекает строку с номером count, либо abs(count) с конца, если count отрицательное. Если count вне допустимого диапазона, курсор устанавливается до первой или после последней строки. Например, ABSOLUTE 0 устанавливает курсор до первой строки.

RELATIVE count : Извлекает следующую строку с номером count, либо предыдущую строку abs(count), если count отрицательное. RELATIVE 0 означает повторное извлечение текущей строки, если таковая имеется.

count : Извлекает следующие count строки (то же самое, что и FORWARD count).

ALL : Извлекает все оставшиеся строки (то же самое, как FORWARD ALL).

FORWARD : Извлекает следующую строку (то же самое, как NEXT).

FORWARD count : Извлекает следующие count строки. FORWARD 0 повторно извлекает текущую строку.

FORWARD ALL : Извлекает все оставшиеся строки.

BACKWARD : Извлекает предыдущей строки (то же самое, что и PRIOR).

BACKWARD count : Извлекает предыдущие count строки (сканирование назад). BACKWARD 0 повторно извлекает текущую строку.

BACKWARD ALL : Извлекает все предыдущие строки (сканирование назад).

count

Задает целое число (может быть отрицательным), определяет номер строки (ABSOLUTE, RELATIVE) или количество строк (FORWARD, BACKWARD).

cursor_name

Задает имя открытого курсора.

Выводимая информация

При успешном выполнении FETCH возвращает тег команды следующего вида:

FETCH count

где count — количество извлеченных строк (возможно, ноль).

Обратите внимание, что в клиенте psql этот тег не отображается, так как вместо этого показываются сами извлеченные строки.

Примечания

Курсор должен быть объявлен с параметром SCROLL, если планируется использовать какие-либо формы FETCH, кроме FETCH NEXT или FETCH FORWARD с положительным количеством. Для простых запросов PostgreSQL позволяет обратное извлечение и без SCROLL, но полагаться на это поведение не рекомендуется. Если курсор объявлен с NO SCROLL, обратное извлечение запрещено.

Извлечение с помощью ABSOLUTE не быстрее, чем навигация с использованием RELATIVE: реализация все равно должна пройти все промежуточные строки. Отрицательные значения в ABSOLUTE — еще медленнее: сначала запрос читается до конца, чтобы найти последнюю строку, а затем перемещается назад оттуда. Однако возврат в начало запроса, например FETCH ABSOLUTE 0, быстр.

Курсоры создаются командой DECLARE. Для перемещения курсора без извлечения данных используйте команду MOVE.

Примеры

В следующем примере используется курсор для обхода таблицы:

BEGIN WORK;

-- Set up a cursor:
DECLARE liahona SCROLL CURSOR FOR SELECT * FROM films;

-- Fetch the first 5 rows in the 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

-- Fetch the previous row:
FETCH PRIOR FROM liahona;

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

-- Close the cursor and end the transaction:
CLOSE liahona;
COMMIT WORK;

Совместимость

Стандарт SQL определяет FETCH только для встроенного SQL. Вариант FETCH, описанный здесь, возвращает данные так, как если бы они были результатом SELECT, а не размещались в переменных хоста. За исключением этого момента, FETCH полностью совместим со стандартом SQL.

Формы, включающие FETCH и FORWARD, а также формы FETCH count и FETCH ALL, в которых FORWARD подразумевается, являются расширениями PostgreSQL.

Стандарт SQL допускает только FROM перед именем курсора, возможность использовать IN или вообще их опустить является расширением.

Смотрите также

CLOSE, DECLARE, MOVE