Variables of Type "Relational" ("Link")
By Miller Prosser, August 2015; Updated by Sandra Schloen, February 2021
Using Relational (Link) Variables
This topic is explained in detail in the OCHRE manual, cited below. However, significant improvements to the use of relational variables are explained below.
See also Auto-inverse Relational Properties.
What is a Relational Variable?
As explained in the OCHRE manual:
"There are two ways to relate items to other items: simple links and relational properties. A simple link indicates that two items are related but says little about the nature of the relationship. A relational property makes use of the item-properties mechanism (see Chapter 5) to establish a relationship between two items in such a way that the relationship itself is named with a project-defined name and so can be described and queried as an entity in its own right. Furthermore, a relational property explicitly indicates the direction of the relationship and allows you to give a different name to the inverse relationship. For example, instead of using a simple link to relate a person item to another person item in an ambiguous fashion in which the nature of the relationship and its direction are unclear, you could use a relational variable named “Teacher of” to represent the fact that one person, represented by the item to which the property is being assigned, is the teacher of another person, who is represented by the value of the relational variable. The name of the inverse relationship would be “Student of.” After this property (a variable-value pair) has been assigned to the person item that represents the teacher, the nature and direction of the relationship between the two persons is clearly represented in the database. A query could then subsequently find all persons who are students of a particular teacher or all teachers of a particular student" (p. 87).
How to define a Relational Variable
Again, from the manual:
"Variables of the relational type are defined in the Property variables category and are constrained within the project’s taxonomy in the usual way (see Chapter 13). However, there are two additional data-entry fields in the item pane for this type of variable. You must enter the Category of related item by selecting the appropriate category in a drop-down list. Secondly, you have the option of entering Name of inverse relationship. If you do not enter a name, the inverse relationship will have the same name as the relational variable. For example, an archaeologist could create a relational variable named “Earlier locus is,” specifying that the category of the related item is Locations & objects and the name of the inverse relationship is “Later than.” When assigning properties to an item, the relational variable would be inserted in the Variable column of the Properties tab, at which point the corresponding Value field would require a link to a target item in the appropriate category—in this case, the Locations & objects category" (pp. 94-95).
A relational variable called "Architectural context" targets values in a Locations & Objects hierarchy also called "Architectural context."
Relational Variable settings
A relational Variable is assigned "Link" as its Type. It must also be assigned to one of the primary OCHRE Categories -- Locations & Objects in the example here.
Values of the relational Variable must be chosen from the specified Category. In addition, a Selected Context within that category can be specified to further constrain the selection of Values to the items within that Context. The pick-list selection method described below honors the constraint specified here. If the Constrain to current context option is used instead, the Value selection will be limited only to qualifying items within the hierarchy in which the user is currently working.
How to use a Relational Variable
There are two ways to enter values: (1) pick values from the Link Manager, or (2) pick values from a dynamic pick list.
The Link Manager method
The Link Manager allows the user to manually select items to add as values. The user can either navigate to an item in the Link Manager or search for the item.
From the manual:
"To enter the value, the user would double-click the Value field to display paperclip+ “add link” and paperclip- “remove link” buttons to the left of the field. After selecting the link target in the usual way via the Linked Items tab of the reference pane, the user would click the paperclip+ button to insert a link to the target item as the value of the relational variable" (p. 95).
The Dynamic Pick-list method
Since the publication of the manual, we added the following method for picking values. Instead of choosing items from the Link Manager, the user now can simply activate a pick list in the Value field. The values for this list are specified on the definition of the Variable in the taxonomy. (See the description of Settings above, and more at The Dynamic Pick-list.)
Pick list mode applies not only to the values of relational properties, but also to the built-in Observer (of Object) field, Creator (of Resource) field, and others like them. Instead of choosing a person from the Link Manager, you may simply activate pick list mode and select from the list offered.
Double-click on the Value field to activate the double chevron button (highlighted in the image below).
Click once on the double chevron to populate the pick list with the available values.
Click once on the Value field to open up the pick list.
Make a choice (or multiple choices where allowed).
To make a choice, you may either scroll through the list or begin typing the name of the item.
Click OK.
To commit the change, either navigate away from the field or click the double chevron to exit pick list mode.
Choices made in pick list mode can be changed by opening the list and deselecting the current choice or by selecting a new choice.
Primary versus Secondary hierarchies
In the usual case, relational properties provide a simple labeled link between two items. In the example here, the current "Lot is under" another Lot. This is a scenario where you would specify in the Settings that the target Values should be Constrained to the current context, since it would make sense to limit the selection of Lot items to those most likely to be related.
Relational variables also provide what we call "cross-cutting links," connecting items in a primary hierarchical context with items in a different secondary hierarchy. For example, excavated items are typically entered within their primary excavation context. Later they may be assigned to items within a secondary, interpretive context which organizes the excavated area into Buildings, Rooms, Streets, and Courtyards. Adding a relational variable and its value to the description of the item it its primary context is a simple way to assign its secondary context.
It is worth noting that items should be cross-linked to the most specific level of the secondary hierarchy, taking advantage of the built-in inheritance provided by the hierarchical structure. That is, by linking a Lot to the "SE room," this implies that the Lot is hierarchically contained within Building 5 too, and so that does not need to be specified as an additional property.
Options for Relational Variables
Values targeted by relational variables are often managed by a secondary hierarchy. Preferences on the secondary hierarchy can control how the linked Values appear in edit and display contexts. See the examples below.
The "Show full path" option turns "SE room" into "Corinth/ET/Bldg. 5/SE room" to help disambiguate items that may be named the same but in different contexts.
The "Show expanded path" option creates a hierarchical display that makes explicit the context.
Related "Lot" items are displayed normally in this example in the edit pane. "Architectural context" items are displayed with "full paths" shown.
Related "Lot" items are displayed normally in this example. "Architectural context" items are display with "expanded paths." Check ON "Highlight links" from the View's Display options if desired.
Finding Related Values
Any hierarchy that has been designated as the Selected Context (as described in Settings above) for a targeted relational variable has a built-in special feature to track and find related values. All items within such a secondary hierarchy have on their edit pane a query-button that lets you "Look up items linked to this context."
In this example we have run this lookup feature for the "SE room." OCHRE finds all direct links to this item from other items (what we think of as "reverse" links), and creates a derived list, showing the results as sub-items. This is a temporary, in-memory list for the purpose of investigation, or as a check of data entry.
Note that this lookup feature is NOT hierarchically aware. That is, a lookup of Building 5's reverse links will not include items linked to its SE room, only those linked directly to Building 5.
Reverse links to items in secondary hierarchies are easily exposed.
Scoping a Query based on Reverse Links
Any hierarchy that has set as a Preference "Allow scoping based on reverse links" (as shown above) can be used in the ordinary way to establish the Scope of a Query. Since this can be a computationally expensive process, you need to opt-in to this feature for secondary hierarchies.
In this example we use the Architectural context secondary hierarchy, rather than the primary excavation-based hierarchy, to provide the Scope of the query.
Note that this query IS hierarchically aware. That is, a query for items within Building 5 will find all of those which were linked directly to Building 5, or to any of its sub-items (including here its SE room), by virtue of inheritance.
Secondary hierarchies can be used to set the Scope of a Query.
For additional strategies for querying and working with relational properties, see also: