Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Django Query by Example (QBE)

synopsis:Admin tool in order to get custom reports.

The objective of django-qbe is provide a assited and interactive way of making complex queries with no technical knowledge (or minimal) to get custom reports from the objects of Django models.

Based on QBE proposal from IBM®, django-qbe is intended to remove the limitations of Django QuerySets objects and to use the whole expresive power of the subjacent SQL.


Using the Python Package Index (PyPI) and easy_install script:

$ easy_install django_qbe

Or through pip:

$ pip install django_qbe

But you also can download the django_qbe directory using git:

$ git clone git://
$ cp -r qbe/django_qbe /path/to/your/project

Adding to the project settings:

    # [...] django builtins applications
    # [...] Any other application

Add the context processor django.core.context_processors.static:

    'BACKEND': 'django.template.backends.django.DjangoTemplates',
    'DIRS': [],
    'APP_DIRS': True,
    'OPTIONS': {
        'context_processors': [
                # [...] django context processors
                # [...] Any other context processors

See the Django documentation on static files for details.

And adding the urlconf in your project

# qbe
url(r'^qbe/', include('django_qbe.urls')),

That's all. Then you can access to http://host:port/qbe However, you can add a link from your admin page changing the admin index template fo your AdminSite:

class AdminSite(admin.AdminSite):
    index_template = "qbe_index.html"

Or adding in your custom admin index template the next javascript:

<script type="text/javascript" src="{% url qbe_js %}"></script>

Saved queries

If you optionally want to store queries in your database, feel free to install the also included app django_qbe.savedqueries:

    # [...] django builtins applications
    # [...] Any other application

Then run the syncdb or optionally South's migrate management command to create the savedqueries_saved_query table.

After that there will be a new option to save a query in a model instance and an admin interface to browse the saved queries, or direclty from the command line using the command qbe_export:

$ python help qbe_export
$ python qbe_export <query_hash>
$ python qbe_export <query_hash> --output test.csv
$ python qbe_export <query_hash> --output test.xls --format xls
$ python qbe_export <query_hash> --output test.xls --format xls --db-alias default


The next lines show de available settings and its default values.

Admin module name to add admin urls in results:

QBE_ADMIN = "admin"

Set your own admin site if it's different to usual

QBE_ADMIN_SITE ="admin.admin_site"

Function to control to users with access to QBE:

QBE_ACCESS_FOR = lambda user: user.is_staff

Some options for the query builder form:

QBE_ALIASES = False  # It allows to add an alias to a model field
QBE_GROUP_BY = False  # It allows to group by in a query
QBE_SHOW_ROW_NUMBER = True  # It disables number rows in results

Path to QBE formats export file, in order to add custom export formats:

QBE_FORMATS_EXPORT = "qbe_formats"

Path to custom QBE operators for the criteria:

QBE_CUSTOM_OPERATORS = "qbe_operators"

Custom Operators

Use Custom Operators only if you know what you are doing and at your own risks!

If you need to define custom operators, in a file in your project root, you need to create a new class that extends django_qbe.operators.CustomOperator:

import datetime
from django.utils import timezone
from django_qbe.operators import CustomOperator

class SinceDaysAgo(CustomOperator):
    slug = 'since-days-ago'  # REQUIRED and must be unique
    label = 'Since Days Ago'  # REQUIRED

    def get_params(self):
        if len(self.params):
            return self.params

        now =
        today = now.replace(hour=0, minute=0, second=0, microsecond=0)
        tomorrow = today + datetime.timedelta(days=1)

        date_since = today - datetime.timedelta(days=int(self.value))

        operator = "gt"
        lookup_since = self._get_lookup(operator, str(date_since))
        lookup_until = self._get_lookup(operator, str(tomorrow))


        return self.params

    def get_wheres(self):
        if len(self.wheres):
            return self.wheres

        lookup_cast = self._db_operations.lookup_cast
        for operator in ["gte", "lt"]:
            db_operator = self._db_operators[operator]
            self.wheres.append(u"%s %s" % (
                lookup_cast(operator) % self.db_field,

        return self.wheres

Your custom operator must have 2 attributes, slug and label in order to be displayed in the Criteria dropdown.

The get_params and get_wheres methods must return an iterable instance (eg. list), otherwise it gets converted to a list.

If you dont want to write it in your make sure that it is imported in one of the files that are evaluated at runtime (eg. or in order to register your Custom Operator.