The following example shows how to cancel an active training job that has been submitted using the submitTrainingJob() method.
var myCluster = new sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");
var mlSolutionVersion = myCluster.getActiveVersion();
mlSolutionVersion.cancelUpdateJob();
Deletes cluster assignments from rows by position in table sequence or GlideDateTime.
Name
Type
Description
options
Object
Object defining one option for deleting cluster assignments.Note: Only one delete option is valid.
options.updatedUntil
String
Deletes rows for clusters with `updated_since` values occurring before this value. Format must be provided as GlideDateTime.
{ "updatedUntil" : "String" }
options.sequenceUntil
String
Deletes rows for clusters with `insert_sequence` values occurring before this value in the ML Cluster Detail \[ml\_cluster\_detail\] table. The sequence position starting point value is 1.
{ "sequenceUntil" : Number }
Type
Description
Number
Number of rows deleted from the ML Cluster Detail [ml_cluster_detail] table.
The following example shows how to delete rows for clusters with updated_since time preceding '2020-06-28 02:50:53'.
var mlSolution = sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");
var mlSolutionVersion = mlSolution.getActiveVersion();
var options = {};
options.updatedUntil = '2020-06-28 02:50:53';
var results = mlSolutionVersion.deleteClusterAssignments(options);
gs.print("Number of deleted rows: "+results);
Output:
Number of deleted rows: 6417
The following example shows how to delete rows for clusters with updated_since that are sequentially positioned prior to 1000.
var mlSolution = sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution");
var mlSolutionVersion = mlSolution.getActiveVersion();
var options = {};
options.sequenceUntil = 1000;
var results = mlSolutionVersion.deleteClusterAssignments(options);
gs.print("Number of deleted rows: "+results);
Values to use to narrow down the returned results by group, level, system update times, and table row number within a clustering solution. Minimum of one argument must be specified.
Optional. Cluster ID of a trained solution in the Cluster Summary \[ml\_cluster\_summary\] table.
options.group\_by
String
Optional. Identifies the segmentation field for which to retrieve cluster memberships, for example, assignment_group.This field provides the same grouping as options provided in the Use Group By check box in the Clustering Definition form. The information provided varies based on the table selected in the Table field. For more information, see Create and train a clustering solution.
options.limit
Number
Optional. Maximum number of cluster assignments to retrieve.
options.sequenceSince
Number
Starting position in a table sequence. Returns information for clusters with insert\_sequence enabled and positioned after this value in the ML Cluster Detail \[ml\_cluster\_detail\] table. The sequence position starting point value is 1.
options.sequenceUntil
Number
Returns assignments for clusters with `insert_sequence` values occurring before this value in the ML Cluster Detail \[ml\_cluster\_detail\] table. The sequence position starting point value is 1.
options.topNPerCluster
Number
Number of top results to receive for each cluster.
options.updatedSince
String
Optional. Date and time. Returns information for clusters with `sys_updated_on` after the value provided in GlideDateTime.
options.updatedUntil
String
Optional. Date and time. Returns information for clusters with `sys_updated_on` before the value provided in GlideDateTime.
Type
Description
Array
List of objects containing cluster information in increasing order by cluster\_id.
Gets information for a specified clustering solution in the store. The purity measurement provides insights as a percentage for the clustering fields on which the purity is based.
Name
Type
Description
options
Object
Optional. Object containing properties that enable filtering results within a clustering solution.
Default: Return cluster memberships for all clusters.
options.clusterId
String
Optional. Cluster ID of a trained solution in the Cluster Summary \[ml\_cluster\_summary\] table.
options.groupBy
String
Optional. Identifies the segmentation field for which to retrieve cluster memberships, for example, assignment_group.This field provides the same grouping as options provided in the Use Group By check box in the Clustering Definition form. The information provided varies based on the table selected in the Table field. For more information, see Create and train a clustering solution.
options.limit
Number
Optional. Maximum number of cluster assignments to retrieve.
options.recSysId
String
Optional. Sys\_id of a record by which to find cluster information.
options.sequenceSince
Number
Starting position in a table sequence. Returns information for clusters with insert\_sequence enabled and positioned after this value in the ML Cluster Detail \[ml\_cluster\_detail\] table. The sequence position starting point value is 1.
options.sequenceUntil
Number
Optional. Ending position in a table sequence. Returns assignments for clusters with `insert_sequence` values occurring before this value in the ML Cluster Detail \[ml\_cluster\_detail\] table. The sequence position starting point value is 1.
options.updatedSince
String
Optional. Date and time. Returns information for clusters with `sys_updated_on` after the value provided in GlideDateTime format.
options.updatedUntil
String
Optional. Date and time. Returns information for clusters with `sys_updated_on` before the value provided in GlideDateTime.
'algorithmConfig': {
"algorithm": "kmeans",
"targetCoverage": Number
}
Data type: String
<Object>.algorithmConfig.distanceMetric
DBSCAN algorithm only. Distance metric to scan for similar data objects. Data type: String
<Object>.algorithmConfig.epsilon
DBSCAN algorithm only. Decimal value between 0 and 1 representing the size of the neighborhood search radius. Data type: Number
<Object>.algorithmConfig.minimumNeighbours
DBSCAN algorithm only. Minimum number of neighbors required in a point to be a part of a cluster. For levenshteinDistance the value must be 1 so that no points are excluded from the dataset. Data type: Number
<Object>.algorithmConfig.targetCoverage
K-means algorithm only. Percentile field to filter out records that are less similar to each other. Data type: Number
<Object>.datasetProperties
Lists the properties of the DatatsetDefinition object associated with the solution. ``` { "encodedQuery": "String", "fieldDetails": [Array], "fieldNames": [Array], "tableName": "String" }
Data type: Object
</td></tr><tr><td>
<Object>.datasetProperties.encodedQuery
</td><td>
Encoded query string in the standard platform format. See <a href="../../../platform-user-interface/c_EncodedQueryStrings/">Encoded query strings</a>.Data type: String.
</td></tr><tr><td>
<Object>.datasetProperties.fieldDetails
</td><td>
List of JavaScript objects that specify field properties. Data type: Array of Objects
[ { "name": "String", "type": "String" } ]
</td></tr><tr><td>
<Object>.datasetProperties.fieldDetails.name
</td><td>
Name of the field defining the type of information to restrict this dataset to. Data type: String
</td></tr><tr><td>
<Object>.datasetProperties.fieldDetails.type
</td><td>
Machine-learning field type. Data type: String
</td></tr><tr><td>
<Object>.datasetProperties.fieldNames
</td><td>
List of field names from the specified table as strings. For example, `"fieldNames" : ["short_description", "priority"]`. Data type: Array
</td></tr><tr><td>
<Object>.datasetProperties.tableName
</td><td>
Name of the table for the dataset. For example, `"tableName" : "Incident"`. Data type: String
</td></tr><tr><td>
<Object>.domainName
</td><td>
Domain name associated with this dataset. See <a href="../../../intelligent-experiences/predictive-intelligence/domain-separation-predictive-intelligence/">Domain separation and Predictive Intelligence</a>.Type: String
</td></tr><tr><td>
Object.groupByFieldName
</td><td>
Field name by which the system groups records into one or more clusters. Data type: String
</td></tr><tr><td>
Object.inputFieldNames
</td><td>
List of input field names as strings. The model uses these fields used to make predictions. Data type: String
</td></tr><tr><td>
<Object>.isActive
</td><td>
Flag that indicates whether this version is active.Valid values:
- true: Version is active.
- false: Version is not active.
Data type: String
</td></tr><tr><td>
<Object>.label
</td><td>
Identifies the prediction task.
{ "label": "my first prediction" }
Data type: String
</td></tr><tr><td>
<Object>.minRecordsPerCluster
</td><td>
Minimum number of records to allow in any cluster. Data type: Number
</td></tr><tr><td>
<Object>.name
</td><td>
System-assigned name. Data type: String
</td></tr><tr><td>
<Object>.processingLanguage
</td><td>
Processing language in two-letter ISO 639-1 language code format. Data type: String
</td></tr><tr><td>
<Object>.scope
</td><td>
Object scope. Currently the only valid value is `global`.Data type: String
</td></tr><tr><td>
<Object>.stopwords
</td><td>Optional. Preset list of strings that the system automatically generates based on the <strong>language</strong> property setting. For details, see <a href="../../../intelligent-experiences/predictive-intelligence/create-custom-stopwords-list/">Create a custom stopwords list</a>. Data type: Array</td></tr><tr><td>
<Object>.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>
<Object>.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
Data type: String
</td></tr><tr><td>
<Object>.versionNumber
</td><td>
Version number of the ClusteringSolution object.
</td></tr></tbody>
</table>
The following example gets properties of the active object version in the store.
// Get properties var mlSolution = sn_ml.ClusteringSolutionStore.get('ml_x_snc_global_global_clustering_solution'); gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getProperties()), null, 2));
## ClusteringSolutionVersion - getStatus\(Boolean includeDetails\)
Gets training completion status.
<table id="table_xfh_vbw_plb" class="parameters"><thead><tr><th>
Name
</th><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
includeDetails
</td><td>
Boolean
</td><td><p>Flag that indicates whether to return status <strong>details</strong>.Valid values:</p>
<ul>
<li>true: Return additional details.</li>
<li>false: Don't return additional details.</li>
</ul>
<p>Default: False</p></td></tr></tbody>
</table>
<table id="table_yfh_vbw_plb" class="returns"><thead><tr><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
Object
</td><td>
JavaScript object containing training status information for a <a href="../ClusteringSolutionAPI/">ClusteringSolution</a> object.
{ "state": "String", "percentComplete": "Number as a String", "hasJobEnded": "Boolean value as a String", "details": {Object} }
</td></tr><tr><td>
<Object>.state
</td><td><p>Training completion state. If the training job reaches a terminal state, the job does not leave that state. If the state is terminal, the <strong>hasJobEnded</strong> property is set to <code>true</code>.Possible values:</p>
<ul>
<li><code>fetching_files_for_training</code></li>
<li><code>preparing_data</code></li>
<li><code>retry</code></li>
<li><code>solution_cancelled</code> (terminal)</li>
<li><code>solution_complete</code>(terminal)</li>
<li><code>solution_error</code> (terminal)</li>
<li><code>solution_incomplete</code></li>
<li><code>training_request_received</code></li>
<li><code>training_request_timed_out</code> (terminal)</li>
<li><code>training_solution</code></li>
<li><code>uploading_solution</code></li>
<li><code>waiting_for_training</code></li>
</ul>
<p>Data type: String</p></td></tr><tr><td>
<Object>.hasJobEnded
</td><td>
Flag that indicates whether training is complete.Valid values:
- true: Training is complete.
- false: Training is incomplete.
Data type: Boolean value as a String
</td></tr><tr><td>
<Object>.percentComplete
</td><td>
Training percent complete. If the completion percentage is less than 100, the job might be in a terminal state. For example, if training times out.Data type: Number as a String
Range: 0 thru 100
</td></tr><tr><td>
<Object>.details
</td><td>
Object containing a list of additional training details.Data type: Object
</td></tr></tbody>
</table>
The following example shows a successful result with training complete.
// Get status var mlSolution = sn_ml.ClusteringSolutionStore.get('ml_x_snc_global_global_cluster_solution'); gs.print(JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getStatus(true), null, 2)));
Output:
{ "state":"solution_complete", "percentComplete":"100", "hasJobEnded":"true", "details":{"stepLabel":"Solution Complete"} // This information is only returned if getStatus(true); }
The following example shows an unsuccessful result with training complete.
// Get status var solutionName = 'ml_x_snc_global_global_cluster_solution'; var mlSolution = sn_ml.ClusteringSolutionStore.get(solutionName); var trainingStatus = mlSolution.getLatestVersion().getStatus(); gs.print(JSON.stringify(JSON.parse(trainingStatus), null, 2));
## ClusteringSolutionVersion - getTopNPurityInfo\(Object options\)
Gets the top purity results for a clustering solution. The purity measurement provides insights as a percentage for the clustering fields on which the purity is based.
<table id="table_q13_tk3_wnb" class="parameters"><thead><tr><th>
Name
</th><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
options
</td><td>
Object
</td><td>
Options that determine the number and format of the top cluster purity results.
</td></tr><tr><td>
options.clusterIds
</td><td>
Array
</td><td>
Optional. List of cluster IDs provided as strings. A cluster ID is provided in the Cluster Summary \[ml\_cluster\_summary\] table. If provided, this method returns purity cluster information for each specified cluster. Default: This method returns purity information for all clusters.
</td></tr><tr><td>
options.groupBy
</td><td>
Array
</td><td>Optional. List of group_by field strings from your table to help the system identify the class which is most frequent in the cluster. If provided, returns purity information for cluster solutions using group_by fields. The Cluster Summary [ml_cluster_summary] table lists clusters and any associated Group by values.This field only applies to clusters that use group by in the clustering definition. Eligible fields are listed in the <strong>Table</strong> field. For details on the group by feature, refer to <a href="../../../intelligent-experiences/predictive-intelligence/create-clustering-solution/">Create and train a clustering solution</a>.</td></tr><tr><td>
options.purityFields
</td><td>
Array
</td><td><p>Optional. List of purity field strings. If provided, this method only returns information for these purity fields. You can view purity values for a cluster in the Cluster Summary [ml_cluster_summary] table lists.<strong>Note:</strong> If both <strong>purity_fields</strong> and <strong>top_n_fields</strong> are provided, this method returns <strong>top_n_fields</strong> first, then selects fields from <strong>purity_fields</strong>.</p>
<p>Default: Return purity information for all purity fields saved for the cluster.</p></td></tr><tr><td>
options.topN
</td><td>
Number
</td><td>
Optional. Restricts the number of predictions to return to the highest values for each purity field.Maximum value: 10
Default: Return all purity information for each purity field.
</td></tr><tr><td>
options.topNFields
</td><td>
Number
</td><td>
Optional. Restricts the number of purity fields returned to fields with the highest purity for each cluster.Maximum value: 10
Default: Return all fields in the cluster.
</td></tr></tbody>
</table>
<table id="table_r13_tk3_wnb" class="returns"><thead><tr><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
String
</td><td><p>JSON-formatted string containing a list of clusters with purity fields and details.<strong>Note:</strong> Results vary based on settings made in the <strong>options</strong> input parameter.</p>
<p>The following information illustrates how cluster purity results are sorted and categorized. Refer to the example for actual output.</p>
<p><code>{
"<clusterID>":[
// List sorted by purity per field
{ "<fieldName>":[
// List sorted by purity per field value
{"<field_val1_1>":"<purity>"},
// Additional field values
]},
// Additional fields
],
// Additional clusters
}</code></p></td></tr><tr><td>
String.<clusterID>
</td><td>
List of clusters arranged in descending order by purity value per cluster.Data type: Array
</td></tr><tr><td>
String.<clusterID>.<field>
</td><td><p>List of objects representing purity fields arranged in descending order by purity value per field. The <strong>options.top_n_fields</strong> input object parameter property determines the number of fields returned.<code>"<field>":[{"<field_val>":"<purity>"}]}</code></p>
<p>Data type: Array</p></td></tr><tr><td>
String.<clusterID>.<field>.<values>
</td><td>List of objects containing field value and purity. For example, <code>{"priority":[{"5":"100"}]}</code> is a priority field with a score of 5 and a purity value of 100 percent. Results list in descending order by purity percentage. The <strong>options.top_n</strong> input object parameter property determines the number of results returned.Data type: Array</td></tr></tbody>
</table>
The following example shows how to get the top two purity results for the category field in specific cluster solutions.
var solution = new GlideRecord('ml_solution'); solution.addQuery('sys_id', ''); solution.addQuery('active', 'true'); solution.query(); while (solution.next()) { var options = {}; options.clusterIds = ['1', '3', '5']; options.purityFields = ['category']; options.topN = '2'; options.topNFields = '2'; var clustering = new sn_ml.ClusteringSolutionVersion(solution); var results = clustering.getTopNPurityInfo(options); gs.info(results); }
Output displays purity insights based on the settings provided in the options parameter.
## ClusteringSolutionVersion - getUpdateStatus\(\)
Gets the status of the most recent clustering solution update job.
|Name|Type|Description|
|----|----|-----------|
|None| | |
<table id="table_lx2_w3b_rlb" class="returns"><thead><tr><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
String
</td><td>
State of the clustering solution update.States:
- Configuration or network error
- Error while updating solution
- Fetching files for updating
- Preparing data
- Unauthorized
- Update complete
- Updating is cancelled
- Updating request received
- Updating request timed out
- Updating solution
- Uploading
- Waiting
</td></tr></tbody>
</table>
The following example shows how to get the update status of a clustering solution.
var myCluster = new sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution"); gs.print(JSON.stringify(myCluster.getActiveVersion().getUpdateStatus()));
Output:
"Update Complete"
## ClusteringSolutionVersion - getVersionNumber\(\)
Gets the version number of a solution object.
|Name|Type|Description|
|----|----|-----------|
|None| | |
|Type|Description|
|----|-----------|
|String|Version number.|
The following example shows how to get a version number.
// Get version number var mlSolution = sn_ml.ClusteringSolutionStore.get('ml_x_snc_global_global_clustering_solution'); gs.print("Version number: "+JSON.stringify(JSON.parse(mlSolution.getActiveVersion().getVersionNumber()), null, 2));
Output:
Version number: 1
## ClusteringSolutionVersion - submitUpdateJob\(Object options\)
Submits clustering update jobs with options to narrow results to a specific table and filter for matching records.
<table id="table_gby_x2w_plb" class="parameters"><thead><tr><th>
Name
</th><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
options
</td><td>
Object
</td><td>
JavaScript object containing options on which to base a clustering solution update.
{ "filter" : "String", "table" : "String" }
</td></tr><tr><td>
options.filter
</td><td>
String
</td><td>
Encoded query string in the standard platform format. Enables running an update job based on the filter provided.
</td></tr><tr><td>
options.table
</td><td>
String
</td><td>
Name of the table on which to run an update job.
</td></tr></tbody>
</table>
|Type|Description|
|----|-----------|
|None| |
The following example shows how to submit an update job.
var myCluster = new sn_ml.ClusteringSolutionStore.get("ml_x_snc_global_global_clustering_solution"); var options = {"filter" : "precision", "table" : "incident"}; myCluster.getActiveVersion().submitUpdateJob(options); ```