PostgreSQL 7.3 Documentation
PrevNext

CREATE FUNCTION

Name

CREATE FUNCTION -- 新しい関数の定義

Synopsis

CREATE [ OR REPLACE ] FUNCTION name ( [ argtype [, ...] ] )
    RETURNS rettype
  { LANGUAGE langname
    | IMMUTABLE | STABLE | VOLATILE
    | CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT
    | [EXTERNAL] SECURITY INVOKER | [EXTERNAL] SECURITY DEFINER
    | AS 'definition'
    | AS 'obj_file', 'link_symbol'
  } ...
    [ WITH ( attribute [, ...] ) ]

説明

CREATE FUNCTION は新しい関数を定義します。CREATE OR REPLACE FUNCTION は、新しい関数の作成、または、既存定義の置換のどちらかを行ないます。

関数を作成したユーザがその関数の所有者になります。

パラメータ

name

作成する関数の名前です。 スキーマ名が含まれている場合、関数は指定されたスキーマで作成されます。 スキーマ名がなければ、関数は現在のスキーマ (検索パスの前にあるスキーマ。CURRENT_SCHEMA() 参照) で作成されます。 新しい関数の名前には、同じスキーマ内の同じ引数データ型を持つ既存の関数と同じ名前は使用できません。 しかし、異なる引数データ型を持つ関数であれば、同じ名前でも構いません (これを、オーバーロード と言います)。

argtype

もしあれば、関数の引数のデータ型です。 入力型には、基本型、複合型、ドメイン型、もしくは既存の列の型と同じ型を使用することができます。 列の型を参照するには、tablename.columnname%TYPE と記述します。この形を使用すると、テーブル定義が変更されても関数が影響を受けないようにすることができる場合があります。 また、実装している言語により、cstring のような「擬似データ型」も指定することが可能です。 擬似データ型が使用されている場合、実際の引数のデータ型は、指定が不完全であるか、もしくは通常の SQL データ型のセットではないデータ型です。

rettype

返されるデータ型です。 返されるデータ型は、基本型、複合型、ドメイン型、もしくは既存の列の型と同じ型に設定することができます。 また、実装している言語により、cstring のような「擬似データ型」も指定することが可能です。setof 修飾子はその関数が、1 つのアイテムではなくアイテムの集合を返すことを示します。

langname

関数を実装している言語の名前です。 このパラメータには、SQL、C、internal、もしくはユーザ定義手続き言語の名前を指定可能です。 (createlang も参照してください。)後方互換のため、この名前を単一引用符で括ることもできます。

IMMUTABLE
STABLE
VOLATILE

上記の属性を指定すると、実行時の最適化のため、関数の複数の評価を 1 つの評価に置き換えても問題ないかどうかという情報を、システムに提供することができます。 指定するのは、いずれか 1 つのみです。 指定がない場合は、VOLATILE がデフォルト解釈です。

IMMUTABLE を指定すると、その関数に同じ引数値を与えた場合、常に同じ結果を返します。つまり、データベースを検索したり、その引数リスト中に存在する情報を直接使用したりはしません。 このオプションが指定された場合、引数が定数である関数が呼び出されるとすぐ、関数値と置き換えることができます。

STABLE を指定すると、その関数に同じ引数値を与えられた場合、1 テーブルスキャン内で常に同じ結果を返すことができます。ただし、その結果は、SQL 文が異なると変わってしまう可能性があります。 これは、関数の結果が、データベース検索や (現在のタイムゾーンのような) パラメータ変数などに依存する関数において適切な選択といえます。 また、関数の CURRENT_TIMESTAMP ファミリーは、その値がトランザクション内で変更されないため、STABLE であることに注意してください。

