CREATE FUNCTION

CREATE FUNCTIONmendefinisikan fungsi baru.

penting

Di Amazon Aurora DSQL, CREATE FUNCTION hanya mendukung SQL-language fungsi (). LANGUAGE sql

Sintaksis yang didukung

CREATE [ OR REPLACE ] FUNCTION
    name ( [ [ argmode ] [ argname ] argtype [ { DEFAULT | = } default_expr ] [, ...] ] )
    [ RETURNS rettype
      | RETURNS TABLE ( column_name column_type [, ...] ) ]
  { LANGUAGE sql
    | { IMMUTABLE | STABLE | VOLATILE }
    | { CALLED ON NULL INPUT | RETURNS NULL ON NULL INPUT | STRICT }
    | { [ EXTERNAL ] SECURITY INVOKER | [ EXTERNAL ] SECURITY DEFINER }
    | PARALLEL { UNSAFE | RESTRICTED | SAFE }
    | COST execution_cost
    | ROWS result_rows
    | SET configuration_parameter { TO value | = value | FROM CURRENT }
    | AS 'definition'
    | RETURN expression
    | BEGIN ATOMIC statement; [ statement; ... ] END
  } ...

where LANGUAGE must be sql

Deskripsi

CREATE FUNCTIONmendefinisikan fungsi baru. CREATE OR REPLACE FUNCTIONakan membuat fungsi baru, atau mengganti definisi yang ada. Untuk dapat mendefinisikan suatu fungsi, Anda harus memiliki USAGE hak istimewa pada bahasa tersebut.

Jika nama skema disertakan, maka fungsi tersebut dibuat dalam skema yang ditentukan. Jika tidak, fungsi dibuat dalam skema saat ini. Nama fungsi baru tidak boleh cocok dengan fungsi yang ada dengan tipe argumen masukan yang sama dalam skema yang sama. Namun, fungsi dari tipe argumen yang berbeda dapat berbagi nama (ini disebut overloading).

Untuk mengganti definisi saat ini dari fungsi yang ada, gunakanCREATE OR REPLACE FUNCTION. Anda tidak dapat mengubah nama atau tipe argumen fungsi dengan cara ini (ini sebenarnya akan membuat fungsi baru yang berbeda). Selain itu, Anda tidak dapat menggunakan CREATE OR REPLACE FUNCTION untuk mengubah tipe pengembalian fungsi yang ada. Untuk melakukan itu, Anda harus menjatuhkan dan membuat ulang fungsi.

Ketika CREATE OR REPLACE FUNCTION digunakan untuk mengganti fungsi yang ada, kepemilikan dan izin fungsi tidak berubah. Semua properti fungsi lainnya diberi nilai yang ditentukan atau tersirat dalam perintah. Anda harus memiliki fungsi untuk menggantinya (ini termasuk menjadi anggota peran pemilik).

Jika Anda menjatuhkan dan kemudian membuat ulang fungsi, fungsi baru bukanlah entitas yang sama dengan yang lama; Anda harus menghapus aturan, tampilan, dan sebagainya yang ada, yang merujuk ke fungsi lama. Gunakan CREATE OR REPLACE FUNCTION untuk mengubah definisi fungsi tanpa merusak objek yang merujuk ke fungsi.

Anda menjadi pemilik fungsi yang Anda buat.

Untuk dapat membuat fungsi, Anda harus memiliki USAGE hak istimewa pada tipe argumen dan tipe pengembalian.

Sebuah SQL fungsi membungkus satu atau lebih SQL pernyataan menjadi unit yang dapat digunakan kembali dan dapat dipanggil. Gunakan fungsi untuk memusatkan ekspresi atau perhitungan umum, menerapkan logika yang konsisten di beberapa kueri, dan menyederhanakan kode aplikasi dengan memanggil satu fungsi alih-alih mengulangi yang sama. SQL

Parameter

name

Nama (opsional schema-qualified) dari fungsi yang akan dibuat.

argmode

Modus argumen:IN,, OUTINOUT, atauVARIADIC. Jika dihilangkan, defaultnya adalah. IN VARIADICharus menjadi parameter masukan terakhir; hanya OUT argumen yang dapat mengikutinya. OUTdan INOUT argumen tidak dapat digabungkan dengan RETURNS TABLE notasi.

