Skip to content

API Reference

Default lookups by field type

Model fields Lookup operators
AutoField eq, ne, ge, gt, le, lt, in, out
BigAutoField ⁠
BigIntegerField ⁠
DateField ⁠
DateTimeField ⁠
DecimalField ⁠
FloatField ⁠
IntegerField ⁠
PositiveIntegerField ⁠
PositiveSmallIntegerField ⁠
SmallIntegerField ⁠
BooleanField eq, ne
NullBooleanField ⁠
CharField eq, ne, in,out, like,ilike
EmailField ⁠
SlugField ⁠
TextField ⁠
URLField ⁠
UUIDField ⁠

Constants

More details about the specifications for the constants py_rql.constants could be found in the library lib-rql.

py_rql.constants.FilterLookups

EQ = 'eq' class-attribute instance-attribute

Equal operator

GE = 'ge' class-attribute instance-attribute

Greater or equal operator

GT = 'gt' class-attribute instance-attribute

Greater than operator

IN = 'in' class-attribute instance-attribute

In operator

I_LIKE = 'ilike' class-attribute instance-attribute

Case-insensitive like operator

LE = 'le' class-attribute instance-attribute

Less or equal operator

LIKE = 'like' class-attribute instance-attribute

like operator

LT = 'lt' class-attribute instance-attribute

Less then operator

NE = 'ne' class-attribute instance-attribute

Not equal operator

NULL = 'null' class-attribute instance-attribute

null operator

OUT = 'out' class-attribute instance-attribute

Not in operator

boolean(with_null = True) classmethod

Returns the default lookups for boolean fields.

Args: with_null (bool): if true, includes the null lookup, defaults to True.

Returns:

Type Description
set

a set with the default lookups.

numeric(with_null: bool = True) -> set classmethod

Returns the default lookups for numeric fields.

Parameters:

Name Type Description Default
with_null bool

if true, includes the null lookup, defaults to True.

 True

Returns:

Type Description
set

a set with the default lookups.

string(with_null = True) classmethod

Returns the default lookups for string fields.

Parameters:

Name Type Description Default
with_null bool

if true, includes the null lookup, defaults to True.

 True

Returns:

Type Description
set

a set with the default lookups.

Exceptions

More details about the specifications for the exceptions py_rql.exceptions could be found in the library lib-rql.

RQLFilterError

Base class for RQL errors.

RQLFilterParsingError

Parsing errors are raised only at query parsing time.

RQLFilterLookupError

Lookup error is raised when provided lookup is not supported by the associated filter.

RQLFilterValueError

Value error is raised when provided values can't be converted to DB field types.

Filter classes

dj_rql.filter_cls.RQLFilterClass

Base class for filter classes.

build_q_for_custom_filter(data: FilterArgs) -> Q

Django Q() builder for custom filter.

Parameters:

Name Type Description Default
data FilterArgs

Prepared FilterArgs filter data for custom filtering.

 required

Returns:

Type Description
Q

A Django queryset django.db.models.Q instance.

Raises:

Type Description
RQLFilterParsingError

Filter logic is not implemented.

build_name_for_custom_ordering(filter_name: str) -> str

Builder for ordering name of custom filter.

Parameters:

Name Type Description Default
filter_name str

Full filter name string (f.e. ns1.ns2.filter1).

 required

Returns:

Type Description
str

A Django field str path.

Raises:

Type Description
RQLFilterParsingError

Ordering logic is not implemented.

apply_filters(query: str, request = None, view = None)

Main entrypoint for request filtering.

Parameters:

Name Type Description Default
query str

RQL query string.

 required
request Request

Request from API view.

 None
view View

API view.

 None

Returns:

Type Description

A Lark AST, Filtered QuerySet (could be None).

build_q_for_filter(data: FilterArgs) -> Q

Django Q() builder for extracted from query RQL expression. In general, this method should not be overridden.

Parameters:

Name Type Description Default
data FilterArgs

Prepared FilterArgs filter data for custom filtering.

 required

Returns:

Type Description
Q

A Q instance.

get_filter_base_item(filter_name: str)

dj_rql.filter_cls.AutoRQLFilterClass

Filter class that automatically collects filters for simple model fields.

EXCLUDE_FILTERS = () class-attribute instance-attribute

This class will collect all simple model fields except the ones in this field.

dj_rql.filter_cls.NestedAutoRQLFilterClass

