Documentation Note for defer might need an example.

[no]

The paragraph in the note section of the defer documentation is not immediately obvious to what it's implying. My understanding is that it's suggesting that one can use two django models to load data from a single database table, is that the only implication, or is there another?

I think adding an example would help to clarify what exactly is meant by the paragraph.

This is what I think it means:

class MyCommonlyUsedModel(models.Model):
    class Meta:
        managed = False
        db_table = 'app_largetable'
    f1 = models.Field(...)
    f2 = models.Field(...)

class MyUsuallyDeferredFieldsModel(models.Model):
    class Meta:
        managed = False
        db_table = 'app_largetable'
    deferred_f3 = models.Field(...)
    deferred_f4 = models.Field(...)

# A model that allows the migrations framework to also manage the table
# Not sure if this actually works, but would allow for a more DRY approach
class MyManagedModel(MyCommonlyUsedModel, MyUsuallyDeferredFieldsModel):
    class Meta:
        managed = True
        tb_table = 'app_largetable'

If the above example is acceptable as an example - and is actually what the note is about - I don't mind creating a PR.

[Tim Graham]

Yes, an example wouldn't hurt. There wasn't much additional context in the commit where that text was added 70e59aeaf85161ed26044c000a43af46719265ad.

Did you test your example? I am not sure field inheritance will work properly with suggested approach, but maybe so. To make the example simpler, there probably isn't a need for MyUsuallyDeferredFieldsModel (just put those fields on MyManagedModel).

[andrei kulakov]

In this paragraph:

only use defer() when you cannot, at queryset load time, determine if you will need the extra fields or not.

Shouldn't it be, instead, ".. when you cannot, before the queryset load time, determine if you will need the extra fields or not." ?

[Tim Graham]

Maybe, actually I am not quite sure what the intention of the wording is there.

[andrei kulakov]

I haven't used defer() myself before, but from reading the section, the idea seems to be that: if you can determine what fields need to be left out before queryset load time, use some other solution; if you can NOT do that, that's the only case where you'd use defer() because that's your only option.

[Tim Graham]

What does "queryset load time" mean? When the queryset is evaluated and the database query occurs, or something else?

[no]

Created a pull request with a minimal example.

​https://github.com/django/django/pull/4539

[andrei kulakov]

Replying to timgraham:

What does "queryset load time" mean? When the queryset is evaluated and the database query occurs, or something else?

I think it means when .only() or .defer() method is executed; -- there's two time points of interest: module load time, when you can define a module with a subset of fields, and queryset object creation time (or modification of existing queryset), when you provide the list of fields to defer. These are the only two times when you could provide this list of fields, so if you know the list at the module load time, it's preferred to define it as a model with a subset of fields, but if you don't know at module load time, then you don't have this option and you only have defer() and only() left to use.

[Tim Graham <timograham@…>]

In dd99f577:

Fixed #24613 -- Added example to QuerySet.defer() documentation

[Tim Graham <timograham@…>]

In bcd7f39:

[1.7.x] Fixed #24613 -- Added example to QuerySet.defer() documentation

Backport of dd99f57710bb4930561a6c049f54719af80850ec from master

[Tim Graham <timograham@…>]

In fe533fc5:

[1.8.x] Fixed #24613 -- Added example to QuerySet.defer() documentation

Backport of dd99f57710bb4930561a6c049f54719af80850ec from master