

Last date modified: April 15 2025
A conceptual index is a type of index used by Relativity Analytics. It uses Latent Semantic Indexing (LSI) to discover concepts between documents. This indexing process is based solely on term co-occurrence. The language, concepts, and relationships are defined entirely by the contents of your documents and learned by the index. For general information about Analytics indexes, see Analytics indexes and on the Relativity
The Analytics Conceptual Index API supports programmatically managing conceptual indexes in Relativity Analytics. It includes the following features:
As a sample use case, you might use this API in an application to programmatically operate on a conceptual index.
You can also use the Conceptual Index API through REST. For more information, see Analytics Conceptual Index (REST).
Review the following information to learn about the methods, classes, and enumerations used by the Conceptual Index API.
The Conceptual Index API includes the following methods available on the IConceptualIndexService interface in the Relativity.Analytics.Conceptual.<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.
The Conceptual Index API uses the following classes and enumerations:
Review the following guidelines for working with the Conceptual Index API.
For Analytics indexes, common workflows include building new ones or incrementally updating existing ones.
Use the following steps to build a new index:
When using any methods in the Conceptual Index API, catch the following exceptions:
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:
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.
When performing operations on an index, make sure the operation is applicable to its current state.
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:
After submitting an index job, monitor its progress by making calls to its status. See Retrieve the status of a job.
Use the CreateAsync() method to add a new index to Relativity. Set the following properties on the ConceptualIndex object passed to the CreateAsync() method:
When the operation succeeds, it returns the Artifact ID of the new index. Use the Artifact ID to submit the index for populating and building.
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
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 (IConceptualIndexService indexService = serviceFactory.CreateProxy<IConceptualIndexService>())
{
int workspaceId = 1023289;
int searchableSetSearchArtifactID = 1038051;
int trainingSetSearchArtifactID = 1038051;
int analyticsServerArtifactID = 1016891;
ConceptualIndex indexToCreate = new ConceptualIndex
{
Name = "my new analytics index",
Order = 1,
SearchableSet = new ArtifactRef { ArtifactID = searchableSetSearchArtifactID },
TrainingSet = new ArtifactRef { ArtifactID = trainingSetSearchArtifactID },
AnalyticsServer = new ArtifactRef { ArtifactID = analyticsServerArtifactID },
OptimizeTrainingSet = true,
RemoveDocumentsThatErroredDuringPopulation = true,
ContinueIndexStepsToCompletion = true,
ConceptStopWords = "a\r\nable\r\nabout\r\nabove\r\naccording\r\n",
Dimensions = 100,
RemoveEnglishSignaturesAndFooters = true,
EnableEmailHeaderFilter = true
};
try
{
int conceptualIndexID = await indexService.CreateAsync(workspaceId, indexToCreate);
Debug.WriteLine("ID of the newly created index is: " + conceptualIndexID);
}
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;
}
}
}
Use the ReadAsync() method to retrieve an index. Pass the Artifact IDs of the workspace and the index to this method. It returns a ConceptualIndex object. You can use this object to examine the index properties before submitting an index job, or updating or deleting the index.
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
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 (IConceptualIndexService indexService = serviceFactory.CreateProxy<IConceptualIndexService>())
{
int workspaceId = 1023289;
int existingIndexArtifactID = 1049079;
try
{
ConceptualIndex conceptualIndex = 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;
}
}
}
Use the UpdateAsync() method to modify an index. You can update multiple properties on a ConceptualIndex object. For a list of properties, see the ConceptualIndex class in Classes and enumerations.
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
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 (IConceptualIndexService indexService = serviceFactory.CreateProxy<IConceptualIndexService>())
{
int workspaceId = 1023289;
int existingIndexArtifactID = 1049079;
ConceptualIndex conceptualIndex= null;
try
{
try
{
conceptualIndex = 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;
}
conceptualIndex.Name = "My Updated Analytics Index";
await indexService.UpdateAsync(workspaceId, existingIndexArtifactID, conceptualIndex);
conceptualIndex = await indexService.ReadAsync(workspaceId, existingIndexArtifactID);
Debug.WriteLine("The updated name of the retrieved index is " + conceptualIndex.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, conceptualIndex);
throw;
}
catch (Exception ex)
{
_logger.LogError(ex,
"Failed to update the index. WorkspaceID {workspaceId} - IndexID {indexId}",
workspaceId, existingIndexArtifactID);
throw;
}
}
}
Use the DeleteAsync() method to remove an index from Relativity. Pass the Artifact IDs of the workspace and the index to this method.
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
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 (IConceptualIndexService indexService = serviceFactory.CreateProxy<IConceptualIndexService>())
{
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;
}
}
}
Use the following helper methods for managing jobs related to conceptual indexes.
Use the SubmitJobAsync() method to submit a job after creating the index. 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.
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
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 (IConceptualIndexService indexService = serviceFactory.CreateProxy<IConceptualIndexService>())
{
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;
}
}
}
Use the GetStatusAsync() method to retrieve the status of an indexing job. Pass the Artifact IDs of the workspace and the index to this method. It returns an AnalyticsIndexStatus object.
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
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 (IConceptualIndexService indexService = serviceFactory.CreateProxy<IConceptualIndexService>())
{
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;
}
}
}
Use the CancelJobAsync() method to cancel an indexing job. Pass the Artifact IDs of the workspace and the index to this method.
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
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 (IConceptualIndexService indexService = serviceFactory.CreateProxy<IConceptualIndexService>())
{
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;
}
}
}
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |