DjangoQL

A DjangoQLSchema defines what users are allowed to search. If no schema is provided, DjangoQL defaults to a recursive schema that includes all fields and relations. Use a schema to improve performance or security by limiting models and fields.

Schema Options

• exclude: A tuple of models to exclude from search.
• include: A tuple of models to include (limits search to these models only).
• suggest_options: A dictionary mapping models to specific fields for auto-completion suggestions. Note: If not using a choices field, this performs a synchronous query; avoid using this on large querysets.
• get_fields(self, model): A method to override which fields are available for a specific model.

class UserQLSchema(DjangoQLSchema):
    exclude = (Book,)
    suggest_options = {
        Group: ['name'],
    }

    def get_fields(self, model):
        if model == Group:
            return ['name']
        return super(UserQLSchema, self).get_fields(model)


@admin.register(User)
class CustomUserAdmin(DjangoQLSearchMixin, UserAdmin):
    djangoql_schema = UserQLSchema

The DjangoQL completion widget is not tied to the Django admin and can be used in any part of your application. You can use it in two ways:

1. As a standalone npm package: Install @djangoql/completion (or the relevant package name) via npm.
2. Via the Python package: If you are not using a JavaScript bundler, you can use the pre-built assets included in the djangoql PyPI package.

To use the pre-built assets, include the CSS and JS files from the djangoql/ static directory in your HTML template and initialize the DjangoQL object in a script block.

{% load static %}
<link rel="stylesheet" type="text/css" href="{% static 'djangoql/css/completion.css' %}" />
<script src="{% static 'djangoql/js/completion.js%}"></script>

<script>
  DjangoQL.DOMReady(function () {
    new DjangoQL({
      // JS object from DjangoQLSchema(MyModel).as_dict(), or a URL for async loading
      introspections: {{ introspections|safe }},
      // CSS selector for the textarea input
      selector: 'textarea[name=q]',
      // Optional: URL for Syntax Help link
      syntaxHelp: null,
      // Optional: enable automatic height adjustment for the textarea
      autoResize: true
    });
  });
</script>

You can use DjangoQL on any model by using DjangoQLQuerySet.as_manager() or by using the apply_search utility function.

Option 1: Using DjangoQLQuerySet.as_manager()

Attach the manager to your model to enable the .djangoql() method directly on the model's manager.

Option 2: Using apply_search()

Use apply_search(queryset, query_string, schema=...) to apply DjangoQL search to any existing Django queryset.

# Option 1: Manager approach
from django.db import models
from djangoql.queryset import DjangoQLQuerySet

class Book(models.Model):
    name = models.CharField(max_length=255)
    author = models.ForeignKey('auth.User')
    objects = DjangoQLQuerySet.as_manager()

# Usage:
qs = Book.objects.djangoql('name ~ "war" and author.last_name = "Tolstoy"')


# Option 2: apply_search approach
from django.contrib.auth.models import User
from djangoql.queryset import apply_search

qs = User.objects.all()
qs = apply_search(qs, 'groups = None')

To power the completion widget, you need a view that handles two tasks:

1. Schema Introspection: Serialize a DjangoQLSchema into JSON to provide the widget with field and model information.
2. Query Execution: Use apply_search to transform a raw query string into a filtered Django QuerySet.

Key Components:

• DjangoQLSchema: Define which models and fields are available for search. Use suggest_options to provide specific field suggestions for related models.
• DjangoQLSchemaSerializer().serialize(): Converts a schema instance into a dictionary suitable for JSON serialization.
• apply_search(queryset, query_string, schema=...): Applies the DjangoQL query string to a queryset using the provided schema.

import json
from djangoql.exceptions import DjangoQLError
from djangoql.queryset import apply_search
from djangoql.schema import DjangoQLSchema
from djangoql.serializers import DjangoQLSchemaSerializer

# 1. Define the schema
class UserQLSchema(DjangoQLSchema):
    include = (User, Group)
    suggest_options = {
        Group: ['name'],
    }

# 2. In your view...
@require_GET
def completion_demo(request):
    q = request.GET.get('q', '')
    query = User.objects.all()
    
    if q:
        try:
            # Apply the DjangoQL query string
            query = apply_search(query, q, schema=UserQLSchema)
        except DjangoQLError as e:
            query = query.none()
            error = str(e)

    # 3. Serialize the schema for the frontend
    introspections = DjangoQLSchemaSerializer().serialize(
      UserQLSchema(query.model),
    )
    
    return render_to_response('template.html', {
        'q': q,
        'search_results': query,
        'introspections': json.dumps(introspections),
    })

When .get_lookup_name() and .get_lookup_value() are insufficient, override the .get_lookup(self, path, operator, value) method. This allows you to return a custom Q object or complex queryset filter logic based on the operator and value provided.

class UserAgeField(IntField):
    """
    Search by given number of full years
    """
    model = User
    name = 'age'

    def get_lookup_name(self):
        """
        We'll be doing comparisons vs. this model field
        """
        return 'date_joined'

    def get_lookup(self, path, operator, value):
        """
        The lookup should support with all operators compatible with IntField
        """
        if operator == 'in':
            result = None
            for year in value:
                condition = self.get_lookup(path, '=', year)
                result = condition if result is None else result | condition
            return result
        elif operator == 'not in':
            result = None
            for year in value:
                condition = self.get_lookup(path, '!=', year)
                result = condition if result is None else result & condition
            return result

        value = self.get_lookup_value(value)
        search_field = '__'.join(path + [self.get_lookup_name()])
        year_start = self.years_ago(value + 1)
        year_end = self.years_ago(value)
        if operator == '=':
            return (
                Q(**{'%s__gt' % search_field: year_start}) &
                Q(**{'%s__lte' % search_field: year_end})
            )
        elif operator == '!=':
            return (
                Q(**{'%s__lte' % search_field: year_start}) |
                Q(**{'%s__gt' % search_field: year_end})
            )
        elif operator == '>':
            return Q(**{'%s__lt' % search_field: year_start})
        elif operator == '>=':
            return Q(**{'%s__lte' % search_field: year_end})
        elif operator == '<':
            return Q(**{'%s__gt' % search_field: year_end})
        elif operator == '<=':
            return Q(**{'%s__gte' % search_field: year_start})

    def years_ago(self, n):
        timestamp = now()
        try:
            return timestamp.replace(year=timestamp.year - n)
        except ValueError:
            # February 29
            return timestamp.replace(month=2, day=28, year=timestamp.year - n)


class UserQLSchema(DjangoQLSchema):
    def get_fields(self, model):
        fields = super(UserQLSchema, self).get_fields(model)
        if model == User:
            fields += [UserAgeField()]
        return fields


@admin.register(User)
class CustomUserAdmin(DjangoQLSearchMixin, UserAdmin):
    djangoql_schema = UserQLSchema