SPI_execute_plan_extended
SPI_execute_plan_extended — выполнить оператор, подготовленный функцией SPI_prepare
Синтаксис
int SPI_execute_plan_extended(SPIPlanPtrplan
, const SPIExecuteOptions *options
)
Описание
SPI_execute_plan_extended
выполняет оператор, подготовленный функцией SPI_prepare
или родственными ей. Данная функция равнозначна SPI_execute_plan
, не считая того, что по-другому представляется информация о значениях параметров, передаваемых запросу. Также ей могут передаваться дополнительные параметры для управления выполнением запроса.
Значения параметров запроса передаются в структуре ParamListInfo
; это удобно, когда имеющиеся значения уже представлены в этом формате. Через функции-обработчики, устанавливаемые в ParamListInfo
, можно также передавать динамические наборы параметров.
Кроме того, кортежи результата могут не только накапливаться в структуре SPI_tuptable
, но и передаваться заданному вызывающим кодом объекту DestReceiver
по мере формирования очередного кортежа исполнителем. Особенно полезно использовать этот объект в запросах, которые могут выдать множество кортежей, поскольку данные будут обрабатываться «на лету», а не накапливаться в памяти.
Аргументы
SPIPlanPtr
plan
подготовленный оператор (возвращаемый функцией
SPI_prepare
)const SPIExecuteOptions *
options
структура, содержащая необязательные аргументы
Структуру options
всегда следует сначала полностью заполнять нулями, а затем уже задавать необходимые значения. Это гарантирует совместимость с будущими изменениями в коде: при добавлении в эту структуру любых новых полей нулевое значение будет определять старое поведение. Сейчас в options
есть такие поля:
ParamListInfo
params
структура данных, содержащая типы и значения параметров запроса; NULL, если их нет
bool
read_only
true
для режима выполнения «только чтение»bool
allow_nonatomic
true
для неатомарного выполнения операторов CALL и DO (но это поле игнорируется, если функцииSPI_connect_ext
не был передан флагSPI_OPT_NONATOMIC
)bool
must_return_tuples
если
true
, вызывает ошибку для типов запросов, не возвращающих кортежи (за исключением случая, когда возвращаются нулевые кортежи)uint64
tcount
максимальное число строк, которое должно быть возвращено; с
0
ограничения нетDestReceiver *
dest
объект
DestReceiver
, получающий все кортежи, которые выдаёт запрос; если NULL, результирующие кортежи накапливаются вSPI_tuptable
, как при выполненииSPI_execute_plan
ResourceOwner
owner
Владелец ресурса, который будет содержать счётчик ссылок на план во время его выполнения. Если NULL, используется текущий владелец ресурса. Параметр игнорируется для несохранённых планов, поскольку SPI не получает счётчики ссылок на них.
Возвращаемое значение
Возвращаемые значения те же, что и у SPI_execute_plan
.
Если options->dest
имеет значение NULL, SPI_processed
и SPI_tuptable
устанавливаются как при выполнении SPI_execute_plan
. Если options->dest
— не NULL, то SPI_processed
принимает нулевое значение, а SPI_tuptable
— NULL. Если необходимо подсчитать число кортежей, это нужно сделать в коде объекта DestReceiver
.