VOLATILE を指定すると、1 テーブルスキャン内でもその関数の値を変更することが可能になります。したがって、最適化を行なうことはできません。 このような意味で揮発的 (volatile) なデータベース関数は、比較的少数です。たとえば、random()、currval()、timeofday() などです。 また、副作用がある関数 (たとえば setval()) は、その結果を完全に予測できるとしても、呼び出しを最適化しないよう、揮発的と分類する必要があることに注意してください。

CALLED ON NULL INPUT
RETURNS NULL ON NULL INPUT
STRICT

CALLED ON NULL INPUT (デフォルト) を指定すると、その関数の引数に NULL がある場合でも、通常通り呼び出されます。 その場合は、必要に応じて NULL 値を確認し、適切な対応をすることが関数の作成者の責任になります。

RETURNS NULL ON NULL INPUT もしくは STRICT を指定すると、関数の引数に NULL がある場合、常に NULL を返します。 このパラメータが指定されると、その関数に NULL 引数がある場合実行されません。 代わりに、NULL という結果が自動的に仮定されます。

[EXTERNAL] SECURITY INVOKER
[EXTERNAL] SECURITY DEFINER

SECURITY INVOKER を指定すると、関数を呼び出したユーザの権限で、その関数が実行されます。 これがデフォルトです。 SECURITY DEFINER を指定すると、関数を作成したユーザの権限で、その関数が実行されます。

キーワード EXTERNAL は、SQL との互換性を保つために存在しています。しかし、SQL とは異なり、この機能は外部関数にのみ適用されるわけではないため、このキーワードはオプションです。

definition

関数を定義する文字列です。 この意味は言語に依存します。内部的な関数名、オブジェクトファイルへのパス、SQL問い合わせ、手続き言語で書かれたテキストなどを指定できます。

obj_file, link_symbol

この形式のAS句は、C言語のソースコード中の関数名がSQL関数の名前と同じでない場合、動的にリンクされたC言語関数に使われます。文字列obj_fileは動的にロードできるオブジェクトを含むファイルの名前で、link_symbolはC言語ソースコード中の関数の名前であるオブジェクトのリンクシンボルです。

attribute

関数に関する情報を、部分的に選択して指定する伝統的な方法です。 ここで関連するのは、以下の属性です。

isStrict

STRICT または RETURNS NULL ON NULL INPUT と同じです。

isCachable

isCachable は、IMMUTABLE と同じですが、すでに廃止されています。しかし、下位互換性のため、まだ受け付けることはできます。

属性名では、大文字小文字を区別しません。

注釈

さらに詳しい外部関数の書き方については PostgreSQL プログラマガイドの、関数を使った PostgreSQL の拡張に関する章を参照してください。

すべてのSQLの型の構文は入力引数と返り値に認められています。しかし、型指定のいくつかの細部（たとえばnumeric型の精度フィールド）は、その関数の実装の仕方に責任があり、CREATE FUNCTION コマンドによって警告なく包含されます（つまり認識や強制はされません）。

PostgreSQLは関数のオーバーロードを許可します。 これは、異なる引数の型を持っていれば別の関数が同じ名前を使うことができるということです。しかしこの機能は内部とC言語関数では注意して使わなくてはなりません。

2つの内部関数が同じCの名前を持っていると、リンク時にエラーが発生します。これを回避するためには、2つの関数に異なるCの名前を与え（たとえば、Cの名前の一部として引数の型などを使います）、そしてそれらの名前を CREATE FUNCTIONのAS句の中で指定します。 もしその AS 句が空のままの場合は、CREATE FUNCTION はその関数の C の名前が SQL の名前と同じであると仮定します。

同様に、SQL関数名を複数のC言語関数でオーバーロードするときは、それぞれのC言語関数のインスタンスに異なる名前を与え、それぞれのオーバーロードされたSQL関数のふさわしいC言語実装を選択するためにCREATE FUNCTION構文の中でAS句の代替形式を使います。

同一オブジェクトファイルを参照する、CREATE FUNCTION 呼び出しが繰り返された場合、そのファイルは一度だけロードされます。(おそらく開発段階で)ファイルをアンロードし再ロードするには、LOAD を使用します。

