Analytics Classification Index (.NET)

A classification index is a type of index used by Relativity Analytics. This index type uses coded examples to build a Support Vector Machine (SVM) to predict the relevance of a document. It learns how terms are related to categories based on the contents of your documents and coding decisions made within the Active Learning project. This index type is used solely by the Active Learning application. For general information, see Analytics indexes and Creating an Active Learning project on the RelativityOne Documentation site.

The Analytics Classification Index API supports programmatically managing classification indexes in Relativity Analytics. It includes the following features:

  • Supports CRUD operations on classification indexes.
  • Provides helper methods that simplify working with index jobs. You can use these methods to submit and cancel jobs, and to check on their statuses. These jobs can populate new data, build new indexes, and activate indexes for use.

As a sample use case, you might use this API in an application to programmatically operate on a classification index.

You can also use the Classification Index API through REST. For more information, see Analytics Classification Index (REST).

The Relativity.Analytics.Classification.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Fundamentals for the Classification Index API

Review the following information to learn about the methods, classes, and enumerations used by the Classification Index API.

Methods

The Classification Index API includes the following methods available on the IClassificationIndexService interface in the Relativity.Analytics.Classification.<VersionNumber>.Services namespace.

Note: The <VersionNumber> variable in the namespace indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 or V2 in .NET.

Classes and enumerations

The Classification Index API uses the following key classes and enumerations:

  • AnalyticsIndexJobType enumeration - defines valid index job types as follows:
    • FullPopulation (0) - runs a full index population.
    • IncrementalPopulation (1) - runs an incremental population. This process adds or removes documents from the training and searchable sets. If active, the index remains active, and you can query it during the incremental population. You can't query new documents until a build followed by an activate is completed.
    • RetryErrors (2) - runs a full population if a previous population attempt failed.
    • RemoveDocumentsInError (3) - removes documents in error.
    • BuildIndex (4) - runs a full index build. If any training documents are added, this step takes longer because the engine rebuilds the concept space. If only searchable documents are added, the engine starts this build at a later step, updating searchable items, because it only maps the new searchable documents into the pre-existing concept space.
    • Activate (5) - activates the index for querying.
    • Deactivate(6) - disables queries on the index. The index must be deactivated to perform a build.
  • AnalyticsIndexStatus class - represents the aggregate state of an index. The GetStatusAsync() method returns a status object. Its properties include:
    • Active - indicates whether the index is active and can be queried.
    • ConsoleButtons - a list of console buttons and links with their current states. The states can be used to determine which job steps can be run for the index. See AnalyticsIndexJobType enumeration in Classes and enumerations.
    • CurrentStep - the current job step when a multi-step job is in progress.
    • DocLevelErrorsExist - indicates whether documents in the training set are in error.
    • LastErrorMessage - the last error that occurred on the index
    • OverallTimeElapsed - the total time of the current job when one exists.
    • PercentageComplete - the completed percentage of the current job step when one exists.
    • PercentDenominator - the denominator value used to generate the percentage of the current job step when one exists.
    • PercentNumerator - the numerator value used to generate the percentage of the current job step when one exists.
    • SearchableSetCount - the count of items in the searchable set when an index is new or active in its final state.
    • SecondaryPercentageComplete - the completed percentage of a stage of a job step when one exists.
    • SecondaryStatusText - additional status text.
    • StatusText - the main status text of the index. For more information, see Index states and job validation.
    • StepTimeElapsed - the elapsed time of the current job step when one exists.
    • TotalSteps - the total number of job steps when a multi-step job is in progress.
    • TrainingSetCount - the count of items in the training set when the index is new or active in its final state.
  • ArtifactRef class - represents a Relativity artifact referenced by an index property, such as repeated content filters, searchable sets, and training sets. Its properties include:
    • ArtifactID - represents a unique identifier, called an Artifact ID, for an object.
    • Guids - represents the GUIDs used to identify an object.
  • ClassificationIndex class - represents an index. Its properties include:
    • Active - indicates whether the index is active
    • AnalyticsServer - the Analytics server used to build the index. This value is a ArtifactRef object.
    • ArtifactID - the Artifact ID of the index.
    • EmailNotificationRecipients - the list of email recipients notified during index population and build.
    • Guids - the GUIDs for this artifact.
    • IndexLastUsedOn - the time when this index was last used.
    • InUseByCategorizationSet - indicates whether the index is in use by an SVM categorization set.
    • LastErrorMessage - the last error message to occur on the index.
    • Name - the user-friendly name of the index.
    • Order - an integer representing the position of the index in drop-down menus. The default value is 0.
    • SearchableSet - the saved search to populate the searchable set. This value is a ArtifactRef object.

