Flask-SQLAlchemy backref function and backref parameter

Question

In Flask-SQLAlchemy, the backref parameter in relationship method allows you to declare a new property under a specified class as seen in the example in their docs:

class Person(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))
    addresses = db.relationship('Address', backref='person', lazy='dynamic')

class Address(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    email = db.Column(db.String(50))
    person_id = db.Column(db.Integer, db.ForeignKey('person.id'))

But then there is also a backref function:

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))
    addresses = db.relationship('Address',
                                backref=db.backref('person', lazy='joined'), 
                                lazy='dynamic')

In this case, what's the role of the backref function passed to the backref parameter, especially with the multiple lazy definitions? How is it different from backref='person'?

Solution

From the documentation for Flask models:

backref is a simple way to also declare a new property on the Address class. You can then also use my_address.person to get to the person at that address. lazy defines when SQLAlchemy will load the data from the database:

select (which is the default) means that SQLAlchemy will load the data as necessary in one go using a standard select statement.

joined tells SQLAlchemy to load the relationship in the same query as the parent using a JOIN statement.

subquery works like 'joined' but instead, SQLAlchemy will use a subquery.

dynamic is special and useful if you have many items. Instead of loading the items SQLAlchemy will return another query object which you can further refine before loading the items. This is usually what you want if you expect more than a handful of items for this relationship.

Comments

[Ilja Everilä]

Using the backref object you can change the behaviour/configuration of the back reference relationship. In your case Address.person has joined loading configured. When you pass just a string, you get the defaults.

[Ilja Everilä]

Using backref just automates the creation of a relationship property at the other end. backref='person' is somewhat akin to having person = db.relationship('Person') explicitly in the Address class (+ back population). Using the backref() object you can pass arguments to that relationship.

[kentwait]

Yes I understand this part. My question is what is the role of the backref function passed to the backref parameter. How is it different from db.relationship('Address', backref='person', lazy='dynamic')

[Ricky Han]

It's not possible to cascade any further inside a function call. I guess they created this function to encapsulate the scoping issue and for redundancy.