Adjacency List trees

This is a simple implementation of the traditional Adjacency List Model for storing trees in relational databases.

In the adjacency list model, every node will have a “parent” key, that will be NULL for root nodes.

Since django-treebeard must return trees ordered in a predictable way, the ordering for models without the node_order_by attribute will have an extra attribute that will store the relative position of a node between it’s siblings: sib_order.

The adjacency list model has the advantage of fast writes at the cost of slow reads. If you read more than you write, use MP_Node instead.

Warning

As with all tree implementations, please be aware of the Known Caveats.

class treebeard.al_tree.AL_Node(*args, **kwargs)

Bases: Node

Abstract model to create your own Adjacency List Trees.

Warning

If you need to define your own Manager class, you’ll need to subclass AL_NodeManager.

node_order_by

Attribute: a list of model fields that will be used for node ordering. When enabled, all tree operations will assume this ordering.

Example:

node_order_by = ['field1', 'field2', 'field3']

parent

ForeignKey to itself. This attribute MUST be defined in the subclass (sadly, this isn’t inherited correctly from the ABC in Django 1.0). Just copy&paste these lines to your model:

parent = models.ForeignKey('self',
                           related_name='children_set',
                           null=True,
                           db_index=True)

sib_order

PositiveIntegerField used to store the relative position of a node between it’s siblings. This attribute is mandatory ONLY if you don’t set a node_order_by field. You can define it copy&pasting this line in your model:

sib_order = models.PositiveIntegerField()

Examples:

class AL_TestNode(AL_Node):
    parent = models.ForeignKey('self',
                               related_name='children_set',
                               null=True,
                               db_index=True)
    sib_order = models.PositiveIntegerField()
    desc = models.CharField(max_length=255)

class AL_TestNodeSorted(AL_Node):
    parent = models.ForeignKey('self',
                               related_name='children_set',
                               null=True,
                               db_index=True)
    node_order_by = ['val1', 'val2', 'desc']
    val1 = models.IntegerField()
    val2 = models.IntegerField()
    desc = models.CharField(max_length=255)

Read the API reference of treebeard.models.Node for info on methods available in this class, or read the following section for methods with particular arguments or exceptions.

get_depth(update=False)

Returns:

the depth (level) of the node Caches the result in the object itself to help in loops.

Parameters:

update – Updates the cached value.

See: treebeard.models.Node.get_depth()

class treebeard.al_tree.AL_NodeManager(*args, **kwargs)

Bases: Manager

Custom manager for nodes in an Adjacency List tree.