فیلدهای اسکالر، ساده‌ترین و رایج‌ترین نوع فیلدها هستند که مقادیر ساده را ذخیره می‌کنند — یعنی هر فیلد فقط یک مقدار ساده (مثل متن، عدد، تاریخ یا بولین) را نگه می‌دارد. این فیلدها مستقیماً به ستون‌های ساده در دیتابیس تبدیل می‌شوند.

الف) فیلدهای متنی:

• • CharField: برای رشته‌های کوتاه با طول مشخص (max_length اجباری است).
  • TextField: برای متن‌های بلند — بدون محدودیت طول.
  • EmailField: اعتبارسنجی ایمیل + محدودیت طول.
  • SlugField: برای URLها — فقط حروف، اعداد، خط تیره و زیرخط.
  • URLField: اعتبارسنجی آدرس اینترنتی.

ب) فیلدهای عددی:

• • IntegerField, BigIntegerField, SmallIntegerField: اعداد صحیح با دامنه‌های مختلف.
  • PositiveIntegerField, PositiveSmallIntegerField: فقط اعداد مثبت.
  • DecimalField: اعداد اعشاری با دقت بالا — مناسب امور مالی.
  • FloatField: اعداد اعشاری با دقت متوسط (با خطای گرد کردن).

ج) فیلدهای تاریخ و زمان:

• • DateField: فقط تاریخ (YYYY-MM-DD)
  • DateTimeField: تاریخ + زمان (YYYY-MM-DD HH:MM:SS)
  • TimeField: فقط زمان (HH:MM:SS)

د) فیلدهای بولی:

• • BooleanField:  مقدار True و یا False

class Sample(models.Model):
    name = models.CharField(max_length=200)
    price = models.DecimalField(max_digits=10, decimal_places=2)
    created_at = models.DateTimeField(auto_now_add=True)
    is_available = models.BooleanField(default=True)

این فیلدها برای ایجاد رابطه بین مدل‌ها استفاده می‌شوند و در پایگاه داده به صورت کلید خارجی (Foreign Key) یا جدول واسط (Intermediate Table) پیاده‌سازی می‌شوند. مدل‌های جنگو به طور پیش‌فرض از RDBMSها استفاده می‌کنند که روابط بین مدل‌ها رو پشتیبانی می‌کند. استفاده از روابط در پایگاه داده باعث بهبود عملکرد، جلوگیری از تکرار داده و ایجاد ساختار رابطه‌ای بین داده‌ها می‌شود.

الف) ForeignKey — رابطه یک به چند

• • یک رکورد در مدل A به چند رکورد در مدل B اشاره می‌کند. (مثال: یک نویسنده — چند مقاله)

• • on_delete اجباری است — تعیین می‌کند در صورت حذف رکورد والد چه اتفاقی بیفتد.

ب) OneToOneField — رابطه یک به یک

• • یک رکورد در مدل A فقط به یک رکورد در مدل B متصل است. (مثال: کاربر — پروفایل کاربری.)

ج) ManyToManyField — رابطه چند به چند

• • چند رکورد در مدل A به چند رکورد در مدل B متصل می‌شوند. (مثال: مقاله — تگ‌ها).

class Smaple(models.Model):
    author = models.ForeignKey('Author', on_delete=models.CASCADE)
    profile = models.OneToOneField('UserProfile', on_delete=models.CASCADE)
    tags = models.ManyToManyField('Tag', blank=True)

در بخش روابط مدل‌ها، به‌صورت مفصل و با جزئیات کاربردی به این مفهوم کلیدی خواهیم پرداخت که چگونه می‌توان با استفاده از فیلدهای رابطه‌ای جنگو — مانند ForeignKey، OneToOneField و ManyToManyField — ساختاری منسجم، پایدار و بدون تکرار داده طراحی کرد. این فیلدها نه‌تنها در سطح کد پایتون، بلکه در عمق پایگاه داده نیز با ایجاد کلیدهای خارجی یا جداول واسط، روابط معنادار بین موجودیت‌ها را پیاده‌سازی می‌کنند. هدف نهایی این است که از ذخیره‌سازی تکراری و غیرضروری داده‌ها جلوگیری شود و هر اطلاعاتی فقط در یک نقطه منحصربه‌فرد نگهداری شود — تا در صورت نیاز به به‌روزرسانی، تنها یک تغییر کافی باشد و تمام بخش‌های مرتبط به‌طور خودکار و بدون خطا بازتابی از آن تغییر ارائه دهند. این رویکرد، پایهٔ اصلی یکپارچگی داده‌ها (Data Integrity) و مقیاس‌پذیری سیستم است و درک عمیق آن، یک توسعه‌دهنده معمولی را به یک معمار داده حرفه‌ای تبدیل می‌کند. 

این فیلدها برای ذخیره داده‌های مرکب، باینری یا رسانه‌ای طراحی شده‌اند. برخلاف فیلدهای اسکالر، این فیلدها ممکن است شامل چند بخش باشند یا نیاز به پردازش خاصی (مثل آپلود فایل یا تجزیه JSON) داشته باشند.

الف) FileField و ImageField

• • برای آپلود فایل و تصویر.
  • نیاز به تنظیم MEDIA_URL و MEDIA_ROOT در فایل تنظیمات پروژه settings.py دارند.
  • ImageField نیازمند کتابخانه Pillow است.

ب) JSONField

