Senzing v4 SDK Breaking Changes

SDK API breaking changes when upgrading from Senzing v3 to v4.

Items listed in this section are breaking changes from Senzing v3 to Senzing v4.

In the following sections, C/C++ language function names are listed. The function names are very similar for C#, Java, and Python. For example:

  • C/C++: Sz_addRecord
  • C#: AddRecord
  • Java: addRecord
  • Python: add_record
  • sz_command: add_record

File changes

Senzing engine configuration file

v3 v4
etc/G2Module.ini etc/sz_engine_config.ini

This file is the equivalent of the SENZING_ENGINE_CONFIGURATION_JSON environment variable. See Senzing Engine Configuration for details.

Package structure changed

v3 Package v4 Package
senzingapi-runtime senzingsdk-runtime
senzingapi-tools senzingsdk-tools
senzingapi-setup senzingsdk-setup
senzingapi senzingsdk-poc

Install path changed

v3 v4
/opt/senzing/g2/ /opt/senzing/er/

Executables changed

v3 v4
bin/g2configupgrade bin/sz_configupgrade
bin/g2dbupgrade bin/sz_dbupgrade

Executables removed

Removed Notes
dbexport A program used for retrieving data from the G2 database repository, originally built for working with different non-SQL database types

Python scripts and utilities changed

v3 v4
python/G2Audit.py bin/sz_audit
python/G2Command.py bin/sz_command
python/G2ConfigTool.py bin/sz_configtool
python/G2Explorer.py bin/sz_explorer
python/G2Loader.py bin/sz_file_loader
python/G2SetupConfig.py bin/sz_setup_config
python/G2Snapshot.py bin/sz_snapshot

Python scripts removed

Removed
CompressedFile.py
DumpStack.py
G2S3.py

Function changes

Function prefix changed

All C/C++ functions now start with the prefix Sz. Any existing functions have been renamed from G2 to Sz.

SzEngine (G2Engine) functions added

Function Notes
Sz_getRecordPreview Allows preprocessing of a record, with output similar to Sz_getRecord. Great for evaluating JSON record mapping or generating statistics prior to loading data.

SzEngine (G2Engine) functions renamed

v3 Function v4 Function
Sz_closeExport Sz_closeExportReport
G2_findPathExcludingByEntityID Sz_findPathByEntityIDWithAvoids
G2_findPathExcludingByEntityID_V2 Sz_findPathByEntityIDWithAvoids_V2
G2_findPathExcludingByRecordID Sz_findPathByRecordIDWithAvoids
G2_findPathExcludingByRecordID_V2 Sz_findPathByRecordIDWithAvoids_V2
G2_findPathIncludingSourceByEntityID Sz_findPathByEntityIDIncludingSource
G2_findPathIncludingSourceByEntityID_V2 Sz_findPathByEntityIDIncludingSource_V2
G2_findPathIncludingSourceByRecordID_V2 Sz_findPathByRecordIDIncludingSource_V2

SzEngine (G2Engine) functions removed

Several SDK functions have been removed. In most cases, another function exists with the same functionality but with an improved signature.

Removed Function Remediation
G2_addRecordWithReturnedRecordID Use Sz_addRecord and always pass in a RECORD_ID
G2_addRecordWithInfoWithReturnedRecordID Use Sz_addRecordWithInfo and always pass in a RECORD_ID
G2_whyEntityByEntityID Sz_howEntity is the preferred method for explaining resolutions
G2_whyEntityByRecordID Sz_howEntity is the preferred method for explaining resolutions
G2_process Was internal. The G2_getRedoRecord/G2_process pattern is now Sz_getRedoRecord/Sz_processRedoRecord
G2_processWithResponse Was internal, now fully removed
G2_processWithResponseResize Was internal, now fully removed
G2_exportConfig Equivalent functionality is now available in the SzConfigManager SDK
G2_exportConfigAndConfigID Equivalent functionality is now available in the SzConfigManager SDK
G2_checkRecord Internal function, now fully removed
G2_purgeRepository Moved to the internal SzDiagnostic SDK

