The Object Query Manager service is scheduled for deprecation in the Relativity Indigo release during January 2020. Don’t implement any new custom functionality with this service and begin upgrading any applications that currently reference it to use the query functionality available through the Object Manager service. For more information, see Object Manager (REST) and Deprecated functionality.

Legacy Object Query Manager (REST)

The Object Query Manager service available in the REST API supports searching 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 use an endpoint 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 endpoint 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 Relativity Services API to retrieve Document objects and RDOs in workspaces. Through the Services API, this service supports the use of progress indicators or cancellation tokens. For more information, see Query for Relativity objects.

This page contains the following information:

Client code sample

To interact with the Object Query Manager service, you send HTTP(S) requests that use the POST method and specify query conditions in the body of the request. See the base URL for this service:

<host>/Relativity.Rest/api/Relativity.Services.ObjectQuery.IObjectQueryModule/Object%20Query%20Manager/

You can use the following .NET code as the REST client for executing object queries. The code illustrates how to perform the following tasks:

  • Instantiate an HttpClient object for sending requests and responses by the URL for the Object Query Manager service.
  • Initialize the parameters used in the query. The QueryAsync() method supports paging through the start and length parameters that you set to determine the size of the data added to the result set. For more information about general query options, see Query for resources.

    Note: You use the Artifact ID Type to specify the Document objects or RDOs for the query.

  • Define the endpoint used by the service and send a request to it.
  • Deserialize the response object if the request is successful, or return an error message if it fails.
  • Return the deserialized results.
public Relativity.Services.ObjectQuery.DataResult QueryAsync()
{
    using (var httpClient = new System.Net.Http.HttpClient())
    {
        Relativity.Services.ObjectQuery.DataResult results = null;
 
        httpClient.BaseAddress = new Uri("http://localhost/Relativity.REST/API/");
        httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
        httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
        httpClient.DefaultRequestHeaders.Add("Authorization", "Basic bXkudXNlckBrY3VyYS5jb206Q250VGNoVGhzMTIzNCE=");
 
        //Initialize the parameters used in the query.
        var query = new Relativity.Services.ObjectQuery.Query() 
        {
                Fields = new string[] { "Edit", "File Icon", "Control Number" },
                Condition = "('Email From' IN ['test1@test.com','test2@test.com'])",
                Sorts = new string[] {"Email From ASC"},
                RelationalField = null,
                SearchProviderCondition = null,
                IncludeIdWindow = true,
                SampleParameters = null,
                TruncateTextFields = true,
                QueryHint = "waitfor:5"
        };
 
        var parameters = new
        {
            workspaceId = 1234567,
            artifactTypeId = 10,
            query = query,
            start = 1,
            length = 100,
            includePermissions = new int[] {4},
            queryToken = string.Empty
        };
 
        System.Net.Http.StringContent parametersJson = new System.Net.Http.StringContent(Newtonsoft.Json.JsonConvert.SerializeObject(parameters), System.Text.Encoding.UTF8, "application/json");
 
        //Define the REST endpoint used by the service.
        String objectQueryUrl = "Relativity.Services.ObjectQuery.IObjectQueryModule/Object%20Query%20Manager/QueryAsync";
 
        //Make the HTTP request against the endpoint for the Object Query Manager service.
        System.Net.Http.HttpResponseMessage response = httpClient.PostAsync(objectQueryUrl, parametersJson).Result;
 
        bool success = response.StatusCode == System.Net.HttpStatusCode.OK;
        String result = response.Content.ReadAsStringAsync().Result;
 
        if (success)
        {
            //Deserialize the response string into a ObjectQueryResultSet object.
            Relativity.Services.ObjectQuery.ObjectQueryResultSet resultSet = Newtonsoft.Json.JsonConvert.DeserializeObject<Relativity.Services.ObjectQuery.ObjectQueryResultSet>(result);
 
            //Retrieve the object query results.
            results = resultSet.Data;
        }
 
        return results;
    }
}

Execute an object query

To execute an object query, send a request to this URL for the Object Query Manager service:

<host>/Relativity.Rest/api/Relativity.Services.ObjectQuery.IObjectQueryModule/Object%20Query%20Manager/QueryAsync

For more information about general query options, see Query for resources.

Request

The request for the object contains multiple fields that define your query and the result set that is returned. You can optionally set the RelationalField, SearchProviderCondition, SampleParameters, TruncateTextFields and IncludeIdWindow fields. You must set all other fields in the request. The fields in the request can be divided into these general categories:

  • Identifiers – includes the Artifact ID of workspace, and the Artifact Type of objects you want to query.
  • Search criteria – includes the search conditions, sort order, search provider, and other settings. On the Query object in the JSON request, you can set a QueryHint field 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. For more information about general query options, see Query for resources and Legacy Object Query Manager (.NET).
  • Sampling – includes optional settings for generating a randomized sample. For more information, see Sampling on the RelativityOne Documentation site.
  • Result set – includes the indexes for the range items that you want returned, the number of items in a result set, and permission type information.