• • برای ذخیره داده‌های JSON — بسیار منعطف.
  • پشتیبانی از کوئری‌های داخل JSON در دیتابیس‌های مدرن (مثل PostgreSQL).
  • مناسب برای: تنظیمات پویا، لاگ‌های ساختاریافته، داده‌های متغیر بین رکوردها.

ج) ArrayField (فقط در PostgreSQL)

• • ذخیره لیستی از مقادیر (مانند لیست تلفن‌های یک کاربر).
  • فقط در PostgreSQL پشتیبانی می‌شود.

class Smaple(models.Model):
    avatar = models.ImageField(upload_to='avatars/')
    resume = models.FileField(upload_to='resumes/')
    metadata = models.JSONField(default=dict)
    phones = models.ArrayField(models.CharField(max_length=10))

د) HStoreField (فقط در PostgreSQL — قدیمی‌تر)

• • ذخیره داده‌های key-value — جایگزین قدیمی‌تر برای JSONField.

این فیلدها معمولاً برای مدیریت زیرساخت مدل یا ذخیره اطلاعات سیستمی استفاده می‌شوند. بعضی از آن‌ها به‌صورت خودکار توسط جنگو ایجاد می‌شوند (مثل id) و بعضی برای موارد خاص طراحی شده‌اند.

الف) AutoField / BigAutoField

• • فیلد عددی که به‌صورت خودکار افزایش می‌یابد.
  • معمولاً به عنوان id پیش‌فرض در هر مدل بصورت خودکار توسط جنگو استفاده می‌شود و نیازی به تعریف دستی ندارد.

ب) UUIDField

• • ذخیره شناسه‌های منحصربه‌فرد جهانی.
  • مناسب برای مواردی که id عددی قابل حدس نباشد.
  • نیازمند بکارگیری کتابخانه uuid است.

ج) GenericIPAddressField

• • ذخیره آدرس IP (هم IPv4 و هم IPv6).

د) BinaryField

• • ذخیره داده‌های باینری خام — مثل فایل‌های رمزگذاری شده یا بایت‌ها.
  • محدودیت در استفاده در فرم‌ها و فیلترها دارد.

import uuid

class smaple(models.Model):
    id = models.BigAutoField(primary_key=True)
    id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False)
    ip_address = models.GenericIPAddressField()
    encrypted_data = models.BinaryField()

هـ) GenericForeignKey (از django.contrib.contenttypes)

• • برای ایجاد رابطه به مدل‌های مختلف — مکانیزم “Generic Relation” (مانند سیستم کامنت که برای مدل‌های مقاله، محصول و ...  کار کند).
  • نیازمند دو فیلد کمکی (content_type و object_id) است.
  • content_type: مشخص می‌کند که رکورد مربوط به کدام مدل است (مثلاً Article یا Product)
  • object_id: مشخص می‌کند که رکورد مربوط به کدام id از آن مدل است
  • content_object: یک فیلد مجازی (غیر فیزیکی) که به شما اجازه می‌دهد مستقیماً به شیء مرتبط دسترسی داشته باشید.

from django.contrib.contenttypes.fields import GenericForeignKey
from django.contrib.contenttypes.models import ContentType

class Comment(models.Model):
    content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE) # Refer to Model (Article, Product, ...)    
    object_id = models.UUIDField()                                          # Refer to Model.Object.id  
    content_object = GenericForeignKey('content_type', 'object_id')         # "content_type" & "object_id" Combination to access the object directly

    comment = models.TextField()
    created = models.DateTimeField(auto_now_add=True)

⚠️ اگر در مدل مقصد (مثلاً Article) از UUIDField به عنوان id بجای AutoField پیش‌فرض جنگو استفاده گردد، باید فیلد object_id در مدل Comment نیز از PositiveIntegerField به UUIDField تغییر داده شود — در غیر این صورت، با خطا مواجه خواهیم شد.

تمام فیلدهای مدل در جنگو (مانند CharField، IntegerField، ForeignKey و غیره) از مجموعه‌ای از پارامترهای مشترک پشتیبانی می‌کنند. این گزینه‌ها رفتار فیلد را در سطح پایگاه داده، فرم‌ها، اعتبارسنجی و رابط کاربری ادمین کنترل می‌کنند. در ادامه، پرکاربردترین و مهم‌ترین این گزینه‌ها را بررسی می‌کنیم.

✺✳ ┅  null  ┅ ✳✺

• نوع: bool
• پیش‌فرض: False
• کاربرد: تعیین می‌کند که آیا فیلد می‌تواند در پایگاه داده مقدار NULL را بپذیرد یا خیر.

اگر null=True باشد، جنگو اجازه می‌دهد که این فیلد در پایگاه داده مقدار NULL را بپذیرد. در غیر این صورت، فیلد اجباری در سطح پایگاه داده قلمداد خواهد شد و هر تلاشی برای ذخیره NULL منجر به خطا می‌شود.

age = models.IntegerField(null=True)

✺✳ ┅  blank  ┅ ✳✺

• نوع: bool
• پیش‌فرض: False
• کاربرد: تعیین می‌کند که آیا فیلد می‌تواند در فرم‌ها (و اعتبارسنجی جنگو) خالی باقی بماند یا خیر.

اگر blank=True باشد، فیلد در فرم‌های جنگو (از جمله ModelForm و پنل ادمین) اختیاری در نظر گرفته می‌شود و کاربر می‌تواند آن را خالی بگذارد و در غیر این‌صورت جنگو اجازه Submit فرم را تا زمان پرکردن فیلد به کاربر نخواهد داد.

