RETURNING גורם לפקודה שמשנה נתונים להחזיר שורות, כמו SELECT. מוסיפים אותו בסוף INSERT, UPDATE, DELETE או (מאז PostgreSQL 17) MERGE, ואחריו העמודות או הביטויים שרוצים: INSERT INTO users (email) VALUES ('ada@example.com') RETURNING id;.
שתי השורות החדשות חוזרות עם ה-ids ש-PostgreSQL יצר ועם ה-plan שמולא מברירת המחדל שלו, בלי שאילתה שנייה.
לקבל את ה-id של שורה שהוכנסה
RETURNING id היא הדרך הסטנדרטית לקבל מפתח שנוצר. הוא מדווח על השורה כפי שנשמרה, ולכן הוא עובד עם עמודות identity, עם serial, עם ערכי ברירת מחדל של UUID ועם ערכים שטריגר BEFORE קבע. VALUES עם כמה שורות או INSERT ... SELECT מחזירים שורה לכל שורה שהוכנסה.
דרייברים קוראים אותו כמו כל תוצאת שאילתה: 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. זו פקודה אחת, ולכן אף session אחר לא רואה אותן בשתי הטבלאות או באף אחת מהן.
לגלות איזו פעולה 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, לא מוחזרות.
שאלות נפוצות
איך מקבלים את ה-id של השורה שהרגע הכנסתי ב-PostgreSQL?
הוסיפו RETURNING id ל-INSERT. הוא מחזיר את הערך שנוצר לכל שורה שהוכנסה באותה פנייה לשרת, וזה בטוח יותר מ-SELECT max(id) ועובד עם עמודות identity, עם serial ועם ערכי ברירת מחדל כמו gen_random_uuid().
האם RETURNING מהיר יותר מ-SELECT נפרד?
בדרך כלל כן. הוא חוסך פקודה שנייה ופנייה שנייה לשרת, והוא מחזיר בדיוק את השורות שהפקודה נגעה בהן, בלי חלון זמן שבו session אחר יכול לשנות אותן בינתיים.
האם MySQL תומך ב-RETURNING?
ל-MySQL אין פסוקית RETURNING; במקום זה קוראים את LAST_INSERT_ID() אחרי הכנסה. SQLite תומך ב-RETURNING מאז גרסה 3.35.