{"id":6603,"library":"djangoql","title":"DjangoQL","description":"DjangoQL is an advanced search language for Django, providing auto-completion and supporting logical operators, parentheses, table joins, and working with any Django model. The current version is 0.19.1, and it is actively maintained with regular updates. It's tested against a wide range of Python (2.7, 3.6–3.14) and Django (1.8–6.0) versions.","status":"active","version":"0.19.1","language":"en","source_language":"en","source_url":"https://github.com/ivelum/djangoql/","tags":["Django","search","ORM","admin","query language","auto-completion"],"install":[{"cmd":"pip install djangoql","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"For integrating DjangoQL search into Django admin models.","symbol":"DjangoQLSearchMixin","correct":"from djangoql.admin import DjangoQLSearchMixin"},{"note":"For adding DjangoQL search functionality to any Django model's queryset outside the admin.","symbol":"DjangoQLQuerySet","correct":"from djangoql.queryset import DjangoQLQuerySet"},{"note":"For applying DjangoQL search to an existing queryset.","symbol":"apply_search","correct":"from djangoql.queryset import apply_search"},{"note":"For defining custom DjangoQL schemas to control searchable models/fields and suggestion options.","symbol":"DjangoQLSchema","correct":"from djangoql.schema import DjangoQLSchema"}],"quickstart":{"code":"import os\nimport django\nfrom django.conf import settings\nfrom django.db import models\nfrom django.contrib import admin\n\n# Minimal Django setup (usually done in settings.py)\nif not settings.configured:\n    settings.configure(\n        INSTALLED_APPS=[\n            'django.contrib.admin',\n            'django.contrib.auth',\n            'django.contrib.contenttypes',\n            'django.contrib.sessions',\n            'django.contrib.messages',\n            'django.contrib.staticfiles',\n            'djangoql', # Add djangoql to installed apps\n            'myapp' # A dummy app for models\n        ],\n        DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},\n        ROOT_URLCONF=__name__,\n        SECRET_KEY='super-secret',\n        TEMPLATES=[\n            {\n                'BACKEND': 'django.template.backends.django.DjangoTemplates',\n                'APP_DIRS': True,\n                'OPTIONS': {\n                    'context_processors': [\n                        'django.template.context_processors.debug',\n                        'django.template.context_processors.request',\n                        'django.contrib.auth.context_processors.auth',\n                        'django.contrib.messages.context_processors.messages',\n                    ],\n                },\n            },\n        ],\n        STATIC_URL='/static/',\n    )\n    django.setup()\n\n\n# myapp/models.py\nclass Book(models.Model):\n    title = models.CharField(max_length=255)\n    author = models.CharField(max_length=100)\n    published_year = models.IntegerField(default=2000)\n    in_stock = models.BooleanField(default=True)\n\n    def __str__(self):\n        return self.title\n\n# myapp/admin.py\nfrom djangoql.admin import DjangoQLSearchMixin\n\nclass BookAdmin(DjangoQLSearchMixin, admin.ModelAdmin):\n    list_display = ('title', 'author', 'published_year', 'in_stock')\n    search_fields = ('title', 'author') # Optional: enables standard Django search alongside DjangoQL\n\nadmin.site.register(Book, BookAdmin)\n\n# Example of using DjangoQLQuerySet outside admin\nfrom djangoql.queryset import DjangoQLQuerySet\n\nclass BookQuerySet(DjangoQLQuerySet):\n    pass\n\nBook.add_to_class('objects', BookQuerySet.as_manager())\n\n# To demonstrate, run `python manage.py createsuperuser` and then `python manage.py runserver`\n# Navigate to /admin/myapp/book/ to see DjangoQL in action.\n# Example query in DjangoQL search bar: `author = \"Tolkien\" and published_year > 1950`","lang":"python","description":"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."},"warnings":[{"fix":"Update `get_options(self, search)` methods in custom schema fields to filter results based on the `search` parameter.","message":"In 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.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Set `djangoql_completion_enabled_by_default = False` in your `ModelAdmin` or globally in Django settings if supported (check documentation for global setting).","message":"Starting 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.","severity":"breaking","affected_versions":">=0.14.0"},{"fix":"Migrate code using `DjangoQLSchema.as_dict()` to utilize the serializers provided in `djangoql.serializers`.","message":"As of version 0.14.0, `DjangoQLSchema.as_dict()` is deprecated. Users should switch to the new schema serializers provided in `djangoql.serializers`.","severity":"deprecated","affected_versions":">=0.14.0"},{"fix":"For 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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 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.","message":"DjangoQL queries are case-sensitive. This differs from some common database search behaviors and might lead to unexpected results if not accounted for.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When upgrading from very old versions, be aware of string literal parsing changes. Standardize on one quote style or inform users of the updated flexibility.","message":"Older 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.","severity":"gotcha","affected_versions":"<0.19.0 (only double quotes), >=0.19.0 (both single and double quotes)"},{"fix":"Define a custom `DjangoQLSchema` using `exclude`, `include`, and `get_fields()` to precisely control which models and fields are searchable.","message":"If 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}