يعرّف CREATE FUNCTION name(arg type) RETURNS type LANGUAGE sql AS $$ ... $$; دالة تستطيع الاستعلامات استدعاءها كأي دالة مدمجة. يُكتب الجسم بين علامتَي $$، بلغة SQL العادية أو بـ PL/pgSQL، اللغة الإجرائية في PostgreSQL. أما CREATE PROCEDURE (PostgreSQL 11+) فيعرّف روتينًا تشغّله بـ CALL.
تستخدم with_tax(50) النسبة الافتراضية وتعيد 60، وتعيد with_tax(50, 0.1) القيمة 55. ويمكن أيضًا تمرير الوسائط بأسمائها: with_tax(50, rate => 0.1).
كتابة المنطق بـ PL/pgSQL
استخدم LANGUAGE plpgsql حين تحتاج الدالة إلى متغيرات أو IF أو حلقات أو معالجة أخطاء. تُكتب المتغيرات في قسم DECLARE، والشيفرة بين BEGIN وEND:
يكلّف الطرد ذو 4 كغ السعر الأساسي 5، والطرد السريع ذو 20 كغ يكلّف (5 + 10 * 0.5) * 2 = 20. وداخل PL/pgSQL يطبع RAISE NOTICE 'value: %', cost; رسالة، ويوقف RAISE EXCEPTION التنفيذ بخطأ.
وحين تستطيع SQL العادية التعبير عن المنطق، ففضّل LANGUAGE sql: يستطيع المخطِّط دمج دالة SQL بسيطة في الاستعلام المستدعي.
إعادة مجموعة من الصفوف
ينشئ RETURNS TABLE (...) دالة تعيد صفوفًا. استدعها في FROM كأنها جدول:
تعيد orders_of('ana') الطلبين 1 و3. ويعيد RETURNS SETOF orders صفوفًا كاملة من الجدول orders بدل الأعمدة المذكورة.
منذ PostgreSQL 14 يمكن أن يكون لدالة SQL جسم SQL قياسي بدل نص. يخزّنه PostgreSQL محلَّلًا ويسجّل الجداول والأعمدة التي يستخدمها، فلا يمكن حذفها ما دامت الدالة موجودة:
CREATE FUNCTION order_count(who text) RETURNS bigint
LANGUAGE sql STABLE
BEGIN ATOMIC
SELECT count(*) FROM orders WHERE customer = who;
END;
إنشاء إجراء مخزّن وتشغيله بـ CALL
ليس للإجراء نوع إرجاع، وتشغّله بـ CALL. يستطيع تعديل البيانات، وحين لا يكون CALL داخل كتلة معاملة صريحة، يستطيع تنفيذ COMMIT في منتصف عمله. وهكذا تعالج عملًا كبيرًا على دفعات.
ينتهي الحساب 1 بـ 70 والحساب 2 بـ 80. وتحويل 200 سيخالف قيد CHECK على الحساب 1، والخطأ يتراجع عن التحديثين معًا.
| الدالة | الإجراء | |
|---|---|---|
| التشغيل | SELECT f(...)، في أي مكان من الاستعلام | CALL p(...) فقط |
| تعيد | قيمة أو صفًا أو مجموعة صفوف | لا شيء (أو معاملات OUT/INOUT) |
COMMIT / ROLLBACK بالداخل | لا | نعم، في PL/pgSQL، حين لا يُستدعى داخل كتلة معاملة |
| منذ | دائمًا | PostgreSQL 11 |
تحديد درجة التقلّب: IMMUTABLE وSTABLE وVOLATILE
يخبر وسم التقلّب (volatility) المخطِّط بما يجوز له افتراضه عن الدالة. والقيمة الافتراضية VOLATILE.
IMMUTABLE: تعتمد النتيجة على الوسائط فقط ولا تتغير أبدًا (with_tax). وهو إلزامي للدوال المستخدمة في تعبير فهرس.STABLE: قد تتغير النتيجة بين الجمل لكن لا داخل جملة واحدة، مثل دالة تقرأ الجداول (orders_of).VOLATILE: كل ما عدا ذلك، مثل الدوال التي تستخدمrandom()أو تعدّل البيانات. يستدعيها PostgreSQL من جديد لكل صف.
والوسم الخاطئ يعطي نتائج خاطئة: دالة IMMUTABLE تقرأ جدولًا قد تعيد قيمًا قديمة من فهرس أو من خطة مخزّنة.
استبدال دالة وتحميلها الزائد وحذفها
يغيّر CREATE OR REPLACE FUNCTION جسم دالة موجودة، لكنه لا يستطيع تغيير نوع إرجاعها، فاحذفها أولًا لذلك. يميّز PostgreSQL الدالة باسمها وأنواع وسائطها، فتكون f(int) وf(text) دالتين مختلفتين. ولحذف واحدة من دالتين بالاسم نفسه، اذكر أنواع الوسائط:
CREATE OR REPLACE FUNCTION with_tax(price numeric, rate numeric DEFAULT 0.2) ...;
DROP FUNCTION with_tax(numeric, numeric);
DROP PROCEDURE transfer;
يوثّق فصل PL/pgSQL الحلقات والمؤشرات (cursors) والاستثناءات وSQL الديناميكي بـ EXECUTE. ولتشغيل دالة تلقائيًا حين تتغير الصفوف، اربطها بـ مشغّل.
الأسئلة الشائعة
ما الفرق بين الدالة والإجراء في PostgreSQL؟
تعيد الدالة قيمة وتُستدعى داخل استعلام (SELECT f(x)). أما الإجراء، الذي أضيف في PostgreSQL 11، فيُشغَّل وحده بـ CALL ويستطيع تنفيذ COMMIT أو ROLLBACK داخل جسمه، بينما تعمل الدالة دائمًا داخل معاملة من استدعاها.
ماذا تعني $$ في دالة PostgreSQL؟
$$ هي الاقتباس بالدولار (dollar quoting): تحدد بداية قيمة نصية حرفية ونهايتها، فيستطيع جسم الدالة احتواء علامات اقتباس مفردة دون تهريبها. ويمكنك أيضًا إضافة وسم، كما في $body$ ... $body$.
كيف أرى شيفرة دالة في PostgreSQL؟
في psql يسرد \df الدوال ويطبع \sf name تعريف الدالة. وفي SQL تعيد SELECT pg_get_functiondef('name'::regproc); جملة CREATE OR REPLACE FUNCTION كاملة.
هل يمكن لدالة في PostgreSQL أن تعيد عدة صفوف؟
نعم. عرّفها بـ RETURNS TABLE (col type, ...) أو RETURNS SETOF type واستدعها في عبارة FROM كأنها جدول: SELECT * FROM f(1);.