Understanding Data References

Introduction

Data References refer to items of GEDCOM Data held within Records, and are used within Expressions that occur most commonly in:

For a full list see the Family Historian Help > Using Family Historian > Advanced Topics > Expressions and Contexts of Use.

Expressions are composed from two Family Historian features:

  • Data References that often appear enclosed within percentage signs, e.g. %INDI.BIRT%
  • Functions that begin with an = sign (except when used within another Function), e.g. =RecordId()

Data References

Data References identify Data items within Records. For example, the following Expression is a Data Reference that specifies a particular Individual Birth Event:

%INDI.BIRT%

For full details see the Family Historian Help > Using Family Historian > Advanced Topics > Understanding Data References including several new features added in fh V6.

The structure of Data References is derived from the The Gedcom Standard, Release 5.5 dated 2nd January 1996.

FIXME: Needs updating for some new fh V6.1 features.

The Basics

You should rarely need to construct a Data Reference yourself, because Family Historian offers a Data Reference Assistant (DRA) associated with every type of Expression. For example, in a Query Window, on the Columns tab, there is a Fields DRA panel on the left, and on the Rows tab, the Expression box has an ellipsis […] DRA button to the right.

Basically each Data Reference is composed of Tags that identify Data. These are separated by either a dot . or a greater than > sign, and the whole reference is usually enclosed within percent % signs.

For example, to identify for any given INDIvidual, the NAME of their father, you could use the following Data Reference:

%INDI.FAMC>HUSB>NAME%

This looks intimidating, but is not as complex as it appears, and the parts have the following meaning:

INDI Start with an INDIvidual Record
FAMC Within this Record, follow the > link to the FAMily they belong to as a Child
HUSB The father is identified by the HUSBand field in this Family Record and another > link leads to another Individual Record
NAME Within that linked Individual Record we find the NAME field of the father

The available Tags are always offered and explained by the relevant Data Reference Assistant (DRA), and Record links are listed with a trailing double greater than >> symbol.

The Tags are mostly the same as used in GEDCOM but there are a few exceptions. For example, in GEDCOM the NOTE tag is used with the format @N321@ to link to a Note Record, or with any other text for a Local Note. Whereas, Data References use the tags NOTE> and NOTE2 respectively to make the distinction clear. Data References also use a special Tag format for custom Events (EVENT-<event_name>) and Attributes (_ATTR-<attr_name>).

Indices

There can be more than one instance of many of the Data fields. An Individual can have more than one Name, more than one Child, or more than one Census entry. Each instance is identified by an index in square brackets [1]. If no index is supplied, then the first instance is assumed by default.

So for example:

%INDI.NAME[2]% identifies the 2nd Name
%INDI.CENS[4]% identifies the 4th Census Event
%INDI.CENS[last]% is an advanced index to identify the last Census Event
%INDI.CENS[year=1881]% is an advanced index to identify the 1881 Census Event

See the Advanced Indices section in the Family Historian Help for more options.

These Indices are one of the rare cases where a Data Reference must be manually edited, because they cannot be selected using a Data Reference Assistant (DRA).

Relative Data References

An ordinary Data Reference starts with a tag that identifies a record, but in some contexts the Data Reference can be relative to a subsidiary tag such as a FACT in a Fact Query or a Sentence Template in later versions of fh.

~.PLAC identifies the Place field of a Fact
~.DATE identifies the Date field of a Fact

In some cases the initial tilde ~ can be followed by > instead of a dot.

Relative data references also apply to parameters of some Functions and throughout Family Historian Plugins.

Shortcuts

Some data items are difficult or impossible to access using an ordinary Data Reference. To solve this problem Family Historian supports five dummy Tags called Shortcuts that begin with a tilde ~ symbol.

~FATH identifies the father of an Individual
~MOTH identifies the mother of an Individual
~CHIL identifies a child of an Individual
~SPOU identifies a spouse of an Individual or a Family Record
~CURSPOU identifies the spouse of an Individual for any particular Diagram Box

So for example:

%INDI.~CHIL[2]% identifies the 2nd child of an Individual by any marriage
%INDI.~SPOU[1]>BIRT.DATE% identifies the date of birth of the 1st spouse of an Individual

The available Shortcuts are always offered and explained by the relevant Data Reference Assistant (DRA), and are listed with an upward pointing arrow prefix.

Qualifiers

A Data Reference in some cases can specify how the data is displayed by using a Qualifier. These are appended to the last Tag separated by a colon : symbol.

The available Qualifiers are always offered and explained by the relevant Data Reference Assistant (DRA).

So for example:

%INDI.NAME:SURNAME% displays just the Surname of an Individual
%INDI.BIRT.DATE:YEAR% displays just the Year of Birth of an Individual
%INDI.DEAT.PLAC:SHORT% displays just the first item up to the first comma in the Death Place field

Contextual Data References

Contextual Data References were added in fh V6 and only have meaning in their specific context of use, mostly within Diagrams where the currently displayed Family couple needs to be identified.

%CUR_SPOU% and %CUR_SPOU>% Current Spouse
%CUR_FAMS% and %CUR_FAMS>% Current Family As Spouse
%CUR_FAMC% and %CUR_FAMC>% Current Family as Child
%CUR_SP_FAMS% and %CUR_SP_FAMS>% Current Spouse's Family as Spouse
%CUR_SP_FAMC% and %CUR_SP_FAMC>% Current Spouse's Family as Child
%CUR_BASE% Base Person
%CUR_TREE_ROOT% Tree Root
%CUR_TREE_ROOT_FAM% Tree Root Family
%CUR_DGM_ROOT% Diagram Root
%CUR_DGM_ROOT_FAM% Diagram Root Family
%CUR_DGM_ROOT_COUPLE_FAM% Diagram Root Couple's Family

Elsewhere:

%CUR_OTHER_IND% Other Individual in 'How Related' report
%CUR_FILE_ROOT% File Root nearly everywhere
%CUR_FILE_OWNER% File Owner nearly everywhere
%CUR_FILE_HEADER% File Header nearly everywhere

Contextual data references behave like ordinary data references, in that you can expand them to refer to any detail of the record in question. For example, %CUR_SPOU>SEX% refers to the sex of the Individual's current spouse, and %CUR_FILE_ROOT.SEX% refers to the sex of the current file root.

Sentence Template Data References

Sentence Template Data References were added in fh V6 and only have meaning in specific template contexts.

See the Family Historian Help > Using Family Historian > Dialog Boxes > Fact Types Dialog > Template Codes towards the end.

Typically the data reference is enclosed in curly brackets and its context is the current fact, e.g. {%FACT.PHON%} refers to the fact phone number.

To refer to witness details from a witness sentence template requires the use of the =GetContextItem() function, and its context codes:

WITNESS Refers to the Witness Individual record
WITNESS_LINK Refers to the link to the current Witness

e.g.

{=GetFieldText(GetContextItem(WITNESS),"%~.NAME:GIVEN%")} Returns the Witness record forename
{=GetFieldText(GetContextItem(WITNESS_LINK),"%~.NOTE2%")} Returns the Witness link role Note