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:

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.

private System.Threading.CancellationTokenSource _cancellationTokenSource = new System.Threading.CancellationTokenSource();

Next, instantiate an ObjectQueryManager object using the ServiceFactory class:

//Create an ObjectQueryManager instance using the ServiceFactory constructor.

private Relativity.Services.ObjectQuery.IObjectQueryManager GetObjectQueryManager()
    String restServerAddress = "http://localhost/";
    String rsapiServerAddress = "http://localhost/";

    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("", "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.

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.

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.

//Define a handler function that is called when the user clicks a Cancel button.
public void CancelButton_Clicked()

To run an object query, implement a method that returns a collection of objects and performs the following tasks:

  • Get the ObjectQueryManager object that you instantiated using the ServiceFactory class.
  • Instantiate a Progress object by passing the constructor an ObjectQueryManagerProgress object callback function. Each time that the Object Query Manager service publishes a progress message, it calls this function.

    Note: If you want to use this progress functionality, you need to implement this callback function.

  • 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.

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.
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;

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.