SPI_prepare
SPI_prepare — подготовить оператор, но пока не выполнять его
Синтаксис
SPIPlanPtr SPI_prepare(const char *command
, intnargs
, Oid *argtypes
)
Описание
SPI_prepare
создаёт и возвращает подготовленный оператор для заданной команды. Подготовленный оператор может быть затем неоднократно выполнен функцией SPI_execute_plan
.
Когда одна и та же или похожие команды выполняются неоднократно, обычно выгоднее произвести анализ запроса только раз, а ещё выгоднее может быть повторно использовать план выполнения команды. SPI_prepare
преобразует строку команды в подготовленный оператор, включающий в себя результаты анализа запроса. Подготовленный оператор также оставляет место для кеширования плана выполнения, если выбор специализированного плана для каждого выполнения не принесёт пользы.
Подготавливаемую команду можно сделать более общей, записав параметры ($1
, $2
, etc.) вместо значений, задаваемыми константами в обычной команде. Фактические значения параметров в этом случае будут задаваться при вызове SPI_execute_plan
. Это позволяет применять подготовленную команду в более широком круге ситуаций, чем это возможно без параметров.
Оператор, возвращаемый функцией SPI_prepare
, может использоваться только в текущем вызове функции на C, так как SPI_finish
освобождает память, выделенную для такого оператора. Но этот оператор может быть сохранён на будущее с помощью функций SPI_keepplan
или SPI_saveplan
.
Аргументы
const char *
command
строка команды
int
nargs
число входных параметров (
$1
,$2
и т. д.)Oid *
argtypes
указатель на массив, содержащий OID типов параметров
Возвращаемое значение
SPI_prepare
возвращает ненулевой указатель на SPIPlan
, скрытую структуру, представляющую подготовленный оператор. В случае ошибки возвращается NULL
, а в SPI_result
устанавливается один из кодов ошибок, определённых для SPI_execute
, за исключением того, что код SPI_ERROR_ARGUMENT
устанавливается, когда command
— NULL
, когда nargs
меньше 0 или когда nargs
больше 0, а argtypes
— NULL
.
Примечания
Если параметры не определены, при первом использовании SPI_execute_plan
создаётся общий план, который затем будет применяться при последующих вызовах. Если же присутствуют параметры, SPI_execute_plan
будет создавать специализированные планы для конкретных значений параметров. После достаточного количества использований полученного подготовленного оператора, функция SPI_execute_plan
построит общий план, и если он не будет значительно дороже специализированных, она начнёт использовать его, а не будет строить план заново. Если это поведение по умолчанию не устраивает, его можно изменить, передав флаг CURSOR_OPT_GENERIC_PLAN
или CURSOR_OPT_CUSTOM_PLAN
в SPI_prepare_cursor
, чтобы ограничиться использованием только общего или специализированных планов, соответственно.
Хотя основной смысл подготовленного оператора в том, чтобы избежать повторного разбора и планирования запроса, PostgreSQL всё же будет принудительно повторять разбор и планирование запроса перед его выполнением, если со времени предыдущего использования подготовленного оператора произойдут изменения определений (DDL) объектов базы, задействованных в этом запросе. Также, если перед очередным использованием было изменено значение search_path, запрос будет разобран заново с новым значением search_path
. (Последняя особенность появилась в PostgreSQL 9.3.) Чтобы узнать о поведении подготовленных операторов больше, обратитесь к PREPARE.
Эту функцию следует вызывать только из подключённой функции на C.
SPIPlanPtr
объявлен в spi.h
как указатель на скрытую структуру. Пытаться обращаться к её содержимому напрямую не стоит, так как ваш код скорее всего сломается при выходе новых версий PostgreSQL.
Имя SPIPlanPtr
объясняется отчасти историческими причинами, так как теперь эта структура может не содержать собственно план выполнения.