Commits

angri committed 5253e29

documented limits in more details

  • Participants
  • Parent commits e19dd8e

Comments (0)

Files changed (2)

 .. _`django-mptt`: http://django-mptt.googlecode.com/
 
 
+Limits
+------
+`sqlamp` imposes some limits on the amount of data in the tree.
+Those limits are configurable for any specific application.
+Here is the list of limits:
+
+*Number of trees:*
+    Imposed by :class:`TreeIdField`, which is of type ``INTEGER``.
+    Therefore the limit of number of trees is defined by the highest
+    integer for DBMS in use. This is not configurable. If you expect
+    to have more than 2**31 trees you might want to use custom field
+    for tree id with a different numeric type (supposedly ``BIGINT``)
+    and probably set up an index on it to speed up creating new trees.
+*Number of children in each node:*
+    Imposed by the length of one path segment. Can be configured
+    using the "steplen" parameter (see :class:`MPManager`). The number
+    of children in each node is equal to "36 ** steplen" and with
+    default "steplen=3" is equal to 46656. Note that it is not the total
+    maximum number of nodes in a tree. Each node can have that much
+    children and each of it children can have that much children,
+    and so on.
+*Maximum nesting depth:*
+    Imposed by length of path field and length of one path segment.
+    Generally speaking the deepest nesting is equal to maximum possible
+    number of path segments in a whole path. So it can be expressed
+    as "pathlen // steplen + 1" (see :class:`MPManager`). The default
+    value for "pathlen" is for historical reason 255, so together with
+    default steplen it sets the maximum depth to 86. Nowadays all major
+    DBMS support a higher length for ``VARCHAR`` so you can freely
+    increase "pathlen" to, say, 10240 and "pathlen" to 4. These values
+    would limit your tree to 1679616 maximum children and 2561 maximum
+    depth.
+*Total number of nodes in a tree:*
+    There is no such limit. Not any that you can hit even (with extremely
+    low) default path length. The total number of nodes in a tree
+    is equal to "36 ** pathlen" and with "pathlen=255" it is something
+    around ``7.2e+397``.
+
+
 Moving nodes
 ------------
 There are several things to consider on moving nodes with materialized
 If your application relies on extensive moving of nodes it might be better
 to stay with AL.
 
-There is also a point to note in a way the moving of nodes is implemented.
+There is also some points to note in a way the moving of nodes is implemented.
 In order to achieve the best performance moving of nodes is not working
 on ORM level, instead it uses bulk update queries. The most important
 implication of that is that node objects which are stored in session
 are incorporated to :class:`MPClassManager` API (not instance managers)
 and accept primary keys instead of node objects.
 
+Another caveat is in limits check. If you put a subtree deep inside another
+one it may be possible to overlook that for some nodes the result path
+can be longer than accepted value by the path field (see `limits`_ for
+details). Unfortunately it is impossible to check in advance without doing
+(probably expensive) queries to find out the deepest path in the subtree
+that is been moving.
+
 The API for moving nodes comprises the following operations (all of them
 are methods of :class:`MPClassManager`):
 

sqlamp/__init__.py

         column should be :class:`TreeIdField`.
 
     :param pathlen=255:
-        an integer, the length for path field.
+        an integer, the length for path field. See `limits`_ for details.
 
     :param steplen=3:
         an integer, the number of characters in each part of the path.
-        This value along with `pathlen` allow to fine-tune the limits for
-        max tree depth (equal to `(pathlen / steplen) + 1`) and max children
-        in each node (`36 ** steplen`). Default values of `3` and `255`
-        set the following limits: max depth is `86` and max children number
-        is `46656`.
+        See `limits`_.
 
     :param instance_manager_key='_mp_instance_manager':
         name for node instance's attribute to cache node's instance