Install & Compatibility
Where this runs
tested against v0.19.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18.7MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DjangoQLSearchMixin
✓ from djangoql.admin import DjangoQLSearchMixin
✗ from djangoql.admin import DjangoQLSearchMixin
To integrate DjangoQL into your Django project, first add 'djangoql' to your `INSTALLED_APPS`. For Django Admin integration, inherit `DjangoQLSearchMixin` in your `ModelAdmin` class. This replaces or augments the default Django search functionality. You can also use `DjangoQLQuerySet` or `apply_search` for programmatic querying outside the admin.
import os
import django
from django.conf import settings
from django.db import models
from django.contrib import admin
# Minimal Django setup (usually done in settings.py)
if not settings.configured:
settings.configure(
INSTALLED_APPS=[
'django.contrib.admin',
'django.contrib.auth',
'django.contrib.contenttypes',
'django.contrib.sessions',
'django.contrib.messages',
'django.contrib.staticfiles',
'djangoql', # Add djangoql to installed apps
'myapp' # A dummy app for models
],
DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},
ROOT_URLCONF=__name__,
SECRET_KEY='super-secret',
TEMPLATES=[
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
],
STATIC_URL='/static/',
)
django.setup()
# myapp/models.py
class Book(models.Model):
title = models.CharField(max_length=255)
author = models.CharField(max_length=100)
published_year = models.IntegerField(default=2000)
in_stock = models.BooleanField(default=True)
def __str__(self):
return self.title
# myapp/admin.py
from djangoql.admin import DjangoQLSearchMixin
class BookAdmin(DjangoQLSearchMixin, admin.ModelAdmin):
list_display = ('title', 'author', 'published_year', 'in_stock')
search_fields = ('title', 'author') # Optional: enables standard Django search alongside DjangoQL
admin.site.register(Book, BookAdmin)
# Example of using DjangoQLQuerySet outside admin
from djangoql.queryset import DjangoQLQuerySet
class BookQuerySet(DjangoQLQuerySet):
pass
Book.add_to_class('objects', BookQuerySet.as_manager())
# To demonstrate, run `python manage.py createsuperuser` and then `python manage.py runserver`
# Navigate to /admin/myapp/book/ to see DjangoQL in action.
# Example query in DjangoQL search bar: `author = "Tolkien" and published_year > 1950`
Debug
Known issues
breakingIn version 0.14.0, the signature of `DjangoQLField.get_options()` changed to accept a mandatory `search` parameter. If you implemented custom suggestion options for your schema, you must update the method to handle this parameter and return results matching the search criteria.fixUpdate `get_options(self, search)` methods in custom schema fields to filter results based on the `search` parameter.
affects: >=0.14.0
breakingStarting from version 0.14.0, the DjangoQL checkbox in the admin, which enables the advanced search, is on by default. If this is not desired, the behavior can be turned off.fixSet `djangoql_completion_enabled_by_default = False` in your `ModelAdmin` or globally in Django settings if supported (check documentation for global setting).
affects: >=0.14.0
deprecatedAs of version 0.14.0, `DjangoQLSchema.as_dict()` is deprecated. Users should switch to the new schema serializers provided in `djangoql.serializers`.fixMigrate code using `DjangoQLSchema.as_dict()` to utilize the serializers provided in `djangoql.serializers`.
affects: >=0.14.0
gotchaWhen defining custom `DjangoQLSchema` with `suggest_options`, if a model field does not have `choices` specified, DjangoQL will synchronously pull *all* distinct values for that field. This can lead to significant performance issues and memory consumption with large querysets.fixFor large fields, define custom `get_options()` methods for `DjangoQLField` subclasses that implement asynchronous loading or more efficient filtering, or ensure fields have `choices` defined where appropriate.
affects: All versions
gotchaDjangoQL queries are case-sensitive. This differs from some common database search behaviors and might lead to unexpected results if not accounted for.fixEnsure users are aware of case-sensitivity. If case-insensitive search is required, you might need to implement custom search fields or modify the schema to apply `__icontains` lookups implicitly.
affects: All versions
gotchaOlder versions of DjangoQL (e.g., prior to 0.19.0, specifically around 0.3.1, 0.17.0, 0.17.1 based on search results) strictly required string values to be enclosed in double quotes. Newer versions now support both single and double quotes. This inconsistency could be a migration challenge or cause confusion for users familiar with older syntax.fixWhen upgrading from very old versions, be aware of string literal parsing changes. Standardize on one quote style or inform users of the updated flexibility.
affects: <0.19.0 (only double quotes), >=0.19.0 (both single and double quotes)
gotchaIf no custom `DjangoQLSchema` is specified, DjangoQL will generate a default schema by recursively walking through all model fields and relations. While convenient, this can expose more data than intended for security reasons or lead to inefficient queries on large, complex models.fixDefine a custom `DjangoQLSchema` using `exclude`, `include`, and `get_fields()` to precisely control which models and fields are searchable.
affects: All versions
Upgrade
Version history
0.19.1latest on PyPI · released Jan 27, 2026
Audit
Dependencies
No dependency data recorded yet.