Guidelines for using the Classification Index API

Review the following guidelines for working with the Classification Index API.

Catch exceptions

When using any methods in the Classification Index API, catch the following exceptions:

  • PermissionException
  • ValidationException
  • Generic .NET Exception

Execute valid operations for the index state

Execute only valid operations for the state of an index. Only certain operations are valid for the current state of your index. See the following examples:

  • A call to cancel a running index job is only valid when a job is currently running for the index.
  • A call to build an index can't run on an index that hasn't been populated.

    • Note: To retrieve a list of valid operations, get the AnalyticsIndexStatus object. Examine the ConsoleButtons property on the returned object for a list of valid operations to call. You can also get additional information about the job from the StatusText and AdditionalStatusText properties. If you attempt to execute an invalid operation, you receive validation error. See Retrieve the status of a job.

Index states and job validation

When performing operations on an index, make sure that the operation is applicable to its current state.

View index states

Some states overlap with each other, and others have sub-states depending on additional index metadata. For example, many states include an error state, such as STATE – 1 or more documents in error status, when state is populating, building, and so on.

For example, an error scenario occurs when items linked to the index (saved searches, Analytics profile) can't be accessed. Regardless of any additional error state, the validator treats it as an error. It subsequently only lets the two error resolution-type jobs run: RetryErrors or RemoveDocumentsInError. The message state values are returned as the StatusText property.

The states of an index are as follows:

  • Activating
  • Activation Recommended
  • Active
  • Attempting to cancel population
  • Build Recommended
  • Building
  • Configuring Analytics Engine
  • Constructing Population Table
  • Content Analyst Server is unavailable
  • Deactivating
  • Disable queries to continue
  • Disabling Queries
  • Enabling Queries
  • Failed to activate index
  • Failed to deactivate index
  • Finalizing build
  • Index Build Failed
  • Indexing Job in Queue
  • New
  • Not enough conceptual content to build
  • Please check your training set
  • Populating
  • Populating Documents
  • Population Canceled by User
  • Population Failed
  • Preparing to build
  • Removing Documents in Error
  • Waiting

Monitor the analysis progress

After submitting an index job, monitor its progress by making calls to its status. See Retrieve a classification index.

Create a classification index

Use the CreateAsync() method to add a new classification index to Relativity. Set the following properties on the ClassificationIndex object passed to the CreateAsync() method:

  • AnalyticsServer - an ArtifactRef object representing the Analytics server used to build the index. In RelativityOne environments, set the Artifact ID -1.
  • Name - the user-friendly name of the index.
  • Order - an integer representing the position of the index in drop-down menus. The default value is 0.
  • SearchableSet - an ArtifactRef object representing the saved search used to populate the searchable set.

When the operation succeeds, it returns the Artifact ID of the new index. Use this Artifact ID to submit the index for populating and building.

