Introduction

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

• QueriesQuerying is a very powerful feature that allows you to specify and save criteria for identifying a set of records of a given record type. to specify Columns, Row filters, and Titles
• Diagram Text Schemes to define the content of Diagram Boxes
• Diagram > Options > Boxes > Conditions to define box style
• Reports to define Data items in certain Report Sections
• Customise or Print Records WindowThe Records Window provides a comprehensive view of all the information stored within a Family Historian project. Columns or Named ListNamed Lists are a way in FH to group related items — which can be records of any type(s) — so that you can easily find them to work with. Columns
• Captions and Custom Fields in Property Boxes
• Narrative Report FactFacts are one of the key concepts at the heart of Family Historian; they are how you record the things that happened to, or described, each ancestor (Individual). Sentence TemplatesSentences are used in conjunction with Fact Sets to produce Narrative Reports; their templates are highly customisable. since ƒh V6
• Override Templates for Fact displays since ƒh V6

For a full list see (ƒh7) Expressions and Contexts of Use or (ƒh6) Expressions and Contexts of Use.

Expressions are composed from two ƒh features:

• Data References that often appear enclosed within percentage signs, e.g.%INDI.BIRT%
• FunctionsA 'function' is an expression which returns values based on computations. Typically, functions require data to be supplied to them as 'parameters'. A function in Family Historian is similar to a 'function' as used in spreadsheet applications (such as MS 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 ExpressionExpressions are composed from two technical features: Data References and Functions; they also often involve Operators to compare values. is a Data Reference that specifies a particular Individual Birth Event:

%INDI.BIRT%

For full details see the help pages linked at the top of this article including several new features added in ƒh6 and ƒh7.

The structure of Data References in all versions of ƒh up to version 6 is derived from the The GedcomGEDCOM, an acronym for GEnealogical Data COMmunication, is a specification for exchanging genealogical data between different genealogy software. It is a file format that most genealogical programs and online trees recognise. Standard, Release 5.5 dated 2nd January 1996.

The Basics

You should rarely need to construct a Data Reference yourself, because ƒh 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, 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 NoteFamily Historian version 6 and below supports two types of Notes: Local notes (associated with a single person, record, or fact); and Note Records (sometimes called Shared Notes), that can be linked to multiple records and/or facts. Version 7 introduced. 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 EventsUsers of Family Historian can customize fact definitions, or create their own fact definitions to more closely match they way they want to work. (EVENT-<event_name>) and AttributesEvents are things that happened to an Individual and Attributes are things that described them. (_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 CensusCensus records are national collections of population statistics. They usually record details about members of a household on a particular date, and are typically collected every ten years. 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

For more options, see the help pages linked at the top of this article.

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.

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 ƒh.

~.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 ƒh PluginsPlugins are small programs that allow new features to be added without upgrading Family Historian itself; some plugins are written by Calico Pie and others are written by users..

Shortcuts

Some data items are difficult or impossible to access using an ordinary Data Reference. To solve this problem ƒh  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, 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.

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 ƒh 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 RootAll Diagrams have a root. This is the person from which the diagram “spreads out”; in the standard diagram preferences the root box is shown in a different colour from other boxes.
%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

Narrative Sentence Templates:

%CUR_PRIN%	First or current principalThe Principal (for Individual Facts) is the person to whom the fact applies — the person who was born, had the occupation, emigrated etc.  Family Facts have two Principals — the people who married, got divorced etc. for the fact
%CUR_PRIN2%	Second or other principal for the Family fact
%CUR~WITN% and %CUR~WITN>%	Current witnessA Witness is somebody who played an important role in an event (or rarely, attribute) but were not a Principal, e.g. they could have been a bridesmaid at a wedding, rather than one of the individuals getting married.

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 ƒh V6 and only have meaning in specific template contexts.

For more detail, see towards the end of (ƒh7) Sentence Template Codes or (ƒh6) Template Codes.

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 %CUR~WITN% contextual data reference shown above.

{%CUR~WITN>NAME:GIVEN%}	Returns the Witness record forename
{%CUR~WITN.NOTE2%}	Returns the Witness role local Note

Embedded Link Data References (V7)

Version 7 introduced the ability to have embedded links to other records within Note fields.

To access these, the reference is e.g. for a link to an individual within the Text from SourceBoth Source records and Citations have a Text From Source field intended to hold transcripts of source documents. for a Source:

%SOUR.TEXT._LINK_I[1]>% for the first linked individual

%SOUR.TEXT._LINK_I[2]>% for the second linked individual

Note1: a linked object should have the same index no matter how many times they are linked in the Note.

Note2: Replace _I with _S for links to SourcesSource: "where information was found". This could be anything from an archive in a county records office, a book, or even a relative's recorded recollection. Citing your Sources helps to show how you reached a particular conclusion about an Individual., _R for Repositories etc.

[/glossary-ignore]