Changes between Version 24 and Version 25 of S3/S3Model/SuperEntities

Timestamp:

02/26/14 12:27:32 (11 years ago)

Author:

Dominic König

Comment:

--

S3/S3Model/SuperEntities

@@ -4 +4 @@
 == Introduction ==
 
-Sometimes it is useful to share the same component across multiple resources. To achieve this in a generic way, S3 supports a special type of link tables - so-called ''Super-Entities'':
+Sometimes it is useful to link the same component to multiple master entities without introducing a separate foreign key constraint for each master.
+
+   Example: both warehouses and offices have contact persons. Instead of creating separate warehouse_contact and office_contact components, you can make use of the super-entity concept to link a single site_contact component to both entities.
+
+To achieve this, S3 supports a special type of key tables called ''Super-Entities'' (referring to the fact that they constitue a generalization concept):
 
 [[Image(super_entity.png)]]
 
-Instead of having several foreign keys for different primary resources, the shared component contains only one foreign key to the link table, the so-called ''super-key''.
+A super-entity stores (tablename, uuid) pairs which identify records across multiple tables, and the primary key of the super-entity (super-key) can then be used for foreign key constraints to link components. The primary key of the super-entity is usually referred to as ''super-key'', and the respective foreign key constraints are called ''super-link''.
 
-The primary resource (=instance table) contains the same ''super-key'' field as the component, thus the forward join of resource-to-component can be established as a natural join, i.e. without accessing the link table.
-
-For the (seldom needed) backward join component-to-resource, the link table must be involved because it contains the table name of the primary resource in the field {{instance_type}}.
-
-Disadvantage of the link table method is that the link table has to be updated whenever a primary resource record is created, updated or deleted - which generates some (minimal) extra load on write, however, it is recommended to not use super-entities for resources where the extra load on write can give a serious performance problem (e.g. messages), or at least to keep the super-entity table lean and free of extra references.
-
-  - ''code examples to follow...''
+The super-entity concept is implemented in S3Model, and supported by both S3CRUD and S3Import. Custom methods can make use of the current.s3db API to handle super-entities as described below.
 == API ==