Copy 
public async Task CreateAsyncSampleCode() {
  ServiceFactorySettings settings = new ServiceFactorySettings(
    new Uri("net.pipe://localhost/relativity.services/"),
    new Uri("http://localhost/relativity.rest/api"),
    new IntegratedAuthCredentials());
  ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityServicesUri), new Uri(relativityRestUri), usernamePasswordCredentials);
  ServiceFactory serviceFactory = new ServiceFactory(settings);

  using (IClassificationIndexService indexService = serviceFactory.CreateProxy<IClassificationIndexService>()) {
    int workspaceId = 1023289;
    int searchableSetSearchArtifactID = 1038051;
    int trainingSetSearchArtifactID = 1038051;
    int analyticsServerArtifactID = 1016891;

    ClassificationIndex indexToCreate = new ClassificationIndex {
      Name = "my new analytics index",
        Order = 1,
        SearchableSet = new ArtifactRef {
          ArtifactID = searchableSetSearchArtifactID
        },
        AnalyticsServer = new ArtifactRef {
          ArtifactID = analyticsServerArtifactID
        }
    };

    try {
      int classificationIndexID = await indexService.CreateAsync(workspaceId, indexToCreate);
      Debug.WriteLine("ID of the newly created index is: " + classificationIndexID);
    } catch (PermissionException ex) {
      _logger.LogError(ex,
        "Failed to create index because of invalid permission. workspaceID: {workspaceId} - IndexToCreate: {@index}",
        workspaceId, indexToCreate);
      throw;
    } catch (ValidationException ex) {
      _logger.LogError(ex,
        "The index you were trying to create was invalid. workspaceID: {workspaceId} - IndexToCreate: {@index}",
        workspaceId, indexToCreate);
      throw;
    } catch (Exception ex) {
      _logger.LogError(ex,
        "Creating index failed. workspaceID: {workspaceId} - IndexToCreate: {@index}",
        workspaceId, indexToCreate);
      throw;
    }
  }
}

Retrieve a classification index

Use the ReadAsync() method to retrieve a classification index. Pass the Artifact IDs of the workspace and the index to this method. It returns a ClassificationIndex object. You can use this object to examine the index properties before submitting an index job, or updating or deleting an index.