argname

Nama argumen. Dalam fungsi SQL, Anda dapat merujuk ke argumen dengan nama di badan fungsi. Nama INOUT argumen OUT atau juga signifikan, karena mendefinisikan nama kolom yang sesuai dalam jenis baris hasil.

argtype

Tipe data dari sebuah argumen. Ini bisa berupa tipe DSQL-supported dasar Aurora, tipe array, atau domain. Untuk informasi selengkapnya, lihat Tipe data yang didukung di Aurora DSQL. Anda juga dapat mereferensikan jenis kolom tabel yang ada dengan menggunakan %TYPE notasi.

default_expr

Ekspresi yang akan digunakan sebagai nilai default jika argumen tidak ditentukan. Ekspresi harus dapat dipaksakan untuk tipe argumen parameter. Hanya IN dan INOUT argumen dapat memiliki nilai default. Setiap argumen setelah satu dengan nilai default juga harus memiliki nilai default.

rettype

Tipe data pengembalian. Ini bisa berupa tipe DSQL-supported dasar Aurora, tipe array, atau domain. Untuk informasi selengkapnya, lihat Tipe data yang didukung di Aurora DSQL. Untuk mengembalikan satu set baris, gunakan SETOF rettype atauRETURNS TABLE. Jika fungsi tidak seharusnya mengembalikan nilai, tentukan void sebagai tipe pengembalian. Ketika ada OUT atau INOUT parameter, RETURNS klausa dapat dihilangkan, dan fungsi mengembalikan record atau jenis baris yang sesuai.

RETURNS TABLE ( column_name column_type [, ...] )

Menentukan bahwa fungsi mengembalikan satu set baris dengan kolom bernama dan jenis mereka. Ini setara dengan mendeklarasikan satu atau lebih OUT parameter dan menentukan SETOF sebagai tipe pengembalian.

LANGUAGE sql

Bahasa yang digunakan untuk mengimplementasikan fungsi. Di Aurora DSQL, ini pasti. sql Jika Anda menghilangkan LANGUAGE klausa dan memberikan a BEGIN ATOMIC atau RETURN badan, sql diasumsikan. Sebuah string-constant body (AS 'definition') memerlukan LANGUAGE sql klausa eksplisit; menghilangkannya gagal dengan kesalahan. no language specified

IMMUTABLE / STABLE / VOLATILE

Atribut ini menginformasikan pengoptimal kueri tentang perilaku fungsi. Anda dapat menentukan paling banyak satu. Jika Anda menghilangkan ketiganya, fungsi default ke. VOLATILE

• IMMUTABLEmenunjukkan bahwa fungsi tidak dapat memodifikasi database dan selalu mengembalikan hasil yang sama ketika diberikan nilai argumen yang sama.

• STABLEmenunjukkan bahwa fungsi tidak dapat memodifikasi database. Dalam pemindaian tabel tunggal, secara konsisten mengembalikan hasil yang sama untuk nilai argumen yang sama, tetapi hasilnya mungkin berubah di seluruh pernyataan SQL.

• VOLATILEmenunjukkan bahwa nilai fungsi dapat berubah bahkan dalam pemindaian tabel tunggal, sehingga tidak ada pengoptimalan yang dapat dilakukan.

CALLED ON NULL INPUT / RETURNS NULL ON NULL INPUT / STRICT

CALLED ON NULL INPUT(default) menunjukkan bahwa fungsi dipanggil secara normal ketika beberapa argumennya adalah nol. RETURNS NULL ON NULL INPUTatau STRICT menunjukkan bahwa fungsi selalu mengembalikan null ketika salah satu argumennya adalah null. Jika ditentukan, Aurora DSQL tidak menjalankan fungsi ketika argumen apapun adalah null; sebagai gantinya, fungsi secara otomatis mengembalikan null.

[ EXTERNAL ] SECURITY INVOKER / [ EXTERNAL ] SECURITY DEFINER