The following list contains information about fields that have specialized functions or usage requirements:

  • Input field for SearchProviderCondition – This field must contain a string that matches the format used by the search provider that you want to use.
  • ExistingToken for Sampling – To execute sampling against your results, specify the token for an existing sample set in this field. You pass this token to the request to rerun the query against the sample set. If you want to use sampling but don't have an existing sample set token, enter values for the other fields under SampleParameters.
  • SampleParameters – To use sampling when you don't have an existing token, set either FixedSampleSize, SamplingPercentage, or both MarginOfError and ConfidenceLevel. For more information, see Sampling on the RelativityOne Documentation site.
  • IncludeIdWindow – To preview a set of objects in the next result set, add the IncludeIdWindow field to the request and set it to true. This setting causes a Window object to return an array of Artifact IDs, which are included in the next set of results. The FluidReviewQueueSize instance setting controls the number of IDs returned in the Window object for the Object Query Manager service. For more information, see on the Relativity Documentation site.
  • includePermissions – To include a user's permissions 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]. The JSON response includes an array of permissions that the user has to an object returned by the query. If a user doesn't have a specific permission, then it isn't included in the array.
  • TruncateTextFields – Set this field to true if you want long text fields truncated. If you set this field to false, you may notice some performance degradation because the query retrieves full text for all long text fields. The response contains a large payload, which may slow down the response.
  • start and length – Set these fields to provide paging for your result set. The start field indicates the index of the first artifact returned in the result set, and the length field indicates the number of items that you want returned in it.
  • queryToken – Set this field to an empty string. You must provide this field in your request.

Response

The response for an object query contains fields for the following information:

  • Identifiers – includes the Artifact ID of workspace where the query ran, the Artifact Type of objects queried, and base artifact information for returned objects, such as its Artifact ID, GUID, and Parent Artifact ID.
  • Results statistics – includes the number of objects retrieved, paging counts, and other information. The ResultCount indicates the number of objects returned in the data result array based on the page size, and the TotalResultCount indicates the entire number of objects found by this query.
  • Data – includes the permissions that you have on the object and other metadata. See includePermissions.

The following response code illustrates the JSON returned in an object query for different field types available in Relativity. It includes examples of simple fields such as Boolean, fixed length, and others. It also includes complex field types such as single choice, single object, multiple choice, multiple object, and user.

Additionally, this response code illustrates the JSON format used to represent a multiobject reflected multichoice field. The Relativity UI uses this basic display field for objects that have multichoice fields. For example, you have a document object associated with a custodian object that has a multichoice field on it. You want to implement a list that displays each document and all the available values for the choice field on its associated custodian object. Return a multiobject reflected multichoice field in the response to display this data.

Query for unique field values

You can run a query that searches for unique values stored in fixed-length text fields. The QueryUniqueFieldValuesAsync endpoint doesn't return any duplicate values.

Client code sample

You can use the following code as the REST client when querying for unique field values. This code illustrates how to perform the following tasks:

  • Instantiate an HttpClient object for sending requests and responses using the URL for the Object Query Manager service .
  • Set the required headers for the request.
  • Set the string represented by parameters variable to the JSON input required to retrieve the unique field values.

    Note: Use the QueryUniqueFieldValuesAsync endpoint 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.

  • Set the uniqueFieldValuesQueryUrl variable to the URL for querying unique field values.
  • Use the PostAsync() method to send a post request.
  • Return the results of the request and deserialize it.

Query for unique field values with the REST API

To query for unique values on fixed-length text fields, send a request to this URL for the Object Query Manager service:

<host>/Relativity.Rest/api/Relativity.Services.ObjectQuery.IObjectQueryModule/Object%20Query%20Manager/QueryUniqueFieldValuesAsync

The request must include the following fields:

  • workspaceId - the Artifact ID of the workspace containing the field that you want to query on.
  • artifactTypeId - the identifier for the Artifact Type of the object associated with the field. In the following example, the field is associated with the Document artifact, which has an artifactTypeId of 10. For more information, see the ArtifactType enumeration in the Relativity API reference.
  • fieldName - the name of the fixed-length text field that you want to query.

    Note: Use the QueryUniqueFieldValuesAsync endpoint 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.

{
    "workspaceId": 1234567,
    "artifactTypeId": 10,
    "fieldName": "Document Extension",
}

The response includes the following fields:

  • 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 on the Relativity Documentation site.
  • UniqueValues - the list of unique values for the queried field.
{
  "FieldName": "Document Extension",
  "MaxNumberOfValuesReached": false,
  "UniqueValues": [
    "",
    "dat",
    "doc",
    "htm",
    "jpg",
    "msg",
    "pdf",
    "ppt",
    "reg",
    "rtf",
    "URL",
    "vcf",
    "xls"
  ]
}

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.