The Object Query Manager API is scheduled for deprecation in the Relativity Indigo release during January 2020. Don’t implement any new custom functionality with this API and begin upgrading any applications that currently reference it to use the query functionality available through the Object Manager API. For more information, see
Object Manager (.NET) and
Deprecated functionality.
Legacy Object Query Manager (.NET)
You can use the Object Query Manager service to search for Document objects and Relativity Dynamic Objects (RDOs) in workspaces. You can specify search criteria called conditions, fields for inclusion in search results, sort order, relational field criteria, and a specific search provider when implementing object queries. In addition, you can also use methods on this service to query for unique field values in fixed-length text fields.
The Object Query Manager service provides you with the ability to search for object data, which you can display in the Relativity UI or use for other purposes in your applications. For example, you can use this service to populate data that appears in the list views available in the Relativity UI. You can also use the QueryUniqueFieldValuesAsync() method in conjunction with the new UI framework. It can query for unique values stored in fixed-length text fields, which you could display as filter choices when the filter type is set to list.
You can use the Object Query Manager service through the REST API. However, the Object Query Manager service doesn't support cancellation tokens or progress indicators through REST. For more information, see Object queries.
This page contains the following information:
Object query fundamentals
In the Services API, the Relativity.Services.ObjectQuery namespace contains the IObjectQueryManager interface and other classes required to query for objects and unique field values. You use the IObjectQueryManager interface to access the Object Query Manager service, and the methods that it provides for retrieving Relativity objects or field values that meet your search criteria. The IObjectQueryManager interface contains these methods:
QueryAsync() method
The overloaded QueryAsync() method on the IObjectQueryManager interface is used to search for Document objects and RDOs. When calling this method, you must specify the following arguments:
- Workspace identifier - the Artifact ID for the workspace where you want to search for objects.
- Artifact Type ID - indicates the type of data transfer object (DTO) returned by your query. For example, an Artifact Type ID of 10 indicates that you want the results set to include Document objects. For more information, see Artifact type.
- Query - includes the conditions that you defined for your search. For more information, see Searching Relativity.
- Start index - indicates the index of the first artifact in QueryResultSet object returned from your search.
- Length - indicates the number of items that you want returned in the ObjectQueryResultSet object. The returned items begin at the index provided in the start index parameter of the method.
- Included permissions - define an array of permissions that you want returned for the object. See includePermissions.
- Query token - set this argument to an empty string. You must pass this argument in the method call.
If you use an overloaded method, you can also pass the following arguments:
- CancellationToken - used to request the cancellation of a query executed by the Object Query Manager service. The IObjectQueryManager interface includes overloaded methods that take an object of the type System.Threading.CancellationTokenSource provided by the .NET framework.
- IProgress<ProgressReport> object - used to define a provider for progress updates. The IObjectQueryManager interface includes overloaded methods that take an object of the type System.IProgress provided by the .NET framework.
Each of the overloaded methods supported by the Object Query Manager service returns a ObjectQueryResultSet object containing the objects that match your search conditions.
In addition, the Relativity.Services.ObjectQuery namespace also contains the following classes that you use when executing object queries:
- Query class - This class has multiple properties that you use to define a query, including the condition, returned fields, sort order, relational fields, search provider, and others. Additionally, this class includes the QueryHint property, which you can set to optimize the view. For example, you can use the hashjoin setting with the value of true or false, or you can use the waitfor setting with a value, such as waitfor:5.
- ObjectQueryResultSet class - The QueryAsync() method returns an object of this type when a query executes successfully. In addition, this class has a Data property that holds DataResult object, which in turn, has a property that holds QueryDataItemResult object. The result object also uses the DataItemFieldResult and DataItemResult classes for returning information from a query.
- SearchProviderCondition class - This class is a property on the Query class that you can use to execute a search for a specific search provider. For more information, see Retrieve search providers.
QueryUniqueFieldValuesAsync() method
The overloaded QueryUniqueFieldValuesAsync() method on the IObjectQueryManager interface is used to search for unique values stored in fixed-length text fields. You should use this method to query only on fixed-length text fields. In addition, we recommend that you create an index on the database fields that you want to query.
When calling this method, you must specify the following arguments:
- Workspace identifier - the Artifact ID of the workspace containing the field that you want to query on.
- Artifact Type ID - the identifier for the Artifact Type of the object associated with the field. For example, a field associated with the Document artifact has an artifactTypeId of 10. For more information, see the ArtifactType enumeration in the Relativity API reference.
- Field name - the name of the fixed-length text field that you want to query.
If you use an overloaded method, you can also pass the following arguments:
- CancellationToken - used to request the cancellation of a query executed by the Object Query Manager service.
- IProgress<ProgressReport> object - provides a report of the query execution progress.
Each of the overloaded QueryUniqueFieldValuesAsync() methods return an object of type ObjectQueryUniqueFieldValuesResult. This class has the following properties:
- FieldName - the name of the fixed-length text field that was queried.
- MaxNumberOfValuesReached - a bool indicating whether the number of values returned by the query reaches the maximum. The maximum number is specified in the DistinctBuilderMaxValue instance setting. This setting is located in the Relativity.Data section of the Instance Settings table. For more information, see Instance settings' descriptions on the Relativity Documentation site.
- UniqueValues - the list of unique values for the queried field.
Note: The properties for the ObjectQueryUniqueFieldValuesResult class include both getters and setters. We recommend using only the getter methods on these properties for your custom development projects.
Execute an object query
You can use the following code samples to learn about how to use the Object Query Manager service to retrieve Document objects, which are email messages in this case. It also illustrates how to set query conditions, how to cancel a query request, and how to provide progress information to the users.
To provide users with the ability to cancel a query, instantiate a new CancellationTokenSource object. You can call the Cancel() method on this object when a user clicks the Cancel button in the UI.
Copy
1
private System.Threading.CancellationTokenSource _cancellationTokenSource = new System.Threading.CancellationTokenSource();
Next, instantiate an ObjectQueryManager object using the ServiceFactory class:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
//Create an ObjectQueryManager instance using the ServiceFactory constructor.
private Relativity.Services.ObjectQuery.IObjectQueryManager GetObjectQueryManager()
{
String restServerAddress = "http://localhost/relativity.rest/api";
String rsapiServerAddress = "http://localhost/relativity.services/api";
Uri keplerUri = new Uri(restServerAddress);
Uri servicesUri = new Uri(rsapiServerAddress);
Relativity.Services.ServiceProxy.ServiceFactorySettings settings = new Relativity.Services.ServiceProxy.ServiceFactorySettings(
servicesUri, keplerUri, new Relativity.Services.ServiceProxy.UsernamePasswordCredentials("jsmith@example.com", "ExamplePassword1!"));
var serviceFactory = new Relativity.Services.ServiceProxy.ServiceFactory(settings);
Relativity.Services.ObjectQuery.IObjectQueryManager objectQueryManager = serviceFactory.CreateProxy<Relativity.Services.ObjectQuery.IObjectQueryManager>();
return objectQueryManager;
}
In addition, you can instantiate a ObjectQueryManager object using the Relativity API Helpers. Use this approach if you want use the Object Query Manager service from a custom page, event handler, or agent. For more information, see Use Relativity API Helpers.
Copy
1
Relativity.Services.ObjectQuery.IObjectQueryManager objectQueryManager = Relativity.CustomPages.ConnectionHelper.Helper().GetServicesManager().CreateProxy<Relativity.Services.ObjectQuery.IObjectQueryManager>(Relativity.API.ExecutionIdentity.System);
Implement a custom method that takes a ProgressReport object used to capture information about the execution of a service by referencing the Message, CompletedSteps, and TotalSteps properties. You can then define how you want this information displayed for users.
Copy
1
2
3
4
private void ObjectQueryManagerProgress(Relativity.Services.DataContracts.DTOs.ProgressReport progressReport)
{
//Optionally, define how to display the progress messages.
}
Implement a handler that calls the Cancel() method on the CancellationTokenSource object when the user clicks a Cancel button.
Copy
1
2
3
4
5
//Define a handler function that is called when the user clicks a Cancel button.
public void CancelButton_Clicked()
{
_cancellationTokenSource.Cancel();
}
To run an object query, implement a method that returns a collection of objects and performs the following tasks:
- Set the conditions for the query. For more information, see Object queries and Searching Relativity.
- To include permissions that a user has to objects in the result set, define an array of permissions that you want returned. For example, you could return edit, delete, and add permissions by defining an array like [2,3,6].
- Call the QueryAsync() method on the IObjectQueryManager interface.
- Run the query in a try-catch block.
- Return a collection of objects or an error message.
View sample method for returning result objects
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
//Instantiate a ObjectQueryManager object and retrieve result objects by passing workspaceId and artifactTypeId arguments
//to the QueryAsync() method.
public IEnumerable<Relativity.Services.ObjectQuery.QueryDataItemResult> QueryAsync(int workspaceId, int artifactTypeId)
{
Relativity.Services.ObjectQuery.IObjectQueryManager objectQueryManager = GetObjectQueryManager();
//Define a progress reporter that provides information about the status of the query.
System.Progress<Relativity.Services.DataContracts.DTOs.ProgressReport> progressReporter = new Progress<Relativity.Services.DataContracts.DTOs.ProgressReport>(ObjectQueryManagerProgress);
//Define values for the query call.
//The following constant defines the 1-based index of first document in the query results that is retrieved.
const int indexOfFirstDocumentInResult = 1;
//The following constant defines the maximum number of results that you want returned in this query call.
const int lengthOfResults = 100;
int[] includePermissions = new int[]
{
1, //view
2, //edit
3, //delete
4, //secure
6 //add
};
Relativity.Services.ObjectQuery.Query query = new Relativity.Services.ObjectQuery.Query()
{
//Use the search condition syntax to build the query.
Condition = "('Email From' IN ['Test0@Test.com','Test1@Test.com'])",
//Define an array of fields to return. The query always returns the ArtifactId.
Fields = new string[] { "Doc ID Beg", "System Created On", "Email From" },
IncludeIdWindow = false,
//Set the name of a relational field if you want the query results to include related objects.
RelationalField = null,
SampleParameters = null,
SearchProviderCondition = null,
//Define an array of Fields.
Sorts = new string[] { "Email From ASC" },
TruncateTextFields = true,
//Define query hint if needed. It is used to optimize the view.
QueryHint = "waitfor:5"
};
//This object isn't used. Set it to an empty string.
string queryToken = string.Empty;
//Make the service call using the instantiated Object Query Manager object.
System.Threading.Tasks.Task<Relativity.Services.ObjectQuery.ObjectQueryResultSet> executeTask = objectQueryManager.QueryAsync(workspaceId, artifactTypeId, query, indexOfFirstDocumentInResult, lengthOfResults, includePermissions, queryToken);
string errorMessage = string.Empty;
List<Relativity.Services.ObjectQuery.QueryDataItemResult> resultObjects = null;
//Run the query and return the results as a ObjectQueryResultSet object. Use a try-catch block to capture and optionally display
//an error message if the query fails.
try
{
executeTask.Wait();
Relativity.Services.ObjectQuery.ObjectQueryResultSet results = executeTask.Result;
if (results.Success)
{
//Optionally, define add code to handle the results.
resultObjects = results.Data.DataResults.ToList();
}
else
{
errorMessage = results.Message;
}
}
catch (Exception exception)
{
errorMessage = exception.ToString();
}
if (!string.IsNullOrWhiteSpace(errorMessage))
{
//Optionally, define how to display the error message.
}
return resultObjects;
}
Query for unique fields values
You can use the QueryUniqueFieldValuesAsync() method to search for unique values stored in fixed-length text fields.
The following code sample illustrates how to perform these tasks:
- Use helper classes to create the proxy and select an appropriate authentication type. See Relativity API Helpers.
- Create the Services API proxy within a using block in your code.
- Call the QueryUniqueFieldValuesAsync() method.
- Use await/async design pattern. See Basic Services API concepts.
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
public async Task<List<string>> QueryUniqueFieldValuesAsync(Client.SamplesLibrary.Helper.IHelper helper, int workspaceArtifactId, int artifactTypeId, string fieldName)
{
List<string> uniqueValues = null;
using (IObjectQueryManager proxy = helper.GetServicesManager().CreateProxy<IObjectQueryManager>(ExecutionIdentity.User))
{
ObjectQueryUniqueFieldValuesResult queryResult = null;
queryResult = await proxy.QueryUniqueFieldValuesAsync(workspaceArtifactId, artifactTypeId, fieldName);
//The result count is limited by DistinctBuilderMaxValue instance setting in the Relativity.Data section of the Instance Settings table.
//You can check the result count if necessary.
if (queryResult.MaxNumberOfValuesReached)
{
//Complete some processings
}
//This variable holds the result from UniqueValues property.
uniqueValues = queryResult.UniqueValues;
}
return uniqueValues;
}