+ endterm="sql-createfunction-title"> command to
understand the examples better. Some examples from this chapter
can be found in funcs.sql and
funcs.c in the src/tutorial
SELECT 1 AS result;
$$ LANGUAGE SQL;
--- Alternative syntax:
+-- Alternative syntax for string literal:
CREATE FUNCTION one() RETURNS integer AS '
SELECT 1 AS result;
' LANGUAGE SQL;
- The select list order in the query must be exactly the same as
- that in which the columns appear in the table associated
- with the composite type. (Naming the columns, as we did above,
- is irrelevant to the system.)
+ The select list order in the query must be exactly the same as
+ that in which the columns appear in the table associated
+ with the composite type. (Naming the columns, as we did above,
+ is irrelevant to the system.)
- You must typecast the expressions to match the
- definition of the composite type, or you will get errors like this:
+ You must typecast the expressions to match the
+ definition of the composite type, or you will get errors like this:
ERROR: function declared to return emp returns varchar instead of text at column 1
- A function that returns a row (composite type) can be used as a table
- function, as described below. It can also be called in the context
- of an SQL expression, but only when you
- extract a single attribute out of the row or pass the entire row into
- another function that accepts the same composite type.
-
-
- This is an example of extracting an attribute out of a row type:
+ When you call a function that returns a row (composite type) in a
+ SQL expression, you might want only one field (attribute) from its
+ result. You can do that with syntax like this:
SELECT (new_emp()).name;
None
- We need the extra parentheses to keep the parser from getting confused:
+ The extra parentheses are needed to keep the parser from getting
+ confused. If you try to do it without them, you get something like this:
SELECT new_emp().name;
ERROR: syntax error at or near "." at character 17
+LINE 1: SELECT new_emp().name;
+ ^
- The other way to use a function returning a row result is to declare a
- second function accepting a row type argument and pass the
- result of the first function to it:
+ Another way to use a function returning a row result is to pass the
+ result to another function that accepts the correct row type as input:
CREATE FUNCTION getname(emp) RETURNS text AS $$
(1 row)
+
+ Another way to use a function that returns a composite type is to
+ call it as a table function, as described below.
+
Note that we only got one row out of the function. This is because
- we did not use SETOF. This is described in the next section.
+ we did not use SETOF. That is described in the next section.
- It is permitted to have polymorphic arguments with a deterministic
+ It is permitted to have polymorphic arguments with a fixed
return type, but the converse is not. For example:
CREATE FUNCTION is_greater(anyelement, anyelement) RETURNS boolean AS $$
+
+
Function Overloading
+
+
+ functions
+
+
+ More than one function may be defined with the same SQL name, so long
+ as the arguments they take are different. In other words,
+ function names can be overloaded. When a
+ query is executed, the server will determine which function to
+ call from the data types and the number of the provided arguments.
+ Overloading can also be used to simulate functions with a variable
+ number of arguments, up to a finite maximum number.
+
+
+ When creating a family of overloaded functions, one should be
+ careful not to create ambiguities. For instance, given the
+ functions
+CREATE FUNCTION test(int, real) RETURNS ...
+CREATE FUNCTION test(smallint, double precision) RETURNS ...
+
+ it is not immediately clear which function would be called with
+ some trivial input like test(1, 1.5). The
+ currently implemented resolution rules are described in
+ , but it is unwise to design a system that subtly
+ relies on this behavior.
+
+
+ A function that takes a single argument of a composite type should
+ generally not have the same name as any attribute (field) of that type.
+ Recall that attribute(table) is considered equivalent
+ to table.attribute. In the case that there is an
+ ambiguity between a function on a composite type and an attribute of
+ the composite type, the attribute will always be used. It is possible
+ to override that choice by schema-qualifying the function name
+ (that is, schema.func(table)) but it's better to
+ avoid the problem by not choosing conflicting names.
+
+
+ When overloading C-language functions, there is an additional
+ constraint: The C name of each function in the family of
+ overloaded functions must be different from the C names of all
+ other functions, either internal or dynamically loaded. If this
+ rule is violated, the behavior is not portable. You might get a
+ run-time linker error, or one of the functions will get called
+ (usually the internal one). The alternative form of the
+ AS clause for the SQL CREATE
+ FUNCTION command decouples the SQL function name from
+ the function name in the C source code. For instance,
+CREATE FUNCTION test(int) RETURNS int
+ AS 'filename', 'test_1arg'
+ LANGUAGE C;
+CREATE FUNCTION test(int, int) RETURNS int
+ AS 'filename', 'test_2arg'
+ LANGUAGE C;
+
+ The names of the C functions here reflect one of many possible conventions.
+
+
+
+
+
Function Volatility Categories
+
+
+ functions
+
+
+ Every function has a volatility classification, with
+ the possibilities being VOLATILE, STABLE, or
+ IMMUTABLE. VOLATILE is the default if the
+ CREATE FUNCTION command does not specify a category.
+ The volatility category is a promise to the optimizer about the behavior
+ of the function:
+
+
+
+ A VOLATILE function can do anything, including modifying
+ the database. It can return different results on successive calls with
+ the same arguments. The optimizer makes no assumptions about the
+ behavior of such functions. A query using a volatile function will
+ re-evaluate the function at every row where its value is needed.
+
+
+
+ A STABLE function cannot modify the database and is
+ guaranteed to return the same results given the same arguments
+ for all calls within a single surrounding query. This category
+ allows the optimizer to optimize away multiple calls of the function
+ within a single query. In particular, it is safe to use an expression
+ containing such a function in an index scan condition. (Since an
+ index scan will evaluate the comparison value only once, not once at
+ each row, it is not valid to use a VOLATILE function in
+ an index scan condition.)
+
+
+
+ An IMMUTABLE function cannot modify the database and is
+ guaranteed to return the same results given the same arguments forever.
+ This category allows the optimizer to pre-evaluate the function when
+ a query calls it with constant arguments. For example, a query like
+ SELECT ... WHERE x = 2 + 2 can be simplified on sight to
+ SELECT ... WHERE x = 4, because the function underlying
+ the integer addition operator is marked IMMUTABLE.
+
+
+
+
+
+ For best optimization results, you should label your functions with the
+ strictest volatility category that is valid for them.
+
+
+ Any function with side-effects must be labeled
+ VOLATILE, so that calls to it cannot be optimized away.
+ Even a function with no side-effects needs to be labeled
+ VOLATILE if its value can change within a single query;
+ some examples are random(), currval(),
+ timeofday().
+
+
+ There is relatively little difference between STABLE and
+ IMMUTABLE categories when considering simple interactive
+ queries that are planned and immediately executed: it doesn't matter
+ a lot whether a function is executed once during planning or once during
+ query execution startup. But there is a big difference if the plan is
+ saved and reused later. Labeling a function IMMUTABLE when
+ it really isn't may allow it to be prematurely folded to a constant during
+ planning, resulting in a stale value being re-used during subsequent uses
+ of the plan. This is a hazard when using prepared statements or when
+ using function languages that cache plans (such as
+
+
+ Because of the snapshotting behavior of MVCC (see )
+ a function containing only SELECT commands can safely be
+ marked STABLE, even if it selects from tables that might be
+ undergoing modifications by concurrent queries.
+
PostgreSQL will execute a
STABLE+ function using the snapshot established for the calling query, and so it
+ will see a fixed view of the database throughout that query.
+ Also note
+ that the current_timestamp family of functions qualify
+ as stable, since their values do not change within a transaction.
+
+
+ The same snapshotting behavior is used for SELECT commands
+ within IMMUTABLE functions. It is generally unwise to select
+ from database tables within an IMMUTABLE function at all,
+ since the immutability will be broken if the table contents ever change.
+ However,
PostgreSQL does not enforce that you
+ do not do that.
+
+
+ A common error is to label a function IMMUTABLE when its
+ results depend on a configuration parameter. For example, a function
+ that manipulates timestamps might well have results that depend on the
+ setting. For safety, such functions should
+ be labeled STABLE instead.
+
+
+
+ Before
PostgreSQL release 8.0, the requirement
+ that STABLE and IMMUTABLE functions cannot modify
+ the database was not enforced by the system. Release 8.0 enforces it
+ by requiring SQL functions and procedural language functions of these
+ categories to contain no SQL commands other than SELECT.
+ (This is not a completely bulletproof test, since such functions could
+ still call VOLATILE functions that modify the database.
+ If you do that, you will find that the STABLE or
+ IMMUTABLE function does not notice the database changes
+ applied by the called function.)
+
+
+
+
Procedural Language Functions
If the name starts with the string $libdir,
that part is replaced by the
PostgreSQL package- library directory
+ library directory
name, which is determined at build time.
$libdir
- pass by value, fixed-length
+ pass by value, fixed-length
- pass by reference, fixed-length
+ pass by reference, fixed-length
- pass by reference, variable-length
+ pass by reference, variable-length
Equivalent C Types for Built-In SQL Types
- |
-
- SQL Type
-
-
- C Type
-
-
- Defined In
-
-
+ |
+
+ SQL Type
+
+
+ C Type
+
+
+ Defined In
+
+
- |
- abstime
- AbsoluteTime
- utils/nabstime.h
-
- |
- boolean
- bool
- postgres.h (maybe compiler built-in)
-
- |
- box
- BOX*
- utils/geo_decls.h
-
- |
- bytea
- bytea*
- postgres.h
-
- |
- "char"
- char
- (compiler built-in)
-
- |
- character
- BpChar*
- postgres.h
-
- |
- cid
- CommandId
- postgres.h
-
- |
- date
- DateADT
- utils/date.h
-
- |
- smallint (int2)
- int2 or int16
- postgres.h
-
- |
- int2vector
- int2vector*
- postgres.h
-
- |
- integer (int4)
- int4 or int32
- postgres.h
-
- |
- real (float4)
- float4*
- postgres.h
-
- |
- double precision (float8)
- float8*
- postgres.h
-
- |
- interval
- Interval*
- utils/timestamp.h
-
- |
- lseg
- LSEG*
- utils/geo_decls.h
-
- |
- name
- Name
- postgres.h
-
- |
- oid
- Oid
- postgres.h
-
- |
- oidvector
- oidvector*
- postgres.h
-
- |
- path
- PATH*
- utils/geo_decls.h
-
- |
- point
- POINT*
- utils/geo_decls.h
-
- |
- regproc
- regproc
- postgres.h
-
- |
- reltime
- RelativeTime
- utils/nabstime.h
-
- |
- text
- text*
- postgres.h
-
- |
- tid
- ItemPointer
- storage/itemptr.h
-
- |
- time
- TimeADT
- utils/date.h
-
- |
- time with time zone
- TimeTzADT
- utils/date.h
-
- |
- timestamp
- Timestamp*
- utils/timestamp.h
-
- |
- tinterval
- TimeInterval
- utils/nabstime.h
-
- |
- varchar
- VarChar*
- postgres.h
-
- |
- xid
- TransactionId
- postgres.h
-
+ |
+ abstime
+ AbsoluteTime
+ utils/nabstime.h
+
+ |
+ boolean
+ bool
+ postgres.h (maybe compiler built-in)
+
+ |
+ box
+ BOX*
+ utils/geo_decls.h
+
+ |
+ bytea
+ bytea*
+ postgres.h
+
+ |
+ "char"
+ char
+ (compiler built-in)
+
+ |
+ character
+ BpChar*
+ postgres.h
+
+ |
+ cid
+ CommandId
+ postgres.h
+
+ |
+ date
+ DateADT
+ utils/date.h
+
+ |
+ smallint (int2)
+ int2 or int16
+ postgres.h
+
+ |
+ int2vector
+ int2vector*
+ postgres.h
+
+ |
+ integer (int4)
+ int4 or int32
+ postgres.h
+
+ |
+ real (float4)
+ float4*
+ postgres.h
+
+ |
+ double precision (float8)
+ float8*
+ postgres.h
+
+ |
+ interval
+ Interval*
+ utils/timestamp.h
+
+ |
+ lseg
+ LSEG*
+ utils/geo_decls.h
+
+ |
+ name
+ Name
+ postgres.h
+
+ |
+ oid
+ Oid
+ postgres.h
+
+ |
+ oidvector
+ oidvector*
+ postgres.h
+
+ |
+ path
+ PATH*
+ utils/geo_decls.h
+
+ |
+ point
+ POINT*
+ utils/geo_decls.h
+
+ |
+ regproc
+ regproc
+ postgres.h
+
+ |
+ reltime
+ RelativeTime
+ utils/nabstime.h
+
+ |
+ text
+ text*
+ postgres.h
+
+ |
+ tid
+ ItemPointer
+ storage/itemptr.h
+
+ |
+ time
+ TimeADT
+ utils/date.h
+
+ |
+ time with time zone
+ TimeTzADT
+ utils/date.h
+
+ |
+ timestamp
+ Timestamp*
+ utils/timestamp.h
+
+ |
+ tinterval
+ TimeInterval
+ utils/nabstime.h
+
+ |
+ varchar
+ VarChar*
+ postgres.h
+
+ |
+ xid
+ TransactionId
+ postgres.h
+
Always zero the bytes of your structures using
- memset. Without this, it's difficult to
- support hash indexes or hash joins, as you must pick out only
- the significant bits of your data structure to compute a hash.
+ memset. Without this, it's difficult to
+ support hash indexes or hash joins, as you must pick out only
+ the significant bits of your data structure to compute a hash.
Even if you initialize all fields of your structure, there may be
alignment padding (holes in the structure) that may contain
garbage values.
&dfunc;
-
Extension <span class="marked">build i</span>nfrastructure
+
Extension <span class="marked">Building I</span>nfrastructure
HeapTupleHeader t = PG_GETARG_HEAPTUPLEHEADER(0);
int32 limit = PG_GETARG_INT32(1);
bool isnull;
- int32 salary;
+ Datum salary;
- salary = DatumGetInt32(GetAttributeByName(t, "salary", &isnull));
+ salary = GetAttributeByName(t, "salary", &isnull);
if (isnull)
PG_RETURN_BOOL(false);
/* Alternatively, we might prefer to do PG_RETURN_NULL() for null salary. */
- PG_RETURN_BOOL(salary > limit);
+ PG_RETURN_BOOL(DatumGetInt32(salary) > limit);
}
return parameter that tells whether the attribute
is null. GetAttributeByName returns a Datum
value that you can convert to the proper data type by using the
- appropriate DatumGetXXX() macro.
+ appropriate DatumGetXXX()
+ macro. Note that the return value is meaningless if the null flag is
+ set; always check the null flag before trying to do anything with the
+ result.
/* stuff done only on the first call of the function */
if (SRF_IS_FIRSTCALL())
{
- MemoryContext oldcontext;
+ MemoryContext oldcontext;
/* create a function context for cross-call persistence */
funcctx = SRF_FIRSTCALL_INIT();
-
-
Function Overloading
-
-
- functions
-
-
- More than one function may be defined with the same SQL name, so long
- as the arguments they take are different. In other words,
- function names can be overloaded. When a
- query is executed, the server will determine which function to
- call from the data types and the number of the provided arguments.
- Overloading can also be used to simulate functions with a variable
- number of arguments, up to a finite maximum number.
-
-
- When creating a family of overloaded functions, one should be
- careful not to create ambiguities. For instance, given the
- functions
-CREATE FUNCTION test(int, real) RETURNS ...
-CREATE FUNCTION test(smallint, double precision) RETURNS ...
-
- it is not immediately clear which function would be called with
- some trivial input like test(1, 1.5). The
- currently implemented resolution rules are described in
- , but it is unwise to design a system that subtly
- relies on this behavior.
-
-
- A function that takes a single argument of a composite type should
- generally not have the same name as any attribute (field) of that type.
- Recall that attribute(table) is considered equivalent
- to table.attribute. In the case that there is an
- ambiguity between a function on a composite type and an attribute of
- the composite type, the attribute will always be used. It is possible
- to override that choice by schema-qualifying the function name
- (that is, schema.func(table)) but it's better to
- avoid the problem by not choosing conflicting names.
-
-
- When overloading C-language functions, there is an additional
- constraint: The C name of each function in the family of
- overloaded functions must be different from the C names of all
- other functions, either internal or dynamically loaded. If this
- rule is violated, the behavior is not portable. You might get a
- run-time linker error, or one of the functions will get called
- (usually the internal one). The alternative form of the
- AS clause for the SQL CREATE
- FUNCTION command decouples the SQL function name from
- the function name in the C source code. For instance,
-CREATE FUNCTION test(int) RETURNS int
- AS 'filename', 'test_1arg'
- LANGUAGE C;
-CREATE FUNCTION test(int, int) RETURNS int
- AS 'filename', 'test_2arg'
- LANGUAGE C;
-
- The names of the C functions here reflect one of many possible conventions.
-
-
-
-
-
Function Volatility Categories
-
-
- functions
-
-
- Every function has a volatility classification, with
- the possibilities being VOLATILE, STABLE, or
- IMMUTABLE. VOLATILE is the default if the
- CREATE FUNCTION command does not specify a category.
- The volatility category is a promise to the optimizer about the behavior
- of the function:
-
-
-
- A VOLATILE function can do anything, including modifying
- the database. It can return different results on successive calls with
- the same arguments. The optimizer makes no assumptions about the
- behavior of such functions. A query using a volatile function will
- re-evaluate the function at every row where its value is needed.
-
-
-
- A STABLE function cannot modify the database and is
- guaranteed to return the same results given the same arguments
- for all calls within a single surrounding query. This category
- allows the optimizer to optimize away multiple calls of the function
- within a single query. In particular, it is safe to use an expression
- containing such a function in an index scan condition. (Since an
- index scan will evaluate the comparison value only once, not once at
- each row, it is not valid to use a VOLATILE function in
- an index scan condition.)
-
-
-
- An IMMUTABLE function cannot modify the database and is
- guaranteed to return the same results given the same arguments forever.
- This category allows the optimizer to pre-evaluate the function when
- a query calls it with constant arguments. For example, a query like
- SELECT ... WHERE x = 2 + 2 can be simplified on sight to
- SELECT ... WHERE x = 4, because the function underlying
- the integer addition operator is marked IMMUTABLE.
-
-
-
-
-
- For best optimization results, you should label your functions with the
- strictest volatility category that is valid for them.
-
-
- Any function with side-effects must be labeled
- VOLATILE, so that calls to it cannot be optimized away.
- Even a function with no side-effects needs to be labeled
- VOLATILE if its value can change within a single query;
- some examples are random(), currval(),
- timeofday().
-
-
- There is relatively little difference between STABLE and
- IMMUTABLE categories when considering simple interactive
- queries that are planned and immediately executed: it doesn't matter
- a lot whether a function is executed once during planning or once during
- query execution startup. But there is a big difference if the plan is
- saved and reused later. Labeling a function IMMUTABLE when
- it really isn't may allow it to be prematurely folded to a constant during
- planning, resulting in a stale value being re-used during subsequent uses
- of the plan. This is a hazard when using prepared statements or when
- using function languages that cache plans (such as
-
-
- Because of the snapshotting behavior of MVCC (see )
- a function containing only SELECT commands can safely be
- marked STABLE, even if it selects from tables that might be
- undergoing modifications by concurrent queries.
-
PostgreSQL will execute a
STABLE- function using the snapshot established for the calling query, and so it
- will see a fixed view of the database throughout that query.
- Also note
- that the current_timestamp family of functions qualify
- as stable, since their values do not change within a transaction.
-
-
- The same snapshotting behavior is used for SELECT commands
- within IMMUTABLE functions. It is generally unwise to select
- from database tables within an IMMUTABLE function at all,
- since the immutability will be broken if the table contents ever change.
- However,
PostgreSQL does not enforce that you
- do not do that.
-
-
- A common error is to label a function IMMUTABLE when its
- results depend on a configuration parameter. For example, a function
- that manipulates timestamps might well have results that depend on the
- setting. For safety, such functions should
- be labeled STABLE instead.
-
-
-
- Before
PostgreSQL release 8.0, the requirement
- that STABLE and IMMUTABLE functions cannot modify
- the database was not enforced by the system. Release 8.0 enforces it
- by requiring SQL functions and procedural language functions of these
- categories to contain no SQL commands other than SELECT.
-
-
-
-
Writing a handler for a new procedural language is described in
. Several procedural languages are
- available in the
standard PostgreSQL+ available in the
core PostgreSQL distribution, which can serve as examples.
+ There are additional procedural languages available that are not
+ included in the core distribution.
+ has information about finding them.
+
+
Installing Procedural Languages
projects / postgresql.git / commitdiff