WithInfo functions

  • The G2_addRecordWithInfo and G2_deleteRecordWithInfo functions have been removed from the Java SDK and Python SDK. The WithInfo functionality has now been included in the Sz_addRecord and Sz_deleteRecord functions when the SZ_WITH_INFO flag is used.

  • G2_processWithInfo: This was internal, though we were using it in 3.x for the G2_getRedoRecord/G2_process pattern, which is now Sz_getRedoRecord/Sz_processRedoRecord. The WithInfo functionality has now been included in the Sz_processRedoRecord function when the SZ_WITH_INFO flag is used.

  • The Sz_addRecord, Sz_deleteRecord, and Sz_processRedoRecord functions now return a null value if the SZ_WITH_INFO flag is not used.

Internal SDK changes

The following changes affect internal SDK components. Most users will not be impacted by these changes.

SzConfig (G2Config) functions renamed

v3 Function v4 Function
G2Config_addDataSource SzConfig_registerDataSource
G2Config_deleteDataSource SzConfig_unregisterDataSource
G2Config_listDataSources SzConfig_getDataSourceRegistry

SzDiagnostic functions added

Function Notes
SzDiagnostic_purgeRepository Moved here from the main SDK
SzDiagnostic_getRepositoryInfo Undocumented

SzDiagnostic functions removed

The following 18 undocumented, internal-use only functions were removed:

Removed Function
G2Diagnostic_getPhysicalCores
G2Diagnostic_getLogicalCores
G2Diagnostic_getTotalSystemMemory
G2Diagnostic_getAvailableMemory
G2Diagnostic_getDBInfo
G2Diagnostic_getDataSourceCounts
G2Diagnostic_getMappingStatistics
G2Diagnostic_getGenericFeatures
G2Diagnostic_getEntitySizeBreakdown
G2Diagnostic_getEntityDetails
G2Diagnostic_getResolutionStatistics
G2Diagnostic_getRelationshipDetails
G2Diagnostic_getEntityResume
G2Diagnostic_getEntityListBySize
G2Diagnostic_fetchNextEntityBySize
G2Diagnostic_closeEntityListBySize
G2Diagnostic_findEntitiesByFeatureIDs
G2Diagnostic_getFeature

SzAudit (G2Audit) deprecated

This SDK is now considered to be fully deprecated and should not be used anymore.

Engine flag changes

For complete flag documentation, see v4 Engine Flags .

Flag prefix changed

All flags now start with the prefix SZ_. Any existing flags have been renamed from G2_ to SZ_.

New flags

Flag Description
SZ_ENTITY_INCLUDE_RECORD_TYPES Include record types in the entity documents
SZ_ENTITY_INCLUDE_RELATED_RECORD_TYPES Include record types for related entities in the entity documents
SZ_ENTITY_INCLUDE_RECORD_UNMAPPED_DATA Include unmapped data in the entity documents
SZ_ENTITY_INCLUDE_MATCH_KEY_DETAILS Include a more detailed version of the match keys for entities and relationships
SZ_FIND_PATH_MATCHING_INFO Include the relationship matching info for entity relationship paths
SZ_FIND_NETWORK_MATCHING_INFO Include the relationship matching info for networks of related entities
SZ_FIND_NETWORK_DEFAULT_FLAGS Provides recommended information for the SDK find-network functions
SZ_HOW_ENTITY_DEFAULT_FLAGS Provides recommended information for the SDK how-functions
SZ_RECORD_PREVIEW_DEFAULT_FLAGS Provides record feature details for getRecordPreview
SZ_SEARCH_INCLUDE_MATCH_KEY_DETAILS Include the detailed match key information in search results
SZ_WHY_ENTITIES_DEFAULT_FLAGS Replaces G2_WHY_ENTITY_DEFAULT_FLAGS, focused on the whyEntities* functions
SZ_WHY_RECORDS_DEFAULT_FLAGS Replaces G2_WHY_ENTITY_DEFAULT_FLAGS, focused on the whyRecords* functions
SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS Replaces G2_WHY_ENTITY_DEFAULT_FLAGS, focused on the whyRecordInEntity* functions
SZ_WITH_INFO Provides an AFFECTED_ENTITIES list when using addRecord or deleteRecord
SZ_VIRTUAL_ENTITY_DEFAULT_FLAGS Provides recommended information for the SDK virtual-entity functions

Renamed and modified flags

