Trait SzEngine 

pub trait SzEngine: Send + Sync {
    // Required methods
    fn prime_engine(&self) -> SzResult<()>;
    fn get_stats(&self) -> SzResult<JsonString>;
    fn add_record(
        &self,
        data_source_code: &str,
        record_id: &str,
        record_definition: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn get_record_preview(
        &self,
        record_definition: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn delete_record(
        &self,
        data_source_code: &str,
        record_id: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn reevaluate_record(
        &self,
        data_source_code: &str,
        record_id: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn reevaluate_entity(
        &self,
        entity_id: EntityId,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn search_by_attributes(
        &self,
        attributes: &str,
        search_profile: Option<&str>,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn why_search(
        &self,
        attributes: &str,
        entity_id: EntityId,
        search_profile: Option<&str>,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn get_entity(
        &self,
        entity_ref: EntityRef<'_>,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn get_record(
        &self,
        data_source_code: &str,
        record_id: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn find_interesting_entities(
        &self,
        entity_ref: EntityRef<'_>,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn find_path_by_entity_id(
        &self,
        start_entity_id: EntityId,
        end_entity_id: EntityId,
        max_degrees: i64,
        avoid_entity_ids: Option<&HashSet<EntityId>>,
        required_data_sources: Option<&HashSet<String>>,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn find_path_by_record_id(
        &self,
        start_data_source_code: &str,
        start_record_id: &str,
        end_data_source_code: &str,
        end_record_id: &str,
        max_degrees: i64,
        avoid_record_keys: Option<&[(&str, &str)]>,
        required_data_sources: Option<&HashSet<String>>,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn find_network_by_entity_id(
        &self,
        entity_list: &[EntityId],
        max_degrees: i64,
        build_out_degrees: i64,
        max_entities: i64,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn find_network_by_record_id(
        &self,
        record_keys: &[(&str, &str)],
        max_degrees: i64,
        build_out_degrees: i64,
        max_entities: i64,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn why_entities(
        &self,
        entity_id1: EntityId,
        entity_id2: EntityId,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn why_records(
        &self,
        data_source_code1: &str,
        record_id1: &str,
        data_source_code2: &str,
        record_id2: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn why_record_in_entity(
        &self,
        data_source_code: &str,
        record_id: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn how_entity(
        &self,
        entity_id: EntityId,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn get_virtual_entity(
        &self,
        record_keys: &[(String, String)],
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn process_redo_record(
        &self,
        redo_record: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<JsonString>;
    fn get_redo_record(&self) -> SzResult<JsonString>;
    fn count_redo_records(&self) -> SzResult<i64>;
    fn export_json_entity_report(
        &self,
        flags: Option<SzFlags>,
    ) -> SzResult<ExportHandle>;
    fn export_csv_entity_report(
        &self,
        csv_column_list: &str,
        flags: Option<SzFlags>,
    ) -> SzResult<ExportHandle>;
    fn fetch_next(&self, export_handle: ExportHandle) -> SzResult<JsonString>;
    fn close_export_report(&self, export_handle: ExportHandle) -> SzResult<()>;
}

Core entity resolution engine operations.

The SzEngine trait provides methods for adding records, retrieving entities, performing searches, and conducting various types of analysis. This is the primary interface for entity resolution operations.

Obtaining an Instance

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

Required Methods

fn prime_engine(&self) -> SzResult<()>

Primes the engine for optimal performance.

Loads internal caches and prepares the engine for high-throughput operations. Call this once after initialization when processing large batches of records.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

engine.prime_engine()?;

Errors

Returns SzError::NotInitialized if the environment is not initialized.

fn get_stats(&self) -> SzResult<JsonString>

Gets engine performance statistics.

Returns a JSON object containing internal performance metrics useful for monitoring and debugging.

Returns

JSON string with engine statistics including cache hit rates and timing data.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let stats = engine.get_stats()?;
assert!(!stats.is_empty());

fn add_record( &self, data_source_code: &str, record_id: &str, record_definition: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Adds a record for entity resolution.

Inserts or updates a record in the entity repository. The record will be matched and potentially merged with existing entities based on configured rules.

Arguments

• data_source_code - The data source identifier (must be registered)
• record_id - Unique identifier for the record within the data source
• record_definition - JSON object containing the record attributes
• flags - Optional flags controlling what information is returned

Returns

JSON string with information about affected entities (when flags request it).

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let record = r#"{"NAME_FULL": "John Smith", "ADDR_FULL": "123 Main St"}"#;
let result = engine.add_record("TEST", "ADD_1001", record, None)?;

With flags to get entity info back:

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let record = r#"{"NAME_FULL": "Jane Doe", "EMAIL": "jane@example.com"}"#;
let result = engine.add_record(
    "TEST",
    "ADD_1002",
    record,
    Some(SzFlags::WITH_INFO),
)?;
// result contains affected entity info when WITH_INFO is set

Errors

• SzError::UnknownDataSource - Data source is not registered
• SzError::BadInput - Invalid JSON or missing required fields

fn get_record_preview( &self, record_definition: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Gets a preview of how a record would be processed without persisting it.

Useful for testing record mappings and seeing how features would be extracted before committing the record to the repository.

Arguments

• record_definition - JSON object containing the record attributes
• flags - Optional flags controlling what information is returned

Returns

JSON string showing extracted features and potential matches.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let record = r#"{"NAME_FULL": "John Smith", "ADDR_FULL": "123 Main St"}"#;
let preview = engine.get_record_preview(record, None)?;

fn delete_record( &self, data_source_code: &str, record_id: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Deletes a record from the entity repository.

Removes the record and re-resolves any affected entities. If the record was the only record in an entity, the entity is also removed.

Arguments

• data_source_code - The data source identifier
• record_id - The record identifier to delete
• flags - Optional flags controlling what information is returned

Returns

JSON string with information about affected entities.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

// First add a record, then delete it
let result = engine.delete_record("TEST", "DEL_1001", None)?;

Errors

• SzError::UnknownDataSource - Data source is not registered
• SzError::NotFound - Record does not exist

fn reevaluate_record( &self, data_source_code: &str, record_id: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Reevaluates a specific record against current rules.

Forces re-resolution of a record using the current configuration. Useful after configuration changes to update entity assignments.

Arguments

• data_source_code - The data source identifier
• record_id - The record identifier to reevaluate
• flags - Optional flags controlling what information is returned

Returns

JSON string with reevaluation results.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let result = engine.reevaluate_record("TEST", "REEV_REC_1001", None)?;

Errors

• SzError::NotFound - Record does not exist

fn reevaluate_entity( &self, entity_id: EntityId, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Reevaluates all records for a specific entity.

Forces re-resolution of all records in an entity. The entity may split into multiple entities or merge with others based on current rules.

Arguments

• entity_id - The entity identifier to reevaluate
• flags - Optional flags controlling what information is returned

Returns

JSON string with reevaluation results.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let result = engine.reevaluate_entity(entity_id, None)?;

Errors

• SzError::NotFound - Entity does not exist

fn search_by_attributes( &self, attributes: &str, search_profile: Option<&str>, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Searches for entities by attributes.

Finds entities that match the provided attributes. Returns scored results based on match quality.

Arguments

• attributes - JSON object with search attributes (e.g., name, address)
• search_profile - Optional search profile name for customized matching
• flags - Optional flags controlling result detail level

Returns

JSON string with matching entities and match scores.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let attrs = r#"{"NAME_FULL": "John Smith"}"#;
let results = engine.search_by_attributes(attrs, None, None)?;

Errors

• SzError::BadInput - Invalid JSON attributes

fn why_search( &self, attributes: &str, entity_id: EntityId, search_profile: Option<&str>, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Analyzes why a search result was returned for an entity.

Provides detailed explanation of why a particular entity matched the search criteria, including feature comparisons and match scores.

Arguments

• attributes - JSON object with search attributes
• entity_id - The entity to analyze
• search_profile - Optional search profile name
• flags - Optional flags controlling detail level

Returns

JSON string with detailed match analysis.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let attrs = r#"{"NAME_FULL": "John Smith"}"#;
let result = engine.why_search(attrs, entity_id, None, None)?;

fn get_entity( &self, entity_ref: EntityRef<'_>, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Gets entity information by entity ID or record key.

Retrieves complete entity data including all constituent records and relationships. The entity can be specified either by its entity ID or by a record key (data source + record ID).

Arguments

• entity_ref - Reference to the entity (entity ID or record key)
• flags - Optional flags controlling what data is included

Returns

JSON string with entity details.

Errors

• SzError::NotFound - Entity or record does not exist

Examples

By record key:

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let entity = engine.get_entity(
    EntityRef::Record { data_source: "TEST", record_id: "ENT_1001" },
    None,
)?;

fn get_record( &self, data_source_code: &str, record_id: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Gets record information.

Retrieves the original record data as stored in the repository.

Arguments

• data_source_code - The data source identifier
• record_id - The record identifier
• flags - Optional flags controlling what data is included

Returns

JSON string with record details.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let record = engine.get_record("TEST", "REC_1001", None)?;

Errors

• SzError::NotFound - Record does not exist

fn find_interesting_entities( &self, entity_ref: EntityRef<'_>, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Finds interesting entities related to a given entity or record.

Identifies entities with notable relationships to the specified entity, such as disclosed relationships or possible matches. The entity can be specified either by its entity ID or by a record key.

Arguments

• entity_ref - Reference to the entity (entity ID or record key)
• flags - Optional flags controlling result detail

Returns

JSON string with interesting entity relationships.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let entity = engine.get_entity(
    EntityRef::Record { data_source: "TEST", record_id: "INT_1001" },
    None,
)?;
// Parse entity_id from the result, then find interesting entities

fn find_path_by_entity_id( &self, start_entity_id: EntityId, end_entity_id: EntityId, max_degrees: i64, avoid_entity_ids: Option<&HashSet<EntityId>>, required_data_sources: Option<&HashSet<String>>, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Finds the shortest path between two entities by entity ID.

Discovers the shortest path connecting two entities through their relationships, useful for understanding indirect connections.

Arguments

• start_entity_id - Starting entity
• end_entity_id - Target entity
• max_degrees - Maximum relationship hops to traverse
• avoid_entity_ids - Optional entities to exclude from the path
• required_data_sources - Optional data sources that must appear in path
• flags - Optional flags controlling result detail

Returns

JSON string with path details and intermediate entities.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let path = engine.find_path_by_entity_id(entity_id1, entity_id2, 3, None, None, None)?;

fn find_path_by_record_id( &self, start_data_source_code: &str, start_record_id: &str, end_data_source_code: &str, end_record_id: &str, max_degrees: i64, avoid_record_keys: Option<&[(&str, &str)]>, required_data_sources: Option<&HashSet<String>>, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Finds the shortest path between two entities by record key.

Identical to find_path_by_entity_id but entities are identified by their data source code and record ID instead of entity ID.

Arguments

• start_data_source_code - Data source of the start record
• start_record_id - Record ID of the start record
• end_data_source_code - Data source of the end record
• end_record_id - Record ID of the end record
• max_degrees - Maximum relationship hops to traverse
• avoid_record_keys - Optional record keys to exclude from the path
• required_data_sources - Optional data sources that must appear in path
• flags - Optional flags controlling result detail

Returns

JSON string with path details and intermediate entities.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let path = engine.find_path_by_record_id(
    "TEST", "FPBR_1001",
    "TEST", "FPBR_1002",
    3, None, None, None,
)?;

fn find_network_by_entity_id( &self, entity_list: &[EntityId], max_degrees: i64, build_out_degrees: i64, max_entities: i64, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Finds a network of related entities by entity ID.

Builds a network graph starting from one or more seed entities, expanding outward through relationships.

Arguments

• entity_list - Seed entity IDs to start from
• max_degrees - Maximum relationship hops from seed entities
• build_out_degrees - Degrees to expand for building connections
• max_entities - Maximum entities to include in the network
• flags - Optional flags controlling result detail

Returns

JSON string with network graph data.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let network = engine.find_network_by_entity_id(&[entity_id], 3, 1, 100, None)?;

fn find_network_by_record_id( &self, record_keys: &[(&str, &str)], max_degrees: i64, build_out_degrees: i64, max_entities: i64, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Finds a network of related entities by record key.

Identical to find_network_by_entity_id but entities are identified by their data source code and record ID instead of entity ID.

Arguments

• record_keys - Seed record keys as (data_source_code, record_id) pairs
• max_degrees - Maximum relationship hops from seed entities
• build_out_degrees - Degrees to expand for building connections
• max_entities - Maximum entities to include in the network
• flags - Optional flags controlling result detail

Returns

JSON string with network graph data.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let network = engine.find_network_by_record_id(
    &[("TEST", "FNBR_1001")],
    3, 1, 100, None,
)?;

fn why_entities( &self, entity_id1: EntityId, entity_id2: EntityId, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Analyzes why two entities are related.

Provides detailed explanation of the relationship between two entities, including shared features and match scores.

Arguments

• entity_id1 - First entity
• entity_id2 - Second entity
• flags - Optional flags controlling detail level

Returns

JSON string with relationship analysis.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let result = engine.why_entities(entity_id1, entity_id2, None)?;

fn why_records( &self, data_source_code1: &str, record_id1: &str, data_source_code2: &str, record_id2: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Analyzes why two records resolved together.

Explains why two specific records were merged into the same entity, showing the matching features and rules that caused the merge.

Arguments

• data_source_code1 - First record’s data source
• record_id1 - First record’s identifier
• data_source_code2 - Second record’s data source
• record_id2 - Second record’s identifier
• flags - Optional flags controlling detail level

Returns

JSON string with merge analysis.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let result = engine.why_records("TEST", "WHYR_1001", "TEST", "WHYR_1002", None)?;

fn why_record_in_entity( &self, data_source_code: &str, record_id: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Analyzes why a record belongs to its entity.

Explains the chain of matches that connected a record to its current entity assignment.

Arguments

• data_source_code - The record’s data source
• record_id - The record identifier
• flags - Optional flags controlling detail level

Returns

JSON string with entity membership analysis.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let result = engine.why_record_in_entity("TEST", "WRIE_1001", None)?;

fn how_entity( &self, entity_id: EntityId, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Analyzes how an entity was constructed.

Provides a step-by-step explanation of how records were merged to form the current entity, useful for understanding complex resolution paths.

Arguments

• entity_id - The entity to analyze
• flags - Optional flags controlling detail level

Returns

JSON string with entity construction history.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let result = engine.how_entity(entity_id, None)?;

fn get_virtual_entity( &self, record_keys: &[(String, String)], flags: Option<SzFlags>, ) -> SzResult<JsonString>

Creates a virtual entity from record keys without persisting.

Simulates what an entity would look like if the specified records were merged, without affecting the actual repository.

Arguments

• record_keys - Pairs of (data_source_code, record_id)
• flags - Optional flags controlling result detail

Returns

JSON string with virtual entity data.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let record_keys = vec![
    ("TEST".to_string(), "VIRT_1001".to_string()),
    ("TEST".to_string(), "VIRT_1002".to_string()),
];
let result = engine.get_virtual_entity(&record_keys, None)?;

fn process_redo_record( &self, redo_record: &str, flags: Option<SzFlags>, ) -> SzResult<JsonString>

Processes a redo record for deferred resolution.

Handles records that were queued for later processing due to conflicts or resource constraints.

Arguments

• redo_record - The redo record JSON from get_redo_record
• flags - Optional flags controlling result detail

Returns

JSON string with processing results.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let redo = engine.get_redo_record()?;
if !redo.is_empty() {
    let result = engine.process_redo_record(&redo, None)?;
}

fn get_redo_record(&self) -> SzResult<JsonString>

Gets the next pending redo record.

Retrieves one record from the redo queue for processing.

Returns

JSON string with redo record data, or empty string if queue is empty.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let redo = engine.get_redo_record()?;
if redo.is_empty() {
    println!("No redo records pending");
}

fn count_redo_records(&self) -> SzResult<i64>

Counts pending redo records.

Returns

Number of records waiting in the redo queue.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let count = engine.count_redo_records()?;
println!("Pending redo records: {}", count);

fn export_json_entity_report( &self, flags: Option<SzFlags>, ) -> SzResult<ExportHandle>

Starts a JSON entity export.

Initiates an export operation returning a handle for fetching results. Use fetch_next to retrieve data and close_export_report when done.

Arguments

• flags - Optional flags controlling what data is exported

Returns

Handle for fetching export data.

Examples

Export all entities as JSON (full export loop):

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let handle = engine.export_json_entity_report(None)?;
loop {
    let chunk = engine.fetch_next(handle)?;
    if chunk.is_empty() {
        break;
    }
    print!("{}", chunk);
}
engine.close_export_report(handle)?;

fn export_csv_entity_report( &self, csv_column_list: &str, flags: Option<SzFlags>, ) -> SzResult<ExportHandle>

Starts a CSV entity export.

Initiates a CSV export with specified columns.

Arguments

• csv_column_list - Comma-separated list of columns to include
• flags - Optional flags controlling what data is exported

Returns

Handle for fetching export data.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let handle = engine.export_csv_entity_report(
    "RESOLVED_ENTITY_ID,RELATED_ENTITY_ID,MATCH_LEVEL_CODE",
    None,
)?;
loop {
    let chunk = engine.fetch_next(handle)?;
    if chunk.is_empty() {
        break;
    }
    print!("{}", chunk);
}
engine.close_export_report(handle)?;

fn fetch_next(&self, export_handle: ExportHandle) -> SzResult<JsonString>

Fetches the next batch of export data.

Call repeatedly until empty string is returned to get all export data.

Arguments

• export_handle - Handle from export_json_entity_report or export_csv_entity_report

Returns

Next batch of export data, or empty string when complete.

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let handle = engine.export_json_entity_report(None)?;
let chunk = engine.fetch_next(handle)?;
// Empty string means no more data
engine.close_export_report(handle)?;

fn close_export_report(&self, export_handle: ExportHandle) -> SzResult<()>

Closes an export operation and releases resources.

Must be called when finished with an export to free the handle.

Arguments

• export_handle - Handle to close

Examples

use sz_rust_sdk::prelude::*;

let engine = env.get_engine()?;

let handle = engine.export_json_entity_report(None)?;
// ... fetch data ...
engine.close_export_report(handle)?;

Implementors

impl SzEngine for SzEngineCore