New definition and syntax for subordinate relations.

[dimitri-yatsenko]

Today we discussed a clearer definition of subordinate relations. We propose the following definitions and syntax.

Base relation B is subordinate to base relation A when B is depends on A and A contains information that is inseparably tied to information in B so that A should never be populated without also populating B and B should never be deleted from without deleting matching tuples from A. A master relation can have multiple subordinate relations. We are not yet sure if nested subordinate relations make good sense.

A common case is a master-detail relationship when B contains a set of tuples for every tuple in A that form one inseparable group. These tuples can only be inserted or delete together as a complete group with their matching A tuple.

The subordinate relation always forms a primary dependency on the master relation.

According to the new definition, subordinate relation classes will be declared inside the master relation's class.

For example:

import datajoint as dj

schema = dj.schema(database='test', context=locals())

@schema
class Root(dj.Manual):
    definition = """  # root table from which all data are populated
    root_id :int 
    """

@schema 
class A(dj.Computed):
    definition = """  # master table
    -> Root
    """

    class B(dj.Subordinate):
        definition = """  # subordinate table
        -> A
        id_b :int 
        """

    def _make_tuples(self, key):
        self.insert1(key)
        sub = self.B()
        for b in range(10):
            sub.insert1(dict(key, id_b=b))

The schema decorator will now traverse the class and look for its properties of the type dj.Subordinate to find all subordinate tables. A subordinate relation will not have its own tier (manual, lookup, imported, or computed) and will need to subclass dj.Subordinate. Effectively, it has the same tier as its master. It's table name in MySQL will be formed by appending __class_name to its master's table name.

[dimitri-yatsenko]

Automated relations will need to populate all their subordinate relations from inside their _make_tuples in the same transaction. Subordinate relations will not be populated independently. However, they will still provide a public insert which users should know not to use. The insert method is necessary for the master relation to populate its subordinate tables.

[dimitri-yatsenko]

Deletes should not be possible in subordinate relations without deleting the matching tuples in the master relations. We are still thinking how to handle this. We are currently considering these two alternatives

1. The current implementation simply refused to delete and suggests that the user must delete from the master relation. I prefer this solution for its explicitness.
2. A more advanced solution is to delete matching tuples from the master relation when deleting from its subordinate relations.

@fabiansinz has edited this post

[dimitri-yatsenko]

Note that the original post has been edited to enhance the example.

[dimitri-yatsenko]

fixed in fdb1bc2