bio = models.TextField(blank=True)

STATUS_CHOICES = [
    ('ON', 'Active'),
    ('OFF', 'Inactive'),
    ('IDL', 'Idle'),
]

status = models.CharField(max_length=1, choices=STATUS_CHOICES)

✺✳ ┅  default  ┅ ✳✺

• نوع: هر مقدار ثابت یا یک تابع قابل فراخوانی (callable)
• کاربرد: تعیین مقدار پیش‌فرض برای فیلد در صورتی که مقداری ارسال نشود.

active = models.BooleanField(default=True)

email = models.EmailField(help_text="Enter your valid mail address ...")

id = models.UUIDField(primary_key=True, default=uuid.uuid4)

✺✳ ┅  unique  ┅ ✳✺

• نوع: bool
• پیش‌فرض: False
• کاربرد: تضمین می‌کند که مقدار این فیلد در کل جدول منحصربه‌فرد باشد.

email = models.EmailField(unique=True)

⚠️ در پایگاه داده، یک محدودیت انحصاری از نوع UNIQUE ایجاد می‌شود.

⚠️ در صورت تلاش برای ذخیره مقدار تکراری، خطای IntegrityError رخ می‌دهد.

✺✳ ┅  editable  ┅ ✳✺

• نوع: bool
• پیش‌فرض: True
• کاربرد: تعیین می‌کند که آیا این فیلد در فرم‌های خودکار جنگو (مثل ادمین پنل یا ModelForm) نمایش داده شود یا خیر.

اگر editable=False باشد، این فیلد در فرم‌های جنگو نمایش داده نخواهد شد.

id = models.UUIDField(primary_key=True, editable=False, default=uuid.uuid4)

⚠️ فیلدهای editable=False در پنل ادمین دیده نمی‌شوند و در فرم‌ها نیز شامل نمی‌شوند. اما همچنان در مدل و پایگاه داده وجود دارند و قابل دسترسی هستند.

✺✳ ┅  verbose_name  ┅ ✳✺

• نوع: str
• کاربرد: تعیین نام خوانا و انسان‌محور برای فیلد (به جای نام متغیر).

در ادمین پنل و فرم‌ها، نامی که برای verbose_name تعیین می‌شود به عنوان جایگزینی نام فیلد، نمایش داده خواهد شد.

full_name = models.CharField("name", max_length=50)
full_name = models.CharField(max_length=50, verbose_name="name")

⚠️ اگر verbose_name تعیین نگردد، جنگو، نام فیلد را با تبدیل _ به فاصله و و بزرگ‌نویسی اول هر کلمه (full_name → Full name) به عنوان نام پیش‌فرض استفاده می‌کند.

این گزینه‌ها، ابزارهای قدرتمندی هستند که امکان طراحی مدل‌هایی دقیق، ایمن و کاربرپسند را فراهم می‌آورند. درک تفاوت بین null و blank، استفاده صحیح از choices و default، و به‌کارگیری verbose_name برای بهبود تجربه کاربری، از جمله بهترین روش‌های توسعه با جنگو محسوب می‌شوند.

علاوه بر پارامترهای مشترکی مانند null، blank و default که در بخش قبلی بررسی شدند، هر کدام از تایپ‌های فیلد در جنگو ممکن است گزینه‌های اختصاصی خود را نیز داشته باشد. و یا به عبارت دیگر، برخی گزینه‌ها فقط برای فیلدهای خاصی معنا دارند و در تعریف آن فیلدها کاربرد دارند. برخی از این گزینه‌ها اجباری هستند (مثل max_length در CharField) و برخی دیگر اختیاری اما مفید.. در ادامه، مهم‌ترین فیلدهای پرکاربرد و گزینه‌های خاص آن‌ها را مرور می‌کنیم.

✺✳ ┅  max_length  ┅ ✳✺

• نوع: int
• فیلدها: CharField, EmailField, SlugField, URLField, FileField, ImageField
• اجباری: برای CharField و زیرمجموعه‌هایش
• کاربرد: حداکثر تعداد کاراکترهای مجاز برای فیلد را تعیین می‌کند. در پایگاه داده، این مقدار به عنوان اندازه ستون VARCHAR(n) استفاده می‌شود.

username = models.CharField(max_length=150)
website = models.URLField(max_length=500)

⚠️ برای FileField و ImageField، این گزینه حداکثر طول مسیر ذخیره‌سازی فایل (path) را تعیین می‌کند و نه حجم فایل. 

✺✳ ┅  max_digits  و decimal_places ┅ ✳✺

• نوع: int
• فیلدها: DecimalField
• اجباری: برای DecimalField
• کاربرد: max_digits حداکثر تعداد ارقام مجاز (شامل ارقام قبل و بعد از ممیز) را مشخص کرده و decimal_places تعداد ارقام پس از ممیز را تعیین می‌کند.

price = models.DecimalField(max_digits=10, decimal_places=2)  # e.g. 12345678.99

⚠️ هر دو گزینه برای DecimalField اجباری هستند و max_digits باید حتما بزرگتر از decimal_places باشد.

 ✺✳ ┅  auto_now  و auto_now_add ┅ ✳✺

