Skip to main content

A RQL-enabled filter backend for django-rest-framework

Project description

# django-rql-filter

[![Build Status](https://travis-ci.org/njoyard/django-rql-filter.svg?branch=master)](https://travis-ci.org/njoyard/django-rql-filter)

This app implements a RQL/RSQL/FIQL filter backend for
[django-rest-framework](http://www.django-rest-framework.org) and enables
passing arbitrary conditional expressions to filter

## Installation

```sh
pip install django-rql-filter
```

## Usage

Add `rql_filter` to your project `INSTALLED_APPS`.

Add the `RQLFilterBackend` to your viewset `filter_backends`:

```python
from rql_filter.backend import RQLFilterBackend

class ThingyViewSet(viewsets.ReadOnlyModelViewSet):
filter_backends = (
...
RQLFilterBackend,
...
)
```

You may now pass a RQL/RSQL/FIQL query to API URLs using the `q` querystring
parameter:

```sh
curl http://my.app/api/thingies/?format=json&q=name==bob;age=gt=30
```

## Query syntax

A query is made using a combination of field comparisons. Comparisons are
composed by a field name, an operator and a value.

| Operator | Meaning | Examples |
|:--------:|--------------------------|------------------------|
| == | Equal to | `name==bob` |
| != | Not equal to | `name!=bob` |
| < =lt= | Less than | `age<30` `age=lt=30` |
| <= =le= | Less than or equal to | `age<=30` `age=le=30` |
| > =gt= | Greater than | `age<30` `age=lt=30` |
| >= =ge= | Greater than or equal to | `age<=30` `age=le=30` |
| =in= | Belongs to set | `name=in=(bob,kate)` |
| =out= | Does not belong to set | `name=out=(bob,kate)` |

Values must be quoted with single or double quotes when they include special
characters or spaces: `name="bob katz"`.

Comparisons may be combined using `;` for a logical AND, and `,` for a logical
OR: `name="bob";age>=30`. AND has priority over OR; grouping is available using
parentheses: `name="bob";(age>=30,age<3)`.

**Note:** RQL/RSQL/FIQL support is still incomplete, it will be enhanced over
time.

## Configuration

`RQL_FILTER_QUERY_PARAM` sets the querystring parameter name to use; it defaults
to `'q'`.

## Using without rest-framework

You may use the backend manually outside a rest-framework viewset:

```python
from rql_filter.backend import RQLFilterBackend

# May be reused any number of times
backend = RQLFilterBackend()

# Fake request object
class FakeRQLRequest:
def __init__(self, q):
self.GET = {'q': q}

qs = Thingy.objects.all()
filtered_qs = backend.filter_queryset(
FakeRQLRequest('name==bob;age=gt=30'),
qs,
None
)
```

## Testing

Install testing dependencies:

```sh
pip install -e .[testing]
```

Run tests:

```sh
py.test
```

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for django-rql-filter, version 0.1.0
Filename, size File type Python version Upload date Hashes
Filename, size django-rql-filter-0.1.0.tar.gz (2.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page