DjangoQL

Warnings

• breaking 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.
  Fix: Update `get_options(self, search)` methods in custom schema fields to filter results based on the `search` parameter.
• breaking 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.
  Fix: Set `djangoql_completion_enabled_by_default = False` in your `ModelAdmin` or globally in Django settings if supported (check documentation for global setting).
• deprecated As of version 0.14.0, `DjangoQLSchema.as_dict()` is deprecated. Users should switch to the new schema serializers provided in `djangoql.serializers`.
  Fix: Migrate code using `DjangoQLSchema.as_dict()` to utilize the serializers provided in `djangoql.serializers`.
• gotcha 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.
  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.
• gotcha DjangoQL queries are case-sensitive. This differs from some common database search behaviors and might lead to unexpected results if not accounted for.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Define a custom `DjangoQLSchema` using `exclude`, `include`, and `get_fields()` to precisely control which models and fields are searchable.

Install

• pip install djangoql Install stable version

Imports

• DjangoQLSearchMixin

  from djangoql.admin import DjangoQLSearchMixin

  For integrating DjangoQL search into Django admin models.
• DjangoQLQuerySet

  from djangoql.queryset import DjangoQLQuerySet

  For adding DjangoQL search functionality to any Django model's queryset outside the admin.
• apply_search

  from djangoql.queryset import apply_search

  For applying DjangoQL search to an existing queryset.
• DjangoQLSchema

  from djangoql.schema import DjangoQLSchema

  For defining custom DjangoQL schemas to control searchable models/fields and suggestion options.

Quickstart

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`