SECURITY INVOKER(default) menunjukkan bahwa fungsi tersebut akan dieksekusi dengan hak istimewa pengguna yang memanggilnya. SECURITY DEFINERmenentukan bahwa fungsi tersebut akan dieksekusi dengan hak istimewa pengguna yang memilikinya. Kata kunci EXTERNAL diperbolehkan untuk kesesuaian SQL, tetapi itu opsional.

PARALLEL { UNSAFE | RESTRICTED | SAFE }

Aurora DSQL menerima dan menyimpan tanda. PARALLEL Namun, penandaan ini tidak memengaruhi eksekusi kueri.

COST execution_cost

Angka positif memberikan perkiraan biaya eksekusi untuk fungsi tersebut. Jika fungsi mengembalikan satu set, nilai ini adalah perkiraan biaya per baris yang dikembalikan. Perencana kueri menggunakan estimasi ini ketika tidak sebaris fungsi.

ROWS result_rows

Angka positif yang memberikan perkiraan jumlah baris yang diharapkan oleh perencana kueri untuk mengembalikan fungsi. Ini hanya diperbolehkan ketika fungsi dideklarasikan untuk mengembalikan satu set. Asumsi default adalah 1000 baris.

SET configuration_parameter { TO value | = value | FROM CURRENT }

SETKlausa menyebabkan parameter konfigurasi yang ditentukan diatur ke nilai yang ditentukan ketika fungsi dimasukkan, dan kemudian dikembalikan ke nilai sebelumnya ketika fungsi keluar. SET FROM CURRENTmenyimpan nilai parameter yang saat ini ketika CREATE FUNCTION dijalankan sebagai nilai yang akan diterapkan ketika fungsi dimasukkan.

AS 'definition'

Sebuah konstanta string mendefinisikan fungsi; artinya tergantung pada bahasa. Untuk suatu SQL-language fungsi, itu adalah pernyataan SQL yang membentuk badan fungsi.

RETURN expression

Mendefinisikan badan fungsi menggunakan SQL-standard sintaks untuk fungsi yang mengembalikan ekspresi tunggal. Ini adalah alternatif dari bentuk konstanta string.

BEGIN ATOMIC statement; [ ... ] END

Mendefinisikan badan fungsi menggunakan SQL-standard sintaks. Tubuh terdiri dari satu atau lebih pernyataan SQL. Formulir ini hanya berlaku untukLANGUAGE sql. Pernyataan dalam badan atom dilacak sebagai dependensi fungsi. Misalnya, tabel yang direferensikan di badan tidak dapat dijatuhkan tanpa juga menjatuhkan fungsi, atau menggunakan. DROP ... CASCADE

Catatan

Gunakan DROP FUNCTION pernyataan untuk menghapus fungsi. Anda juga dapat memberikan dan mencabut hak istimewa pada fungsi dengan GRANT dan REVOKE (misalnya,). REVOKE ALL ON FUNCTION

Setiap fungsi yang membaca atau memodifikasi data dalam tabel tunduk pada transaksi dan perilaku konkurensi yang sama dengan pernyataan SQL setara yang dijalankan secara langsung. Fungsi dideklarasikan IMMUTABLE atau tidak STABLE boleh memodifikasi database.

Untuk memperbarui definisi fungsi yang ada, gunakanCREATE OR REPLACE FUNCTION. Anda tidak dapat mengubah tipe argumen atau mengembalikan tipe fungsi dengan cara ini; sebagai gantinya, jatuhkan dan buat ulang fungsi.

Untuk mengganti nama fungsi, mengubah pemiliknya, atau memindahkannya ke skema lain, gunakan. ALTER FUNCTION Untuk mengubah atribut lainnya, gunakan CREATE OR REPLACE FUNCTION dengan perubahan yang diinginkan. Untuk informasi selengkapnya, lihat ALTER FUNCTION.

Fungsi overloading didukung: Anda dapat menentukan beberapa fungsi dengan nama yang sama selama jenis argumen masukan mereka berbeda. Fungsi yang ditentukan pengguna juga dapat memanggil fungsi lain, dan dapat membayangi fungsi bawaan dengan nama dan tipe argumen yang sama.

