mlavin / django-qjoin

Declarative Joins for the Django ORM

django-qjoin

Welcome to the documentation for django-qjoin!

Django-qjoin is an experimental package that provides a way of adding arbitrary joins to a query using expressions. This is very much a work in progress and isn't currently working on the latest Django versions.

Examples

Given the models:

class Person(models.Model):
    """Simple Person model."""

    FEMALE = 'F'
    MALE = 'M'

    SEX_CHOICES = (
        (FEMALE, 'Female'),
        (MALE, 'Male'),
    )

    name = models.CharField(max_length=255)
    age = models.PositiveSmallIntegerField(default=0)
    sex = models.CharField(max_length=1, choices=SEX_CHOICES)


class Email(models.Model):
    """A Person may have one or more emails. Emails are not necessarily tied to people."""
    email = models.EmailField()
    person = models.ForeignKey(Person, null=True)
    primary = models.BooleanField(default=False)


class Bounce(models.Model):
    """Simple model to track an email bounce."""
    email = models.EmailField()
    bounced = models.DateTimeField(auto_now_add=True)

A simple join:

PersonAddress.objects.filter(QJoin(person=JoinExpression(Person)))

Any join can be converted in to a left outer join:

PersonAddress.objects.filter(QJoin(person=JoinExpression(Person, outer=True)))

Joining on a non related field:

join = QJoin(email=JoinExpression(
    Email.objects.filter(primary=True, email='[email protected]'),
    'email')
)
bounces = Bounce.objects.filter(bounced__gt='2014-01-01').filter(join)

Running the Tests

You can run the tests with via:

python setup.py test

or:

python runtests.py

django-qjoin's Issues

Tests Failing on 1.5.X

join_field argument doesn't exist for query.join. This might not be solvable.

Tests Failing on 1.7.X

One is a white space issue and the other is the ordering of the table joins.

Non-FK Join

It should be possible to create a join between two on columns which don't have an existing FK.

Functional Tests

I expect the SQL tests will be too fragile particularly across Django versions. I created QJoinTestCase to hold functional tests for the queries but haven't written any yet.

Documentation

Need documentation with examples of how to use.

Outer Join

It should be possible to change a join to an outer join.

Does not work on Django 1.11

>>> from qjoin.models import QJoin, JoinExpression
ImportError: cannot import name 'ExpressionNode'

Looks like Django 1.11 changed ExpressionNode location (if still exists)
from django.db.models.expressions import ExpressionNode