{"id":21581442,"url":"https://github.com/dlr-eoc/rest_framework_filterdsl","last_synced_at":"2025-04-10T18:53:20.916Z","repository":{"id":28332359,"uuid":"106530124","full_name":"dlr-eoc/rest_framework_filterdsl","owner":"dlr-eoc","description":"A filtering and sorting DSL for the Django REST framework","archived":false,"fork":false,"pushed_at":"2022-06-20T09:21:48.000Z","size":82,"stargazers_count":22,"open_issues_count":1,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-24T16:41:16.839Z","etag":null,"topics":["api","django","django-rest-framework","dsl","filtering","sorting"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dlr-eoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-10-11T08:57:06.000Z","updated_at":"2021-06-02T07:45:44.000Z","dependencies_parsed_at":"2022-09-04T09:00:23.819Z","dependency_job_id":null,"html_url":"https://github.com/dlr-eoc/rest_framework_filterdsl","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Frest_framework_filterdsl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Frest_framework_filterdsl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Frest_framework_filterdsl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlr-eoc%2Frest_framework_filterdsl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dlr-eoc","download_url":"https://codeload.github.com/dlr-eoc/rest_framework_filterdsl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248275230,"owners_count":21076552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","django","django-rest-framework","dsl","filtering","sorting"],"created_at":"2024-11-24T14:12:31.871Z","updated_at":"2025-04-10T18:53:20.888Z","avatar_url":"https://github.com/dlr-eoc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# A filtering and sorting DSL for the [Django REST framework](http://www.django-rest-framework.org/)\n\nThis package provides a small [domain-specific language](https://en.wikipedia.org/wiki/Domain-specific_language)\n(DSL) for filtering and sorting the views provided using Django\nREST framework by GET parameters.\n\nThe filtering and sorting is performed by Django's querysets, so the\n[SQL injection\nprotection](https://docs.djangoproject.com/en/1.11/topics/security/#sql-injection-protection) provided\nby django is also used for the filtering. The fields of the model can be used in the queries in the DSL.\n\n## Syntax\n\n### Filtering\n\nThe basic filter syntax for a comparison of a field to a value is as follow\n\n    [field] ([negation]) [filter operator] [value]\n\nThe `field` is the name of the model field to be queried. The `value` is the\nvalue the field shall be compared to. Values for strings and timestamps need\nto be quoted in single quotes. For boolean fields the values `true` and `false`\nare valid.\n\nThe possible values for the `filter operator` are listed in the table futher\nbelow. Some of these filters can be negated with the optional keyword `not`, to see\nwhich operators support negation also see the table below.\n\n\n| Filter operator | Alias | Meaning | Negatable with \"not\" | Field type requirements |\n| --- | --- | --- | --- | --- |\n| `=` | `eq` | \"equal to\" | `=` is not, but the `eq` alias is negatable | - |\n| `!=` | `not eq` | \"not equal to\" | no             | - |\n| `\u003c` | `lt` |\"less than\"|no             | - |\n| `\u003e` | `gt` |\"greater than\"| no             | - |\n| `\u003c=` | `lte` |\"less than or equal to\"| no             | - |\n| `\u003e=` | `gte` |\"greater than or equal to\"| no | - |\n| `contains` || substring search (case sensitive) | yes | requires text or char fields |\n| `icontains` || substring search (case insensitive)| yes | requires text or char fields |\n| `startswith` || substring search at the beginning of the field value (case sensitive) | yes | requires text or char fields |\n| `istartswith` || substring search at the beginning of the field value (case insensitive)| yes | requires text or char fields |\n| `endswith` || substring search at the end of the field value (case sensitive) | yes | requires text or char fields |\n| `iendswith` || substring search at the end of the field value (case insensitive)| yes | requires text or char fields |\n| `isnull` || value must be NULL | yes | - |\n\nIt is possible to combine multiple filters using the logical operators `and`\nand `or`. `or` has precedence over `and`. It is also possible to use parenthesis: `(` and `)`.\n\nThe default name of the GET parameter for filtering is `filter`.\n\n### Sorting\n\nThe basic sorting syntax is\n\n    ([direction])(field)\n\nThe name of the `field` is mandatory. The direction is optional an when not set\n`+`, which means ascending order is implied. To sort in descending order use\n`-`.\n\n\nMultiple sorting operations can be chained by separating them with `,`. The\nfirst terms will be used first for the ordering, then the following term(s)\nwill be used.\n\nThe default name of the GET parameter for sorting is `sort`.\n\n### Example queries\n\nThe queries in this section use the API provided by the unittest\napplication in the `tests` directory of this repository.\n\nThe queries need to be correctly escaped before being send. The ones\nlisted further down this section are listed un-escaped for a better\nreadability. Escape should happen in the following form: `age \u003c legs` should be\nescaped to become:\n\n    GET /animal?filter=age+%3C+legs\n\n| Description | Filter query | Sort query |\n| --- | --- | --- |\n| An empty filter | | |\n| Match an integer field | age = 132 ||\n| Match the boolean field \"is_bird\" to be true | is_bird = true ||\n| Match NULL values | favorite_food isnull ||\n| Match Non-NULL values | favorite_food not isnull ||\n| Compare a timestamp | birthday \u003c '2007-10-13T11:13:09.250219+00:00' ||\n| Chain multiple filters with \"AND\" | name = 'tortoise' and age \u003e= 100 ||\n| Chain multiple filters with \"OR\" | name = 'tortoise' or name = 'dog' ||\n| Implicit sort by the field \"name\" in ascending order || name |\n| Explicit sort by the field \"name\" in ascending order || +name |\n| Sort by the field \"name\" in descending order || -name |\n| Sort by the \"legs\" field in descending order and name in ascending order || -legs,+name |\n| Compare the two fields \"age\" and \"legs\" | age \u003c legs ||\n| Match the field name to contain the substring \"rtoi\" | name contains 'rtoi' ||\n| Match the field name to NOT contain the substring \"rtoi\" | name not contains 'rtoi' ||\n| Combination of filtering and sorting | name startswith 'd' | sort=-id |\n\n\n## Using this module in your application\n\nThis module just provides a custom [`DjangoFilterBackend`](http://www.django-rest-framework.org/api-guide/filtering/#djangofilterbackend) which\ncan be used like in the following example:\n\n\n    from rest_framework import generics\n    from rest_framework_filterdsl import FilterDSLBackend\n    ...\n\n    class MyListView(generics.ListAPIView):\n        ...\n        filter_backends = (FilterDSLBackend,)\n        ...\n\n\nSettings like the names of the GET parameters or the casts for the user-provided\nvalues can be customized by subclassing the `FilterDSLBackend` implementation.\n\n\nFor more example usage please also see the unittests of this repository. Additional\nthe REST framework [filtering documentation](http://www.django-rest-framework.org/api-guide/filtering/) may\nbe helpful.\n\n# Unittests\n\nThis projects includes a set of unittests implemented using\n[pytest](https://docs.pytest.org/en/latest/index.html). To run these use the\n`runtests.sh` script.\n# License\n\nSee [LICENSE.txt](LICENSE.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlr-eoc%2Frest_framework_filterdsl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdlr-eoc%2Frest_framework_filterdsl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlr-eoc%2Frest_framework_filterdsl/lists"}