The SimilaritySolution API is a scriptable object used in Predictive Intelligence stores.

This API requires the Predictive Intelligence plugin (com.glide.platform_ml) and is provided within the sn_ml namespace.

The solution setup-to-training flow is as follows:
  1. Build an encoder using the Encoder API.
  2. Use the constructor to create a similarity solution object.
  3. Add the solution object to the similarity solution store using the SimilaritySolutionStore - add() method.
  4. Train the solution using the submitTrainingJob() method. This creates a version of the object that you can manage using the SimilaritySolutionVersion API.
  5. Get predictions using the SimilaritySolutionVersion – predict() method.
Note: This API runs with full privileges before the Vancouver Patch 7 Hotfix 2b and Washington DC Patch 7 releases. With later releases, grant access using ACLs. For more information see Query ACLs.

For usage guidelines, refer to Using ML APIs.

SimilaritySolution - SimilaritySolution(Object config)

Creates a similarity solution.

Table 1. Parameters
NameTypeDescription
config Object JavaScript object containing configuration properties of the solution.
{  
  "domainName": "String",
  "encoder": {Object},
  "label": "String",
  "lookupDataset": {Object},
  "minRowCount": "String",
  "processingLanguage": "String",
  "stopwords": [Array],
  "testDataset": {Object},
  "trainingFrequency": "String",
  "updateFrequency": "String"
}
config.domainName String Optional. Domain name associated with this dataset. See Domain separation and Predictive Intelligence.

Default: Current domain, for example, "global".
config.encoder Object Trained encoder object to assign to this solution. See Encoder - Encoder(Object config).
config.label String Identifies the prediction task.
config.lookupDataset Object Name of the DatasetDefinition to use as the lookup set.
config.minRowCount String Optional. Minimum number of records required in the dataset for training.

Default: 10000
config.processingLanguage String Optional. Processing language in two-letter ISO 639-1 language code format.

Default: "en"
config.stopwords Array Optional. Preset list of strings that the system automatically generates based on the language property setting. For details, see Create a custom stopwords list.

Default: English Stopwords
config.testDataset Object Name of the DatasetDefinition to scan for similarities with lookupDataset results.
config.trainingFrequency String Optional. The frequency to retrain the model.
Possible values:
  • every_30_days
  • every_60_days
  • every_90_days
  • every_120_days
  • every_180_days
  • run_once
Default: run_once
config.updateFrequency The frequency at which the model for the solution definition must be rebuilt.
Possible values:
  • do_not_update
  • every_1_day
  • every_1_hour
  • every_6_hours
  • every_12_hours
  • every_1_minute
  • every_15_minutes
  • every_30_minutes
Default: do_not_update

Example

The following example shows how to create an object and add it to the SimilaritySolution store.

var incidentData = new sn_ml.DatasetDefinition({
        'tableName' : 'incident',
        'fieldNames' : ['category', 'short_description']        
    });
    var kbData = new sn_ml.DatasetDefinition({
        'tableName' : 'kb_knowledge',
        'fieldNames' : ['short_description'],
        'encodedQuery' : 'active=true'
    });
    var encoder = sn_ml.EncoderStore.get('GloVe');
    var mySolution = new sn_ml.SimilaritySolution({
        'label': "similarity solution",
        'lookupDataset' : kbData,
        'testDataset' : incidentData,        
        'encoder' : encoder        
    });
    
    // add solution
    var solutionName = sn_ml.SimilaritySolutionStore.add(mySolution);

SimilaritySolution - cancelTrainingJob()

Cancels a job for a solution object that has been submitted for training.

Table 2. Parameters
Name Type Description
None
Table 3. Returns
Type Description
None

Example

The following example shows how to cancel an existing training job.

var mySolution = sn_ml.SimilaritySolutionStore.get('ml_sn_global_global_similarity');

mySolution.cancelTrainingJob();

SimilaritySolution - getActiveVersion()

Gets the active SimilaritySolutionVersion object.

Table 4. Parameters
Name Type Description
None
Table 5. Returns
Type Description
Object Active SimilaritySolutionVersion object.

Example

The following example shows how to get an active SimilaritySolution version from the store and return its training status.

var mlSolution = sn_ml.SimilaritySolutionStore.get('ml_x_snc_global_global_similarity');

gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getStatus()), null, 2));

Output:

{
  "state": "solution_complete",
  "percentComplete": "100",
  "hasJobEnded": "true"
}

SimilaritySolution - getAllVersions()

Gets all versions of a SimilaritySolution object.

Table 6. Parameters
Name Type Description
None
Table 7. Returns
Type Description
Array Existing versions of a solution object. See also SimilaritySolutionVersion API.

Example

The following example shows how to get all SimilaritySolution version objects and call the getVersionNumber() and getStatus() solution version methods on them.

var mlSolution = sn_ml.SimilaritySolutionStore.get('ml_x_snc_global_global_Similarity');

