Analytics Classification Index (REST)
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 on the Relativity Documentation site.
The Analytics Classification Index service supports programmatically managing classification indexes in Relativity Analytics. It includes the following features:
- Supports CRUD operations on classification indexes.
- Provides helper endpoints that simplify working with index jobs. You can use these endpoints 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 service in an application to programmatically operate on a classification index.
You can also use the Classification Index service through .NET. For more information, see Analytics Classification Index (.NET).
Guidelines for using the Classification Index service
Review the following guidelines for working with the Classification Index service. For additional information, see Analytics Classification Index (.NET).
URLs
The URLs for REST endpoints contain path parameters that you need to set before making a call:
- Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1 or v2
- Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.
Note: To indicate the admin-level context, set the {workspaceID} path parameter to -1.
For example, you can use the following URL to retrieve a classification index:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes/{indexID}
Set the path parameters as follows:
- {versionNumber} to the version of the service, such as v1.
- {workspaceID} to the Artifact ID of the workspace that contains the index.
- {indexID} to the Artifact ID of a specific index.
Postman sample file
You can use the Postman sample file to become familiar with making calls to endpoints on the Classification Index service. To download the sample file, click Classification Index Postman file.
To get started with Postman, complete these steps:
- Obtain access to a Relativity environment. You need a username and password to make calls to your environment.
- Install Postman.
- Import the Postman sample file for the service. For more information, see Working with data files on the Postman web site.
- Select an endpoint. Update the URL with the domain for your Relativity environment and any other variables.
- In the Authorization tab, set the Type to Basic Auth, enter your Relativity credentials, and click Update Request.
- See the following sections on this page for more information on setting required fields for a request.
- Click Send to make a request.
Create a classification index
To create an index, send a POST request to a URL with the following format:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes
View field descriptions for a request
The request payload must include a valid JSON representation of the index object.
The following properties are required:
- AnalyticsServer - the Analytics server used to build 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.
The following property is optional:
- EmailNotificationRecipients - the list of email recipients notified during index population and build.
Note: For the SearchableSet field, the Artifact ID for the ArtifactRef object can be set to 0 to use the built-in search for all documents in a workspace, or -1 for the default search. Setting this value to 0 or -1 can negatively impact system performance.
View a sample JSON request
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"index":{
"AnalyticsServer":{
"ArtifactID":1018616
},
"EmailNotificationRecipients":[
],
"Name":"Jane Doe Case Analytics Index",
"Order":1,
"SearchableSet":{
"ArtifactID":1038051
},
"Active":true
}
}
When the index is successfully created, the response returns the status code of 201 and the Artifact ID of the index object.
View possible exceptions
The following exceptions may occur:
- ValidationException – An exception representing the case where an invalid or malformed request is made. For example, this exception occurs when an invalid value is specified for an index property.
- PermissionException – An exception representing the case where the user doesn't have permission to perform an attempted action. For example, this exception occurs when a user doesn't have access to a workspace, a searchable or training set, or to perform index operations.
Retrieve a classification index
To read an index, send a GET request to a URL with the following format:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes/{indexID}
The body of the request is empty.
View field descriptions for a response
The response returns an index object with the following properties:
- ArtifactID - the Artifact ID of the index.
- Guids - the GUIDs for this index.
- AnalyticsServer - the Analytics server used to build the index.
- EmailNotificationRecipients - the list of email recipients notified during index population and build.
- 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.
- Active - indicates whether the search provider associated with the index has been activated.
- LastErrorMessage - the last error message to occur on the index.
- IndexLastUsedOn - the time when this index was last used.
View a sample JSON response
This JSON sample represents an index object:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
"ArtifactID": 1118331,
"Guids": [],
"AnalyticsServer": {
"ArtifactID": 1018616
},
"EmailNotificationRecipients": [],
"Name": "John Doe Case Analytics Index",
"Order": 1,
"SearchableSet": {
"ArtifactID": 1038051
},
"Active":true,
"LastErrorMessage": "",
"IndexLastUsedOn": "2017-05-09T19:22:17"
}
View possible exceptions
The following exceptions may occur:
- NotFoundException – An exception representing the case where an item isn't available or doesn't exist. For example, this exception occurs when reading or deleting an index that doesn't exist.
- PermissionException – An exception representing the case where the user doesn't have permission to perform an attempted action. For example, this exception occurs when a user doesn't have access to a workspace, a searchable or training set, or to perform index operations.
Update a classification index
To update an index, send a PUT request to a URL with the following format:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes/{indexID}
The request for an update operation contains the same fields as those for a create request. See the field descriptions for the request in Create a classification index.
View a sample JSON request
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"index": {
"AnalyticsServer": {
"ArtifactID": 1018616
},
"EmailNotificationRecipients": [],
"Name": "Jane Doe Case Analytics Index",
"Order": 2,
"SearchableSet": {
"ArtifactID": 1038051
},
"Active": false
}
}
When the index is successfully updated, the response returns the status code of 201.
View possible exceptions
The following exceptions may occur:
- ValidationException – An exception representing the case where an invalid or malformed request is made. For example, this exception occurs when an invalid value is specified for an index property.
- PermissionException – An exception representing the case where the user doesn't have permission to perform an attempted action. For example, this exception occurs when a user doesn't have access to a workspace, a searchable or training set, or to perform index operations.
Delete a classification index
To delete an index, send a DELETE request to a URL with the following format:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes/{indexID}
The body of the request is empty.
When the index is successfully deleted, the response returns the status code of 200.
View possible exceptions
The following exceptions may occur:
- DeletionDependencyException - An exception representing the case where an object deletion fails because it's referenced by dependencies. For example, this exception occurs when attempting to delete an index that's being used.
- NotFoundException – An exception representing the case where an item isn't available or doesn't exist. For example, this exception occurs when reading or deleting an index that doesn't exist.
- PermissionException – An exception representing the case where the user doesn't have permission to perform an attempted action. For example, this exception occurs when a user doesn't have access to a workspace, a searchable or training set, or to perform index operations.
Helper endpoints for classification index jobs
Use the following endpoints for managing jobs related to classification indexes.
Submit a classification index job
To submit an index job, send a POST request to a URL with the following format:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes/{indexID}/job
View descriptions of fields in a request
The request payload must include a valid JSON representations of the index job type. Valid values include:
- FullPopulation – runs a full index population.
- IncrementalPopulation - runs an incremental population.
- RetryErrors - retries errors that occurred during population.
- RemoveDocumentsInError - removes documents in error.
- BuildIndex - runs a full index build.
- Activate - activates the index for querying.
- Deactivate - disables queries on the index.
- Tag Documents - tags documents that are a part of the search set.
When the job is successfully submitted, the response returns the status code of 200.
View possible exceptions
The following exceptions may occur:
- NotFoundException – An exception representing the case where an item isn't available or doesn't exist. For example, this exception occurs when reading or deleting an index that doesn't exist.
- PermissionException – An exception representing the case where the user doesn't have permission to perform an attempted action. For example, this exception occurs when a user doesn't have access to a workspace, a searchable or training set, or to perform index operations.
- ValidationException – An exception representing the case where an invalid or malformed request is made. For example, this exception occurs when an invalid value is specified for an index property.
Retrieve the status of a job
To get an index status, send a GET request to a URL with the following format:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes/{indexID}/status
The body of the request is empty.
View the field descriptions for a response
The response returns an index status object with the following properties:
- 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 Fundamentals for the Classification Index API.
- 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 this 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.
- 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.
View a sample JSON response
This JSON sample represents an index status object:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
{
"Active": true,
"ConsoleButtons": [
{
"DisplayText": "Populate Index: Full",
"Identifier": "populateIndexFull",
"Class": "consoleButtonEnabled",
"HelpText": "",
"Enabled": true
},
{
"DisplayText": "Cancel Full Population",
"Identifier": "cancelPopulateIndexFull",
"Class": "consoleButtonHide",
"HelpText": "Cannot cancel full population if index is not populating.",
"Enabled": false
},
{
"DisplayText": "Populate Index: Incremental",
"Identifier": "populateIndexIncremental",
"Class": "consoleButtonEnabled",
"HelpText": "",
"Enabled": true
},
{
"DisplayText": "Cancel Incremental Population",
"Identifier": "cancelPopulateIndexIncremental",
"Class": "consoleButtonHide",
"HelpText": "Cannot cancel incremental population if index is not populating.",
"Enabled": false
},
{
"DisplayText": "Retry Errors",
"Identifier": "retryErrors",
"Class": "consoleButtonDisabled",
"HelpText": "There are no errors to retry.",
"Enabled": false
},
{
"DisplayText": "Cancel Retry Errors",
"Identifier": "cancelRetryErrors",
"Class": "consoleButtonHide",
"HelpText": "Cannot cancel retry errors if index is not populating.",
"Enabled": false
},
{
"DisplayText": "Remove Documents in Error",
"Identifier": "removeDocumentsInError",
"Class": "consoleButtonDisabled",
"HelpText": "There are no errored documents to remove.",
"Enabled": false
},
{
"DisplayText": "Build Index",
"Identifier": "buildIndex",
"Class": "consoleButtonDisabled",
"HelpText": "Index cannot be built while the index is active.",
"Enabled": false
},
{
"DisplayText": "Activate",
"Identifier": "activate",
"Class": "consoleButtonHide",
"HelpText": "Index cannot be activated unless it is not active.",
"Enabled": false
},
{
"DisplayText": "Deactivate",
"Identifier": "deactivate",
"Class": "consoleButtonEnabled",
"HelpText": "",
"Enabled": true
},
{
"DisplayText": "Show Document Errors",
"Identifier": "showDocumentErrors",
"Class": "consoleLinkDisabled",
"HelpText": "There are no errors to show.",
"Enabled": false
},
{
"DisplayText": "Show Population Statistics",
"Identifier": "showPopulationStatistics",
"Class": "consoleLinkEnabled",
"HelpText": "",
"Enabled": true
},
{
"DisplayText": "Show Index Statistics",
"Identifier": "showIndexStatistics",
"Class": "consoleLinkEnabled",
"HelpText": "",
"Enabled": true
}
],
"DocLevelErrorsExist": false,
"SearchableSetCount": 73966,
"StatusText": "Active",
"TrainingSetCount": 63403
}
View possible exceptions
The following exceptions may occur:
- NotFoundException – An exception representing the case where an item isn't available or doesn't exist. For example, this exception occurs when reading or deleting an index that doesn't exist.
- PermissionException – An exception representing the case where the user doesn't have permission to perform an attempted action. For example, this exception occurs when a user doesn't have access to a workspace, a searchable or training set, or to perform index operations.
Cancel a job
To cancel a running index job, send a DELETE request to a URL with the following format:
Copy
1
<host>/Relativity.REST/API/classification-analytics/{versionNumber}/workspaces/{workspaceID}/indexes/{indexID}/job
The body of the request is empty.
When the job is successfully canceled, the response returns the status code of 200.
View possible exceptions
The following exceptions may occur:
- DeletionDependencyException - An exception representing the case where an object deletion fails because it's referenced by dependencies. For example, this exception occurs when attempting to delete an index that's being used.
- NotFoundException – An exception representing the case where an item isn't available or doesn't exist. For example, this exception occurs when reading or deleting an index that doesn't exist.
- PermissionException – An exception representing the case where the user doesn't have permission to perform an attempted action. For example, this exception occurs when a user doesn't have access to a workspace, a searchable or training set, or to perform index operations.