ユーザ定義の関数を削除するには DROP FUNCTION を使用します。

既存の関数定義を更新するには、CREATE OR REPLACE FUNCTION を使用します。この方法では関数の名前や引数の型を変更することはできないことに注意して下さい。 (これを行なった場合、新しい別の関数が作成さ れるだけです。)また、CREATE OR REPLACE FUNCTION では、既存関数の戻り値の型を変更させることはできません。このためには、その関数を削除し、再度作成して下さい。

関数を削除し再作成した場合、新しい関数は古いものと同じ実体にはなりません。 古い関数を参照する、既存のルール、ビュー、トリガなどは壊れてしまいます。関数を参照するオブジェクトを破壊しないように、関数定義を変更するには CREATE OR REPLACE FUNCTION を使用します。

関数を定義可能にするには、ユーザがその言語に対し USAGE 権限を持つ必要があります。

デフォルトでは、関数の所有者 (作成者) のみ、その関数を実行する権限を保持しています。 他のユーザが関数を使用するためには、その関数の EXECUTE 権限が与えられる必要があります。

例

単純なSQL関数を作成するには以下のようにします。 

CREATE FUNCTION one() RETURNS integer
    AS 'SELECT 1 AS RESULT;'
    LANGUAGE SQL;

SELECT one() AS answer;
 answer
--------
      1

次の例は、ユーザ作成の(拡張子はプラットフォームによって大きく変わる)funcs.soという名前の共有ライブラリからルーチンを呼び出すことにより C 関数を作成します。共有ライブラリファイルはサーバの動的ライブラリ検索パスから検索されます。 その特定のルーチンは桁数を検査し、パラメータとして渡される値と等しければ、TRUE を返します。これは CHECK制約内で使用されることを意図しています。 

CREATE FUNCTION ean_checkdigit(char, char) RETURNS boolean
    AS 'funcs' LANGUAGE C;
    
CREATE TABLE product (
    id        char(8) PRIMARY KEY,
    eanprefix char(8) CHECK (eanprefix ~ '[0-9]{2}-[0-9]{5}')
                      REFERENCES brandname(ean_prefix),
    eancode   char(6) CHECK (eancode ~ '[0-9]{6}'),
    CONSTRAINT ean    CHECK (ean_checkdigit(eanprefix, eancode))
);

次の例で、ユーザ定義データ型 complex から組み込みデータ型 point への型変換を行なう関数を作成します。 この関数は、C のソースからコンパイルされた動的にロードされるオブジェクトによって実装されています (共有オブジェクトファイルを絶対ファイル名で指定するという、現在は勧められない方法を説明しています)。PostgreSQL に型変換関数を自動的に検出させるために、この SQL 関数は戻り型と同じ名前を持たなければなりませんので、オーバーロードは避け ることができません。関数名は SQL 定義中の AS 句の 2 番目の形式を使ってオーバーロードされます。 

CREATE FUNCTION point(complex) RETURNS point
    AS '/home/bernie/pgsql/lib/complex.so', 'complex_to_point'
    LANGUAGE C STRICT;

関数の C 宣言は以下のようになります。 

Point * complex_to_point (Complex *z)
{
	Point *p;

	p = (Point *) palloc(sizeof(Point));
	p->x = z->x;
	p->y = z->y;
		
	return p;
}

関数に「厳格 (strict)」と記述されていることに注意してください。これにより、関数本体で NULL 入力のチェックをスキップすることができます。

互換性

CREATE FUNCTION コマンドは SQL99 で定義されています。 PostgreSQL 版は似てはいますが、完全な互換性はありません。属性は移植性がなく、また、使用可能な言語も異なります。

関連項目

DROP FUNCTION、GRANT、LOAD、REVOKE、createlang、PostgreSQL プログラマガイド

PrevHomeNext
CREATE DOMAINUpCREATE GROUP