GBDS Relational Databases

Introduction

This manual describes all tables, schemas and information of the GBDS 4.x relational databases. GBDS uses a relational database to store metadata about people, transactions, notification groups, configuration overrides and exceptions.

The document is divided into four sections that describe:

• The general tables ;

• The Unresolved Latents (UL) tables ;

• The Notification tables ;

• The GBDS configuration tables .

General tables

The general tables are tables that store vital information for the operation of GBDS, such as exceptions, information about people, information about transactions and others. These tables are described below.

gbds.people

Error in the Federal Revenue peopletable is intended to store the indexes of all people stored in the GBDS database and is described as follows:

Column	Type	Size	Value	Additional information
id	bigint	20	not null	Primary key; Private key of the relational database
pguid	varchar	255	not null	Personal UGUID stored in HBase
deleted	tinyint	1	null	Indicates whether the candidate was deleted so that they are not included when listing operations are performed

gbds.people_version

Error in the Federal Revenue people_versiontable is intended to store information about the last changes in a person's record and is described as follows:

Column	Type	Size	Value	Additional information
version	int	11	not null	Primary key; Version index (incremental from the first change)
person_id	bigint	20	not null	Reference to the persongbds.people.id
_timestamp	datetime	6	null	date and time timestamp for the current version of a person
deleted	tinyint	1	null	Indicates whether the candidate was deleted to be excluded when performing candidate listing operations
active	tinyint	1	null	Defines whether a version of a person is eligible for master registry transactions

gbds.transactions_ref

Error in the Federal Revenue transactionstable is intended to store the indexes of all transactions stored in the GBDS database and is described as follows:

Column	Type	Size	Value	Additional information
id	bigint	20	not null	Primary key; Private key of the relational database
tguid	varchar	255	not null	UGUID of the transaction stored in HBase

gbds.transactions

Error in the Federal Revenue transactionstable is intended to store information about the biometric data quality analysis of a transaction.

Column	Type	Size	Value	Additional Information
id	bigint	20	not null	Primary key; Private key of the relational database
tguid	varchar	255	not null	Reference to the transactiontransactions_ref.tguid
pguid	varchar	255	null	UGUID of the person stored in HBase
active	tinyint	1	not null	Defines whether a version of a person is eligible for Master Registry transactions
finger_quality_extracted	tinyint	1	null	False if fingerprints can be extracted
face_quality_extracted	tinyint	1	null	False if the face can be extracted in the background. True if it has already been extracted.
created	datetime	6	null	creation date and time timestamp of the transaction
updated	datetime	6	null	date and time timestamp of the last modification of the transaction
enroll_status	varchar	255	null	Enrollment status (such as ENQUEUED, PROCESSING, FAILED, and others)
quality_status	varchar	255	null	Quality analysis status (such as OK, PENDING, APPROVED, and others)
extraction_time	varchar	255	null	Elapsed time for model extractions
extraction_quality	varchar	255	null	Elapsed time for quality extractions
match_time	int	11	null	Elapsed matching time for this transaction
total_time	int	11	null	Total operation minus queue waiting time
type	varchar	20	null	Type of transaction. Enum: ENROLL, UPDATE, VERIFY,IDENTIFY
fingerprint_global_quality	int	11	null	Fingerprint global quality score
global_quality	int	11	null	Profile global quality score
quality_extraction_api_id	varchar	255	null	ID of the API that will perform or performed the quality extraction
latent	tinyint	1	null	Flags whether the transaction is a latent search
ul	tinyint	1	null	Flags whether the transaction is a UL search
api_id	varchar	255	null	The ID of the API instance that received the transaction
num_fingers	int	11	null	The number of fingerprints in the transaction
num_faces	int	11	null	The number of face images in the transaction (0 or 1)
gbds_version	varchar	255	not null	GBDS version that processed the transaction
ginger_extractor_type	enum	n/a	null	Type of ginger extractor used in the transaction. Enum: GRIAULE_FAST, GRIAULE_BASIC, GRIAULE_2020, GRIAULE_2024, GRIAULE_2018.

gbds.transaction_fields

Error in the Federal Revenue transaction_fieldstable aims to store information about quality information and link it to the non-biometric information of the fieldstable.

