Error when performing a join in SQLAlchemy 'Please specify the 'onclause' of this join explicitly.'

I have the following sqlalchemy model using flask-sqlalchemy. I have 3 talentpref items in my schedule model. There will always need to be 3 and no fewer.

class TalentPref(db.Model):
    __tablename__ = 'talentpref'
    id = db.Column(db.Integer, primary_key=True)
    firstName = db.Column(db.String(80), unique=True)
    lastName = db.Column(db.String(80), unique=True)

    def __init__(self, firstName, lastName):
        self.firstName = firstName
        self.lastName = lastName

    def __repr__(self):
        return '<talentpref %r %r>' % (self.firstName, self.lastName)

class Schedule(db.Model):
    __tablename__ = 'schedule'

    id = db.Column(db.Integer, primary_key=True)

    talentpref1_id = db.Column(db.Integer, db.ForeignKey('talentpref.id'))
    talentpref2_id = db.Column(db.Integer, db.ForeignKey('talentpref.id'))
    talentpref3_id = db.Column(db.Integer, db.ForeignKey('talentpref.id'))

    talentpref1 = db.relationship("TalentPref", uselist=False, foreign_keys=talentpref1_id)
    talentpref2 = db.relationship("TalentPref", uselist=False, foreign_keys=talentpref2_id)
    talentpref3 = db.relationship("TalentPref", uselist=False, foreign_keys=talentpref3_id)

I am using flask-restless to serve the schedule model as an api resource. When I perform a query on schedule and ask to sort my query by talentpref1__lastName, I receive an error which is related to my having multiple instances that refer to the "TalentPref" table:

I can use a query string successfully on the id column, like so:

/api/schedule?id=id&page=1&q={"order_by":[{"field":"id","direction":"desc"}]}

But a query using the following http GET query string fails:

/api/schedule?id=id&page=1&q={"order_by":[{"field":"talentpref1__lastName","direction":"desc"}]}

with:

Traceback (most recent call last):
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/flask_restless/views.py", line 1172, in _search
    result = search(self.session, self.model, search_params)
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/flask_restless/search.py", line 587, in search
    query = create_query(session, model, search_params, _ignore_order_by)   
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/flask_restless/search.py", line 549, in create_query
    _ignore_order_by)
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/flask_restless/search.py", line 498, in create_query
    query = query.join(relation_model)
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/sqlalchemy/orm/query.py", line 1971, in join
    from_joinpoint=from_joinpoint)
  File "<string>", line 2, in _join
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/sqlalchemy/orm/base.py", line 201, in generate
    fn(self, *args[1:], **kw)
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/sqlalchemy/orm/query.py", line 2115, in _join
    outerjoin, full, create_aliases, prop)
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/sqlalchemy/orm/query.py", line 2188, in _join_left_to_right
    self._join_to_left(l_info, left, right, onclause, outerjoin, full)   
  File "/Users/myuser/Documents/pythonenvironments/venv/lib/python2.7/site-packages/sqlalchemy/orm/query.py", line 2317, in _join_to_left
    "Tried joining to %s, but got: %s" % (right, ae))

InvalidRequestError: Could not find a FROM clause to join from.  Tried
joining to <class 'app.model.TalentPref'>, but got: Can't determine
join between 'schedule' and 'talentpref'; tables have more than one
foreign key constraint relationship between them. Please specify the
'onclause' of this join explicitly.

Is there a way I can query this relationship successfully?

This seems to be a limitation of flask-restless itself. When passed a <fieldname> of the form <relationname>__<fieldname> it will split the name and use the 1st part as the relationship. It uses the relationship attribute to find the related model class to join to:

if '__' in field_name:
    field_name, field_name_in_relation = \
        field_name.split('__')
    relation = getattr(model, field_name)
    relation_model = relation.mapper.class_
    field = getattr(relation_model, field_name_in_relation)
    direction = getattr(field, val.direction)
    query = query.join(relation_model)
    #                  ^^^^^^^^^^^^^^ TalentPref model class
    query = query.order_by(direction())

https://github.com/jfinkels/flask-restless/blob/0.17.0/flask_restless/search.py#L498

In your case this is effectively

query = query.join(TalentPref)

and since you have multiple join paths, SQLAlchemy is unable to determine what to do. This would not be an issue, if flask-restless were to either use a simple relationship join instead of joining a target entity, or adapt the relationship() -driven ON clause to the target entity.

You could patch your flask-restless to fix this particular query:

--- search.py   2017-03-29 09:56:00.439981932 +0300
+++ search_joinfix.py   2017-03-29 09:56:41.375851375 +0300
@@ -495,7 +495,7 @@
                         relation_model = relation.mapper.class_
                         field = getattr(relation_model, field_name_in_relation)
                         direction = getattr(field, val.direction)
-                        query = query.join(relation_model)
+                        query = query.join(relation)
                         query = query.order_by(direction())
                     else:
                         field = getattr(model, val.field)