A DRF mixin for aggregation endpoints
Project description
You can find the original Project here: https://github.com/kit-oz/drf-aggregation
Django Rest Framework Aggregation
A simple Django Rest Framework extension to add aggregation endpoints to your API.
Key features:
- count, sum, average, minimum, maximum
- grouping by multiple fields
- filtering and ordering
Installation
To install, use pip: ❌
pip install [COMING SOON]
Quickstart
Inherit the AggregationMixin in your ViewSet.
from django_rest_aggregation.mixins import AggregationMixin
...
class BookViewSet(GenericViewSet, AggregationMixin):
queryset = Book.objects.all()
serializer_class = BookSerializer
Register the ViewSet in your urls.py
. The default aggregation endpoint is {base_url}/aggregation/.
router = DefaultRouter()
router.register(r'book', BookViewSet)
urlpatterns = [
path('', include(router.urls)),
# or
path('book/custom/endpoint/', BookViewSet.as_view({'get': 'aggregation'}))
]
Get the aggregation results by sending a GET request to the aggregation endpoint.
URL | What it does |
---|---|
/book/aggregation/?aggregation=count |
Get the total number of books |
/book/aggregation/?aggregation=maximum&aggregation_field=price |
Get the most expensive book |
/book/aggregation/?aggregation=average&aggregation_field=rating&group_by=author |
Get the average rating grouped by author |
/book/aggregation/?aggregation=sum&aggregation_field=pages&group_by=author&value__gt=1000 |
Get the sum of all pages grouped by authors which are greater than 1000 |
Parameter overview
URL Parameters
query parameter | description | example |
---|---|---|
aggregation | determines the type of aggregation | aggregation=sum |
aggregation_field | the field to aggregate on | aggregation_field=price |
group_by | the field on which the queryset is grouped | group_by=author |
value | the value to filter the queryset | value__gt=1000 |
View Class Variables
class variable | description | example |
---|---|---|
aggregation_name | changes the default value name | aggregation_name=foo |
aggregation_serializer_class | Sets a custom serializer for the queryset | aggregation_serializer_class=CustomSerializer |
aggregated_filtering_class | Sets a FilterSet Class for filtering the value field | aggregated_filtering_class=ValueFilter |
aggregated_filterset_fields | A shortcut for setting a value Filtersets | aggregated_filterset_fields=[lt, lte, gt] |
Aggregations
Available aggregations are:
- count
- sum
- average
- minimum
- maximum
They can be used by adding the mandatory aggregation parameter to the request URL.
/book/aggregation/?aggregation=count
Aggregation Field
The aggregation field is the field to aggregate on. It can be used by adding the aggregation_field parameter to the request URL. This is a mandatory parameter for the sum, average, minimum and maximum aggregations. Both model fields and annotated fields can be used.
/book/aggregation/?aggregation=sum&aggregation_field=price
You can also use the double underscore notation to aggregate on related model fields.
/book/aggregation/?aggregation=sum&aggregation_field=author__age
If the aggregation is sum or average, the aggregation field must be a numeric field. If the aggregation is min or max, the aggregation field must be date or numeric field.
Grouping
Grouping is done by adding the group_by parameter to the request URL. Again, model fields and annotated fields can be used.
/book/aggregation/?aggregation=count&group_by=author
You can group throughout multiple model relations (ForeignKey & ManyToMany Fields) by using the double underscore notation.
/store/aggregation/?aggregation=count&group_by=books__author__age
To group by multiple fields, separate them with a comma.
/book/aggregation/?aggregation=count&group_by=author,genre
Filtering & Ordering
To filter the queryset, you can use the standard Django Filter Backend. That implies:
-
filtering before aggregation
/book/aggregation/?aggregation=count&group_by=author&pages__gt=100
-
filtering after aggregation
/book/aggregation/?aggregation=count&group_by=author&value__gt=5
-
combined filtering
/book/aggregation/?aggregation=count&group_by=author&pages__gt=100&value__gt=100
To control which filtering options are available, you can use the aggregated_filtering_class class variable. This sets a custom FilterSet Class for filtering the value field.
class BookViewSet(GenericViewSet, AggregationMixin):
queryset = Book.objects.all()
serializer_class = BookSerializer
aggregated_filtering_class = ValueFilter
class ValueFilter(filters.FilterSet):
value__gte = filters.NumberFilter(field_name='test123', lookup_expr='gte')
value__lte = filters.NumberFilter(field_name='test123', lookup_expr='lte')
class Meta:
fields = ['test123__gte', 'test123__lte']
A shortcut for setting value Filtersets is the aggregated_filtering_fields class variable. This automatically creates a FilterSet class for filtering the value field.
class BookViewSet(GenericViewSet, AggregationMixin):
queryset = Book.objects.all()
serializer_class = BookSerializer
aggregated_filtering_fields = ['lt', 'lte', 'gt']
You can use 'lt', 'lte', 'gt', 'gte', 'exact' and __all__ as values for the aggregated_filtering_fields class variable.
To order the queryset, you can use the standard Django ordering filter.
class BookViewSet(GenericViewSet, AggregationMixin):
queryset = Book.objects.all()
serializer_class = BookSerializer
ordering_fields = ['value', 'grouped_by_field']
ordering_fields = __all__
is also possible.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_rest_aggregation-0.1.0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | dc87aa19bd435057c35edd0f41b45b5fb5b3c6767cc7e352356c77d411bbc18e |
|
MD5 | c4e30286a11bb13648eb28887fd58e49 |
|
BLAKE2b-256 | 6fb1a06879c73f8d1b7ecfd582f3bde7ba0c568a840648a5ee731bb540f17a92 |
Hashes for django_rest_aggregation-0.1.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f205f37d14274a98b3f4a6d2204c6da4690826cd08817250a58e16bbf0afeb1c |
|
MD5 | 7376458982e46cb4e40e5159d976103b |
|
BLAKE2b-256 | df54a8356fc1f293993229f38e04ec4dbdd0af6e0b8fce455a486128d686dea4 |