SimilaritySolution - Global

concept brazil Updated Sep 10, 2026 8 min read SimilaritySolutionAPI.md
Raw file servicenow.com

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. Use the constructor to create a similarity solution object.
  2. Add the solution object to the similarity solution store using the SimilaritySolutionStore - add() method.
  3. Train the solution using the submitTrainingJob() method. This creates a version of the object that you can manage using the SimilaritySolutionVersion API.
  4. 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.

Parent Topic:Server API reference

SimilaritySolution - SimilaritySolution(Object config)

Creates a similarity solution.

Name

Type

Description

config

Object

JavaScript object containing configuration properties of thesolution.``` {
"domainName": "String", "label": "String", "lookupDataset": {Object}, "minRowCount": "String", "processingLanguage": "String", "stopwords": [Array], "testDataset": {Object}, "trainingFrequency": "String", "updateFrequency": "String" }

Text
</td></tr><tr><td>
config.domainName
</td><td>
String
</td><td>
Optional. Domain name associated with this dataset. Default: Current domain, for example, `"global"`.
</td></tr><tr><td>
config.label
</td><td>
String
</td><td>
Identifies the prediction task.
</td></tr><tr><td>
config.lookupDataset
</td><td>
Object
</td><td>
Name of the [DatasetDefinition](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/DatasetDefinitionAPI.md) to use as the lookup set.
</td></tr><tr><td>
config.minRowCount
</td><td>
String
</td><td>
Optional. Minimum number of records required in the dataset for training.Default: 10000
</td></tr><tr><td>
config.processingLanguage
</td><td>
String
</td><td>
Optional. Processing language in two-letter ISO 639-1 language code format. Default: "en"
</td></tr><tr><td>
config.stopwords
</td><td>
Array
</td><td>
Optional. Preset list of strings that the system automatically generates based on the **language** property setting. For details, see [Create a custom stopwords list](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/intelligent-experiences/create-custom-stopwords-list.md). Default: English Stopwords
</td></tr><tr><td>
config.testDataset
</td><td>
Object
</td><td>
Name of the [DatasetDefinition](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/DatasetDefinitionAPI.md) to scan for similarities with **lookupDataset** results.
</td></tr><tr><td>
config.trainingFrequency
</td><td>
String
</td><td>
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
</td></tr><tr><td>
config.updateFrequency
</td><td>
 
</td><td>
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
</td></tr></tbody></table>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 mySolution = new sn_ml.SimilaritySolution({
    'label': "similarity solution",
    'lookupDataset' : kbData,
    'testDataset' : incidentData,              
});

// add solution
var solutionName = sn_ml.SimilaritySolutionStore.add(mySolution);
Text
## SimilaritySolution - cancelTrainingJob\(\)
Cancels a job for a solution object that has been submitted for training.
|Name|Type|Description||----|----|-----------||None| | |
|Type|Description||----|-----------||None| |
The following example shows how to cancel an existing training job.

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

mySolution.cancelTrainingJob();

Text
## SimilaritySolution - getActiveVersion\(\)
Gets the active SimilaritySolutionVersion object.
|Name|Type|Description||----|----|-----------||None| | |
|Type|Description||----|-----------||Object|Active [SimilaritySolutionVersion](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionVersionAPI.md) object.|
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));

Text
Output:

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

Text
## SimilaritySolution - getAllVersions\(\)
Gets all versions of a SimilaritySolution object.
|Name|Type|Description||----|----|-----------||None| | |
|Type|Description||----|-----------||Array|Existing versions of a solution object. See also [SimilaritySolutionVersion](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionVersionAPI.md) API.|
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");

Text
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"}

Text
## SimilaritySolution - getLatestVersion\(\)
Gets the latest version of a solution.
|Name|Type|Description||----|----|-----------||None| | |
|Type|Description||----|-----------||Object|[SimilaritySolutionVersion](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionVersionAPI.md) object corresponding to the latest version of a [SimilaritySolution](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionAPI.md).|
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));

Text
Output:

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

Text
## SimilaritySolution - getName\(\)
Gets the name of the object to use for interaction with the store.
|Name|Type|Description||----|----|-----------||None| | |
|Type|Description||----|-----------||String|Name of the solution object.|
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());

Text
Output:

Solution Name: ml_x_snc_global_global_my_solution_definition_4

Text
## SimilaritySolution - getProperties\(\)
Gets solution object properties.
|Name|Type|Description||----|----|-----------||None| | |
<table id="table_qps_43z_llb" class="returns"><thead><tr><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
Object
</td><td>
Contents of the Dataset and [SimilaritySolution\(\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionAPI.md) object details in the [SimilaritySolutionStore](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionStoreAPI.md).```{  "domainName": "String",  "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.Type: String

<Object>.label

Identifies the prediction task. ``` { "label": "my first prediction" }

Text
 Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.lookupDatasetProperties
</td><td>
Details of the [DatasetDefinition\(\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/DatasetDefinitionAPI.md) 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" } ]

Text
 Data type: Array.
</td></tr><tr><td>
&lt;Object&gt;.lookupDatasetProperties.fieldNames.fieldDetails.&lt;object&gt;.name
</td><td>
Name of the field defining the type of information to restrict this dataset to. Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.lookupDatasetProperties.fieldDetails.&lt;object&gt;.type
</td><td>
Machine-learning field type. Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.lookupDatasetProperties.fieldDetails.encodedQuery
</td><td>
Encoded query string in the standard platform format. See [Encoded query strings](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/platform-user-interface/c_EncodedQueryStrings.md).Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.name
</td><td>
System-assigned name. Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.processingLanguage
</td><td>
Processing language in two-letter ISO 639-1 language code format. Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.scope
</td><td>
Object scope. Currently the only valid value is `global`.Data type: String
</td></tr><tr><td>
&lt;Object&gt;.stopwords
</td><td>
Optional. Preset list of strings that the system automatically generates based on the **language** property setting. For details, see [Create a custom stopwords list](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/intelligent-experiences/create-custom-stopwords-list.md). Data type: Array.
</td></tr><tr><td>
&lt;Object&gt;.testDatasetProperties
</td><td>
Details of the [DatasetDefinition\(\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/DatasetDefinitionAPI.md) 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" } ]

Text
 Data type: Array.
</td></tr><tr><td>
&lt;Object&gt;.testDatasetProperties.fieldNames.fieldDetails.&lt;object&gt;.name
</td><td>
Name of the field defining the type of information to restrict this dataset to. Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.testDatasetProperties.fieldDetails.&lt;object&gt;.type
</td><td>
Machine-learning field type. Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.testDatasetProperties.fieldDetails.encodedQuery
</td><td>
Encoded query string in the standard platform format. Data type: String.
</td></tr><tr><td>
&lt;Object&gt;.trainingFrequency
</td><td>
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.
</td></tr><tr><td>
&lt;Object&gt;.updateFrequency
</td><td>
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
</td></tr></tbody></table>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));

Text
Output:

*** Script: { "domainName": "global", "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" }

Text
## SimilaritySolution - getVersion\(String version\)
Gets a solution by provided version number.
|Name|Type|Description||----|----|-----------||version|String|Existing version number of a solution.|
|Type|Description||----|-----------||Object|Specified version of the [SimilaritySolution\(\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionAPI.md) object on which you can call [SimilaritySolutionVersion](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionVersionAPI.md) API methods.|
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));

Text
Output:

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

Text
## SimilaritySolution - setActiveVersion\(String version\)
Activates a specified version of a solution in the store.
<table id="table_pps_43z_llb" class="parameters"><thead><tr><th>
Name
</th><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
version
</td><td>
String
</td><td>
Name of the [SimilaritySolution\(\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionAPI.md) object version to activate.Activating this version deactivates any other version.
</td></tr></tbody></table>|Type|Description||----|-----------||None| |
The following example shows how to activate a solution version in the store.

sn_ml.SimilaritySolution.setActiveVersion("ml_x_snc_global_similarity_solution");

Text
## SimilaritySolution - submitTrainingJob\(\)
Submits a training job.
**Note:** Before running this method, you must first add a solution to the store using the [SimilaritySolutionStore - add\(\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionStoreAPI.md) method.
|Name|Type|Description||----|----|-----------||None| | |
|Type|Description||----|-----------||Object|[SimilaritySolutionVersion](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionVersionAPI.md) object corresponding to the [SimilaritySolution](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/SimilaritySolutionAPI.md) being trained.|

// 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 mySolution = new sn_ml.SimilaritySolution({ 'label': "similarity solution", 'lookupDataset' : kbData, 'testDataset' : incidentData });

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

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

Text
Search documentation
Search document titles and file paths on the brazil branch