Copy 
public async Task ReadSingleAsyncSampleCode() {
  string userName = "user@test.com";
  string password = "Test1234!";

  string relativityServicesUri = "http://localhost/relativity.services";
  string relativityRestUri = "http://localhost/relativity.rest/api";

  var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, password);
  ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityServicesUri), new Uri(relativityRestUri), usernamePasswordCredentials);
  ServiceFactory serviceFactory = new ServiceFactory(settings);

  using (IClassificationIndexService indexService = serviceFactory.CreateProxy<IClassificationIndexService>()) {
    int workspaceId = 1023289;
    int existingIndexArtifactID = 1049079;

    try {
      ClassificationIndex classificationIndex = await indexService.ReadAsync(workspaceId, existingIndexArtifactID);
    } catch (PermissionException ex) {
      _logger.LogError(ex,
        "You don't have permission to retrieve the index. WorkspaceID {workspaceId} - IndexID {IndexId} - username: {username}",
        workspaceId, existingIndexArtifactID, userName);
      throw;
    } catch (NotFoundException ex) {
      _logger.LogError(ex,
        "Failed to retrieve the index because index could not be found. WorkspaceID: {workspaceID} - IndexID: {IndexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    } catch (Exception ex) {
      _logger.LogError(ex,
        "Failed to retrieve the index. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    }
  }
}

Update a classification index

Use the UpdateAsync() method to modify a classification index. You can update multiple properties on a ClassificationIndex object. For a list of properties, see the ClassificationIndex class in Classes and enumerations.

Copy 
public async Task UpdateAsyncSampleCode() {
  string userName = "user@test.com";
  string password = "Test1234!";

  string relativityServicesUri = "http://localhost/relativity.services";
  string relativityRestUri = "http://localhost/relativity.rest/api";

  var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, password);
  ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityServicesUri), new Uri(relativityRestUri), usernamePasswordCredentials);
  ServiceFactory serviceFactory = new ServiceFactory(settings);

  using (IClassificationIndexService indexService = serviceFactory.CreateProxy<IClassificationIndexService>()) {
    int workspaceId = 1023289;
    int existingIndexArtifactID = 1049079;

    ClassificationIndex classificationIndex = null;

    try {
      try {
        classificationIndex = await indexService.ReadAsync(workspaceId, existingIndexArtifactID);
      } catch (PermissionException ex) {
        _logger.LogError(ex,
          "You don't have permission to read the index. WorkspaceID {workspaceId} - IndexID {IndexId} - username: {username}",
          workspaceId, existingIndexArtifactID, userName);
        throw;
      } catch (NotFoundException ex) {
        _logger.LogError(ex,
          "Failed to read the index because index could not be found. WorkspaceID: {workspaceID} - IndexID: {IndexId}",
          workspaceId, existingIndexArtifactID);
        throw;
      }
      classificationIndex.Name = "My Updated Analytics Index";
      await indexService.UpdateAsync(workspaceId, existingIndexArtifactID, classificationIndex);

      classificationIndex = await indexService.ReadAsync(workspaceId, existingIndexArtifactID);

      Debug.WriteLine("The updated name of the retrieved index is " + classificationIndex.Name);

    } catch (PermissionException ex) {
      _logger.LogError(ex,
        "You don't have permission to update the index. WorkspaceID {workspaceId} - IndexID {IndexId} - username: {username}",
        workspaceId, existingIndexArtifactID, userName);
      throw;
    } catch (ValidationException ex) {
      _logger.LogError(ex,
        "The index you were trying to update has invalid data. workspaceID: {workspaceId} - IndexToUpdate: {@index}",
        workspaceId, classificationIndex);
      throw;
    } catch (Exception ex) {
      _logger.LogError(ex,
        "Failed to update the index. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    }
  }
}

Delete a classification index

Use the DeleteAsync() to remove a classification index from Relativity. Pass the Artifact IDs of the workspace and the index to this method.

Copy 
public async Task DeleteAsyncSampleCode() {
  string userName = "user@test.com";
  string password = "Test1234!";

  string relativityServicesUri = "http://localhost/relativity.services";
  string relativityRestUri = "http://localhost/relativity.rest/api";

  var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, password);
  ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityServicesUri), new Uri(relativityRestUri), usernamePasswordCredentials);
  ServiceFactory serviceFactory = new ServiceFactory(settings);

  using (IClassificationIndexService indexService = serviceFactory.CreateProxy<IClassificationIndexService>()) {
    int workspaceId = 1023289;
    int existingIndexArtifactID = 1054085;

    try {
      await indexService.DeleteAsync(workspaceId, existingIndexArtifactID);
    } catch (PermissionException ex) {
      _logger.LogError(ex,
        "Deleting Index failed because of invalid permission. WorkspaceID {workspaceId} - IndexID {IndexId} - username: {username}",
        workspaceId, existingIndexArtifactID, userName);
      throw;
    } catch (NotFoundException ex) {
      _logger.LogError(ex,
        "Deleting Index failed because index could not be found. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    } catch (DeletionDependencyException ex) {
      _logger.LogError(ex,
        "Deleting Index failed because there is a dependecy on it. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    } catch (Exception ex) {
      _logger.LogError(ex,
        "Deleting index failed. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    }
  }
}

Helper methods for classification index jobs

Use the following methods for managing jobs related to classification indexes.

Submit a classification index job

Use the SubmitJobAsync() method to submit a classification index job. Pass the Artifact IDs for the workspace and index, and a job type to this method. For a list of job types, see Classes and enumerations.

Copy 
public async Task SubmitJobAsyncSampleCode() {
  string userName = "user@test.com";
  string password = "Test1234!";

  string relativityServicesUri = "http://localhost/relativity.services";
  string relativityRestUri = "http://localhost/relativity.rest/api";

  var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, password);
  ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityServicesUri), new Uri(relativityRestUri), usernamePasswordCredentials);
  ServiceFactory serviceFactory = new ServiceFactory(settings);

  using (IClassificationIndexService indexService = serviceFactory.CreateProxy<IClassificationIndexService>()) {
    int workspaceId = 1023289;
    int existingIndexArtifactID = 1054087;

    try {
      await indexService.SubmitJobAsync(workspaceId, existingIndexArtifactID, AnalyticsIndexJobType.FullPopulation);
    } catch (PermissionException ex) {
      _logger.LogError(ex,
        "You don't have permission to submit the index. WorkspaceID {workspaceId} - IndexID {IndexId} - username: {username}",
        workspaceId, existingIndexArtifactID, userName);
      throw;
    } catch (Exception ex) {
      _logger.LogError(ex,
        "Failed to submit the index. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    }
  }
}

Retrieve the status of a job

Use the GetStatusAsync() method to get the status of a classification index job. Pass the Artifact IDs of the workspace and the index to this method. It returns an AnalyticsIndexStatus object.

Copy 
public async Task GetStatusAsyncSampleCode() {
  string userName = "user@test.com";
  string password = "Test1234!";

  string relativityServicesUri = "http://localhost/relativity.services";
  string relativityRestUri = "http://localhost/relativity.rest/api";

  var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, password);
  ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityServicesUri), new Uri(relativityRestUri), usernamePasswordCredentials);
  ServiceFactory serviceFactory = new ServiceFactory(settings);

  using (IClassificationIndexService indexService = serviceFactory.CreateProxy<IClassificationIndexService>()) {
    int workspaceId = 1023289;
    int existingIndexArtifactID = 1049072;

    try {
      AnalyticsIndexStatus status = await indexService.GetStatusAsync(workspaceId, existingIndexArtifactID);
      Debug.WriteLine("Status of the index is " + status.StatusText);
    } catch (PermissionException ex) {
      _logger.LogError(ex,
        "You don't have permission to get the index states. WorkspaceID {workspaceId} - IndexID {IndexId} - username: {username}",
        workspaceId, existingIndexArtifactID, userName);
      throw;
    } catch (NotFoundException ex) {
      _logger.LogError(ex,
        "Couldn't get the index status because index could not be found. WorkspaceID: {workspaceID} - IndexID: {IndexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    } catch (Exception ex) {
      _logger.LogError(ex,
        "Failed to get the index status. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    }
  }
}

Cancel a job

Use the CancelJobAsync() method to cancel a running classification index job. Pass the Artifact IDs of the workspace and the index to this method.

Copy 
public async Task CancelJobAsyncSampleCode() {
  string userName = "user@test.com";
  string password = "Test1234!";

  string relativityServicesUri = "http://localhost/relativity.services";
  string relativityRestUri = "http://localhost/relativity.rest/api";

  var usernamePasswordCredentials = new UsernamePasswordCredentials(userName, password);
  ServiceFactorySettings settings = new ServiceFactorySettings(new Uri(relativityServicesUri), new Uri(relativityRestUri), usernamePasswordCredentials);
  ServiceFactory serviceFactory = new ServiceFactory(settings);

  using (IClassificationIndexService indexService = serviceFactory.CreateProxy<IClassificationIndexService>()) {
    int workspaceId = 1023289;
    int existingIndexArtifactID = 1054087;

    try {
      await indexService.CancelJobAsync(workspaceId, existingIndexArtifactID);
    } catch (PermissionException ex) {
      _logger.LogError(ex,
        "Cancelling job failed because of invalid permission. WorkspaceID {workspaceID} - IndexID {indexID} - username: {username}",
        workspaceId, existingIndexArtifactID, userName);
      throw;
    } catch (NotFoundException ex) {
      _logger.LogError(ex,
        "Cancelling Job failed because index could not be found. WorkspaceID {workspaceID} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    } catch (Exception ex) {
      _logger.LogError(ex,
        "Cancelling Job failed. WorkspaceID {workspaceId} - IndexID {indexId}",
        workspaceId, existingIndexArtifactID);
      throw;
    }
  }
}