Interface SzEngine

Namespace: Senzing.Sdk

Assembly: Senzing.Sdk.dll

Defines the interface to the Senzing engine functions.

public interface SzEngine

Examples

An SzEngine instance is typically obtained from an SzEnvironment instance via the GetEngine() method as follows.

For example:

// How to obtain an SzEngine instance
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to get SzEngine.", e);
}

Remarks

The Senzing engine functions primarily provide means of working with identity data records, entities and their relationships.

Methods

AddRecord(string, string, string, SzFlag?)

Loads the record described by the specified string record definition having the specified data source code and record ID using the specified bitwise-OR'd SzFlag values.

string AddRecord(string dataSourceCode, string recordID, string recordDefinition, SzFlag? flags = (SzFlag)0)

Parameters

dataSourceCode string: The data source code identifying the data source for the record being added.
recordID string: The record ID that uniquely identifies the record being added within the scope of its associated data source.
recordDefinition string: The string that defines the record, typically in JSON format.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzAddRecordFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzAddRecordDefaultFlags. Specify SzWithInfo for an INFO response. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string result produced by adding the record to the repository, or null if the specified flags do not indicate that an INFO message should be returned.

Examples

Usage:

// How to load a record
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get a record definition (varies by application)
    string recordDefinition =
            """
            {
                "DATA_SOURCE": "TEST",
                "RECORD_ID": "ABC123",
                "NAME_FULL": "Joe Schmoe",
                "PHONE_NUMBER": "702-555-1212",
                "EMAIL_ADDRESS": "joeschmoe@nowhere.com"
            }
            """;

    // add the record to the repository
    string infoJson = engine.AddRecord(
        "TEST", "ABC123", recordDefinition, SzWithInfo);

    // do something with the "info JSON" (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(infoJson)?.AsObject();
    if (jsonObject != null && jsonObject.ContainsKey("AFFECTED_ENTITIES"))
    {
        JsonArray? affectedArr = jsonObject["AFFECTED_ENTITIES"]?.AsArray();
        for (int index = 0; affectedArr != null && index < affectedArr.Count; index++)
        {
            JsonObject? affected = affectedArr[index]?.AsObject();
            long affectedID = affected?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to add record.", e);
}

Remarks

If a record already exists with the same data source code and record ID, then it will be replaced.

The specified JSON data may optionally contain the DATA_SOURCE and RECORD_ID properties, but, if so, they must match the specified parameters.

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzAddRecordFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzBadInputException: If the specified record definition has a data source or record ID value that conflicts with the specified data source code and/or record ID values.
SzException: If a failure occurs.

See Also: SzNoFlags

SzWithInfo

SzAddRecordDefaultFlags

SzAddRecordFlags

Code Snippet: Load Records

Code Snippet: Load Truth Set "With Info"

Code Snippet: Load via Futures

Code Snippet: Load via Loop

Code Snippet: Load via Queue

Code Snippet: Load "With Info" via Futures

Code Snippet: Load "With Stats" Via Loop

CloseExport(IntPtr)

This function closes an export handle of a previously opened export to clean up system resources.

void CloseExport(IntPtr exportHandle)

Parameters

exportHandle IntPtr: The export handle of the export to close.

Examples

Usage (JSON Export):

// How to export entity data in JSON format
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // export the JSON data
    IntPtr exportHandle = engine.ExportJsonEntityReport(SzExportDefaultFlags);

    // read the data
    try
    {
        // fetch the first JSON record
        string jsonData = engine.FetchNext(exportHandle);

        while (jsonData != null)
        {
            // parse the JSON data
            JsonObject? jsonObject = JsonNode.Parse(jsonData)?.AsObject();

            // do something with the parsed data (varies by application)
            ProcessJsonRecord(jsonObject);

            // fetch the next JSON record
            jsonData = engine.FetchNext(exportHandle);
        }

    }
    finally
    {
        // close the export handle
        engine.CloseExport(exportHandle);
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to perform JSON export.", e);
}

Usage (CSV Export):

// How to export entity data in CSV format
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // export the JSON data
    IntPtr exportHandle = engine.ExportCsvEntityReport("*", SzExportDefaultFlags);

    // read the data
    try
    {
        // fetch the CSV header line from the exported data
        string csvHeaders = engine.FetchNext(exportHandle);

        // process the CSV headers (varies by application)
        ProcessCsvHeaders(csvHeaders);

        // fetch the first CSV record from the exported data
        string csvRecord = engine.FetchNext(exportHandle);

        while (csvRecord != null)
        {
            // do something with the exported record (varies by application)
            ProcessCsvRecord(csvRecord);

            // fetch the next exported CSV record
            csvRecord = engine.FetchNext(exportHandle);
        }

    }
    finally
    {
        // close the export handle
        engine.CloseExport(exportHandle);
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to perform CSV export.", e);
}

Remarks

This function is idempotent and may be called for an export that has already been closed.

Exceptions

SzException: If a failure occurs.

See Also: FetchNext(IntPtr)

ExportJsonEntityReport(SzFlag?)

ExportCsvEntityReport(string, SzFlag?)

CountRedoRecords()

Gets the number of redo records pending to be processed.

long CountRedoRecords()

Returns

long: The number of redo records pending to be processed.

Examples

Usage:

// How to check for and process redo records
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the redo count
    long redoCount = engine.CountRedoRecords();

    // check if we have redo records
    if (redoCount > 0L)
    {
        // get the next redo record
        string redoRecord = engine.GetRedoRecord();

        // loop while we still have redo records
        while (redoRecord != null)
        {
            try
            {
                // process the redo record
                string infoJson = engine.ProcessRedoRecord(redoRecord, SzEntityDefaultFlags);

                // do something with the "info JSON" (varies by application)
                JsonObject? jsonObject = JsonNode.Parse(infoJson)?.AsObject();
                if (jsonObject != null && jsonObject.ContainsKey("AFFECTED_ENTITIES"))
                {
                    JsonArray? affectedArr = jsonObject["AFFECTED_ENTITIES"]?.AsArray();
                    for (int index = 0; affectedArr != null && index < affectedArr.Count; index++)
                    {
                        JsonObject? affected = affectedArr[index]?.AsObject();
                        long affectedID = affected?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

                        . . .
                    }
                }

            }
            catch (SzException e)
            {
                // handle or rethrow the other exceptions
                LogError("Failed to process redo record: " + redoRecord, e);
            }

            // get the next redo record
            redoRecord = engine.GetRedoRecord();
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to process redos.", e);
}

Exceptions

SzException: If a failure occurs.

See Also: ProcessRedoRecord(string, SzFlag?)

GetRedoRecord()

Code Snippet: Processing Redos while Loading

Code Snippet: Continuous Redo Processing

Code Snippet: Continuous Redo Processing via Futures

Code Snippet: Continuous Redo "With Info" Processing

DeleteRecord(string, string, SzFlag?)

Delete a previously loaded record identified by the specified data source code and record ID.

string DeleteRecord(string dataSourceCode, string recordID, SzFlag? flags = (SzFlag)0)

Parameters

dataSourceCode string: The data source code identifying the data source for the record being deleted.
recordID string: The record ID that uniquely identifies the record being deleted within the scope of its associated data source.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzDeleteRecordFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzDeleteRecordDefaultFlags. Specify SzWithInfo for an INFO response. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string result produced by deleting the record from the repository, or null if the specified flags do not indicate that an INFO message should be returned.

Examples

Usage:

// How to delete a record
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // delete the record from the repository
    string infoJson = engine.DeleteRecord("TEST", "ABC123", SzWithInfo);

    // do something with the "info JSON" (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(infoJson)?.AsObject();
    if (jsonObject != null && jsonObject.ContainsKey("AFFECTED_ENTITIES"))
    {
        JsonArray? affectedArr = jsonObject["AFFECTED_ENTITIES"]?.AsArray();

        for (int index = 0; affectedArr != null && index < affectedArr.Count; index++)
        {
            JsonObject? affected = affectedArr[index]?.AsObject();

            long affectedID = affected?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to delete record.", e);
}

Remarks

This method is idempotent, meaning multiple calls this method with the same parameters will all succeed regardless of whether or not the record is found in the repository.

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzDeleteRecordFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzException: If a failure occurs.

See Also: SzNoFlags

SzWithInfo

SzDeleteRecordFlags

SzDeleteRecordDefaultFlags

Code Snippet: Delete via Loop

Code Snippet: Delete via Futures

Code Snippet: Delete "With Info" via Futures

ExportCsvEntityReport(string, SzFlag?)

Initiates an export of entity data in CSV format and returns an "export handle" that can be used to read the export data and must be closed when complete.

IntPtr ExportCsvEntityReport(string csvColumnList, SzFlag? flags = SzFlag.SzExportIncludeMultiRecordEntities | SzFlag.SzExportIncludeSingleRecordEntities | SzFlag.SzEntityIncludePossiblySameRelations | SzFlag.SzEntityIncludePossiblyRelatedRelations | SzFlag.SzEntityIncludeNameOnlyRelations | SzFlag.SzEntityIncludeDisclosedRelations | SzFlag.SzEntityIncludeRepresentativeFeatures | SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzEntityIncludeRecordData | SzFlag.SzEntityIncludeRecordMatchingInfo | SzFlag.SzEntityIncludeRelatedEntityName | SzFlag.SzEntityIncludeRelatedMatchingInfo | SzFlag.SzEntityIncludeRelatedRecordSummary)

Parameters

csvColumnList string: Specify "*" to indicate "all columns", specify empty-string to indicate the "standard columns", otherwise specify a comma-separated list of column names.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzExportFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzExportDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

IntPtr: The export handle to use for retrieving the export data.

Examples

Usage:

// How to export entity data in CSV format
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // export the JSON data
    IntPtr exportHandle = engine.ExportCsvEntityReport("*", SzExportDefaultFlags);

    // read the data
    try
    {
        // fetch the CSV header line from the exported data
        string csvHeaders = engine.FetchNext(exportHandle);

        // process the CSV headers (varies by application)
        ProcessCsvHeaders(csvHeaders);

        // fetch the first CSV record from the exported data
        string csvRecord = engine.FetchNext(exportHandle);

        while (csvRecord != null)
        {
            // do something with the exported record (varies by application)
            ProcessCsvRecord(csvRecord);

            // fetch the next exported CSV record
            csvRecord = engine.FetchNext(exportHandle);
        }

    }
    finally
    {
        // close the export handle
        engine.CloseExport(exportHandle);
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to perform CSV export.", e);
}

Remarks

The first exported line contains the CSV header and each subsequent line contains the exported entity data for a single resolved entity.

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzExportFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzException: If a failure occurs.

See Also: SzExportDefaultFlags

SzExportFlags

FetchNext(IntPtr)

CloseExport(IntPtr)

ExportJsonEntityReport(SzFlag?)

ExportJsonEntityReport(SzFlag?)

Initiates an export of entity data as JSON-lines format and returns an "export handle" that can be used to read the export data and must be closed when complete.

IntPtr ExportJsonEntityReport(SzFlag? flags = SzFlag.SzExportIncludeMultiRecordEntities | SzFlag.SzExportIncludeSingleRecordEntities | SzFlag.SzEntityIncludePossiblySameRelations | SzFlag.SzEntityIncludePossiblyRelatedRelations | SzFlag.SzEntityIncludeNameOnlyRelations | SzFlag.SzEntityIncludeDisclosedRelations | SzFlag.SzEntityIncludeRepresentativeFeatures | SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzEntityIncludeRecordData | SzFlag.SzEntityIncludeRecordMatchingInfo | SzFlag.SzEntityIncludeRelatedEntityName | SzFlag.SzEntityIncludeRelatedMatchingInfo | SzFlag.SzEntityIncludeRelatedRecordSummary)

Parameters

flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzExportFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzExportDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

IntPtr: The export handle to use for retrieving the export data.

Examples

Usage:

// How to export entity data in JSON format
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // export the JSON data
    IntPtr exportHandle = engine.ExportJsonEntityReport(SzExportDefaultFlags);

    // read the data
    try
    {
        // fetch the first JSON record
        string jsonData = engine.FetchNext(exportHandle);

        while (jsonData != null)
        {
            // parse the JSON data
            JsonObject? jsonObject = JsonNode.Parse(jsonData)?.AsObject();

            // do something with the parsed data (varies by application)
            ProcessJsonRecord(jsonObject);

            // fetch the next JSON record
            jsonData = engine.FetchNext(exportHandle);
        }

    }
    finally
    {
        // close the export handle
        engine.CloseExport(exportHandle);
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to perform JSON export.", e);
}

Remarks

Each output line contains the exported entity data for a single resolved entity.

Exceptions

SzException: If a failure occurs.

See Also: SzExportDefaultFlags

SzExportFlags

FetchNext(IntPtr)

CloseExport(IntPtr)

ExportCsvEntityReport(string, SzFlag?)

FetchNext(IntPtr)

Fetches the next line of entity data from the export identified by the specified export handle.

string FetchNext(IntPtr exportHandle)

Parameters

exportHandle IntPtr: The export handle to identify the export from which to retrieve the next line of data.

Returns

string: The next line of export data whose format depends on which function was used to initiate the export, or null if there is no more data to be exported via the specified handle.

Examples

Usage (JSON Export):

// How to export entity data in JSON format
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // export the JSON data
    IntPtr exportHandle = engine.ExportJsonEntityReport(SzExportDefaultFlags);

    // read the data
    try
    {
        // fetch the first JSON record
        string jsonData = engine.FetchNext(exportHandle);

        while (jsonData != null)
        {
            // parse the JSON data
            JsonObject? jsonObject = JsonNode.Parse(jsonData)?.AsObject();

            // do something with the parsed data (varies by application)
            ProcessJsonRecord(jsonObject);

            // fetch the next JSON record
            jsonData = engine.FetchNext(exportHandle);
        }

    }
    finally
    {
        // close the export handle
        engine.CloseExport(exportHandle);
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to perform JSON export.", e);
}

Usage (CSV Export):

// How to export entity data in CSV format
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // export the JSON data
    IntPtr exportHandle = engine.ExportCsvEntityReport("*", SzExportDefaultFlags);

    // read the data
    try
    {
        // fetch the CSV header line from the exported data
        string csvHeaders = engine.FetchNext(exportHandle);

        // process the CSV headers (varies by application)
        ProcessCsvHeaders(csvHeaders);

        // fetch the first CSV record from the exported data
        string csvRecord = engine.FetchNext(exportHandle);

        while (csvRecord != null)
        {
            // do something with the exported record (varies by application)
            ProcessCsvRecord(csvRecord);

            // fetch the next exported CSV record
            csvRecord = engine.FetchNext(exportHandle);
        }

    }
    finally
    {
        // close the export handle
        engine.CloseExport(exportHandle);
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to perform CSV export.", e);
}

Remarks

The specified export handle can be obtained from ExportJsonEntityReport(SzFlag?) or ExportCsvEntityReport(string, SzFlag?).

Exceptions

SzException: If a failure occurs.

See Also: CloseExport(IntPtr)

ExportJsonEntityReport(SzFlag?)

ExportCsvEntityReport(string, SzFlag?)

FindInterestingEntities(long, SzFlag?)

An experimental method to obtain interesting entities pertaining to the entity identified by the specified entity ID using the specified flags.

string FindInterestingEntities(long entityID, SzFlag? flags = (SzFlag)0)

Parameters

entityID long: The entity ID identifying the entity that will be the focus for the interesting entities to be returned.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzFindInterestingEntitiesFlags group control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzFindInterestingEntitiesDefaultFlags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the interesting entities.

Examples

Usage:

// How to find interesting entities related to an entity via entity ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the ID of an entity to retrieve (varies by application)
    long entityID = GetEntityID();

    // find the interesting entities by entity ID
    string responseJson = engine.FindInterestingEntities(
        entityID, SzFindInterestingEntitiesDefaultFlags);

    // do something with the response JSON (varies by application)                
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();

    . . .

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for entity ID.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to find interesting entities by entity ID.", e);
}

Remarks

The result is returned as a JSON document describing the interesting entities.

The optionally specified bitwise-OR'd SzFlag values may contain any flags, but only flags belonging to the SzFindInterestingEntitiesFlags group are guaranteed to be recognized (other SzFlag instances will be ignored unless they have equivalent bit flags to supported flags).

Exceptions

SzNotFoundException: If no entity could be found with the specified entity ID.
SzException: If a failure occurs.

See Also: SzNoFlags

SzFindInterestingEntitiesDefaultFlags

SzFindInterestingEntitiesFlags

FindInterestingEntities(string, string, SzFlag?)

An experimental method to obtain interesting entities pertaining to the entity that contains a specific record that is identified by the specified data source code and record ID using the specified flags.

string FindInterestingEntities(string dataSourceCode, string recordID, SzFlag? flags = (SzFlag)0)

Parameters

dataSourceCode string: The data source code that identifies the data source of the constituent record belonging to the entity that is the focus for the interesting entities to be returned.
recordID string: The record ID (unique within the scope of the record's data source) identifying the constituent record belonging to the entity that is the focus for the interesting entities to be returned.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzFindInterestingEntitiesFlags group control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzFindInterestingEntitiesDefaultFlags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the interesting entities.

Examples

Usage:

// How to find interesting entities related to an entity via record key
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // retrieve the entity by record key                
    string responseJson = engine.FindInterestingEntities(
        "TEST", "ABC123", SzFindInterestingEntitiesDefaultFlags);

    // do something with the response JSON (varies by application)                
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();

    . . .

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for record key.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to find interesting entities by record key.", e);
}

Remarks

The result is returned as a JSON document describing the interesting entities.

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzNotFoundException: If no record can be found for the specified record ID.
SzException: If a failure occurs.

FindNetwork(ISet<long>, int, int, int, SzFlag?)

Finds a network of entity relationships surrounding the paths between a set of entities identified by one or more long entity ID's included in the specified ISet<T>.

string FindNetwork(ISet<long> entityIDs, int maxDegrees, int buildOutDegrees, int buildOutMaxEntities, SzFlag? flags = SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzFindNetworkIncludeMatchingInfo)

Parameters

entityIDs ISet<long>: The non-null ISet<T> of long entity ID's identifying the entities for which to build the network.
maxDegrees int: The maximum number of degrees for the path search between the specified entities.
buildOutDegrees int: The number of relationship degrees to build out from each of the found entities on the network, or zero to prevent network build-out.
buildOutMaxEntities int: The maximum number of entities to build out for the entire network.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzFindNetworkFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to the default recommended flags (SzFindNetworkDefaultFlags). Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the resultant entity network and the entities on the network.

Examples

Usage:

// How to find an entity network using entity ID's
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get entity ID's for the path endpoints (varies by application)
    ISet<long> entityIDs = GetNetworkEntityIDs();

    // determine the maximum path degrees (varies by application)
    int maxDegrees = 3;

    // determine the degrees to build-out the network (varies by application)
    int buildOutDegrees = 0;

    // determine the max entities to build-out (varies by application)
    int buildOutMaxEntities = 10;

    // retrieve the entity network using the entity ID's
    string responseJson = engine.FindNetwork(entityIDs,
                                             maxDegrees,
                                             buildOutDegrees,
                                             buildOutMaxEntities,
                                             SzFindNetworkDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? pathArr = jsonObject?["ENTITY_PATHS"]?.AsArray();

    for (int index = 0; pathArr != null && index < pathArr.Count; index++)
    {
        JsonObject? path = pathArr[index]?.AsObject();

        long startEntityID = path?["START_ENTITY_ID"]?.GetValue<long>() ?? 0L;
        long endEntityID = path?["END_ENTITY_ID"]?.GetValue<long>() ?? 0L;
        JsonArray? pathIDs = path?["ENTITIES"]?.AsArray();

        for (int index2 = 0; pathIDs != null && index2 < pathIDs.Count; index2++)
        {
            long entityID = pathIDs[index2]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for entity ID.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve entity network.", e);
}

Remarks

Additionally, the maximum degrees of separation for the paths between entities must be specified so as to prevent the network growing beyond the desired size. Further, a non-zero number of degrees to build out the network may be specified to find other related entities. If build out is specified, it can be limited to a maximum total number of build-out entities for the whole network.

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzFindNetworkFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzNotFoundException: If any of the entities for the specified entity ID's cannot be found.
SzException: If a failure occurs.

See Also: SzFindNetworkDefaultFlags

SzFindNetworkFlags

FindNetwork(ISet<(string dataSourceCode, string recordID)>, int, int, int, SzFlag?)

FindNetwork(ISet<(string dataSourceCode, string recordID)>, int, int, int, SzFlag?)

Finds a network of entity relationships surrounding the paths between a set of entities having the constituent records identified by the tuples of data source code and record ID pairs included in the specified ISet<T>.

string FindNetwork(ISet<(string dataSourceCode, string recordID)> recordKeys, int maxDegrees, int buildOutDegrees, int buildOutMaxEntities, SzFlag? flags = SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzFindNetworkIncludeMatchingInfo)

Parameters

recordKeys ISet<(string dataSourceCode, string recordID)>: The non-null ISet<T> of tuples of data source code and record ID pairs identifying the constituent records of the entities for which to build the network.
maxDegrees int: The maximum number of degrees for the path search between the specified entities.
buildOutDegrees int: The number of relationship degrees to build out from each of the found entities on the network, or zero to prevent network build-out.
buildOutMaxEntities int: The maximum number of entities to build out for the entire network.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzFindNetworkFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to the default recommended flags (SzFindNetworkDefaultFlags). Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the resultant entity network and the entities on the network.

Examples

Usage:

// How to find an entity network using record keys
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get entity ID's for the path endpoints (varies by application)
    ISet<(string, string)> recordKeys = GetNetworkRecordKeys();

    // determine the maximum path degrees (varies by application)
    int maxDegrees = 3;

    // determine the degrees to build-out the network (varies by application)
    int buildOutDegrees = 0;

    // determine the max entities to build-out (varies by application)
    int buildOutMaxEntities = 10;

    // retrieve the entity network using the record keys
    string responseJson = engine.FindNetwork(recordKeys,
                                             maxDegrees,
                                             buildOutDegrees,
                                             buildOutMaxEntities,
                                             SzFindNetworkDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? pathArr = jsonObject?["ENTITY_PATHS"]?.AsArray();

    for (int index = 0; pathArr != null && index < pathArr.Count; index++)
    {
        JsonObject? path = pathArr[index]?.AsObject();

        long startEntityID = path?["START_ENTITY_ID"]?.GetValue<long>() ?? 0L;
        long endEntityID = path?["END_ENTITY_ID"]?.GetValue<long>() ?? 0L;
        JsonArray? pathIDs = path?["ENTITIES"]?.AsArray();

        for (int index2 = 0; pathIDs != null && index2 < pathIDs.Count; index2++)
        {
            long entityID = pathIDs[index2]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for record key.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve entity network.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzFindNetworkFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzNotFoundException: If any of the records for the specified data source code and record ID pairs cannot be found.
SzException: If a failure occurs.

See Also: SzFindNetworkDefaultFlags

SzFindNetworkFlags

FindNetwork(ISet<long>, int, int, int, SzFlag?)

FindPath(long, long, int, ISet<long>, ISet<string>, SzFlag?)

Finds a relationship path between two entities identified by their entity ID's.

string FindPath(long startEntityID, long endEntityID, int maxDegrees, ISet<long> avoidEntityIDs = null, ISet<string> requiredDataSources = null, SzFlag? flags = SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzFindPathIncludeMatchingInfo)

Parameters

startEntityID long: The entity ID of the first entity.
endEntityID long: The entity ID of the second entity.
maxDegrees int: The maximum number of degrees for the path search.
avoidEntityIDs ISet<long>: The optional ISet<T> of long entity ID's identifying entities to be avoided when finding the path, or null if no entities are to be avoided.
requiredDataSources ISet<string>: The optional ISet<T> of non-null string data source codes identifying the data sources for which at least one record must be included on the path, or null if none are required.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzFindPathFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to the default recommended flags (SzFindPathDefaultFlags). Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the resultant entity path which may be an empty path if no path exists between the two entities given the path parameters.

Examples

Usage:

// How to find an entity path using entity ID's
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get entity ID's for the path endpoints (varies by application)
    long startEntityID = GetPathStartEntityID();
    long endEntityID = GetPathEndEntityID();

    // determine the maximum path degrees (varies by application)
    int maxDegrees = 4;

    // determine any entities to be avoided (varies by application)
    ISet<long> avoidEntities = GetPathAvoidEntityIDs();

    // determine any data sources to require in the path (varies by application)
    ISet<string>? requiredSources = null;

    // retrieve the entity path using the entity ID's
    string responseJson = engine.FindPath(startEntityID,
                                          endEntityID,
                                          maxDegrees,
                                          avoidEntities,
                                          requiredSources,
                                          SzFindPathDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? pathArr = jsonObject?["ENTITY_PATHS"]?.AsArray();

    for (int index = 0; pathArr != null && index < pathArr.Count; index++)
    {
        JsonObject? path = pathArr[index]?.AsObject();
        JsonArray? entityIDs = path?["ENTITIES"]?.AsArray();

        for (int index2 = 0; entityIDs != null && index2 < entityIDs.Count; index2++)
        {
            long entityID = entityIDs[index2]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for entity ID.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve entity path by entity ID.", e);
}

Remarks

Entities to be avoided when finding the path may optionally be specified as a non-null ISet<T> of long entity ID's identifying entities to be avoided. By default the specified entities will be avoided unless absolutely necessary to find the path. To strictly avoid the specified entities specify the SzFindPathStrictAvoid flag.

Further, a ISet<T> of string data source codes may optionally be specified to identify required data sources. If specified as non-null, then the required data sources set contains non-null string data source codes that identify data sources for which a record from at least one must exist on the path.

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the level of detail provided for the entity path and those entities on the path. Any SzFlag value may be included, but only flags belonging to the SzFindPathFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzNotFoundException: If either the path-start or path-end entities for the specified entity ID's cannot be found.
SzUnknownDataSourceException: If an unrecognized required data source is specified.
SzException: If a failure occurs.

See Also: SzFindPathDefaultFlags

SzFindPathFlags

FindPath(string, string, string, string, int, ISet<(string dataSourceCode, string recordID)>, ISet<string>, SzFlag?)

FindPath(string, string, string, string, int, ISet<(string dataSourceCode, string recordID)>, ISet<string>, SzFlag?)

Finds a relationship path between two entities identified by the specified data source codes and record ID's of their constituent records.

string FindPath(string startDataSourceCode, string startRecordID, string endDataSourceCode, string endRecordID, int maxDegrees, ISet<(string dataSourceCode, string recordID)> avoidRecordKeys = null, ISet<string> requiredDataSources = null, SzFlag? flags = SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzFindPathIncludeMatchingInfo)

Parameters

startDataSourceCode string: The data source code identifying the data source for the starting record of the requested path.
startRecordID string: The record ID that uniquely identifies the starting record of the requested path within the scope of its associated data source.
endDataSourceCode string: The data source code identifying the data source for the ending record of the requested path.
endRecordID string: The record ID that uniquely identifies the ending record of the requested path within the scope of its associated data source.
maxDegrees int: The maximum number of degrees for the path search.
avoidRecordKeys ISet<(string dataSourceCode, string recordID)>: The optional ISet<T> of tuples containing data source code and record ID pairs identifying records whose entities are to be avoided when finding the path, or null if no entities are to be avoided.
requiredDataSources ISet<string>: The optionalISet<T> of non-null string data source codes identifying the data sources for which at least one record must be included on the path, or null if none are required.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzFindPathFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to the default recommended flags (SzFindPathDefaultFlags). Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the resultant entity path which may be an empty path if no path exists between the two entities given the path parameters.

Examples

Usage:

// How to find an entity path using record keys
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get entity ID's for the path endpoints (varies by application)
    (string dataSourceCode, string recordID) startRecordKey = GetPathStartRecordKey();
    (string dataSourceCode, string recordID) endRecordKey = GetPathEndRecordKey();

    // determine the maximum path degrees (varies by application)
    int maxDegrees = 4;

    // determine any records to be avoided (varies by application)
    ISet<(string, string)> avoidRecords = GetPathAvoidRecordKeys();

    // determine any data sources to require in the path (varies by application)
    ISet<string>? requiredSources = null;

    // retrieve the entity path using the record keys
    string responseJson = engine.FindPath(startRecordKey.dataSourceCode,
                                          startRecordKey.recordID,
                                          endRecordKey.dataSourceCode,
                                          endRecordKey.recordID,
                                          maxDegrees,
                                          avoidRecords,
                                          requiredSources,
                                          SzFindPathDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? pathArr = jsonObject?["ENTITY_PATHS"]?.AsArray();

    for (int index = 0; pathArr != null && index < pathArr.Count; index++)
    {
        JsonObject? path = pathArr[index]?.AsObject();
        JsonArray? entityIDs = path?["ENTITIES"]?.AsArray();

        for (int index2 = 0; entityIDs != null && index2 < entityIDs.Count; index2++)
        {
            long entityID = entityIDs[index2]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for record key.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve entity path by record key.", e);
}

Remarks

Entities to be avoided when finding the path may optionally be specified as a non-null ISet<T> of tuples of data source code and record ID pairs identifying the constituent records of entities to be avoided. By default the associated entities will be avoided unless absolutely necessary to find the path. To strictly avoid the associated entities specify the SzFindPathStrictAvoid flag.

The optionally specified bitwise-OR'd SzFlag values may contain any SzFlag value, but only flags belonging to the SzFindPathFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags).

Exceptions

SzNotFoundException: If either the path-start or path-end records for the specified data source code and record ID pairs cannot be found.
SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzException: If a failure occurs.

See Also: SzFindPathDefaultFlags

SzFindPathFlags

FindPath(long, long, int, ISet<long>, ISet<string>, SzFlag?)

GetEntity(long, SzFlag?)

This method is used to retrieve information about a specific resolved entity.

string GetEntity(long entityID, SzFlag? flags = SzFlag.SzEntityIncludePossiblySameRelations | SzFlag.SzEntityIncludePossiblyRelatedRelations | SzFlag.SzEntityIncludeNameOnlyRelations | SzFlag.SzEntityIncludeDisclosedRelations | SzFlag.SzEntityIncludeRepresentativeFeatures | SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzEntityIncludeRecordData | SzFlag.SzEntityIncludeRecordMatchingInfo | SzFlag.SzEntityIncludeRelatedEntityName | SzFlag.SzEntityIncludeRelatedMatchingInfo | SzFlag.SzEntityIncludeRelatedRecordSummary)

Parameters

entityID long: The entity ID identifying the entity to retrieve.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzEntityFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzEntityDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the entity.

Examples

Usage:

// How to retrieve an entity via its entity ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the ID of an entity to retrieve (varies by application)
    long entityID = GetEntityID();

    // retrieve the entity by entity ID                
    string responseJson = engine.GetEntity(entityID, SzEntityDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonObject? entity = jsonObject?["RESOLVED_ENTITY"]?.AsObject();
    string? entityName = entity?["ENTITY_NAME"]?.GetValue<string>();

    . . .

    if (jsonObject != null && jsonObject.ContainsKey("RECORDS"))
    {

        JsonArray? recordArr = jsonObject["RECORDS"]?.AsArray();

        for (int index = 0; recordArr != null && index < recordArr.Count; index++)
        {
            JsonObject? record = recordArr[index]?.AsObject();

            string? dataSource = record?["DATA_SOURCE"]?.GetValue<string>();
            string? recordID = record?["RECORD_ID"]?.GetValue<string>();

            . . .
        }
    }

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for entity ID.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve entity by entity ID.", e);
}

Remarks

The result is returned as a JSON document describing the entity.

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzEntityFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzNotFoundException: If no entity could be found with the specified entity ID.
SzException: If a failure occurs.

See Also: SzEntityDefaultFlags

SzEntityBriefDefaultFlags

SzEntityFlags

GetEntity(string, string, SzFlag?)

This method is used to retrieve information about the resolved entity that contains a specific record that is identified by the specified data source code and record ID.

string GetEntity(string dataSourceCode, string recordID, SzFlag? flags = SzFlag.SzEntityIncludePossiblySameRelations | SzFlag.SzEntityIncludePossiblyRelatedRelations | SzFlag.SzEntityIncludeNameOnlyRelations | SzFlag.SzEntityIncludeDisclosedRelations | SzFlag.SzEntityIncludeRepresentativeFeatures | SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzEntityIncludeRecordData | SzFlag.SzEntityIncludeRecordMatchingInfo | SzFlag.SzEntityIncludeRelatedEntityName | SzFlag.SzEntityIncludeRelatedMatchingInfo | SzFlag.SzEntityIncludeRelatedRecordSummary)

Parameters

dataSourceCode string: The data source code that identifies the data source of the constituent record belonging to the entity to be retrieved.
recordID string: The record ID (unique within the scope of the record's data source) identifying the constituent record belonging to the entity to be retrieved.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzEntityFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzEntityDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the entity.

Examples

Usage:

// How to retrieve an entity via its record key
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // retrieve the entity by record key
    string responseJson = engine.GetEntity("TEST", "ABC123", SzEntityDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonObject? entity = jsonObject?["RESOLVED_ENTITY"]?.AsObject();
    string? entityName = entity?["ENTITY_NAME"]?.GetValue<string>();

    . . .

    if (jsonObject != null && jsonObject.ContainsKey("RECORDS"))
    {

        JsonArray? recordArr = jsonObject["RECORDS"]?.AsArray();

        for (int index = 0; recordArr != null && index < recordArr.Count; index++)
        {
            JsonObject? record = recordArr[index]?.AsObject();

            string? dataSource = record?["DATA_SOURCE"]?.GetValue<string>();
            string? recordID = record?["RECORD_ID"]?.GetValue<string>();

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for record key.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve entity by record key.", e);
}

Remarks

The result is returned as a JSON document describing the entity.

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzEntityFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzNotFoundException: If no entity could be found with the specified entity ID.
SzException: If a failure occurs.

See Also: SzEntityDefaultFlags

SzEntityBriefDefaultFlags

SzEntityFlags

GetRecord(string, string, SzFlag?)

Retrieves the record identified by the specified data source code and record ID.

string GetRecord(string dataSourceCode, string recordID, SzFlag? flags = SzFlag.SzEntityIncludeRecordJsonData)

Parameters

dataSourceCode string: The data source code identifying the data source for the record.
recordID string: The record ID that uniquely identifies the record within the scope of its associated data source.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzRecordFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzRecordDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the record.

Examples

Usage:

// How to retrieve a record via its record key
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // retrieve the entity by record key
    string responseJson = engine.GetRecord("TEST", "ABC123", SzEntityDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    string? dataSource = jsonObject?["DATA_SOURCE"]?.GetValue<string>();
    string? recordID = jsonObject?["RECORD_ID"]?.GetValue<string>();

    . . .

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Record not found for record key.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve record by record key.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzRecordFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzNotFoundException: If the record for the specified data source code and record ID pairs cannot be found.
SzException: If a failure occurs.

See Also: SzRecordDefaultFlags

SzRecordFlags

GetRedoRecord()

Retrieves a pending redo record from the reevaluation queue.

string GetRedoRecord()

Returns

string: The retrieved redo record or null if there were no pending redo records.

Examples

Usage:

// How to check for and process redo records
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the redo count
    long redoCount = engine.CountRedoRecords();

    // check if we have redo records
    if (redoCount > 0L)
    {
        // get the next redo record
        string redoRecord = engine.GetRedoRecord();

        // loop while we still have redo records
        while (redoRecord != null)
        {
            try
            {
                // process the redo record
                string infoJson = engine.ProcessRedoRecord(redoRecord, SzEntityDefaultFlags);

                // do something with the "info JSON" (varies by application)
                JsonObject? jsonObject = JsonNode.Parse(infoJson)?.AsObject();
                if (jsonObject != null && jsonObject.ContainsKey("AFFECTED_ENTITIES"))
                {
                    JsonArray? affectedArr = jsonObject["AFFECTED_ENTITIES"]?.AsArray();
                    for (int index = 0; affectedArr != null && index < affectedArr.Count; index++)
                    {
                        JsonObject? affected = affectedArr[index]?.AsObject();
                        long affectedID = affected?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

                        . . .
                    }
                }

            }
            catch (SzException e)
            {
                // handle or rethrow the other exceptions
                LogError("Failed to process redo record: " + redoRecord, e);
            }

            // get the next redo record
            redoRecord = engine.GetRedoRecord();
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to process redos.", e);
}

Remarks

If no redo records are available then this returns an null.

Exceptions

SzException: If a failure occurs.

See Also: ProcessRedoRecord(string, SzFlag?)

CountRedoRecords()

Code Snippet: Processing Redos while Loading

Code Snippet: Continuous Redo Processing

Code Snippet: Continuous Redo Processing via Futures

Code Snippet: Continuous Redo "With Info" Processing

GetStats()

Returns the current internal engine workload statistics for the process. The counters are reset after each call.

string GetStats()

Returns

string: The string describing the statistics as JSON.

Examples

Usage:

// How to get engine stats after loading records
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // load some records to prime the stats
    . . .

    // get the stats
    string statsJson = engine.GetStats();

    // do something with the stats
    Log(statsJson);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to load records with stats.", e);
}

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Load with Stats

GetVirtualEntity(ISet<(string dataSourceCode, string recordID)>, SzFlag?)

Describes a hypothetically entity that would be composed of the one or more records identified by the tuples of data source code and record ID pairs in the specified ISet<T>.

string GetVirtualEntity(ISet<(string dataSourceCode, string recordID)> recordKeys, SzFlag? flags = SzFlag.SzEntityIncludeRepresentativeFeatures | SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzEntityIncludeRecordData | SzFlag.SzEntityIncludeRecordMatchingInfo)

Parameters

recordKeys ISet<(string dataSourceCode, string recordID)>: The non-null non-empty ISet<T> of tuples of data source code and record ID pairs identifying the records to use to build the virtual entity.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzVirtualEntityFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzWhyEntitiesDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the virtual entity having the specified constituent records.

Examples

Usage:

// How to retrieve a virtual entity via a set of record keys
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the records to operate on (varies by application)
    ISet<(string, string)> recordKeys = GetVirtualEntityRecordKeys();

    // retrieve the virtual entity for the record keys
    string responseJson = engine.GetVirtualEntity(recordKeys, SzVirtualEntityDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonObject? entity = jsonObject?["RESOLVED_ENTITY"]?.AsObject();
    string? entityName = entity?["ENTITY_NAME"]?.GetValue<string>();

    . . .

    if (jsonObject != null && jsonObject.ContainsKey("RECORDS"))
    {
        JsonArray? recordArr = jsonObject["RECORDS"]?.AsArray();

        for (int index = 0; recordArr != null && index < recordArr.Count; index++)
        {
            JsonObject? record = recordArr[index]?.AsObject();

            string? dataSource = record?["DATA_SOURCE"]?.GetValue<string>();
            string? recordID = record?["RECORD_ID"]?.GetValue<string>();

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Specified record key was not found.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve virtual entity.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzVirtualEntityFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzNotFoundException: If any of the records for the specified data source code and record ID pairs cannot be found.
SzException: If a failure occurs.

See Also: SzVirtualEntityDefaultFlags

SzHowFlags

HowEntity(long, SzFlag?)

HowEntity(long, SzFlag?)

Determines how an entity identified by the specified entity ID was constructed from its constituent records.

string HowEntity(long entityID, SzFlag? flags = SzFlag.SzIncludeFeatureScores)

Parameters

entityID long: The entity ID of the entity.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzHowFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzHowEntityDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the how the entity was constructed.

Examples

Usage:

// How to retrieve the "how analysis" for an entity via its entity ID
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the entity ID on which to operate (varies by application)
    long entityID = GetEntityID();

    // determine how the entity was formed
    string responseJson = engine.HowEntity(entityID, SzHowEntityDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonObject? howResults = jsonObject?["HOW_RESULTS"]?.AsObject();
    JsonArray? stepsArr = howResults?["RESOLUTION_STEPS"]?.AsArray();

    for (int index = 0; stepsArr != null && index < stepsArr.Count; index++)
    {
        JsonObject? step = stepsArr[index]?.AsObject();

        JsonObject? matchInfo = step?["MATCH_INFO"]?.AsObject();

        . . .
    }

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for entity ID.", e);

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to retrieve how analysis.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzHowFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzNotFoundException: If the entity for the specified entity ID could not be found.
SzException: If a failure occurs.

See Also: SzHowEntityDefaultFlags

SzHowFlags

GetVirtualEntity(ISet<(string dataSourceCode, string recordID)>, SzFlag?)

PreprocessRecord(string, SzFlag?)

Performs a hypothetical load of a the record described by the specified string record definition using the specified bitwise-OR'd SzFlag values.

string PreprocessRecord(string recordDefinition, SzFlag? flags = SzFlag.SzEntityIncludeRecordFeatureDetails)

Parameters

recordDefinition string: The string that defines the record, typically in JSON format.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzRecordFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzPreprocessRecordDefaultFlags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string result produced by preprocessing the record (depending on the specified flags).

Examples

Usage:

// How to pre-process a record
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get a record definition (varies by application)
    string recordDefinition =
            """
            {
                "DATA_SOURCE": "TEST",
                "RECORD_ID": "DEF456",
                "NAME_FULL": "John Doe",
                "PHONE_NUMBER": "702-555-1212",
                "EMAIL_ADDRESS": "johndoe@nowhere.com"
            }
            """;

    // preprocess the record
    string responseJson = engine.PreprocessRecord(
        recordDefinition, SzPreprocessRecordDefaultFlags);

    // do something with the response JSON (varies by application)                
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    if (jsonObject != null && jsonObject.ContainsKey("FEATURES"))
    {
        JsonObject? featuresObj = jsonObject["FEATURES"]?.AsObject();

        if (featuresObj != null)
        {
            foreach (KeyValuePair<string, JsonNode?> pair in featuresObj)
            {
                string featureName = pair.Key;
                . . .
            }
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to preprocess record.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzPreprocessRecordFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzException: If a failure occurs.

See Also: SzPreprocessRecordDefaultFlags

SzPreprocessRecordFlags

PrimeEngine()

May optionally be called to pre-initialize some of the heavier weight internal resources of the SzEngine.

void PrimeEngine()

Examples

Usage:

// How to prime the SzEngine to expedite subsequent operations
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // prime the engine
    engine.PrimeEngine();

    // use the primed engine to perform additional tasks
    . . .

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to prime engine.", e);
}

Exceptions

SzException: If a failure occurs.

See Also: Code Snippet: Engine Priming

ProcessRedoRecord(string, SzFlag?)

Processes the specified redo record using the specified flags. The redo record can be retrieved from GetRedoRecord().

string ProcessRedoRecord(string redoRecord, SzFlag? flags = (SzFlag)0)

Parameters

redoRecord string: The redo record to be processed.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzRedoFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzRedoDefaultFlags. Specify SzWithInfo for an INFO response. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string result produced by processing the redo record, or null if the specified flags do not indicate that an INFO message should be returned.

Examples

Usage:

// How to check for and process redo records
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the redo count
    long redoCount = engine.CountRedoRecords();

    // check if we have redo records
    if (redoCount > 0L)
    {
        // get the next redo record
        string redoRecord = engine.GetRedoRecord();

        // loop while we still have redo records
        while (redoRecord != null)
        {
            try
            {
                // process the redo record
                string infoJson = engine.ProcessRedoRecord(redoRecord, SzEntityDefaultFlags);

                // do something with the "info JSON" (varies by application)
                JsonObject? jsonObject = JsonNode.Parse(infoJson)?.AsObject();
                if (jsonObject != null && jsonObject.ContainsKey("AFFECTED_ENTITIES"))
                {
                    JsonArray? affectedArr = jsonObject["AFFECTED_ENTITIES"]?.AsArray();
                    for (int index = 0; affectedArr != null && index < affectedArr.Count; index++)
                    {
                        JsonObject? affected = affectedArr[index]?.AsObject();
                        long affectedID = affected?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

                        . . .
                    }
                }

            }
            catch (SzException e)
            {
                // handle or rethrow the other exceptions
                LogError("Failed to process redo record: " + redoRecord, e);
            }

            // get the next redo record
            redoRecord = engine.GetRedoRecord();
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the other exceptions
    LogError("Failed to process redos.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzRedoFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzException: If a failure occurs.

See Also: SzWithInfo

SzRedoFlags

SzRedoDefaultFlags

GetRedoRecord()

CountRedoRecords()

Code Snippet: Processing Redos while Loading

Code Snippet: Continuous Redo Processing

Code Snippet: Continuous Redo Processing via Futures

Code Snippet: Continuous Redo "With Info" Processing

ReevaluateEntity(long, SzFlag?)

Reevaluate a resolved entity identified by the specified entity ID.

string ReevaluateEntity(long entityID, SzFlag? flags = (SzFlag)0)

Parameters

entityID long: The ID of the resolved entity to reevaluate.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzReevaluateEntityFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzReevaluateEntityDefaultFlags. Specify SzWithInfo for an INFO response. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string result produced by reevaluating the entity, or null if the specified flags do not indicate that an INFO message should be returned.

Examples

Usage:

// How to reevaluate an entity
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the ID of an entity to reevaluate (varies by application)
    long entityID = GetEntityID();

    // reevaluate an entity in the repository
    string infoJson = engine.ReevaluateEntity(entityID, SzWithInfo);

    // do something with the "info JSON" (varies by application)                
    JsonObject? jsonObject = JsonNode.Parse(infoJson)?.AsObject();
    if (jsonObject != null && jsonObject.ContainsKey("AFFECTED_ENTITIES"))
    {
        JsonArray? affectedArr = jsonObject["AFFECTED_ENTITIES"]?.AsArray();

        for (int index = 0; affectedArr != null && index < affectedArr.Count; index++)
        {
            JsonObject? affected = affectedArr[index]?.AsObject();

            long affectedID = affected?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to reevaluate entity.", e);
}

Remarks

If the entity for the entity ID is not found, then the operation silently does nothing with no exception. This is to ensure consistent behavior in case of a race condition with entity re-resolve or unresolve. To ensure that the entity was found, specify the SzWithInfo flag and check the returned INFO document for affected entities.

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzReevaluateEntityFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzException: If a failure occurs.

See Also: SzNoFlags

SzWithInfo

SzReevaluateEntityDefaultFlags

SzReevaluateEntityFlags

ReevaluateRecord(string, string, SzFlag?)

Reevaluate the record identified by the specified data source code and record ID.

string ReevaluateRecord(string dataSourceCode, string recordID, SzFlag? flags = (SzFlag)0)

Parameters

dataSourceCode string: The data source code identifying the data source for the record to reevaluate.
recordID string: The record ID that uniquely identifies the record to reevaluate within the scope of its associated data source.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzReevaluateRecordFlags group to control how the operation is performed and the content of the response. Omitting this parameter will default its value to SzReevaluateRecordDefaultFlags. Specify SzWithInfo for an INFO response. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string result produced by reevaluating the record, or null if the specified flags do not indicate that an INFO message should be returned.

Examples

Usage:

// How to reevaluate a record
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // reevaluate a record in the repository
    string infoJson = engine.ReevaluateRecord("TEST", "ABC123", SzWithInfo);

    // do something with the "info JSON" (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(infoJson)?.AsObject();
    if (jsonObject != null && jsonObject.ContainsKey("AFFECTED_ENTITIES"))
    {
        JsonArray? affectedArr = jsonObject["AFFECTED_ENTITIES"]?.AsArray();

        for (int index = 0; affectedArr != null && index < affectedArr.Count; index++)
        {
            JsonObject? affected = affectedArr[index]?.AsObject();

            long affectedID = affected?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to reevaluate record.", e);
}

Remarks

If the data source code is not recognized then an SzUnknownDataSourceException is thrown but if the record for the record ID is not found, then the operation silently does nothing with no exception. This is to ensure consistent behavior in case of a race condition with record deletion. To ensure that the record was found, specify the SzWithInfo flag and check the returned INFO document for affected entities.

The optionally specified bitwise-OR'd SzFlag values not only controls how the operation is performed, but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzReevaluateRecordFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzException: If a failure occurs.

See Also: SzNoFlags

SzWithInfo

SzReevaluateRecordDefaultFlags

SzReevaluateRecordFlags

SearchByAttributes(string, SzFlag?)

Convenience method for calling SearchByAttributes(string, string, SzFlag?) with a null value for the search profile parameter.

string SearchByAttributes(string attributes, SzFlag? flags = SzFlag.SzExportIncludeMultiRecordEntities | SzFlag.SzExportIncludePossiblySame | SzFlag.SzExportIncludePossiblyRelated | SzFlag.SzExportIncludeNameOnly | SzFlag.SzEntityIncludeRepresentativeFeatures | SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzIncludeFeatureScores | SzFlag.SzSearchIncludeStats)

Parameters

attributes string: The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzSearchFlags group to control how the operation is performed and the content of the response, omitting this parameter will default its value to SzSearchByAttributesDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The resulting JSON string describing the result of the search.

Examples

Usage:

// How to search for entities matching criteria
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the search attributes (varies by application)
    string searchAttributes =
            """
            {
                "NAME_FULL": "Joe Schmoe",
                "PHONE_NUMBER": "702-555-1212",
                "EMAIL_ADDRESS": "joeschmoe@nowhere.com"
            }
            """;

    // search for matching entities in the repository                
    string responseJson = engine.SearchByAttributes(
        searchAttributes,
        SzSearchByAttributesDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    if (jsonObject != null && jsonObject.ContainsKey("RESOLVED_ENTITIES"))
    {
        JsonArray? resultsArr = jsonObject["RESOLVED_ENTITIES"]?.AsArray();

        for (int index = 0; resultsArr != null && index < resultsArr.Count; index++)
        {
            JsonObject? result = resultsArr[index]?.AsObject();

            // get the match info for the result
            JsonObject? matchInfo = result?["MATCH_INFO"]?.AsObject();

            . . .

            // get the entity for the result
            JsonObject? entityInfo = result?["ENTITY"]?.AsObject();
            JsonObject? entity = entityInfo?["RESOLVED_ENTITY"]?.AsObject();
            long entityID = entity?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to search for entities.", e);
}

Remarks

See SearchByAttributes(string, string, SzFlag?) documentation for details.

Exceptions

SzException: If a failure occurs.

See Also: SearchByAttributes(string, string, SzFlag?)

SzSearchByAttributesDefaultFlags

SzSearchByAttributesAll

SzSearchByAttributesStrong

SzSearchByAttributesMinimalAll

SzSearchByAttributesMinimalStrong

SzSearchFlags

Code Snippet: Search Records

Code Snippet: Search via Futures

SearchByAttributes(string, string, SzFlag?)

This method searches for entities that match or relate to the provided search attributes using the optionally specified search profile.

string SearchByAttributes(string attributes, string searchProfile, SzFlag? flags = SzFlag.SzExportIncludeMultiRecordEntities | SzFlag.SzExportIncludePossiblySame | SzFlag.SzExportIncludePossiblyRelated | SzFlag.SzExportIncludeNameOnly | SzFlag.SzEntityIncludeRepresentativeFeatures | SzFlag.SzEntityIncludeEntityName | SzFlag.SzEntityIncludeRecordSummary | SzFlag.SzIncludeFeatureScores | SzFlag.SzSearchIncludeStats)

Parameters

attributes string: The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
searchProfile string: The optional search profile identifier, or null if the default search profile should be used for the search.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzSearchFlags group to control how the operation is performed and the content of the response, omitting this parameter will default its value to SzSearchByAttributesDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The resulting JSON string describing the result of the search.

Examples

Usage:

// How to search for entities matching criteria using a search profile
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the search attributes (varies by application)
    string searchAttributes =
            """
            {
                "NAME_FULL": "Joe Schmoe",
                "PHONE_NUMBER": "702-555-1212",
                "EMAIL_ADDRESS": "joeschmoe@nowhere.com"
            }
            """;

    // get a search profile (varies by application)
    string searchProfile = GetSearchProfile();

    // search for matching entities in the repository                
    string responseJson = engine.SearchByAttributes(
        searchAttributes,
        searchProfile,
        SzSearchByAttributesDefaultFlags);

    // do something with the response JSON (varies by application)                
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    if (jsonObject != null && jsonObject.ContainsKey("RESOLVED_ENTITIES"))
    {
        JsonArray? resultsArr = jsonObject["RESOLVED_ENTITIES"]?.AsArray();

        for (int index = 0; resultsArr != null && index < resultsArr.Count; index++)
        {
            JsonObject? result = resultsArr[index]?.AsObject();

            // get the match info for the result
            JsonObject? matchInfo = result?["MATCH_INFO"]?.AsObject();

            . . .

            // get the entity for the result
            JsonObject? entityInfo = result?["ENTITY"]?.AsObject();
            JsonObject? entity = entityInfo?["RESOLVED_ENTITY"]?.AsObject();
            long entityID = entity?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

            . . .
        }
    }

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to search for entities.", e);
}

Remarks

The specified search attributes are treated as a hypothetical record and the search results are those entities that would match or relate to that hypothetical record on some level (depending on the specified flags).

If the specified search profile is null then the default generic thresholds from the default search profile will be used for the search (alternatively, use SearchByAttributes(string, SzFlag?) to omit the parameter). If your search requires different behavior using alternate generic thresholds, please contact support@senzing.com for details on configuring a custom search profile.

The optionally specified bitwise-OR'd SzFlag values not only control how the search is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzSearchFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzException: If a failure occurs.

See Also: SearchByAttributes(string, SzFlag?)

SzSearchByAttributesDefaultFlags

SzSearchByAttributesAll

SzSearchByAttributesStrong

SzSearchByAttributesMinimalAll

SzSearchByAttributesMinimalStrong

SzSearchFlags

Code Snippet: Search Records

Code Snippet: Search via Futures

WhyEntities(long, long, SzFlag?)

Determines the ways in which two entities identified by the specified entity ID's are related to each other.

string WhyEntities(long entityID1, long entityID2, SzFlag? flags = SzFlag.SzIncludeFeatureScores)

Parameters

entityID1 long: The entity ID of the first entity.
entityID2 long: The entity ID of the second entity.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzWhyEntitiesFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzWhyEntitiesDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the ways in which the records are related to one another.

Examples

Usage:

// How to determine how two entities are related
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the entities on which to operate (varies by application)
    long entityID1 = GetWhyEntitiesID1();
    long entityID2 = GetWhyEntitiesID2();

    // determine how the entities are related
    string responseJson = engine.WhyEntities(entityID1,
                                             entityID2,
                                             SzWhyEntitiesDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? resultsArr = jsonObject?["WHY_RESULTS"]?.AsArray();

    for (int index = 0; resultsArr != null && index < resultsArr.Count; index++)
    {
        JsonObject? result = resultsArr[index]?.AsObject();

        long whyEntityID1 = result?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

        long whyEntityID2 = result?["ENTITY_ID_2"]?.GetValue<long>() ?? 0L;

        . . .
    }

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for entity ID.", e);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to perform why entities.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzWhyEntitiesFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzNotFoundException: If either of the entities for the specified entity ID's could not be found.
SzException: If a failure occurs.

See Also: SzWhyEntitiesDefaultFlags

SzWhyEntitiesFlags

WhyRecords(string, string, string, string, SzFlag?)

WhyRecordInEntity(string, string, SzFlag?)

WhyRecordInEntity(string, string, SzFlag?)

Determines why the record identified by the specified data source code and record ID is included in its respective entity.

string WhyRecordInEntity(string dataSourceCode, string recordID, SzFlag? flags = SzFlag.SzIncludeFeatureScores)

Parameters

dataSourceCode string: The data source code that identifies the data source of the record.
recordID string: The record ID that identifies the record within the scope of the record's data source.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzWhyRecordInEntityFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzWhyRecordInEntityDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing why the record is included in its respective entity.

Examples

Usage:

// How to determine why a record is a member of its respective entity
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // determine why the record is part of its entity                
    string responseJson = engine.WhyRecordInEntity(
        "TEST", "ABC123", SzWhyRecordInEntityDefaultFlags);

    // do something with the response JSON (varies by application)                
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? resultsArr = jsonObject?["WHY_RESULTS"]?.AsArray();

    for (int index = 0; resultsArr != null && index < resultsArr.Count; index++)
    {
        JsonObject? result = resultsArr[index]?.AsObject();

        long entityID = result?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

        . . .
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for record key.", e);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to reevaluate record.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzWhyRecordInEntityFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzNotFoundException: If any of the records for the specified data source code and record ID pairs cannot be found.
SzException: If a failure occurs.

See Also: SzWhyRecordInEntityDefaultFlags

SzWhyRecordInEntityFlags

WhyEntities(long, long, SzFlag?)

WhyRecords(string, string, string, string, SzFlag?)

WhyRecords(string, string, string, string, SzFlag?)

Determines ways in which two records identified by their data source code and record IDs are related to each other.

string WhyRecords(string dataSourceCode1, string recordID1, string dataSourceCode2, string recordID2, SzFlag? flags = SzFlag.SzIncludeFeatureScores)

Parameters

dataSourceCode1 string: The data source code identifying the data source for the first record.
recordID1 string: The record ID that uniquely identifies the first record within the scope of its associated data source.
dataSourceCode2 string: The data source code identifying the data source for the second record.
recordID2 string: The record ID that uniquely identifies the second record within the scope of its associated data source.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzWhyRecordsFlags group to control how the operation is performed and the content of the response. Omitting this parameter defaults it value to SzWhyRecordsDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The JSON string describing the ways in which the records are related to one another.

Examples

Usage:

// How to determine how two records are related
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the records on which to operate (varies by application)
    (string dataSourceCode, string recordID) recordKey1 = GetWhyRecordsKey1();
    (string dataSourceCode, string recordID) recordKey2 = GetWhyRecordsKey2();

    // determine how the records are related
    string responseJson = engine.WhyRecords(recordKey1.dataSourceCode,
                                            recordKey1.recordID,
                                            recordKey2.dataSourceCode,
                                            recordKey2.recordID,
                                            SzWhyRecordsDefaultFlags);

    // do something with the response JSON (varies by application)
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? resultsArr = jsonObject?["WHY_RESULTS"]?.AsArray();

    for (int index = 0; resultsArr != null && index < resultsArr.Count; index++)
    {
        JsonObject? result = resultsArr[index]?.AsObject();

        long entityID1 = result?["ENTITY_ID"]?.GetValue<long>() ?? 0L;
        long entityID2 = result?["ENTITY_ID_2"]?.GetValue<long>() ?? 0L;

        . . .
    }

}
catch (SzUnknownDataSourceException e)
{
    // handle the unknown data source exception
    LogError("Expected data source is not configured.", e);

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for record key.", e);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to reevaluate record.", e);
}

Remarks

The optionally specified bitwise-OR'd SzFlag values not only control how the operation is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzWhyRecordsFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzUnknownDataSourceException: If an unrecognized data source code is specified.
SzNotFoundException: If either of the records for the specified data source code and record ID pairs cannot be found.
SzException: If a failure occurs.

See Also: SzWhyRecordsDefaultFlags

SzWhyRecordsFlags

WhyRecordInEntity(string, string, SzFlag?)

WhyEntities(long, long, SzFlag?)

WhySearch(string, long, string, SzFlag?)

Compares the specified search attribute criteria against the entity identified by the specified entity ID to determine why that entity was or was not included in the results of a "search by attributes" operation.

string WhySearch(string attributes, long entityID, string searchProfile = null, SzFlag? flags = SzFlag.SzIncludeFeatureScores | SzFlag.SzSearchIncludeStats | SzFlag.SzSearchIncludeRequestDetails)

Parameters

attributes string: The search attributes defining the hypothetical record to match and/or relate to in order to obtain the search results.
entityID long: The entity ID identifying the entity to analyze against the search attribute criteria.
searchProfile string: The optional search profile identifier, or null if the default search profile should be used for the search.
flags SzFlag?: The optional bitwise-OR'd SzFlag values belonging to the SzWhySearchFlags group to control how the operation is performed and the content of the response, omitting this parameter will default its value to SzWhySearchDefaultFlags for the default recommended flags. Specifying null is equivalent to specifying SzNoFlags.

Returns

string: The resulting JSON string describing the result of the why analysis against the search criteria.

Examples

Usage:

// How to determine why an entity was excluded from search results
try
{
    // obtain the SzEnvironment (varies by application)
    SzEnvironment env = GetEnvironment();

    // get the engine
    SzEngine engine = env.GetEngine();

    // get the search attributes (varies by application)
    string searchAttributes =
            """
            {
                "NAME_FULL": "Joe Schmoe",
                "PHONE_NUMBER": "702-555-1212",
                "EMAIL_ADDRESS": "joeschmoe@nowhere.com"
            }
            """;

    // get the entities on which to operate (varies by application)
    long entityID = GetWhySearchEntityID();

    // determine how the entities are related                
    string responseJson = engine.WhySearch(searchAttributes,
                                           entityID,
                                           null, // search profile
                                           SzWhySearchDefaultFlags);

    // do something with the response JSON (varies by application)                
    JsonObject? jsonObject = JsonNode.Parse(responseJson)?.AsObject();
    JsonArray? resultsArr = jsonObject?["WHY_RESULTS"]?.AsArray();

    for (int index = 0; resultsArr != null && index < resultsArr.Count; index++)
    {
        JsonObject? result = resultsArr[index]?.AsObject();

        long whyEntityID1 = result?["ENTITY_ID"]?.GetValue<long>() ?? 0L;

        . . .
    }

}
catch (SzNotFoundException e)
{
    // handle the not-found exception
    LogError("Entity not found for entity ID.", e);

}
catch (SzException e)
{
    // handle or rethrow the exception
    LogError("Failed to perform why search.", e);
}

Remarks

The specified search attributes are treated as a hypothetical single-record entity and the result of this operation is the "why analysis" of the entity identified by the specified entity ID against that hypothetical entity. The details included in the response are determined by the specified flags.

If the specified search profile is null then the default generic thresholds from the default search profile will be used for the search candidate determination. If your search requires different behavior using alternate generic thresholds, please contact support@senzing.com for details on configuring a custom search profile.

The optionally specified bitwise-OR'd SzFlag values not only control how the search is performed but also the content of the response. Any SzFlag value may be included, but only flags belonging to the SzWhySearchFlags group will be recognized (other SzFlag values will be ignored unless they have equivalent bit flags to recognized flags).

Exceptions

SzNotFoundException: If no entity could be found with the specified entity ID.
SzException: If a failure occurs.

See Also: SzWhySearchDefaultFlags

SzWhySearchFlags

Table of Contents

Interface SzEngine

Examples

Remarks

Methods

AddRecord(string, string, string, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

CloseExport(IntPtr)

Parameters

Examples

Remarks

Exceptions

CountRedoRecords()

Returns

Examples

Exceptions

DeleteRecord(string, string, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

ExportCsvEntityReport(string, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

ExportJsonEntityReport(SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

FetchNext(IntPtr)

Parameters

Returns

Examples

Remarks

Exceptions

FindInterestingEntities(long, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

FindInterestingEntities(string, string, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

FindNetwork(ISet<long>, int, int, int, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

FindNetwork(ISet<(string dataSourceCode, string recordID)>, int, int, int, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

FindPath(long, long, int, ISet<long>, ISet<string>, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions

FindPath(string, string, string, string, int, ISet<(string dataSourceCode, string recordID)>, ISet<string>, SzFlag?)

Parameters

Returns

Examples

Remarks

Exceptions