var mlSolutionVersions = mlSolution.getAllVersions();

for (i = 0; i < mlSolutionVersions.length; i++) {
gs.print("Version " + mlSolutionVersions[i].getVersionNumber() + " Status: " + mlSolutionVersions[i].getStatus() +"\n");

Output:

Version 3 Status: {"state":"solution_complete","percentComplete":"100","hasJobEnded":"true"}

Version 2 Status: {"state":"solution_complete","percentComplete":"100","hasJobEnded":"true"}

Version 1 Status: {"state":"solution_cancelled","percentComplete":"0","hasJobEnded":"true"}

SimilaritySolution - getLatestVersion()

Gets the latest version of a solution.

Table 8. Parameters
Name Type Description
None
Table 9. Returns
Type Description
Object SimilaritySolutionVersion object corresponding to the latest version of a SimilaritySolution.

Example

The following example shows how to get the latest version of a solution and return its training status.

var mlSolution = sn_ml.SimilaritySolutionStore.get('ml_x_snc_global_global_Similarity');

gs.print(JSON.stringify(JSON.parse(mlSolution.getLatestVersion().getStatus()), null, 2));

Output:

{
  "state": "solution_complete",
  "percentComplete": "100",
  "hasJobEnded": "true"
}

SimilaritySolution - getName()

Gets the name of the object to use for interaction with the store.

Table 10. Parameters
Name Type Description
None
Table 11. Returns
Type Description
String Name of the solution object.

Example

The following example shows how to update SimilaritySolution dataset information and print the name of the object.

// Update solution
var myIncidentData = new sn_ml.DatasetDefinition({
   'tableName' : 'incident',
   'fieldNames' : ['category', 'short_description', 'priority'],
   'encodedQuery' : 'activeANYTHING'
});

var eligibleFields = JSON.parse(myIncidentData.getEligibleFields('Similarity'));

var mySimilarity = new sn_ml.SimilaritySolution({
   'label': "my Similarity solution",
   'dataset' : myIncidentData,
   'inputFieldNames': eligibleFields['eligibleInputFieldNames'],
   'predictedFieldName': 'category'
});

// update solution
sn_ml.SimilaritySolutionStore.update('ml_x_snc_global_global_my_solution_definition_4', mySimilarity);

// print solution name
gs.print('Solution Name: '+mySimilarity.getName());

Output:

Solution Name: ml_x_snc_global_global_my_solution_definition_4

SimilaritySolution - getProperties()

Gets solution object properties.

Table 12. Parameters
Name Type Description
None
Table 13. Returns
TypeDescription
Object Contents of the Dataset and SimilaritySolution() object details in the SimilaritySolutionStore.
{
  "domainName": "String",
  "encoder": {Object},
  "label": "String",
  "lookupDatasetProperties": {Object},
  "name": "String",
  "processingLanguage": "String",
  "scope": "String",
  "stopwords": [Array],
  "testDatasetProperties": {Object},
  "trainingFrequency": "String",
  "updateFrequency": "String"
}
<Object>.domainName Domain name associated with this dataset. See Domain separation and Predictive Intelligence.

Data type: String.
<Object>.encoder Encoder object assigned to this solution. See Encoder - Encoder(Object config).

Data type: Object.
<Object>.label Identifies the prediction task. 
{
  "label": "my first prediction"
}

Data type: String.
<Object>.lookupDatasetProperties Details of the DatasetDefinition() object used as the lookup set. 
{
  "encodedQuery": "String",
  "fieldDetails": [Array],
  "fieldNames": [Array],
  "tableName": "String"
}

Data type: Object.
<Object>.lookupDatasetProperties.tableName Name of the table for the dataset. For example, "tableName" : "Incident".

Data type: String.
<Object>.lookupDatasetProperties.fieldNames List of field names from the specified table as strings. For example, "fieldNames" : ["short_description", "priority"].

Data type: Array.
<Object>.lookupDatasetProperties.fieldNames.fieldDetails List of JavaScript objects that specify field properties. 
[
  {
    "name": "String",
    "type": "String"
  }
]

Data type: Array.
<Object>.lookupDatasetProperties.fieldNames.fieldDetails.<object>.name Name of the field defining the type of information to restrict this dataset to.

Data type: String.
<Object>.lookupDatasetProperties.fieldDetails.<object>.type Machine-learning field type.

Data type: String.
<Object>.lookupDatasetProperties.fieldDetails.encodedQuery Encoded query string in standard Glide format. See Encoded query strings.

Data type: String.
<Object>.name System-assigned name.

Data type: String.
<Object>.processingLanguage Processing language in two-letter ISO 639-1 language code format.

Data type: String.
<Object>.scope Object scope. Currently the only valid value is global.

Data type: String
<Object>.stopwords Optional. Preset list of strings that the system automatically generates based on the language property setting. For details, see Create a custom stopwords list.

Data type: Array.
<Object>.testDatasetProperties Details of the DatasetDefinition() object used to retrieve similarities between results searched in this model and results found in the lookupDataset. 
{
  "encodedQuery": "String",
  "fieldDetails": [Array],
  "fieldNames": [Array],
  "tableName": "String"
}

Data type: Object.
<Object>.testDatasetProperties.tableName Name of the table for the dataset. For example, "tableName" : "Incident".

Data type: String.
<Object>.testDatasetProperties.fieldNames List of field names from the specified table as strings. For example, "fieldNames" : ["short_description", "priority"].

Data type: Array.
<Object>.testDatasetProperties.fieldNames.fieldDetails List of JavaScript objects that specify field properties. 
[
  {
    "name": "String",
    "type": "String"
  }
]

Data type: Array.
<Object>.testDatasetProperties.fieldNames.fieldDetails.<object>.name Name of the field defining the type of information to restrict this dataset to.

Data type: String.
<Object>.testDatasetProperties.fieldDetails.<object>.type Machine-learning field type.

Data type: String.
<Object>.testDatasetProperties.fieldDetails.encodedQuery Encoded query string in standard Glide format. See Encoded query strings.

Data type: String.
<Object>.trainingFrequency The frequency to retrain the model.
Possible values:
  • every_30_days
  • every_60_days
  • every_90_days
  • every_120_days
  • every_180_days
  • run_once
Default: run_once

Data type: String.
<Object>.updateFrequency The frequency at which the model for the solution definition must be rebuilt.
Possible values:
  • do_not_update
  • every_1_day
  • every_1_hour
  • every_6_hours
  • every_12_hours
  • every_1_minute
  • every_15_minutes
  • every_30_minutes
Default: do_not_update

Datatype: String

Example

The following example gets properties of a solution object in the store.

var mySolution = sn_ml.SimilaritySolutionStore.get('ml_sn_global_global_similarity_solution');

gs.print(JSON.stringify(JSON.parse(mySolution.getProperties()), null, 2));
Output:
*** Script: {
  "domainName": "global",
  "encoderProperties": {
    "datasetsProperties": [],
    "name": "wordCorpusA"
  },
  "label": "similarity",
  "lookupDatasetProperties": {
    "tableName": "incident",
    "fieldNames": [
      "short_description"
    ]
  },
  "name": "ml_x_snc_global_global_similarity",
  "processingLanguage": "en",
  "scope": "global",
  "stopwords": [
    "Default English Stopwords"
  ],
  "testDatasetProperties": {
    "tableName": "incident",
    "fieldNames": [
      "short_description"
    ]
  },
  "trainingFrequency": "every_30_days",
  "updateFrequency": "do_not_update"
}

SimilaritySolution - getVersion(String version)

Gets a solution by provided version number.

Table 14. Parameters
Name Type Description
version String Existing version number of a solution.
Table 15. Returns
Type Description
Object Specified version of the SimilaritySolution() object on which you can call SimilaritySolutionVersion API methods.

Example

The following example shows how to get the training status of a solution by version number.

var mlSolution = sn_ml.SimilaritySolutionStore.get('ml_x_snc_global_global_similarity');

gs.print(JSON.stringify(JSON.parse(mlSolution.getVersion('1').getStatus()), null, 2));

Output:

{
  "state": "solution_complete",
  "percentComplete": "100",
  "hasJobEnded": "true"
}

SimilaritySolution - setActiveVersion(String version)

Activates a specified version of a solution in the store.

Table 16. Parameters
Name Type Description
version String Name of the SimilaritySolution() object version to activate.

Activating this version deactivates any other version.
Table 17. Returns
Type Description
None

Example

The following example shows how to activate a solution version in the store.

sn_ml.SimilaritySolution.setActiveVersion("ml_incident_categorization");

SimilaritySolution - submitTrainingJob()

Submits a training job.

Note: Before running this method, you must first add a solution to the store using the SimilaritySolutionStore - add() method.
Table 18. Parameters
Name Type Description
None
Table 19. Returns
Type Description
Object SimilaritySolutionVersion object corresponding to the SimilaritySolution being trained.

Example

// Create a dataset 
var incidentData = new sn_ml.DatasetDefinition({
    'tableName' : 'incident',
    'fieldNames' : ['category', 'short_description']
});

var kbData = new sn_ml.DatasetDefinition({
    'tableName' : 'kb_knowledge',
    'fieldNames' : ['short_description'],
    'encodedQuery' : 'active=true'
});

// Create a solution 
var encoder = sn_ml.EncoderStore.get('GloVe');
var mySolution = new sn_ml.SimilaritySolution({
    'label': "similarity solution",
    'lookupDataset' : kbData,
    'testDataset' : incidentData,
    'encoder' : encoder,
});

// Add solution
var solutionName = sn_ml.SimilaritySolutionStore.add(mySolution);


// Train the solution - this is a long running job 
var mySimilarityVersion = mySolution.submitTrainingJob();