• نوع: bool
• پیش‌فرض: False
• فیلدها: DateField, DateTimeField
• اختیاری
• کاربرد: اگر True باشد، در auto_now هر بار که یک رکورد ویرایش شده و ذخیره گردد، به زمان فعلی، بروزرسانی می‌شود و برای ثبت زمان آخرین ویرایش (updated_at) کاربرد دارد، ولی در auto_now_add فقط هنگام ایجاد اولیه رکورد به زمان فعلی تنظیم شده و برای ثبت زمان ایجاد (created_at) بیشترین کاربرد را خواهد داشت

updated_at = models.DateTimeField(auto_now=True)
created_at = models.DateTimeField(auto_now_add=True)

✺✳ ┅  on_delete  ┅ ✳✺

• نوع: models
• فیلدها: ForeignKey, OneToOneField, ManyToManyField
• اجباری: برای فیلدهای رابطه‌ای
• کاربرد: رفتار سیستم را هنگام حذف رکورد مقصد (related object) تعیین می‌کند.

• مقادیر رایج:

  • models.CASCADE: حذف تمامی زنجیره‌‌ی رکوردهای وابسته.
  • models.PROTECT: جلوگیری از حذف با خطای ProtectedError.
  • models.SET_NULL: تنظیم فیلد به NULL (نیاز به null=True دارد).
  • models.SET_DEFAULT: تنظیم به مقدار پیش‌فرض (نیاز به default دارد).

author = models.ForeignKey(User, on_delete=models.CASCADE)

✺✳ ┅  related_name  ┅ ✳✺

• نوع: str
• فیلدها: ForeignKey, OneToOneField, ManyToManyField
• اختباری
• کاربرد: نامی که برای دسترسی معکوس از مدل مقصد به مدل مبدا استفاده می‌شود

class Article(models.Model):
    author = models.ForeignKey(User, on_delete=models.CASCADE, related_name='articles')

  ✺✳ ┅  allow_unicode  ┅ ✳✺

• نوع: bool
• فیلدها: SlugField
• اختیاری
• کاربرد: اگر True باشد، اجازه استفاده از کاراکترهای غیر-لاتین (مثل فارسی، عربی، چینی) در اسلاگ را می‌دهد.

slug = models.SlugField(allow_unicode=True)  # "مقاله-سلام-دنیا"

در سیستم‌های مدیریت پایگاه‌داده‌های رابطه‌ای و به‌ویژه در چارچوب جنگو، رابطه ForeignKey ابزاری بنیادین برای ایجاد ارتباط جهت‌دار بین دو مدل محسوب می‌شود که از نظر منطقی معادل یک رابطه یک به چند (One-to-Many) است. این بدان معناست که یک رکورد در مدل والد — مثلاً User — می‌تواند با چندین رکورد در مدل فرزند — مثلاً Project — مرتبط باشد، در حالی که هر رکورد در مدل فرزند تنها می‌تواند به یک رکورد منحصربه‌فرد در مدل والد ارجاع دهد.

این الگو در مثال‌های واقعی مانند «مسئولیت یک کاربر بر چندین پروژه می‌تواند باشد، در حالی که هر پروژه تنها یک مسئول می‌تواند داشته باشد» به خوبی قابل مشاهده است. • از دید مدل فرزند (Project)، همین رابطه به‌عنوان چند به یک (ManyToOne) تفسیر می‌شود، زیرا چندین رکورد در این مدل به یک رکورد واحد در مدل والد اشاره می‌کنند.

این دوگانگی در نام‌گذاری رابطه — OneToMany از دید والد و ManyToOne از دید فرزند — گاهی برای توسعه‌دهندگان مبتدی گمراه کتنده خواهد بود، اما درک دقیق آن شرط لازم برای طراحی صحیح مدل‌ها و دسترسی کارآمد به داده‌های مرتبط در لایه منطق کسب‌وکار است.

در پیاده‌سازی، فیلد ForeignKey، همواره در مدل فرزند تعریف می‌گردد و به مدل والد متصل می‌شود — چرا که در سطح پایگاه‌داده، این مدل فرزند است که نیازمند ارجاع به اطلاعات مدل والد خواهد بود. در واقع، فرآیندی که در سطح پایگاه‌داده اتفاق می‌افتد به این صورت است که هنگام تعریف یک فیلد ForeignKey در مدل فرزند، یک ستون جدید (مثلاً owner_id) به صورت خودکار در جدول مربوط به مدل فرزند اضافه می‌شود که به کلید اصلی مدل والد (User) اشاره می‌کند.

coreapp/models.py

from django.db import models
from django.contrib.auth.models import User
import uuid

class Project(models.Model):
    owner = models.ForeignKey(User, on_delete=models.CASCADE, related_name="projects")  # ManyToOne Field
    title = models.CharField(max_length=100)
    area = models.CharField(max_length=50)
    content = models.TextField(null=True, blank=True)
    created = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)
    id = models.UUIDField(default=uuid.uuid4, unique=True, primary_key=True, editable=False)

    def __str__(self):
        return self.title

در مدل Project که در کد فوق تعریف شده است، رابطه ForeignKey از طریق فیلد owner به مدل User (از اپ django.contrib.auth) متصل شده است که مدل پیش‌فرض جنگو بوده و هنگام ایجاد کاربری superuser شرح مختصری از آن رفت. این تعریف به‌صورت دقیق یک رابطه چند به یک (ManyToOne) را از دید مدل Project پیاده‌سازی می‌کند — یعنی هر پروژه تنها می‌تواند یک مالک (owner) داشته باشد، اما یک کاربر می‌تواند مالک چندین پروژه باشد. این رابطه در سطح پایگاه‌داده با افزودن یک ستون owner_id در جدول project پیاده‌سازی می‌شود که به کلید اصلی (id) جدول auth_user اشاره می‌کند.

