Ancestry_matchGroups Table

The Ancestry_matchGroups table is the primary table for A* DNA match data. Each row represents one match for one test kit. It is populated at different stages of the gather process.

Data Sources

Fields are populated at four different levels during gathering:

Level	When It Happens	Fields Populated
Match List Batch — every page of matches	Every page load during match gathering (50 matches per page)	testGuid, matchGuid, matchTestDisplayName, matchTestAdminDisplayName, sharedCentimorgans, sharedSegment, meiosisValue, starred, viewed, note, userPhoto, parentCluster, paternal, maternal, subjectGender, created_date, groupName (from kinship codes)
Match List — Relationship Batch — every page of matches	Every page load (covers ~60% of matches; close relatives excluded since they already have kinship codes)	groupName, paternal, maternal, percentDna, plus detailed predictions stored in Ancestry_RelationshipPredictions table
Match Compare Per-match — individual match pages	When visiting individual match comparison pages (requires tree or ICW gathering to be enabled)	totalSharedCentimorgans, longestSegmentCentimorgans, fetchedSegmentInfo, matchTreeNodeCount, matchTreeIsPrivate, matchTreeId, treeId
Match Compare — Origins Per-match — individual match pages	When visiting individual match comparison pages	Ethnicity comparison data (shared ethnicity regions between you and the match) and shared genetic communities/journeys. Stored in separate ethnicity tables.
Shared Matches Per-match — ICW pages	When ICW gathering is enabled, visits each match’s shared matches page	Data stored in the Ancestry_ICW table (not in matchGroups)

Column Reference

Identifiers

Column	Type	Source	Description
Id	int (PK)	Auto	Auto-incrementing primary key
testGuid	string	Match List	The test kit GUID (your kit)
matchGuid	string	Match List	The matched person’s GUID
matchTestDisplayName	string	Match List	Match’s display name
matchTestAdminDisplayName	string	Match List	Match’s admin display name
matchTestAdminUcdmId	string	Match List	Match admin’s user ID
loginUsername	string	App	DNAGedcom username who gathered this data

DNA Data

Column	Type	Source	Description
sharedCentimorgans	decimal	Match List	Shared cM (A*’s reported value, excludes small segments)
totalSharedCentimorgans	decimal	Match Compare	Total shared cM including small segments. Always ≥ sharedCentimorgans. Only populated when compare pages are visited.
longestSegmentCentimorgans	decimal	Match Compare	Longest shared DNA segment in cM. Only populated when compare pages are visited.
sharedSegment	int	Match List	Number of shared DNA segments
meiosisValue	int	Match List	Number of meiotic events (genetic distance)
confidence	float	Legacy	Match confidence (0–1 scale). No longer populated for new data; preserved for existing records.
percentDna	int	Match List — Relationship	Percentage of DNA shared (integer)
fetchedSegmentInfo	bool	Match Compare	True if per-match segment data has been fetched via compare page visit. Indicates totalSharedCentimorgans and longestSegmentCentimorgans are populated.

Relationship & Classification

Column	Type	Source	Description
groupName	string	Match List + Relationship	Predicted relationship label (e.g., “2nd cousin 1x removed”, “niece”). Close relatives get this from kinship code translation at the Match List level; distant relatives from the Relationship data.
paternal	bool	Match List + Relationship	True if match is on the paternal side
maternal	bool	Match List + Relationship	True if match is on the maternal side
parentCluster	string	Match List	Parent cluster assignment code (e.g., “both”, “p1”, “p2”)
subjectGender	string	Match List	Match’s gender (“M” or “F”)

Match Metadata

Column	Type	Source	Description
starred	string	Match List	“True” if match is starred on A*
viewed	string	Match List	“True” if match has been viewed on A*
note	string	Match List	User-entered note on A*
userPhoto	string	Match List	URL to match’s profile photo
hasHint	string	Match List	Whether match has an A* hint
lastLoggedInDate	string	Match List	Match’s last login date

Tree Data

Column	Type	Source	Description
matchTreeNodeCount	int	Match Compare	Number of people in match’s tree
matchTreeIsPrivate	string	Match Compare	Whether match’s tree is private
matchTreeId	string	Match Compare	Match’s tree ID
treeId	string	Match Compare	User’s tree ID

Gather Tracking

Column	Type	Source	Description
created_date	string	Match List	When the match record was created (A*’s timestamp)
matchRunDate	string	App	When match detail data was last gathered
icwRunDate	string	App	When ICW data was last gathered for this match
treeRunDate	string	App	When tree data was last gathered for this match
sync	string	App	Sync status flag

How Data Flows During Gathering

Step 1: Match List Pages

When you start an A* gather, the browser navigates to the match list. For each page of 50 matches, the following data is captured:

1. Match data — basic DNA data (sharedCentimorgans, segments, meiosis) and metadata (tags, starred, viewed, notes). Each match is inserted or updated in the database.
2. Kinship translations — a dictionary translating kinship codes (like “PGD”) to relationship names (like “1st cousin”). The match list includes kinship codes in each match’s tags, which are translated to populate groupName. Close relatives (~60% of matches) have kinship codes.
3. Relationship predictions — batch predictions for ~60% of matches on the page (close relatives are excluded since they already have kinship codes). Populates groupName with human-readable labels like “2nd cousin 1x removed”, plus parentSide and percentDna. Detailed prediction probabilities are stored in the Ancestry_RelationshipPredictions table.

This process repeats for each page of matches.

Step 2: Individual Match Pages (Compare Pages)

If tree gathering or ICW gathering is enabled, the browser visits individual match comparison pages. Each visit captures:

1. Shared DNA details — totalSharedCentimorgans (includes small segments), longestSegmentCentimorgans, and sets fetchedSegmentInfo = true.
2. Tree data — match tree information (stored in separate Ancestry_matchTrees and Ancestry_TreeData tables).
3. Common ancestors — shared ancestors (stored in AncestryAncestorCouple table).
4. Origins comparison — ethnicity region comparison between your kit and the match, showing shared regions with percentages (e.g., “Southern Germanic Europe: you 30%, match 33%”). Also captures shared genetic communities/journeys with display names and descriptions.

Step 3: Shared Matches (ICW)

If ICW gathering is enabled, the browser visits each match’s shared matches page. This captures which other matches you share in common with this match, stored in the Ancestry_ICW table.

Data Preservation Rules

When re-gathering, the application never overwrites good data with blank or zero values:

• groupName — only updated if the incoming value is non-empty and the stored value is null or empty.
• totalSharedCentimorgans / longestSegmentCentimorgans — precision preservation: if the stored value has decimal places and the incoming value is a rounded integer, the stored value is kept.
• confidence — only updated if the incoming value is greater than 0 and the stored value is 0.
• paternal / maternal — only set to true, never reset to false.
• percentDna — only updated if the incoming value is greater than 0.
• fetchedSegmentInfo — once set to true, never reset to false.
• Names — records with “name unavailable” never overwrite existing records with real names.

Related Tables

• Ancestry_RelationshipPredictions — stores detailed relationship predictions from the RelationshipData API, with multiple predictions per match ranked by probability.
• Ancestry_ICW — In Common With data (shared matches between two people).
• Ancestry_matchTrees — family tree individuals linked to matches.
• Ancestry_TreeData — tree metadata (tree ID, size, privacy).
• AncestryAncestorCouple — common ancestor couples shared between matches.