🐍 مرجع استعلامات Django ORM بالعربي

filter()

تصفية النتائج بشرط

filter() تُرجع QuerySet جديدًا يحتوي فقط السجلات المطابقة للشرط الممرَّر.

exclude()

استبعاد نتائج بشرط

exclude() عكس filter() تمامًا — تُرجع كل السجلات التي لا تحقّق الشرط الممرَّر.

get()

جلب سجل واحد بالضبط

get() تُرجع كائنًا واحدًا مطابقًا للشرط — ترمي خطأ إذا لم يوجد أي تطابق أو وُجد أكثر من تطابق واحد.

order_by()

ترتيب النتائج

order_by() ترتّب نتائج الاستعلام حسب حقل أو أكثر — تصاعديًا افتراضيًا، أو تنازليًا بوضع علامة سالبة قبل اسم الحقل.

values() / values_list()

استخراج حقول محدّدة فقط

values() تُرجع النتائج كقواميس Python بدل كائنات نموذج كاملة، وvalues_list() تُرجعها كصفوف (tuples) — أخف وأسرع عند الحاجة لحقول محدّدة فقط.

count()

عدّ النتائج

count() تُرجع عدد السجلات المطابقة كرقم صحيح — أكفأ بكثير من len(queryset) لأنها تُنفَّذ كاستعلام COUNT بقاعدة البيانات مباشرة.

exists()

فحص وجود سجل بلا جلبه

exists() تُرجع True/False بسرعة — هل يوجد سجل واحد على الأقل مطابق، بدون تحميل أي بيانات فعلية.

get_or_create()

جلب سجل أو إنشاؤه إن لم يوجد

get_or_create() تبحث عن سجل مطابق، وتُنشئه تلقائيًا إذا لم يوجد — بعملية واحدة آمنة بدل شرط يدوي.

select_related()

تحسين استعلامات العلاقات (ForeignKey)

select_related() تجلب الكائنات المرتبطة عبر ForeignKey/OneToOne بنفس استعلام SQL واحد (JOIN) بدل استعلام منفصل لكل وصول.

prefetch_related()

تحسين استعلامات العلاقات المتعدّدة

prefetch_related() تحل نفس مشكلة N+1 لكن للعلاقات العكسية أو ManyToMany، حيث JOIN واحد غير كافٍ.

fetch_mode()

أنماط جلب الحقول الجديدة (Django 6.1)

fetch_mode() تضبط سلوك الجلب التلقائي للحقول غير المُجلَبة على مستوى الاستعلام كاملًا — حل جديد لمشكلة N+1 لا يتطلّب تحديد اسم كل حقل صراحة كـ select_related/prefetch_related.

aggregate()

حساب إحصائي على كل النتائج

aggregate() تحسب قيمة إحصائية واحدة (مجموع، متوسط، أكبر، أصغر) على كل الاستعلام، وتُرجع قاموسًا بالنتيجة.

annotate()

إضافة حقل محسوب لكل سجل

annotate() تضيف قيمة محسوبة (غالبًا من عدّ أو تجميع علاقة) لكل سجل بنتيجة الاستعلام على حدة.

distinct()

إزالة النتائج المكرّرة

distinct() تحذف السجلات المكرّرة تمامًا من نتيجة الاستعلام — مفيدة خصوصًا بعد استعلام يعبر علاقة ManyToMany أو عكسية قد يُنتج نفس السجل أكثر من مرة.

first()

جلب أول نتيجة أو None

first() تُرجع أول سجل بالنتيجة، أو None إن كانت فارغة — بلا استثناء مهما كانت النتيجة.

last()

جلب آخر نتيجة أو None

last() تُرجع آخر سجل بالنتيجة حسب الترتيب الحالي، أو None إن كانت فارغة — تمامًا مثل first() لكن بالاتجاه المعاكس.

in_bulk()

جلب عدّة سجلات كقاموس pk → كائن

in_bulk() تجلب عدّة سجلات دفعة واحدة حسب مفاتيحها الأساسية، وتُرجعها كقاموس Python يربط كل pk بكائنه — بحث فوري بلا حلقة استعلامات.

only()

تحديد الحقول المطلوب جلبها فقط

only() تجلب فقط الحقول المذكورة من قاعدة البيانات (والباقي عند الوصول الفعلي له لاحقًا)، على عكس values() التي تُرجع قواميس بدل كائنات نموذج كاملة.

defer()

تأجيل جلب حقول ثقيلة

defer() عكس only() تمامًا — تستثني الحقول المذكورة من الاستعلام الأول، وتجلبها فقط عند الوصول الفعلي لها.

update()

تحديث جماعي بلا جلب الكائنات

update() تُحدّث كل السجلات المطابقة بجملة SQL واحدة مباشرة، بلا تحميل الكائنات للذاكرة أو استدعاء save() على كل واحد.

delete()

حذف سجل أو مجموعة سجلات

delete() تحذف كائنًا واحدًا أو كل نتائج QuerySet دفعة واحدة، وتُرجع عدد السجلات المحذوفة مع تفصيل حسب النوع.

on_delete=models.DB_CASCADE

خيارات الحذف على مستوى قاعدة البيانات (Django 6.1)

منذ Django 6.1، يقبل on_delete قيمًا جديدة (DB_CASCADE وأخواتها) تُنفَّذ داخل قاعدة البيانات مباشرة عبر قيد ON DELETE، بدل جلب السجلات المرتبطة وحذفها من جهة Django.

create()

إنشاء وحفظ كائن بخطوة واحدة

create() تُنشئ كائنًا جديدًا وتحفظه بقاعدة البيانات فورًا بسطر واحد، بدل استدعاء المُنشئ ثم save() بسطرين منفصلين.

bulk_create()

إنشاء عدّة سجلات باستعلام واحد

bulk_create() تُنشئ قائمة كاملة من الكائنات بأقل عدد استعلامات ممكن (غالبًا استعلام إدراج واحد)، أسرع بكثير من حلقة create() لكل عنصر.

Q()

شروط OR وNOT معقّدة

Q() يغلّف شرطًا واحدًا بكائن Python يمكن دمجه مع غيره بعمليات AND (&) وOR (|) وNOT (~) — يحل مشكلة أن filter() العادية تجمع كل معاملاتها بـ AND فقط ولا تدعم OR مباشرة.

F()

الإشارة لقيمة حقل داخل الاستعلام نفسه

F() تشير لقيمة حقل موجود بقاعدة البيانات نفسها داخل الاستعلام، فتُمكّنك من مقارنة حقلين ببعض أو تحديث حقل بالاعتماد على قيمته الحالية — بجملة SQL واحدة آمنة من تعارض التزامن (race condition).