يجعل RETURNING جملة تعديل البيانات تعيد صفوفًا مثل SELECT. أضفه في نهاية INSERT أو UPDATE أو DELETE أو (منذ PostgreSQL 17) MERGE، متبوعًا بالأعمدة أو التعبيرات التي تريدها: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.
يعود الصفان الجديدان بالمعرّفات التي ولّدها PostgreSQL وبقيمة plan التي ملأتها القيمة الافتراضية، دون استعلام ثانٍ.
الحصول على معرّف صف مدرج
RETURNING id هي الطريقة القياسية للحصول على مفتاح مولّد. وهي تعرض الصف كما خُزّن، لذا تعمل مع أعمدة identity وserial والقيم الافتراضية من نوع UUID والقيم التي يضبطها مشغّل BEFORE. ويعيد VALUES متعدد الصفوف أو INSERT ... SELECT صفًا لكل صف مدرج.
تقرأ برامج التشغيل (drivers) النتيجة كأي نتيجة استعلام: cursor.fetchone() في Python مع psycopg، وresult.rows في Node.js مع pg. لا بأس بـ RETURNING * أثناء التجربة، لكن في شيفرة التطبيق اذكر الأعمدة لتبقى النتيجة ثابتة حين يتغير الجدول.
معرفة ما غيّره UPDATE
في UPDATE يعرض RETURNING الصفوف بعد التغيير، والصفوف التي طابقت WHERE فقط:
يعود صفّان: Book بسعر 16.5 وLamp بسعر 33. لم يُمسّ Pen، لذا لا يظهر في النتيجة.
في PostgreSQL 17 لا يرى RETURNING إلا القيم الجديدة، ويضيف PostgreSQL 18 old وnew (RETURNING old.price, new.price). أما على 17 فاربط الجدول بنسخة مقفلة منه:
يعود كل صف بسعره قبل التغيير وبعده: 10 و15، و20 و25.
إرجاع الصفوف التي حذفها DELETE
يعطيك DELETE ... RETURNING الصفوف التي حذفها، للتسجيل أو التراجع، أو لطابور مهام يحذف فيه العامل (worker) مهمة ويستعيد بياناتها. وداخل استعلام WITH تغذّي الصفوف المعادة الجملة التالية، فتنقل الصفوف بين الجداول في جملة واحدة:
تغادر المهمتان 1 و3 الجدول tasks وتصلان إلى done_tasks. إنها جملة واحدة، فلا ترى أي جلسة أخرى المهام في الجدولين معًا ولا في أي منهما.
معرفة الإجراء الذي نفّذه MERGE
منذ PostgreSQL 17 يقبل MERGE عبارة RETURNING، وتعيد الدالة merge_action() INSERT أو UPDATE أو DELETE لكل صف:
حُدّث A-100 إلى 7، وأُدرج C-300 بالقيمة 4. وللإدراج أو التحديث بحسب المفتاح مع الكتابة المتزامنة، فضّل upsert باستخدام ON CONFLICT، الذي يدعم RETURNING أيضًا.
ما الذي يمكن أن يحتويه RETURNING
كل ما تحتويه قائمة SELECT: الأعمدة و* والتعبيرات واستدعاءات الدوال والأسماء المستعارة (RETURNING price * qty AS total)، باستثناء دوال التجميع. ولعدّ الصفوف المعادة أو جمعها، غلّف الجملة باستعلام WITH واجمع في SELECT الخارجي.
الصفوف التي يتخطاها ON CONFLICT DO NOTHING، أو مشغّل BEFORE أعاد NULL، لا تُعاد.
الأسئلة الشائعة
كيف أحصل على معرّف الصف الذي أدرجته للتو في PostgreSQL؟
أضف RETURNING id إلى INSERT. يعيد القيمة المولّدة لكل صف مدرج في الرحلة نفسها إلى الخادم، وهذا أكثر أمانًا من SELECT max(id)، ويعمل مع أعمدة identity وserial والقيم الافتراضية مثل gen_random_uuid().
هل RETURNING أسرع من SELECT منفصل؟
غالبًا نعم. فهو يوفّر جملة ثانية ورحلة ثانية إلى الخادم، ويعيد بالضبط الصفوف التي لمستها الجملة، دون فجوة زمنية تستطيع فيها جلسة أخرى تغييرها.
هل يدعم MySQL عبارة RETURNING؟
لا توجد في MySQL عبارة RETURNING، وإنما تقرأ LAST_INSERT_ID() بعد الإدراج. أما SQLite فيدعم RETURNING منذ الإصدار 3.35.