⚠️ پارامتر on_delete=models.CASCADE تعیین می‌کند که در صورت حذف کاربر، تمام پروژه‌های مرتبط با او نیز، به‌صورت خودکار حذف گردند — رفتاری که در بسیاری از سیستم‌ها برای حفظ تمامیت داده‌ها منطقی و مطلوب است. 

⚠️ در جنگو، برای دسترسی معکوس — یعنی از مدل والد به مدل فرزند — از ویژگی related_name استفاده می‌شود که در زمان تعریف ForeignKey اختیاری اما بسیار توصیه‌شده است. این ویژگی امکان تعریف یک نام معنادار برای دسترسی به مجموعه رکوردهای فرزند را از مدل والد فراهم می‌کند

⚠️ برای بازتاب این تغییرات در ساختار پایگاه‌داده، الزامی است که دو دستور makemigrations و migrate به ترتیب اجرا شوند

با بررسی داده‌های واقعی در جداول، این رابطه به‌وضوح قابل مشاهده است. در جدول auth_user، کاربری با id = 1 و نام کاربری admin وجود دارد که پیشتر در بخش ایجاد کاربری superuser ایجاد گردید.

TABLE 🡺 auth_user

id    username    email            first_name  last_name   is_superuser     is_staff    is_active  
----  ----------  ---------------  ----------- ---------   --------------   ----------  -----------
1  	  admin       admin@admin.com              			   1  		        1           1  

در مقابل، در جدول coreapp_project، سه رکورد مختلف وجود دارد که همگی در فیلد owner_id مقدار 1 دارند — یعنی هر سه پروژه Fleunt Speech و Coverage Map و Yoga Academy به همان کاربر admin تعلق دارند..

TABLE 🡺 coreapp_project

owner_id	title          area      content    created         updated         id     
----------  -------------  --------  ---------  --------------  --------------  -------
1			Fluent Speech  Health               2025-09-29 ...  2025-09-29 ...  ac26...
1			Coeverage Map  Industry             2025-09-29 ...  2025-09-29 ...  0fac...
1			Yoga Academy   Sport                2025-09-29 ...  2025-09-29 ...  45da...

این دقیقاً همان مفهوم One-to-Many است که در این نمونه با مفهوم یک کاربر ←→ چندین پروژه، از دید پایگاه‌ داده می‌باشد، این رابطه با یک کلید خارجی (Foreign Key) پیاده‌سازی شده که تمامیت رابطه را تضمین می‌کند — یعنی هیچ پروژه‌ای نمی‌تواند owner_idای داشته باشد که در جدول auth_user وجود نداشته باشد (مگر در صورتی که on_delete مقدار SET_NULL یا SET_DEFAULT داشته باشد — بخش مربوط به پارامترهای فیلد — که در این مدل پیاده‌سازی نشده است).

این تحلیل نشان می‌دهد که رابطه تعریف‌شده در سطح مدل، نه‌تنها در کد بلکه در ساختار فیزیکی پایگاه‌داده نیز به‌درستی پیاده‌سازی شده و با داده‌های واقعی همخوانی کامل دارد. 

در رابطه One-To-One، هر رکورد از یک مدل می‌تواند، دقیقاً با یک و فقط یک رکورد از مدل دیگر مرتبط باشد و بالعکس، برخلاف رابطه ForeignKey — رابطه فرزند و والد — در رابطه OneToOne هر دو طرف تنها یک همسر دارند!

برای استفاده از رابطه one-to-one در مدل‌های جنگو باید از گزینه OneToOneField برای فیلد استفاده نمود تا بدین صورت رابطه یک به یک (one-to-one) را تعریف کرد.

clientapp/models.py

# clientapp.models.py
from django.db import models
from django.contrib.auth.models import User

class Profile(models.Model):
    user = models.OneToOneField(User, on_delete=models.CASCADE) # OneToOne Field
    mobile = models.CharField(max_length=15, unique=True)
    birth = models.DateField(null=True, blank=True)
    avatar = models.ImageField(upload_to='profiles/', null=True, blank=True)
    id = models.UUIDField(default=uuid.uuid4, primary_key=True, unique=True, editable=False)

    def __str__(self):
        return self.user.username

در رابطه چند به چند (Many-to-Many یا به اختصار ManyToMany)، هر رکورد از یک مدل می‌تواند با چندین رکورد از مدل دیگر مرتبط شود و بالعکس. این نوع رابطه زمانی کاربرد دارد که بین داده‌های دو مدل، ارتباطِ یک‌طرفه FoerignKey یا یک‌به‌یک OneToOne کافی نباشد. فرض کنیم در یک وب‌سایت پورتفولیوی شخصی برای نمایش لیستی از تجربه پروژه‌های نرم‌افزاری اجراشده، هر پروژه می‌تواند چندین تگ (برچسب) داشته باشد — Python، Django، React و غیره. از سوی دیگر، یک تگ مانند Python می‌تواند به چندین پروژه مختلف تعلق داشته باشد (به عنوان مثال،یک پروژه وب، یک پروژه اسکریپتی و یا یک ربات تلگرام که همگی با پایتون اجرا شده‌ باشند). در چنین شرایطی، رابطه ManyToMany ایده‌آل‌ترین گزینه خواهد بود.

