PostgreSQL 8.0.0 文書
前のページ | 巻戻し |  | 早送り | 次のページ

# CREATE FUNCTION

## 名前

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

## 概要

    CREATE [ OR REPLACE ] FUNCTION name ( [ [ argname ] 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`は、新しい関数の作成、または、既存定義の置換のどちらかを行ないます。

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

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

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

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

## パラメータ

`name`

  作成する関数の名前です(スキーマ修飾も可能)。

`argname`

  引数の名前です。 言語の中にはこの名前を関数本体で使用できるものもあります。 （今のところPL/pgSQLのみです。） 他の言語では単なるドキュメント用の余計なものです。

`argtype`

  もしあれば、関数の引数のデータ型です。(スキーマ修飾名も可。) 引数の型は、基本、複合、ドメイン、もしくはテーブル列の型の参照を使用することができます。

  また、言語の実装に依存しますが、`cstring`といった"疑似型"を指定することもできる場合があります。 疑似型は、実際の引数の型の指定が不完全である、もしくは、普通のSQLデータ型の集合を越えていることを示します。

  列の型を参照するには、``tablename`.`columnname`%TYPE`と記述します。 これを使用すると、テーブル定義が変更されても関数が影響を受けないようにすることができ、時折役に立ちます。

`rettype`

  返されるデータ型です。(スキーマ修飾名も可。) 返されるデータ型は、基本型、複合型、ドメイン型のいずれか、もしくは、テーブル列の型の参照を設定することができます。 また、実装している言語によりますが、`cstring`のような"疑似型"も指定することが可能です。

  `SETOF`修飾子は、その関数が、1つのアイテムではなくアイテムの集合を返すことを示します。

  列の型は、``tablename`.`columnname`%TYPE`と記述することで参照されます。

`langname`

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

`IMMUTABLE`
`STABLE`
`VOLATILE`

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

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

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

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

  詳細は項31.6を参照してください。

`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言語ソースコード中の関数の名前であるオブジェクトのリンクシンボルです。 リンクシンボルが省略された場合、定義されるSQL関数の名前と同じものであると仮定されます。

`attribute`

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

  `isStrict`

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

  `isCachable`

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

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

## 注釈

更に詳しい外部関数の作成方法については項31.3を参照してください。

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

PostgreSQLは関数のオーバーロードを許可します。 これは、異なる引数の型を持っていれば別の関数が同じ名前を使うことができるということです。 しかし、全ての関数のC言語における名前は異なる必要があります。 従って、オーバーロードするC言語関数には異なるC言語の名前を与える必要があります。 (例えば、C言語の名前の一部に引数の型を使用してください。)

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

ユーザ定義の関数を削除するにはDROP FUNCTIONを使用してください。

関数を定義する文字列を記述する際に、通常の単一引用符構文ではなく、ドル引用符（項4.1.2.2参照）を使用することはよく役に立ちます。 ドル引用符を使用しない限り、関数定義内の単一引用符やバックスラッシュは必ず2重にしてエスケープしなければなりません。

関数を定義するには、ユーザはその言語の`USAGE`権限が必要です。

## 例

ここでは、初心者向けの簡単な例を示します。 より多くの情報と例が項31.3に記載されています。

    CREATE FUNCTION add(integer, integer) RETURNS integer
        AS 'select $1 + $2;'
        LANGUAGE SQL
        IMMUTABLE
        RETURNS NULL ON NULL INPUT;

PL/pgSQLで、引数名を使用して、整数を1増やします。

    CREATE OR REPLACE FUNCTION increment(i integer) RETURNS integer AS $$
            BEGIN
                    RETURN i + 1;
            END;
    $$ LANGUAGE plpgsql;

## 互換性

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

## 関連項目

ALTER FUNCTION, DROP FUNCTION, GRANT, LOAD, REVOKE, createlang

前のページ | ホーム | 次のページ
CREATE DOMAIN | 上に戻る | CREATE GROUP