Untuk fungsi yang mengembalikan set (SETOFatauRETURNS TABLE) yang tubuhnya berisi lebih dari satu pernyataan, hanya hasil dari pernyataan akhir yang dikembalikan. Fungsi ini masih mengeksekusi pernyataan sebelumnya, tetapi membuang hasilnya. Ini adalah perilaku standar untuk SQL-language fungsi. Susun fungsi sehingga pernyataan akhirnya menghasilkan himpunan hasil yang lengkap.

Fungsi set-return tidak menjamin urutan baris tertentu. Untuk mengontrol urutan baris, sertakan ORDER BY klausa dalam kueri.

Pertimbangan-pertimbangan

CREATE FUNCTIONKemampuan berikut mengembalikan kesalahan yang ditampilkan.

LEAKPROOF

Mengembalikan kesalahanonly superuser can define a leakproof function. NOT LEAKPROOF(default) diterima.

TRANSFORM FOR TYPE

Mengembalikan kesalahantransform for type type language "sql" does not exist.

SUPPORT(fungsi dukungan perencana)

Mengembalikan kesalahanfunction name(internal) does not exist.

User-defined tipe komposit (CREATE TYPE ... AS), termasuk fungsi yang mengembalikan tipe komposit

Mengembalikan kesalahanunsupported statement: CompositeType.

Aurora DSQL tidak mendukungCREATE PROCEDURE, yang gagal dengan kesalahan. PROCEDURE is not supported

WINDOWAtribut diterima secara sintaksis tetapi tidak berguna untuk SQL-language fungsi. Hindari menggunakan atribut ini.

Contoh

Buat fungsi SQL sederhana yang menambahkan dua bilangan bulat, menggunakan badan konstanta string:

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

Buat fungsi yang sama menggunakan SQL-standard RETURN body dan argumen bernama:

CREATE FUNCTION add(a integer, b integer) RETURNS integer
    LANGUAGE sql
    IMMUTABLE
    RETURN a + b;

Buat fungsi yang mengembalikan satu set baris menggunakan RETURNS TABLE dan BEGIN ATOMIC badan:

CREATE FUNCTION employees_in_dept(dept_id integer)
    RETURNS TABLE (id integer, name text)
    LANGUAGE sql
    STABLE
    BEGIN ATOMIC
        SELECT id, name FROM employees WHERE department_id = dept_id;
    END;

Buat fungsi yang berjalan dengan hak istimewa pemiliknya, dan tetapkan parameter konfigurasi selama durasi panggilan:

CREATE FUNCTION current_department() RETURNS text
    LANGUAGE sql
    STABLE
    SECURITY DEFINER
    SET search_path = app
    AS 'SELECT current_setting(''app.department'');';

Kompatibilitas

CREATE FUNCTIONPerintah didefinisikan dalam standar SQL. Implementasi PostgreSQL dapat digunakan dengan cara yang kompatibel tetapi memiliki banyak ekstensi. Sebaliknya, standar SQL menentukan sejumlah fitur opsional yang tidak diimplementasikan di PostgreSQL.

Berikut ini adalah masalah kompatibilitas penting:

• OR REPLACEadalah ekstensi PostgreSQL.

• Untuk kompatibilitas dengan beberapa sistem database lainnya, argmode dapat ditulis baik sebelum atau sesudahargname. Tetapi hanya cara pertama yang memenuhi standar.

• Untuk parameter default, standar SQL hanya menentukan sintaks dengan kata kunci. DEFAULT Sintaks dengan = digunakan dalam T-SQL dan Firebird.

• SETOFPengubah adalah ekstensi PostgreSQL.

• Hanya SQL yang distandarisasi sebagai bahasa.

• Semua atribut lainnya kecuali CALLED ON NULL INPUT dan tidak RETURNS NULL ON NULL INPUT distandarisasi.

• Untuk badan LANGUAGE sql fungsi, standar SQL hanya menentukan formulir. sql_body

LANGUAGE sqlFungsi sederhana dapat ditulis dengan cara yang sesuai standar dan portabel untuk implementasi lainnya. Fungsi yang lebih kompleks menggunakan fitur-fitur canggih, atribut optimasi, atau bahasa lain tentu akan spesifik untuk PostgreSQL secara signifikan.