v3 Flag v4 Flag Notes
G2_EXPORT_DEFAULT_FLAGS SZ_EXPORT_DEFAULT_FLAGS Reduced the information returned for each entity, to match the normal entity defaults
G2_EXPORT_INCLUDE_RESOLVED SZ_EXPORT_INCLUDE_MULTI_RECORD_ENTITIES
G2_EXPORT_INCLUDE_SINGLETONS SZ_EXPORT_INCLUDE_SINGLE_RECORD_ENTITIES
G2_EXPORT_INCLUDE_ALL_RELATIONSHIPS SZ_EXPORT_INCLUDE_ALL_HAVING_RELATIONSHIPS
G2_FIND_PATH_DEFAULT_FLAGS SZ_FIND_PATH_DEFAULT_FLAGS Returns more path-based information, and less entity information

Removed flags

Removed Flag Remediation
G2_ENTITY_INCLUDE_RECORD_FORMATTED_DATA Unmapped data is now available with the SZ_ENTITY_INCLUDE_RECORD_UNMAPPED_DATA flag
G2_WHY_ENTITY_DEFAULT_FLAGS Divided into SZ_WHY_ENTITIES_DEFAULT_FLAGS , SZ_WHY_RECORDS_DEFAULT_FLAGS , and SZ_WHY_RECORD_IN_ENTITY_DEFAULT_FLAGS

JSON response document changes

The format and contents of the JSON response documents has changed significantly.

Sz_findNetwork response document

Sz_findNetwork response document includes all Sz_getEntity* response document changes.

  • Added ENTITY_PATH_LINKS section
  • Added ENTITY_NETWORK_LINKS section

RESOLVED_ENTITY Section

  • Removed LAST_SEEN_DT
  • Added FIRST_SEEN_DT
  • Added RECORD_TYPES section

FEATURES Section

  • Added ELEMENT values

RECORD SUMMARY Section

  • Removed FIRST_SEEN_DT and LAST_SEEN_DT

RECORDS Section

  • Added FIRST_SEEN_DT
  • Added UNMAPPED_DATA section
  • Removed ENTITY_TYPE, ENTITY_KEY, ENTITY_DESC, and MATCH_LEVEL
  • Removed NAME_DATA, ATTRIBUTE_DATA, IDENTIFIER_DATA, ADDRESS_DATA, PHONE_DATA, RELATIONSHIP_DATA, ENTITY_DATA, and OTHER_DATA sections
  • Added MATCH_KEY_DETAILS
  • Added RECORD_TYPES section
  • Removed MATCH_LEVEL
  • Removed FIRST_SEEN_DT and LAST_SEEN_DT
  • Removed FIRST_SEEN_DT and LAST_SEEN_DT from RECORDS subsection

Sz_getRecord response document

RECORDS Section

  • Added FIRST_SEEN_DT
  • Added UNMAPPED_DATA section
  • Removed ENTITY_TYPE, ENTITY_KEY
  • Removed NAME_DATA, ATTRIBUTE_DATA, IDENTIFIER_DATA, ADDRESS_DATA, PHONE_DATA, RELATIONSHIP_DATA, ENTITY_DATA, and OTHER_DATA sections

Sz_howEntity response document

Sz_howEntity response document includes all Sz_getEntity* response document changes.

  • Added WHY_KEY_DETAILS section (equivalent to MATCH_KEY_DETAILS)

FEATURE_SCORES Section

  • Renamed INBOUND_FEAT to INBOUND_FEAT_DESC, CANDIDATE_FEAT to CANDIDATE_FEAT_DESC
  • Added ADDITIONAL_SCORES subsection that contains the different component scores

Sz_searchByAttributes response document

Sz_searchByAttributes response document includes all Sz_getEntity* response document changes.

RESOLVED_ENTITY Section

  • Added MATCH_KEY_DETAILS to MATCH_INFO subsection
  • Removed MATCH_LEVEL from MATCH_INFO subsection

FEATURE_SCORES Section

  • Renamed INBOUND_FEAT to INBOUND_FEAT_DESC, CANDIDATE_FEAT to CANDIDATE_FEAT_DESC
  • Added ADDITIONAL_SCORES subsection that contains the different component scores

Migration guides

For detailed migration instructions, see:

If you have any questions, contact Senzing Support. Support is 100% FREE!