در سطح پایگاه داده، رابطه چند به چند به‌صورت مستقیم قابل پیاده‌سازی نیست. به همین دلیل، جنگو به‌صورت خودکار یک جدول میانی (Intermediate Table یا Junction Table) ایجاد می‌کند. این جدول دو ستون دارد که هر ستون به id  رکورد یا فیلد کلید اصلی (Primary Key) در مدل مقابل اشاره می‌کند. هر بار که یک تگ به یک پروژه اضافه گردد، جنگو یک رکورد جدید در جدول میانی درج می‌کند که شامل project_id و tag_id خواهد بود.

TABLE 🡺 coreapp_project_tags

  id  project_id                        tag_id
----  --------------------------------  --------------------------------
   1  ac260bde5f1347449f239052420573a7  ab2050e16c94483db24aeab26b0c4330
   2  0fac050182a84fffa37d6033c276d2c2  ab2050e16c94483db24aeab26b0c4330
   3  45da0e0c546a4b0991f665edba168b89  ab2050e16c94483db24aeab26b0c4330
   4  ac260bde5f1347449f239052420573a7  41de4854a25b40ac860c5b28ff4b8c17
   5  ac260bde5f1347449f239052420573a7  50cb432fb44c487daedfd427eac08bcd

برای ایجاد یک رابطه چند به چند در مدل‌های جنگو، از فیلد ManyToManyField استفاده می‌گردد. فیلد ManyToManyField فقط در یکی از دو مدل تعریف می‌گردد— به طور معمول، در مدلی که از لحاظ منطقی "مالک" رابطه تلقی می‌گردد. اگر ManyToManyField را در هر دو مدل قرار دهیم، جنگو دو جدول میانی جداگانه ایجاد می‌کند که کاملاً اشتباه است! رابطه چند به چند یک رابطه دوطرفه است و فقط نیاز به یک فیلد در یکی از مدل‌ها دارد.

coreapp/models.py

# coreapp.models.py
from django.db import models
from django.contrib.auth.models import User
import uuid

class Tag(models.Model):
    name = models.CharField(max_length=50, unique=True)
    id = models.UUIDField(default=uuid.uuid4, unique=True, primary_key=True, editable=False)

    def __str__(self):
        return self.name

#-------------------------------------------------------------------------------------------

class Project(models.Model):
    owner = models.ForeignKey(User, on_delete=models.CASCADE, related_name="projects")
    title = models.CharField(max_length=100)
    area = models.CharField(max_length=50)
    content = models.TextField(null=True, blank=True)
    tags = models.ManyToManyField(Tag, related_name='projects')
    created = models.DateTimeField(auto_now_add=True)
    updated = models.DateTimeField(auto_now=True)
    id = models.UUIDField(default=uuid.uuid4, unique=True, primary_key=True, editable=False)

    def __str__(self):
        return self.title

⚠️ چون پروژه‌ها مالک تگ‌ها محسوب می‌شوند، فیلد ManyToMany در مدل project تعریف شده است.

⚠️ برای بازتاب تغییرات جدید در ساختار پایگاه‌داده، الزامی است که دو دستور makemigrations و migrate به ترتیب اجرا شوند.

⚠️ ثبت مدل Tag ایجاد شده، در admins.py جهت نمایش در پنل ادمین، توسط دستور admin.site.register(models.Tag) می‌بایست صورت پذیرد.

در اولین گام، نیاز است داده‌های ذخیره‌شده در پایگاه داده فراخوانی شوند — Retrieving Data. جنگو برای این کار مجموعه‌ای از متدهای پرس‌وجو (QuerySet methods) را در اختیار قرار می‌دهد که هر یک کارکرد مشخصی دارند: از جمله بازیابی تمام رکوردها، دریافت یک رکورد منحصربه‌فرد، فیلتر کردن نتایج بر اساس شرایط دلخواه و همچنین حذف رکوردهای نامرتبط از مجموعه نتایج.

این متدها پایه و اساس کار با داده‌ها در ORM هستند و در اکثر پروژه‌ها بیشترین استفاده را دارند.

⸺ دریافت همه رکوردها

projects = Project.objects.all()

✅ این متد تمام رکوردهای مدل project را برمی‌گرداند. در عمل معادل SELECT * FROM coreapp_project در SQL است.
📌 کاربرد: زمانی که بخواهیم کل داده‌های یک جدول را نمایش دهیم (به عنوان مثال لیست همه پروژه‌های اجرا شده).

⸺ دریافت یک رکورد خاص

projectObj = Project.objects.get(id="4f0928dd-5d68-484c-bd19-aa7a18d27d66")

✅ متد get() فقط یک رکورد را بر اساس شرط مشخص برمی‌گرداند.
⚠️ اگر هیچ رکوردی پیدا نشود ⇄ خطای DoesNotExist
⚠️ اگر بیش از یک رکورد پیدا شود ⇄ خطای MultipleObjectsReturned

📌 کاربرد: زمانی که مطمئن هستیم شرط دقیقاً یک رکورد را مشخص می‌کند (مثل id یا username که منحصربه‌فرد و یا به اصطلاح Unique هستند).

⸺ فیلتر کردن رکوردها

projectObjs = Project.objects.filter(subject="Health")

✅ متد filter()، لیستی از رکوردهایی که شرایط را احراز می‌کنند، برمی‌گرداند.
📌 کاربرد: گرفتن لیست داده‌هایی که ویژگی مشترک دارند. ( بعنوان مثال 🡠 همه پروژه‌های اجرا شده در موضوع سلامت Health )

