= Super-Entities = [[TOC]] == Introduction == 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)]] 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 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 == To simplify the handling of super-entities in the model, S3Model provides a unified API for super-entities: === Defining a Super-Entity === A super-entity can be defined using the {{{super_entity()}}} method of S3Model: {{{#!python class MyModel(S3Model): def model(self): # Define a dict with nice names for the instance types: my_instance_types = { "my_instance_tablename": current.T("Nice name for the instance type"), } # Define the super-entity tablename = "my_super_entity" table = self.super_entity(tablename, "my_super_id", # specify the super ID my_instance_types, # specify the instance types Field("start_date", "datetime"), # shared field location_id()) # shared field }}} Shared fields will mirror the values from the respective instance record, which allows easy access without need to join multiple tables. === Defining an Instance of a Super-Entity === To make a table an instance of a super-entity, you can use {{{s3db.configure()}}}: {{{ s3db.configure(table, super_entity = db.sit_situation) }}} By default, all fields that the table and the super-entity have in common will be mirrored in the super-entity ("shared fields"). You can override this by specifying a list of fields to be mirrored by the super-entity. {{{ s3db.configure(table, super_entity = db.sit_situation, sit_situation_fields = ["datetime"]) }}} In case your table uses different names for the shared fields, you can use a dict instead to specify a mapping: {{{ s3db.configure(table, super_entity = db.sit_situation, sit_situation_fields = dict(datetime="timestmp", location_id="location_id")) }}} === Linking to a Super-Entity === Both, instance tables as well as shared components need to be linked to the super-entity. This can be done by inserting a ''super-key'' field into the instance/component table which must have the same name as the primary key of the super-entity. You can use the {{{super_link()}}} function as a DRY method for this: {{{ tablename = "pr_presence" table = db.define_table(tablename, super_link("pe_id", "pr_pentity"), super_link("sit_id", "sit_situation"), # sit_id ...) }}} Note: {{{super_link}}} generates a {{{Field}}} instance - if you just need the name of the super-key field, you can use: {{{ sk = s3db.super_key(db.pr_pentity) # returns the string "pe_id" }}} === Updating a Super-Entity === If you use [wiki:S3XRC/RESTfulAPI/s3_rest_controller s3_rest_controller()] for CRUD, it will automatically create, update and delete super-entities as necessary. Otherwise, or if you manipulate records outside s3_rest_controller, you have to update all super-entities which an instance table implements whenever you create, update or delete a record in that table. To do this, you can use: {{{ s3db.update_super(table, record) }}} where {{{table}}} is the instance table and {{{record}}} the newly created/updated record. In case you're going to delete a record from an instance table, you may use: {{{ s3db.delete_super(table, record) }}} before you delete the record, where {{{table}}} is the instance table and {{{record}}} the record to be deleted. ---- DeveloperGuidelines