Django JSON Agg

Features

Exposes JSON related aggregation functions (like postgres's json_object_agg and json_agg) as Django Aggregate objects.

Requirements

Django version 4.2. It might work with other versions, but it is not tested with them. For now only sqlite and postgresql databases are supported.

Installation

You can install Django JSON Agg via pip from PyPI:

$ pip install django-json-agg

And add it to Django settings INSTALLED_APPS:

INSTALLED_APPS = [
    # other apps
    'json_agg',
]

Usage

Let's assume you have the following models

class Post(models.Model):
    """Model representing a blog post."""

    title = models.CharField(max_length=100, null=True, unique=True)
    content = models.TextField(null=True)
    author = models.ForeignKey(
        "tests.Author", related_name="posts", on_delete=models.CASCADE
    )


class Author(models.Model):
    """Model representing a blog post Author."""
    name = models.CharField(max_length=100)

If you want all author objects and their posts formatted as a dict, with title as key and content as value, you can run the following

from json_agg import JSONObjectAgg

from .models import Author


queryset = Author.objects.annotate(
    post_map=JSONObjectAgg("posts__title", "posts__content")
).all()

In the example above, Author instances would have the attribute post_map, which would a a dict.

A similar aggregator, JSONArrayAgg, is also available.

Please see the reference for details.

Is this project for me?

django-json-agg aims to improve the ergonomics for aggregating data as dicts or lists while still keeping other model instances. All that in a single query. One might argue it also adds some efficiency by building the dict/list in the database, instead of python side.

However, reliance on django-json-agg and JSON data structures in general for storing "relational" data may be an anti-pattern or an indicator of a problematic or suboptimal database schema design. Your time may be better spent refactoring your models to use more native primitive data types and relations (foreign keys, indexes, etc).

Without this project, a similar result to the example above could be achieved with:

from collections import defaultdict

from json_agg import JSONObjectAgg

from .models import Author, Post


posts = Post.objects.values_list("author_id", "title", "content")
posts_per_author = defaultdict(dict)
for author_id, title, content in posts:
    posts_per_author[author_id][title] = content

authors = Author.objects.all()
# accessing posts per author
for author in Author.objects.all():
    author_posts = posts_per_author[author.id]

Contributing

Contributions are very welcome. To learn more, see the Contributor Guide.

License

Distributed under the terms of the GPL 3.0 license, Django JSON Agg is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.

Credits

This project was generated from @cjolowicz's Hypermodern Python Cookiecutter template.