Filter class that automatically collects filters for all model fields with specified depth for related models.

DEPTH = 1 class-attribute instance-attribute

Specifies how deep model relations will be traversed. If DEPTH = 0 this class behaves as AutoRQLFilterClass. (default 1).

SELECT = True class-attribute instance-attribute

If True, this FilterClass supports the select operator (default True).

DB optimization

The following DB optimizations could be done found on dj_rql.filter_cls.

Annotation

Apply an annotate optimization to the queryset.

apply(queryset: QuerySet) -> QuerySet

Apply an annotate operation for the given queryset.

Parameters:

Name Type Description Default
queryset QuerySet

queryset instance to optimize.

 required

Returns:

Name Type Description
QuerySet QuerySet

queryset optimized.

SelectRelated

Apply a select_related optimization to the queryset.

apply(queryset: QuerySet) -> QuerySet

Apply a select related operation for the given queryset.

Parameters:

Name Type Description Default
queryset QuerySet

queryset instance to optimize.

 required

Returns:

Name Type Description
QuerySet QuerySet

queryset optimized.

PrefetchRelated

Apply a prefetch_related optimization to the queryset.

apply(queryset: QuerySet) -> QuerySet

Apply a prefetch related operation for the given queryset.

Parameters:

Name Type Description Default
queryset QuerySet

queryset instance to optimize.

 required

Returns:

Name Type Description
QuerySet QuerySet

queryset optimized.

NestedPrefetchRelated

Apply a prefetch_related optimization to a nested attribute of the queryset.

NestedSelectRelated

Apply a select_related optimization to a nested attribute of the queryset.

Chain

Apply a chain of optimizations to the queryset.

apply(queryset)

Django Rest Framework extensions

Filter backend dj_rql.drf.backend.RQLFilterBackend

RQL filter backend for DRF GenericAPIViews.

Set the backend filter for the GenericAPIView class-based view, and set the rql_filter_class class attribute to the RQLFilterClass to use:

    class ViewSet(mixins.ListModelMixin, GenericViewSet):
        filter_backends = (RQLFilterBackend,)
        rql_filter_class = ModelFilterClass

Yo can also add a get_rql_filter_class() method to the view to get the filter class:

    class ViewSet(mixins.ListModelMixin, mixins.RetrieveModelMixin, GenericViewSet):
        filter_backends = (RQLFilterBackend,)

        def get_rql_filter_class(self):
            if self.action == 'retrieve':
                return ModelDetailFilterClass
            return ModelFilterClass

filter_queryset(request, queryset, view)

Return a filtered queryset.

Pagination

The following pagination classes found on dj_rql.drf.paginations:

RQLLimitOffsetPagination

RQL limit offset pagination.

RQLContentRangeLimitOffsetPagination

RQL RFC2616 limit offset pagination.

Examples:

Response

200 OK
Content-Range: items <FIRST>-<LAST>/<TOTAL>

Serialization

dj_rql.drf.serializers.RQLMixin

OpenAPI

The following OpenAPI classes found on dj_rql.openapi:

RQLFilterClassSpecification

get(filter_instance) classmethod

Returns OpenAPI specification for filters. Filter sorting is alphabetic with deprecated filters in the end.

Parameters:

Name Type Description Default
filter_instance RQLFilterClass

Instance of RQLFilterClass Class.

 required

Returns:

Type Description

An OpenAPI compatible specification of Filter Class Filters list or dict.

get_for_field(filter_item: dict, filter_instance) classmethod

This method can be overridden to support custom specs for certain filters.

Parameters:

Name Type Description Default
filter_item dict

Extended Filter Item dict.

 required
filter_instance RQLFilterClass

Instance of RQLFilterClass Class.

 required

RQLFilterClassSpecification

render(filter_item: dict, filter_instance) classmethod

Render for the given item and instance.

Parameters:

Name Type Description Default
filter_item dict)

Extended Filter item dict.

 required
filter_instance RQLFilterClass)

Instance of RQLFilterClass Class.

 required

Returns:

Type Description

Rendered description string for filter item.

Testing

dj_rql.utils.assert_filter_cls

Helper function for testing of custom view rql filter classes.

Parameters:

Name Type Description Default
filter_cls cls

Custom RQL Filter.

 required
filters dict

filter_cls.filters

 required
ordering_filters set

filter_cls.ordering_filters

 required
search_filters set

filter_cls.search_filters

 required