Django Related Models - magic behind the scenes

I was trying to find the answer in Django Documentation, but failed to do so.

Can anyone please explain how does Django "match" the objects of the related models?

eg. I have two models, and I am showing Django that they are related:

class Reporter(models.Model):
    # ...
    pass

class Article(models.Model):
    reporter = models.ForeignKey(Reporter, related_name='report')

Then the magic happens and Django matches the two models, and adds _id field.

My question is: How does Django know which objects of those two models are related? Is it checking each and every field of those objects and sees if there is a match?

EDIT: How does Django determine that a particular Reporter object is related to a particular Article object? I understand that when it finds a match it adds the _id field, what I do not understand is based on what django "matches" two objects from different models.

To be more specific:

Let's say that there are two Reporter objects - r1 and r2.
There is one object in Article class - a1

How does django know that a1 is related to r1 and not to r2?

Thanks for your help!

Solution

It looks like you're not really SQL-savy, because there's really no "magic" involved and it's all basic relational model design.

Your above models translates to the canonical one to many SQL schema:

CREATE TABLE yourappname_reporter (
    id int(11) NOT NULL AUTO_INCREMENT, 
    PRIMARY KEY(id)
    );

CREATE TABLE yourappname_article(  
   id int(11) NOT NULL AUTO_INCREMENT,
   reporter_id int(11) NOT NULL,
   PRIMARY KEY(id),
   CONSTRAINT `reporter_id_refs_id_XXXX` FOREIGN KEY (`reporter_id`) REFERENCES `yourappname_reporter` (`id`)
    );

As you can see, Django adds an 'id' primary key to your models (since you didn't explicitely defined one yourself), and the Article.reporter field translates to the reporter_id foreign key which references reporter.id. Here again Django uses the reporter.id primary key as foreign key reference as a (very sensible) default since you didn't explicitely told him to target another field.

Now when you create a new Article, you have to provide a Reporter instance, ie (assuming you have a reporter with id 1):

reporter = Reporter.objects.get(id=1)
article = Article.objects.create(reporter=reporter)

Then the ORM will issue the SQL query insert into yourappname_article (reporter_id) values (1), hence relating this new article row with this reporter row, and you can now get all articles from reporter 1 with select * from yourappname_article where reporter_id=1 (which is the query Django ORM will issue for Article.objects.filter(reporter_id=1))

To make a long story short: Django ORM is only a thin wrapper over your database, and you do have to know what a relational database is, how it works and how to properly use it (including how to properly design your db schema) if you expect to do anything good. If you don't even know what a foreign key is then by all means first learn about the relational model, proper relational design and basic SQL stuff.