ClusterSnapshot

Allows you to take a snapshot of the IDOL Server data index, or of the profiles stored in the IDOL Server agent index. A snapshot is an internal raw data format that IDOL Category Component uses to extract clusters. Snapshots allow you to generate cluster information and spectrographs.

NOTE: This is an administrative action that can be sent only by users that belong to an authorization role that allows the Admin standard role, or which enables the action explicitly. See Authorization Roles Configuration Parameters.

When you send the ClusterSnapshot action, it is queued. After it has finished, the snapshot it has produced is timestamped in epoch seconds (the number of seconds since 1 January 1970) and listed in binary .CLS format in the idol/category/cluster/SNAPSHOTS directory in your IDOL Category Component installation directory. This process allows you to have several snapshots with the same name (for example, of one particular IDOL Server data index) and snapshots with different names (for example, of different IDOL Server data indexes).

You can restrict snapshots of the IDOL Server data index to:

  • IDOL Server query results

  • specific IDOL Server databases

  • a specific period of time

  • multiple snapshots over a period, at specified intervals

NOTE: If you take a snapshot of the IDOL Server data index, the index must ideally contain at least 5,000 documents with good quality content (that is, relevant text for various topics).

You can restrict snapshots of profiles to:

  • a specific period of time

  • multiple snapshots over a period, at specified intervals

If you send the ClusterSnapshot action multiple times, it is likely to result in different snapshots (even if you use the same parameters with the action), because snapshots are based on a random selection of IDOL Server documents. You can change this behavior by setting the RandomSeed parameter in the [Server] section of the IDOL Category Component configuration file, which ensures that multiple snapshots of the same data are based on the same sample of IDOL Server documents.

After you take a snapshot, you can use the ClusterCluster action to generate cluster WhatsHot or WhatsNew information, and to provide the information that you need to generate spectrograph data by using the ClusterSGDataGen action.

Example

http://12.3.4.56:9020/action=ClusterSnapshot&TargetJobName=Job1&DREQuery=action%3DQuery%26Text%3Dstock%20market%26MaxResults%3D5000

This action sends a request for a snapshot called Job1. The snapshot is restricted to 5000 result documents that contain the term stock market.

Required Parameters

The following action parameters are required.

Parameter Description
TargetJobName The name of the snapshot to generate.

Optional Parameters

This action accepts the following optional parameters.

Parameter Description
AndCluster Whether to generate clusters immediately from the snapshot.
Cluster If using FocusJobName, the IDs of one or more clusters that you want to re-cluster.
Cycles The number of times to run the action.
Databases Restricts the snapshot to one or more databases.
DREQuery Restricts the snapshot to query results.
EndDays How many days ago a snapshot period ends.
Gap The interval between periods when snapshots are taken.
Fields Fields to add to the snapshot.
FocusJobName The name of a clustering job that contains one or more clusters that you want to re-cluster.
FocusStrength If using FocusJobName, how strongly to apply the focusing.
NegativeClusters If using RefineJobName, one or more existing clusters to bias the new clustering away from.
NegativeTerms If using RefineJobName, one or more terms to bias the new clustering away from.
NumClusters The maximum number of clusters to identify.
Params The names of parameters to use in the Suggest actions that IDOL Category Component uses to create seeds for the snapshot.
Period The number of days that the snapshot spans.
PositiveClusters If using RefineJobName, one or more existing clusters to bias the new clustering toward.
PositiveTerms If using RefineJobName, one or more terms to bias the new clustering toward.
Profile Takes a snapshot of the profiles in the IDOL Server Agent index.
RefineJobName The name of a clustering job to re-cluster, biasing toward or against certain terms or clusters.
RefineStrength If using RefineJobName, how strongly or weakly to apply the refinement.
Repeat The time to elapse between runs of the action.
Retries The number of times to retry a failed action.
RetryInterval The number of seconds to wait before retrying a failed action.
SecurityInfo Sends security details.
SeedBindLevel A value that specifies how closely bound concepts must be to form a cluster seed.
SeedSize The size of the document group that forms a seed.
SentientClustering Whether to automatically derive the appropriate SeedBindLevel and SeedSize.
StartDays How many days ago a snapshot period starts.
StartTime The time to run the first action.
StartingSuggestOverrideFactor The portion of the Data index to use in the snapshot.
SummaryField The field that contains a result summary.
TimeSpanSnapshot Whether to take snapshots across a particular period.
Values The values for the specified Params.
XMLEncoding Overrides the default XML encoding.

This action accepts the following standard ACI action parameters.

Parameter Description
ActionID A string to use to identify an ACI action.
FileName The file to write output to.
ForceTemplateRefresh Forces the server to load the template from disk.
Output Writes output to a file.
ResponseFormat The format of the action output.
Template The template to use for the action output.
TemplateParamCSVs A list of variables to use for the specified template.