Django Tree Queries

Common errors

• FieldError: Cannot resolve keyword 'tree_depth' into field.

  cause Attempting to access `tree_depth` or other tree-specific fields without calling `.with_tree_fields()` on the queryset. These fields are dynamic annotations, not stored model fields.
  fix Add `.with_tree_fields()` to your queryset before accessing `tree_depth`, `tree_path`, or `tree_ordering`. Example: `MyModel.objects.with_tree_fields().first().tree_depth`.

• AttributeError: 'MyModel' object has no attribute 'ancestors' (or 'descendants', etc.)

  cause The model instance was retrieved without using the `TreeQuerySet` methods, or the model does not inherit from `TreeNode`. Standard Django model instances do not inherently have these tree methods.
  fix Ensure your model inherits from `tree_queries.models.TreeNode` and retrieve instances using `MyModel.objects` (which is a `TreeQuerySet`) or explicitly use `TreeQuerySet.as_manager()` for custom managers. Example: `node = MyModel.objects.get(pk=1); ancestors = node.ancestors()`.

• django.db.utils.ProgrammingError: subquery must return only one column

  cause This error can occur when using complex subqueries or aggregations with tree querysets, especially when trying to aggregate values bottom-up (from descendants to ancestors), which is difficult or impossible with the library's top-down CTE approach.
  fix For complex aggregations, particularly bottom-up, consider loading smaller trees into Python memory and performing calculations there, or restructuring your query to align with the top-down nature of the CTE.

Warnings

• breaking Django's standard `order_by()` method is not supported for tree ordering; nodes are returned according to a depth-first search. Use `order_siblings_by("field_name")` instead.
  Fix: Replace `.order_by(...)` with `.order_siblings_by('field_name')` for sibling ordering. General ordering of the full tree is implicit depth-first.
• gotcha The `tree_depth`, `tree_path`, and `tree_ordering` fields are only available on querysets where `with_tree_fields()` has been explicitly called. They are not stored in the database or available on newly created/saved instances.
  Fix: Always append `.with_tree_fields()` to your queryset when you intend to access these tree-specific attributes. Example: `Category.objects.with_tree_fields().get(pk=1)`.
• gotcha Performance can degrade significantly on very large tables or deep trees, especially when queries involve filtering or aggregating parts of the tree, as the recursive CTE might calculate all trees in the table before filtering.
  Fix: For very large datasets, consider using `tree_filter()` and `tree_exclude()` for better performance as they filter the base table before building the tree. For complex bottom-up aggregations, consider performing calculations in Python for small trees or exploring other tree libraries (e.g., django-treebeard, django-closuretree) if `django-tree-queries` becomes a bottleneck for specific use cases.
• gotcha The `parent` foreign key field in models must explicitly be named `parent` for `TreeNode` to function correctly.
  Fix: Ensure your model's self-referencing ForeignKey is defined as `parent = models.ForeignKey('self', ...)`
• gotcha The internal representation of `tree_path` and `tree_ordering` can change in future versions and should not be relied upon for application logic, especially for non-PostgreSQL databases where `tree_path` is a string representation.
  Fix: Use the provided integer `tree_depth` and queryset methods for tree traversal and logic, avoiding direct parsing or reliance on the exact string format of `tree_path` or `tree_ordering` if your application needs to be future-proof or database-agnostic.
• gotcha MySQL and MariaDB databases have a maximum tree depth limit of 50 levels due to their lack of native array support, which `django-tree-queries` uses for `tree_path` and `tree_ordering` internally.
  Fix: Design your tree structure to stay within the 50-level limit when using MySQL or MariaDB. Consider PostgreSQL for deeper trees.

Install

• pip install django-tree-queries Install stable version

Imports

• TreeNode
  wrong:

  from django.db import models; class MyModel(models.Model): ...

  correct:

  from tree_queries.models import TreeNode

  To enable tree query capabilities, models should inherit from tree_queries.models.TreeNode or use tree_queries.query.TreeQuerySet with a custom manager.
• TreeQuerySet
  wrong:

  from django.db.models import QuerySet

  correct:

  from tree_queries.query import TreeQuerySet

  Use TreeQuerySet to build custom managers for tree-aware querysets if not inheriting from TreeNode.
• TreeNodeForeignKey

  from tree_queries.fields import TreeNodeForeignKey

  Provides a model field that augments the default foreign key field with tree structure visualization in forms.

Quickstart

Define a model inheriting from `tree_queries.models.TreeNode`. This automatically adds a `parent` ForeignKey and provides tree-aware query methods. To access `tree_depth`, `tree_path`, and `tree_ordering` fields, you must explicitly call `.with_tree_fields()` on your queryset. Siblings can be ordered using `.order_siblings_by()` method.

import os
from django.db import models

# Assuming 'myapp' is in INSTALLED_APPS
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')
import django
django.setup()

from tree_queries.models import TreeNode

class Category(TreeNode):
    name = models.CharField(max_length=255)

    class Meta:
        app_label = 'myapp'

    def __str__(self):
        return self.name

# Example Usage (after makemigrations and migrate)
# from myapp.models import Category
# root = Category.objects.create(name='Electronics')
# child1 = Category.objects.create(name='Smartphones', parent=root)
# child2 = Category.objects.create(name='Laptops', parent=root)
# grandchild = Category.objects.create(name='Gaming Laptops', parent=child2)

# Retrieve a tree with additional fields
# for node in Category.objects.with_tree_fields().order_siblings_by('name'):
#     print(f"{'--' * node.tree_depth} {node.name} (depth: {node.tree_depth})")