`<edgeForeignKey>`

You use the <edgeForeignKey> element to define a reference to another entity, in a manner similar to the <foreignkey> element. However, you use an edge foreign key in place of a standard foreign key to break a cycle of foreign keys in the data model. Guidewire defines this element in the data model metadata files as the <edgeForeignKey> XML subelement.

This topic includes the following:

The data model and circular references

A chain of foreign keys can form a cycle, also known as a circular reference, in the data model. As an example of a circular reference, entity type A has a foreign key to entity type B, and B has a foreign key to A. Circular references can occur with more extensive chains of foreign keys, such as A refers to B, which refers to C, which refers to A. The PolicyCenter data model does not permit circular foreign keys reference, because PolicyCenter cannot determine a safe order for committing the entity instances in a circular reference to the database.

For example, entity types A and B have foreign key references to each other. The foreign keys create a circular reference. Suppose that a bundle contains a new instance of A and a new instance of B. The circular reference would cause a foreign key constraint to fail upon committing the bundle. If PolicyCenter commits A before B is committed and in the database, a constraint failure occurs on the foreign key from A to B. The converse order of committing B before A causes a similar failure.

An edge foreign key in place of a standard foreign key resolves circular references so PolicyCenter can determine a safe order for committing the entity instances within a cycle. An edge foreign key from A to B introduces a new, hidden associative entity with a foreign key to A and a foreign key to B. The edge foreign key associates A and B without establishing foreign keys in the database directly between them. With an edge foreign key, PolicyCenter can safely first commit new object A, then new object B, and finally the edge foreign key instance.

Edge foreign keys in entity database tables

Unlike a standard foreign key, an edge foreign key does not correspond to an actual column in the database table of an entity type. Nor does an edge foreign key implement a database foreign key constraint. However, the PolicyCenter Data Dictionary labels edge foreign keys as standard foreign keys. In Gosu code, you access edge foreign keys in the same manner that you access standard foreign keys.

Edge foreign keys and associative database tables

An edge foreign key creates an associative table in the database. An associative table is essentially a table of foreign keys relationships. An associative table associates other database tables with each other but holds no other essential business data itself.

In PolicyCenter, the associative table that implements an edge foreign key has two columns:

OwnerID
ForeignEntityID

If entity instance A has an edge foreign key to entity type B, PolicyCenter creates a row in the edge foreign key table. The value in the row for OwnerID points to A and the value for ForeignEntityID points to B.

Every time you traverse, or dereference, the edge foreign key, PolicyCenter loads the join array.

If the array is of size 0, then the value of the edgeForeignKey is null.
If the array is of size 1, the PolicyCenter follows the ForeignEntityID on the row.

Important: When you change a foreign key to an edge foreign key, you must write an upgrade trigger to populate the edge table for existing data. Otherwise, the associative edge table will remain empty even upon a database upgrade. Moreover, when you reference the edge foreign key, you will receive a null value.

Edge foreign keys in Gosu

In Gosu code, edge foreign keys work in a manner similar to standard foreign keys. Just like a standard foreign key, you can query an edge foreign key and get and set its attributes.

Edge foreign keys and performance

An edge foreign key has more performance issues than a standard foreign key, because PolicyCenter must manage a separate table for the relationship. Queries must join an extra table. Nullability constraints in the database do not work with edge foreign keys, so you must enforce nullability constraints with extra Gosu code the you develop.

Edge foreign keys and archiving

If you add an edge foreign key to an entity that is part of the archive domain graph, set the extractable attribute on the edge foreign key to true. The value true causes PolicyCenter to add the Extractable delegate to the associative table generated for the edge foreign key. If the extractable attribute of an edge foreign key on an entity that is part of the archive domain graph is not set to true, the server will not start. In addition, the entity type that the edge foreign key relates to must implement the Extractable delegate.

When to use edge foreign keys

Use an edge foreign key only to avoid circular foreign key references in the data model. Circular foreign key references can prevent PolicyCenter from determining a safe order for committing the entity instances in a circular reference to the database.

Use an edge foreign key instead of a standard foreign key in the following situations:

An entity type has self-referencing foreign keys, including foreign keys between subtypes.
A Group entity must specify its parent group.
Entity type A has a foreign key to B, and entity type B has a foreign key to A.
Cycles that involve more that two entity types.
The primary member of an array requires a foreign key to its owner.

Note: <edgeForeignKey> is a valid subelement for all entity types, including entity extension types.

Attributes of `<edgeForeignKey>`

The <edgeForeignKey> element contains the following attributes.

`<edgeForeignKey>` attribute	Description	Default
`createhistogram`	Whether to create a histogram on the column during an update to the database statistics. Note: It is possible to override this attribute on an existing column in an extension (.etx) file using the `<column-override>` element. You can use the override to turn off an existing histogram or to create one that did not previously exist. This change does not take effect during an upgrade. The change occurs only if you regenerate statistics for the affected table by using the Guidewire maintenance_tools command. See also* Working with attribute and element overrides Understanding database statistics maintenance_tools command	`false`
`deprecated`	If `true`, then PolicyCenter marks the item as deprecated in the Data Dictionary and places a `Deprecated` annotation on it in the Guidewire Studio API Reference. If you deprecate an item, use the description to explain why. For more information, see Data entity subelements.	`false`
`desc`	A description of the purpose and use of the edge foreign key.	None
`edgeTableEntityName`	The name of the edge table entity. If you do not specify a name, then PolicyCenter creates one automatically by taking the `edgeTableName` attribute and capitalizing the first letter. If the `edgeTableName` contains an underscore, then all text up to and including the first underscore is discarded, and the first letter after the underscore is capitalized.	None
`edgeTableName`	Required. The name of the edge, or join array, table to create. As with other entity table names, the `edgeTableName` does not require a prefix such as `pc_`.	None
`exportable`	Unused.
`exportasid`	Unused.
`extractable`	Whether the edge entity is marked `Extractable` for archiving.	`false`
`fkentity`	Required. The entity to which this foreign key points.	None
`getterScriptability`	See Data objects and scriptability for information.	`all`
`ignoreForEvents`	This attribute has complex, non-intuitive interactions with data entity relationships. See Interactions of ignoreForEvents attribute with data entity relationships for information on how to use and configure it.	`false`
`importableagainstexistingobject`	If `true` and the entity is importable, or loadable, then the value in the staging table can be a reference to an existing object. This reference is the `publicID` of a row in the source table for the referenced object.	`true`
`loadable`	If `true`, then PolicyCenter creates a staging table for the edge table.	`false`
`loadedByCallback`	Internal. If true, then the loading code does not use a default value or report a warning if the column is nullable without a default.	`false`
`name`	Required. Specifies the name of the property on the entity.	None
`nullok`	Whether the column can contain `null` values. This value is meaningless for edgeForeignKey objects.	`true`
`overlapTable`	Whether the edge entity implements the OverlapTable delegate and is marked OverlapTable for archiving.	`false`
`overwrittenInStagingTable`	Internal. If `true` and the edge table is loadable, the loader process auto-populates the staging table during import. IMPORTANT If set to `true`, do not attempt to populate the table yourself, as the loader import process overwrites this table.	`false`
`setterScriptability`	See Data objects and scriptability for information.	`all`
`soapnullok`	Unused.

Subelements of `<edgeForeignKey>`

`<edgeForeignKey>` subelement	Attributes	Description
`fulldescription`	None	See <fulldescription>.
`tag`	None	See <tag>.

<edgeForeignKey>