⸺ حذف رکوردهای نامرتبط

projectObjs = Project.objects.exclude(subject="Sport")

✅ متد exclude()، برعکس filter() عمل می‌کند؛ یعنی رکوردهایی که مصداق شرط را ندارند، برمی‌گرداند.
📌 کاربرد: وقتی بخواهیم همه داده‌ها به جز یک دسته خاص را نمایش دهیم.( بعنوان مثال 🡠 همه پروژه‌های اجرا شده یه غیر از موضوع ورزش Sports )

پس از بازیابی داده‌ها، گاهی نیاز داریم که رکوردها را مرتب‌سازی — Ordering — یا محدودسازی — Limiting — کنیم. به عنوان مثال محدودسازی ۱۰ کتاب آخر یک نویسنده یا مرتب‌کردن محصولات فروشگاه بر اساس قیمت. جنگو این کار را به‌سادگی با متدهای order_by و slicing فراهم می‌کند.

⸺ مرتب‌سازی صعودی

projects = Project.objects.all().order_by("title")

همهٔ پروژه‌ها را بر اساس عنوان (title) به‌صورت الفبایی صعودی (از الف به ی) مرتب می‌کند. یعنی پروژه‌هایی که عنوانشان با «آ» شروع می‌شود، اول لیست می‌آیند.

⸺ مرتب‌سازی نزولی

projects = Project.objects.all().order_by("-created")

همهٔ پروژه‌ها را بر اساس فیلد created (معمولاً تاریخ ایجاد) به‌صورت نزولی مرتب می‌کند. علامت منفی (-) نشان‌دهندهٔ ترتیب معکوس است؛ یعنی جدیدترین پروژه‌ها اول لیست ظاهر می‌شوند.

⸺ محدود کردن تعداد رکوردها

projects = Project.objects.all()[:5]

فقط 5 رکورد اول از لیست پروژه‌ها را برمی‌گرداند. این روش معمولاً برای نمایش «آخرین پروژه‌ها» یا «محدود کردن نتایج در صفحه‌بندی» استفاده می‌شود. این کار در پس‌زمینه با LIMIT 5 در SQL پیاده‌سازی می‌شود و بسیار کارآمد است.

⸺ رد کردن چند رکورد اول

projects = Project.objects.all()[5:]

اولین 5 رکورد را نادیده می‌گیرد و از ششمین رکورد به بعد را برمی‌گرداند. استفاده مستقیم از slice در پروژه‌های واقعی به‌جای Paginator جنگو توصیه نمی‌شود، چون Paginator امن‌تر و بهینه‌تر است.

گاهی تنها به یک رکورد خاص (مثل اولین یا آخرین مورد) یا اطلاعات خلاصه‌ای مانند تعداد کل رکوردها نیاز داریم. جنگو برای این موارد متدهای کمکی ساده‌ای مانند first(), last(), count() و exists() را فراهم کرده است تا بتوانیم بدون نوشتن کوئری‌های پیچیده یا اضافی، به‌صورت کارآمد و خوانا با داده‌ها کار کنیم.

⸺ اولین رکورد

اولین رکورد از مجموعه نتایج را برمی‌گرداند (بر اساس ترتیب پیش‌فرض یا order_by). اگر رکوردی وجود نداشته باشد، مقدار None را برمی‌گرداند — خطا نمی‌دهد.

projectObj = Project.objects.first()

⸺ آخرین رکورد

آخرین رکورد از مجموعه نتایج را برمی‌گرداند. مانند first()، در صورت عدم وجود داده، None بازمی‌گرداند.

projectObj = Project.objects.last()

💡 نکته: first() و last() بر اساس ترتیب تعیین‌شده توسط order_by() عمل می‌کنند. اگر order_by مشخص نشده باشد، ترتیب بر اساس primary key در نظر گرفته می‌شود.

⸺ تعداد رکوردها

تعداد کل رکوردها را به‌صورت یک عدد صحیح برمی‌گرداند. این متد بهینه‌تر از len(Project.objects.all()) است، چون در پس‌زمینه از SELECT COUNT(*) استفاده می‌کند و داده‌های واقعی را fetch نمی‌کند.

projectObj = Project.objects.count()

⸺ بررسی وجود رکورد

بررسی می‌کند که آیا حداقل یک رکورد با شرط مورد نظر وجود دارد یا خیر. نتیجه یک مقدار True یا False است. این روش بهینه‌ترین راه برای چک کردن وجود داده است، چون فقط یک سطر از دیتابیس را بررسی می‌کند و داده‌های اضافه‌ای را بارگیری نمی‌کند.

projectObj = Project.objects.filter(area="AI").exist()

اغلب اوقات نیاز خواهد بود که داده‌ها را بر اساس شرایط دقیق‌تری—مانند «بزرگ‌تر از»، «کوچک‌تر از»، «شامل یک عبارت» یا «بین دو تاریخ»—فیلتر کنیم. جنگو برای این منظور از سیستم عبارات جستجو (lookup expressions) پشتیبانی می‌کند که با استفاده از دو زیرخط (__) پس از نام فیلد اعمال می‌شوند.

⸺ مساوی

projectObj = Project.objects.filter(title="Fluent Speech")

رکوردهایی که فیلد title آن‌ها دقیقاً برابر با مقدار داده‌شده باشد. (معادل با استفاده از = در SQL)

💡 نیازی به __exact نیست؛ این رفتار پیش‌فرض filter() است.