Column	Type	Size	Value	Additional information
id	bigint	20	not null	Primary key; Private key of the relational database
fkey	varchar	255	null	Field key that describes the information contained (for example, whether it is a blood type, mother's name, date of birth, document, etc.) Reference tofields.fkey
type	varchar	255	null	Type of information (search or label) Reference tofields.type
fvalue	varchar	255	null	Effective value of the field (for example, the document number) Reference tofields.fvalue
transaction_id	bigint	20	not null	Transaction Id. Reference totransaction.id

gbds.transaction_fingerprint_quality

The table columns below are dynamic, according to the quality extraction. If any editing of the fields occurs in future versions, the data here may become outdated for a while.

Column	Type	Size	Value
transaction_id	bigint	20	not null
idx	int	11	not null
image_quality	int	11	null
template_quality	int	11	null
minutiae_count	int	11	null
blank	varchar	100	null
contrast	varchar	100	null
fingerArea	varchar	100	null
fingerCenterX	varchar	100	null
fingerCenterY	varchar	100	null
fingerExtentX	varchar	100	null
fingerExtentY	varchar	100	null
hasjoint	varchar	100	null
__index	varchar	100	null
marginBiteEast	varchar	100	null
marginBiteNorth	varchar	100	null
marginBiteSouth	varchar	100	null
marginBiteWest	varchar	100	null
nfiq	varchar	100	null
orientation	varchar	100	null
sizeX	varchar	100	null
sizeY	varchar	100	null

gbds.transaction_face_quality

The table columns below are dynamic, according to the quality extraction. If any editing of the fields occurs in future versions, the data here may become outdated for a while.

Column	Type	Size	Value
transaction_id	bigint	20	not null
idx	int	11	not null
image_quality	int	11	null
template_quality	int	11	null
autoBrightness	varchar	100	null
bgBelowPictureQuality	varchar	100	null
bgBlueStandardDeviation	varchar	100	null
bgDarknessQuality	varchar	100	null
bgGreenStandardDeviation	varchar	100	null
bgRedStandardDeviation	varchar	100	null
bgUniformityQuality	varchar	100	null
blurCompliance	varchar	100	null
busyBackground	varchar	100	null
busyBackgroundInCropped	varchar	100	null
cropContainmentError	varchar	100	null
eyesLookDown	varchar	100	null
eyesLookLeft	varchar	100	null
eyesLookRight	varchar	100	null
eyesLookUp	varchar	100	null
eyesObstruction	varchar	100	null
eyesTooClosed	varchar	100	null
eyesTooOpen	varchar	100	null
faceDown	varchar	100	null
faceLeft	varchar	100	null
faceObstruction	varchar	100	null
faceOrientationPitchCompliance	varchar	100	null
faceOrientationRollAngle	varchar	100	null
faceOrientationYawCompliance	varchar	100	null
faceRight	varchar	100	null
faceUp	varchar	100	null
glasses	varchar	100	null
grayscaleSpan	varchar	100	null
hat	varchar	100	null
heavyGlasses	varchar	100	null
icaoCompliance	varchar	100	null
leftEyeX	varchar	100	null
leftEyeY	varchar	100	null
mouthObstruction	varchar	100	null
mouthOpen	varchar	100	null
obstruction	varchar	100	null
openMouth	varchar	100	null
pictureHeight	varchar	100	null
pictureWidth	varchar	100	null
pixelated	varchar	100	null
redEye	varchar	100	null
result	varchar	100	null
rightEyeX	varchar	100	null
rightEyeY	varchar	100	null
saturated	varchar	100	null
saturationGrayscaleDistribGrade	varchar	100	null
saturationNumGrayTones	varchar	100	null
saturationOverExposure	varchar	100	null
shadows	varchar	100	null
skinColorCompliance	varchar	100	null
smile	varchar	100	null
smilingMouth	varchar	100	null
spoof	varchar	100	null
spoofGrade	varchar	100	null
tiltAngle	varchar	100	null
tooDark	varchar	100	null
unnaturalSkinColor	varchar	100	null
visibleTeeth	varchar	100	null
wrongFacePose	varchar	100	null
wrongShoulderPoseLeft	varchar	100	null
wrongShoulderPoseRight	varchar	100	null

gbds.biometrics

The table biometricsintended to store a person's biometric data, being linked to the transactionand to the people_versionsystem. It is described as follows:

Column	Type	Size	Value	Additional Information
id	bigint	20	not null	Primary key; Private key of the relational database
idx	int	11	null	Index of the current biometric
quality	int	11	null	Quality score for the extracted biometric model
type	varchar	255	null	Modality of the current biometric
person_id	bigint	20	not null	Reference to the persongbds.people.id
transaction_id	bigint	20	not null	Reference to the transactiontransactions_ref.id
person_version	bigint	11	not null	Reference to the personpeople_version.version

gbds.fields

The table fields intended to store a person's non-biometric information, being linked to the transactiontables people_version. It is described as follows:

Column	Type	Size	Value	Additional Information
id	bigint	20	not null	Primary key; Private key of the relational database
fkey	varchar	255	null	Field key that describes the information contained (for example, whether it is a blood type, mother's name, date of birth, document, etc.)
type	varchar	255	null	Type of information (search or label)
fvalue	varchar	255	null	Effective value of the field (for example, the document number)
person_id	bigint	20	not null	Reference to the personperson.id
person_version	int	11	not null	Reference to the personpeople_version.version

gbds.exceptions

The table exceptionsintended to store information about any biometric exception and its handling. It is described below:

Column	Type	Size	Value	Additional Information
id	bigint	20	not null	Primary key; Private key of the relational database
aguid	varchar	255	not null	Exception stored HBase UGUID
comments	varchar	255	null	Any comments provided when handling the exception
_timestamp	datetime	6	null	date and time timestamp for the creation of the exception
status	varchar	255	not null	The current status of the exception is defined whether it is handled or pending
user	varchar	255	null	Identification of the user responsible for handling the exception
reference_person_id	bigint	20	not null	Foreign key: Reference to the reference personpeople.id
entrant_person_id	bigint	20	not null	Foreign key: Reference to the entrant personpeople.id
transaction_id	bigint	20	not null	Foreign key: Reference to the transactiontransactions_ref.id
reference_person_version	int	11	not null	Foreign key: Reference to the reference personpeople_version.version
entrant_person_version	int	11	not null	Foreign key: Reference to the entrant personpeople_version.version

gbds.apis

The apisis used by GBDS to manage multiple APIs active at the same time.

Column	Type	Size	Value	Additional Information
api-id	varchar	255	not null	ID of the unique API instance
hostname	varchar	255	not null	Host name of the node where the API is running
port	int	11	not null	Port where the API is running
type	varchar	255	null	Type of API instance (LEADER, RUNNER or null)

On API startup, each API will look for itself in this table. If not found by host name/IP and port, it inserts itself into the table with a GUID as api-id and null type , which means it is not ready for quality extraction. Changes applied directly to this table will be polled every 15 minutes.

Unresolved Latents (UL) tables

Unresolved Latents tables are used to store information about UL data and the candidates. The tables are described below.

gbds.ul

The table ulwas designed to store all GBDS ULs and is described as follows:

Column	Type	Size	Value	Additional Information
uguid	varchar	255	not null	Primary key; UGUID stored in HBase
ul_status	varchar	255	not null	UNSOLVEDor SOLVED; HBase replicates this status
creation_time	timestamp	4	not null	current_timestampby default
person_pguid	varchar	255	null	PGUID of the corresponding person whenSOLVED
person_tguid	varchar	255	null	TGUID of the corresponding person whenSOLVED
fragment_id	varchar	255	null	Original fragment ID for the fragment that generated the UL
fragment_case_id	varchar	255	null	Original case ID for the fragment that generated the UL
fragment_index	int	11	null	Fragment index for the UL. By default, the index is set to -1(unknown index, any index)
analysis_user	varchar	255	null	User responsible for UL analysis
analysis_timestamp	timestamp	4	null	date and time timestamp of the analysis
group_guid	varchar	255	not null	Grouping GUID (to list linked ULs)

gbds.ul_candidates

The table ul_candidates was designed to store the candidates of each UL that GBDS keeps after any REVERSE LATENT MATCHING performed on enrollments that generated a match with a UL, and is described as follows:

Column	Type	Size	Value	Additional Information
ul_uguid	varchar	255	not null	Primary key; UL UGUID
person_pguid	varchar	255	not null	Primary key; Candidate PGUID
person_tguid	varchar	255	not null	Primary key; Candidate TGUID
person_index	int	11	not null	Primary key; Candidate finger index
score	int	11	not null	Corresponding matching score for the candidate
deleted	tinyint	1	not null	0by default, indicates whether the candidate was deleted to be excluded when performing candidate listing operations
minutiae	longblob	Up to 4Gb	null	JSON serialization containing the corresponding minutiae. It is a list with the following structure: - queryIndex, int - referenceIndex,int

Notification tables

The notification tables are used to store data for auditing purposes, such as emails, people to be notified and groups.

gbds.notify_user

The table notify_user was designed to store the authenticated user data for gbds.

Column	Type	Size	Value	Additional Information
id	bigint	20	not null	Primary key; Unique user ID.
username	varchar	255	not null	authenticated gbds username

gbds.notify_group

The table notify_groupwas designed to store information about notification groups.

Column	Type	Size	Value	Additional Information
id	bigint	20	not null	Primary key;
name	varchar	255	not null	Group name
enabled	tinyint	1	not null	Defines whether the group will be active or not

gbds.notify_group_email

The table notify_group_email was designed to store the emails of a given group.

Column	Type	Size	Value	Additional Information
notify_group_id	bigint	20	not null	Primary key; Group ID.
email	varchar	255	not null	Primary key; Email that belongs to the group

gbds.notify_user_group

The table notify_user_group was designed to store information about which group a given user belongs to.

Column	Type	Size	Value	Additional Information
notify_user_id	bigint	20	not null	Primary key; Reference to the usernotify_user.id
notify_group_id	bigint	20	not null	Primary key; Reference to the groupnotify_group_email.notify_group.id

gbds.people_transparency

The table people_transparency was designed to store information about a given person and which actions are taken when that person is searched.

Column	Type	Size	Value	Additional Information
id	bigint	20	not null	Primary key;
pguid	varchar	255	not null	Reference to the personpeople.pguid
enabled	tinyint	1	not null	Reference to the personpeople.pguid
action	varchar	255	null	Action to be taken

gbds.people_transparency_group

The table people_transparency_group was designed to store information about the groups to which a person belongs.

Column	Type	Size	Value	Additional Information
people_transparency_id	bigint	20	not null	Primary key; Reference to people_transparency'speople_transparency.id
notify_group_id	bigint	20	not null	Primary key; Reference to the groupnotify_group_email.notify_group.id

GBDS configuration tables

GBDS uses a relational database to store some API and GBDS configurations. The settings table is a special table designed to control certain GBDS and GBDS API settings. These settings are stored in the gbds.settingstable. The table may contain settings present in the GBDS API, in GBDS or in both, following the schema below:

Type	Type	Size	Value	Additional Information
skey	varchar	255	not null	Primary key. Name of the parameter key.
stype	varchar	50	not null	Location from where the parameter comes. API or GBDS
svalue	varchar	4096	null	Parameter value
description	varchar	4096	null	Parameter description
stimestamp	datetime	6	not null	Timestamp
host	varchar	1024	null	Host name of a node

All settings found in the table will be written to the respective file, gbdsapi.propertiesboth for the GBDS API and application.conffor GBDS, every 15 minutes. Additionally, all settings updated in memory, both in the API and in GBDS, will be propagated.

The parameter value set in the gbds.settingstable will be propagated to ALL nodes.

This feature is controlled by a configuration parameter in the table, gbds.rdbSystemConfiguration.enabled. This parameter will allow overriding the GBDS and API configuration values. Setting the parameter value to BOTHwill cause the GBDS and API settings to be overridden.

gbds.settings / File configuration key	Type
gbscluster.min.quality	API
gbds.enroll.fingerprints.min-nr-template	API
gbds.enroll.face.min-nr-template	API
gbds.enroll.iris.min-nr-template	API
gbds.enroll.palmprint.min-nr-template	API
gbds.enroll.newborn-palmprint.min-nr-template	API
gbscluster.enroll.fingerprints.verify.matchthreshold	API
gbscluster.update.min.quality	API
gbds.transparency.search.identify.request.notify.enabled	API
gbds.transparency.search.identify.result.actions.enabled	API
gbds.api.logLevel	API
gbds.extraction.service	API
gbds.extraction.service.face.count	API
gbds.extraction.service.ginger.count	API
gbds.extraction.service.girl.count	API
gbds.extraction.service.hostname	API
gbds.extraction.service.initialPort	API
gbds.extraction.service.logLevel	API
gbds.extraction.service.maxTries	API
gbds.extraction.service.linkLibSegfault	API
gbds.extraction.quality.service	API
gbds.extraction.quality.fillTransactionQualityPropertiesTable	API
gbds.faces.extraction.quality.api	API
gbds.faces.extraction.quality.background	API
gbds.fingerprints.extraction.quality.api	API
gbds.fingerprints.extraction.quality.background	API
gbds.extraction.quality.service.finger.count	API
gbds.extraction.quality.service.face.count	API
gbds.extraction.quality.service.initialPort	API
gbds.extraction.quality.service.logLevel	API
gbds.extraction.quality.service.timeout	API
gbds.extraction.quality.service.hostname	API
gbds.extraction.quality.service.maxTries	API
gbds.extraction.quality.service.linkLibSegfault	API
gbds.extraction.quality.service.rows-on-select	API
gbds.extraction.quality.service.submitted-queue-factor	API
gbds.enroll.face.min.quality	API
gbds.update.face.min.quality	API
gbds.monitor.url	API
gbds.template.face.multiplicity	API
gbds.biographicBase.enabled	API
gbds.biographicBase.endpoints	API
gbds.biographicBase.get.timeout.ms	API
gbds.biographicBase.list.timeout.ms	API
gbds.biographicBase.logLevel	API
gbds.biographicBase.clientID	API
gbds.biographicBase.clientSecret	API
gbds.biographicBase.lookAllServers	API
gbscluster.fingerprints.extraction.enroll.type	API
gbscluster.fingerprints.extraction.verify.type	API
gbds.update.exception.reextract	API
gbds.update.exception.reextract.save	API
gbds.biographicBase.autoUpdate	API
gbds.biographicBase.sendPguidAsKey	API
gbds.biographicBase.sendTguidAsKey	API
gbds.log.diagnose	GBDS
gbds.ul.boot.scan.enabled	GBDS
gbds.boot.scan.ignoreErrorsOnRegion	GBDS
gbds.boot.matcher.creation.sleepTime.ms	GBDS
gbds.biometric.fingerprint.identify.threshold	GBDS
gbds.biometric.fingerprint.exception.threshold	GBDS
gbds.biometric.fingerprint.exception.enabled	GBDS
gbds.biometric.fingerprint.exception.enroll.min-matches-for-exception	GBDS
gbds.biometric.face.identify.threshold	GBDS
gbds.biometric.face.exception.threshold	GBDS
gbds.peopleList.countFromRDB	GBDS
gbds.biometric.face.enabled.threshold	GBDS
gbds.driver.logLevel	GBDS
gbds.log.loadUnload	GBDS
gbds.template.memory.format	GBDS
gbds.match.service.enabled	GBDS
gbds.match.service.initialPort	GBDS
gbds.match.service.logLevel	GBDS
gbds.match.service.timeout	GBDS
gbds.match.service.templateSend.parallelByModality	GBDS
gbds.match.service.linkLibSegfault	GBDS
gbds.match.service.maxTries	GBDS
gbds.match.service.maxConnectionErrors	GBDS
gbds.memory-monitor	GBDS
gbds.watchdog.interval	GBDS
gbds.watchdog.log.mode	GBDS
gbds.watchdog.log.level	GBDS
gbds.verifyPostMatch.enabled	GBDS
gbds.transparency.search.identify.result.notify.enabled	BOTH
gbds.transparency.email-notifier.url	BOTH
gbds.transparency.email-notifier.log-level	BOTH
gbds.transparency.email-notifier.timeout	BOTH
gbscluster.update.consider.fingerprints	BOTH
gbscluster.update.consider.faces	BOTH
gbscluster.update.consider.faces.beforeFingerprints	BOTH
gbscluster.update.faces.verify.matchthreshold	BOTH
gbscluster.update.minimum.fingers	BOTH
gbds.search.verify.adjust-resolution	BOTH

Other settings can be placed in the table gbds.settingsin rdb and they will all be written in the API or in the GBDS file, according to the type of configuration. However, runtime memory reloads will not be performed for these new settings, only after restarting the API and/or GBDS.