⸺ شامل بودن (Contains)

آخرین رکورد از مجموعه نتایج را برمی‌گرداند. مانند first()، در صورت عدم وجود داده، None بازمی‌گرداند.

projectObjs = Project.objects.filter(title__contains="AI")

رکوردهایی که فیلد title آن‌ها عبارت "AI" را در هر جایی داشته باشند (حساس به بزرگ‌وکوچکی حروف).

💡 برای جستجوی غیرحساس به بزرگ‌وکوچکی حروف، از __icontains استفاده می‌شود.

⸺ بزرگ‌تر یا مساوی

projectObjs = Project.objects.filter(created__gte="2023-01-01") # gte = greater than or equal

رکوردهایی که تاریخ ایجاد (created) آن‌ها بزرگ‌تر یا مساوی تاریخ داده‌شده باشد.

⸺ کوچک‌تر یا مساوی

projectObj = Project.objects.filter(updated__lte='2023-01-01') # lte = less than or equal

رکوردهایی که تاریخ اخرین تغییرات آن‌ها (updated) کوچک‌تر یا مساوی تاریخ مشخص‌شده باشد.

⸺ بین دو مقدار (Range)

projectObj = Project.objects.filter(created__range=('2024-01-01', '2025-01-01'))

رکوردهایی که مقدار فیلد created آن‌ها بین دو تاریخ (شامل خود دو سر) باشد.

💡 معادل با  BETWEEN '2024-01-01' AND '2025-01-01' در SQL

⸺ داخل یک لیست (In)

projectObjs = Project.objects.filter(area__in=["Health", "Sport"])

رکوردهایی که فیلد subject آن‌ها یکی از مقادیر داخل لیست باشد.

💡 معادل با subject IN ('AI', 'Sports', 'Health') در SQL.

⸺ مقدار تهی (Null)

projectObjs = Project.objects.filter(content_isnull=False)

رکوردهایی که فیلد content آن‌ها مقدار NULL نباشد (یعنی داده داشته باشد).

💡 برای یافتن رکوردهایی که content آن‌ها خالی است: content__isnull=True.

💡 isnull فقط برای فیلدهایی که null=True دارند معنی دارد. برای فیلدهای CharField معمولاً بهتر است از __exact="" یا __isempty (در صورت نیاز) استفاده کرد.

سیستم ORM جنگو فقط برای خواندن داده‌ها طراحی نشده است؛ بلکه امکان بروزرسانی و حذف داده‌ها را نیز به‌صورت ایمن و کارآمد فراهم می‌کند—بدون نیاز به نوشتن دستورات SQL دستی.

⸺ بروزرسانی رکوردها

متد update()، رکورد(های) مطابق با شرط را مستقیماً در پایگاه داده به‌روزرسانی می‌کند.

Project.objects.filter(id="4f0928dd-5d68-484c-bd19-aa7a18d27d66").update(title="Fluent Speech AI")

⸺ حذف رکوردها

همهٔ پروژه‌هایی که فیلد content آن‌ها خالی (NULL) باشد را به‌طور کامل از پایگاه داده حذف می‌کند.

Project.objects.filter(content__isnull=True).delete()

💡 حذف انبوه با یک دستور ساده.
⚠️ این عملیات غیرقابل بازگشت است و از سیگنال pre_delete/post_delete پشتیبانی می‌کند (برخلاف update).

یکی از مهم‌ترین توانایی‌های ORM جنگو، کار با داده‌های مرتبط بین مدل‌ها است. در پروژه‌های واقعی، داده‌ها معمولا به‌صورت مستقل ذخیره نمی‌شوند؛ مثلاً یک کاربر ممکن است یک پروفایل داشته باشد، یک نویسنده می‌تواند چند کتاب نوشته باشد، یا در یک پروژه چندین تکنولوژی استفاده شده باشد.

برای مدیریت و جستجو در این روابط، جنگو مجموعه‌ای از کوئری‌های مخصوص فیلدهای رابطه‌ای فراهم کرده است که امکان می‌دهد

• داده‌های مرتبط را خیلی راحت استخراج نمود.

• روی فیلدهای مدل‌های مرتبط فیلتر یا مرتب‌سازی انجام داد.

• داده‌های وابسته را با کمترین تعداد Query ممکن بازیابی کرد.

این بخش دقیقا روی این موضوع تمرکز خواهد داشت و در نهایت یاد می‌گیریم چگونه با استفاده از کوئری‌ها:

1. روابط یک به چند (One-to-Many) مثل نویسنده و کتاب

2. روابط چند به چند (Many-to-Many) مثل پروژه‌ها و تکنولوژی‌ها

3. روابط یک به یک (One-to-One) مثل کاربر و پروفایل

را مدیریت نمود. همچنین به نکات مهمی مثل استفاده از lookups و بهینه‌سازی Queryها با select_related و prefetch_related هم خواهیم پرداخت.

1. روابط در جنگو سه نوع اصلی دارند: ForeignKey، ManyToManyField، OneToOneField.

2. می‌توانیم با استفاده از __ به فیلدهای مدل‌های مرتبط دسترسی پیدا کنیم.

3. متدهای select_related و prefetch_related برای بهینه‌سازی Queryها ضروری هستند.

4. مدیریت داده‌های رابطه‌ای در جنگو بسیار ساده و مشابه نوشتن کوئری‌های SQL است، اما با قابلیت‌های سطح بالاتر و امن‌تر.