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 service and Deprecated functionality.

Legacy Object Query Manager service

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 API.
  • Sampling – includes optional settings for generating a randomized sample. For more information, see Sampling on the Relativity 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.
{
    //Specify the workspace that you want to query.
    "workspaceId": 1020741,
     
    //Set the Artifact Type identifier of the DTO that you want to query on. 
    //This example retrieves documents, which have an ArtifactTypeID value of 10.
    "artifactTypeId": 10,
     
    //Define the criteria used to determine the data included in the result set. 
    "query": {
         
        //Define the set of data returned for each item in the result set.
        "Fields": ["Control Number", "Extracted Text"],
         
        //Define the search criteria that you want to use.
        "Condition": "('Artifact ID' < 1003564)",
         
        //Define how the data returned by the query is ordered.
        "Sorts": ["Control Number DESC"],
         
        //Include an artifact identifier (such as ID, GUID, or Name) of the relational field used when retrieving the result set.
        //Set this value to the empty string if you don't want to include a relational field.
        "RelationalField": "1003786",
         
        //Define the criteria used to execute an index search against the result set.
        "SearchProviderCondition": {
             
            //Set the ArtifactID of the search provider that you are using for this query.
            "SearchProviderArtifactId": 1005645,
             
            //Set the input string used by the search provider.
            //The format of the string must match that format required by the search provider.
            "Input": ""           
        },
         
        //Define the parameters used to execute sampling against the result set.
        "SampleParameters": {
         
            //If a valid token is provided, the sample results include those from a previously executed sample.
            "ExistingToken": "",
             
            //Define the margin of error for the sample.
            "MarginOfError": .9,
             
            //Define the confidence level for the sample.
            "ConfidenceLevel": .9,
             
            //Define the size of the sample by a fixed number.
            "FixedSampleSize": 250,
             
            //Define the size of the sample by a percentage.
            "SamplingPercentage": .75
        },
         
        //If you set the IncludeIdWindow field to true, the result set includes an array of ArtifactIDs beginning with the value that you specify as the start index.
        //It contains up to the number of items defined by the window size. The default is 5,000.
        "IncludeIdWindow": true,
         
        //If you set the TruncateTextFields field to true, the system truncates the fixed length and long text fields in the response to the number of characters specified by
        //the MaximumListPageTextLength instance setting. If false, it returns all the text. This could cause a slow down in the return of the query,
        //so only set this to false if necessary.
        "TruncateTextFields": true,

        //Define query hint if needed. It is used to optimize the view.
        "QueryHint": "waitfor:5"
    },
     
    //Set the index at which you want to start retrieving results. 
    //For example, if the total item count is 1,000 and the start index is 901 with a length of 100, the query returns items 901 through 1,000.
    "start": 1,
     
    //Set the number of items returned in the result set.
    "length": 100,
     
    //Define an array of permission type IDs. For each corresponding permission type ID in the array, item level permission information is added to the items in the result set. 
    "includePermissions": [2,3,4],
     
    //Token used for caching queries. Set this field to an empty string, since caching isn't currently supported.
    "queryToken": ""
}

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.
    • KeywordSearch
      "<?xml version=\"1.0\" encoding=\"utf-16\" ?>
<InputData xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">
<SortByRank xmlns=\"kCura.EDDS.SQLServer2005SearchProvider\">false</SortByRank>
<SearchText xmlns=\"kCura.EDDS.SQLServer2005SearchProvider\">Search Text goes here</SearchText></InputData>"
    • dtSearch
      "<?xml version=\"1.0\" encoding=\"utf-16\" ?>
<InputData xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">
<SortByRank xmlns=\"kCura.EDDS.DTSearchSearchProvider\">false</SortByRank>
<SearchText xmlns=\"kCura.EDDS.DTSearchSearchProvider\">Search Text goes here</SearchText>
<FuzzinessLevel xmlns=\"kCura.EDDS.DTSearchSearchProvider\" />
<EnableStemming xmlns=\"kCura.EDDS.DTSearchSearchProvider\">false</EnableStemming></InputData>"
    • AnalyticsSearch
      "<?xml version=\"1.0\" encoding=\"utf-16\" ?>
<InputData xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">
<SortByRank xmlns=\"kCura.EDDS.ContentAnalystSearchProvider\">false</SortByRank>
<KeywordsText xmlns=\"kCura.EDDS.ContentAnalystSearchProvider\">Keyword Text goes here</KeywordsText>
<ConceptsText xmlns=\"kCura.EDDS.ContentAnalystSearchProvider\">Concept Text goes here</ConceptsText>
<MinimumConceptRank xmlns=\"kCura.EDDS.ContentAnalystSearchProvider\">.8</MinimumConceptRank>
<FuzzinessLevel xmlns=\"kCura.EDDS.ContentAnalystSearchProvider\" />
<IsSimilarDocQuery xmlns=\"kCura.EDDS.ContentAnalystSearchProvider\">false</IsSimilarDocQuery>
<DocumentArtifactID xmlns=\"kCura.EDDS.ContentAnalystSearchProvider\">0</DocumentArtifactID></InputData>"
    • DataGridSearch
      "<?xml version=\"1.0\" encoding=\"utf-16\" ?>
<InputData xmlns:xsd=\"http://www.w3.org/2001/XMLSchema\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\">
<SortByRank>false</SortByRank>
<SearchText>Search Text goes here</SearchText></InputData>"
  • 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 on the Relativity 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 Instance settings' descriptions 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.
{
  "Success": true,
  "Data": {
    "WorkspaceId": 1020741,
    "ArtifactTypeId": 10,
    "ArtifactTypeGuids": [
      "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
    ],
    "ResultCount": 10,
    "TotalResultCount": 250,
    "CurrentStartIndex": 1,
    "PreviousPage": "",
    "NextPage": "",
    "Sample": {
      "SampleSize": 250,
      "UniverseSize": 20185,
      "Token": "d71398df-3049-4d96-8903-36e4e30f35d0"
    },
    "DataResults": [
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1038363,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0007918",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "Value": "Veronica Espinoza",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1038381,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0007936",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "Value": "Drew Ries",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1038397,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0007952",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "Value": "Susan Flynn",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1038462,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0008017",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "Value": "Louise Kitchen",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1038470,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0008025",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1038488,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0008043",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1038510,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0008065",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "Value": "Justin Boyd",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1039369,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0008264",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1040348,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0008423",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      },
      {
        "Permissions": [
          {
            "ID": 2,
            "Name": "Edit"
          },
          {
            "ID": 3,
            "Name": "Delete"
          },
          {
            "ID": 4,
            "Name": "Secure"
          }
        ],
        "ArtifactId": 1040400,
        "ArtifactGuids": [],
        "ArtifactTypeId": 10,
        "ArtifactTypeGuids": [
          "15c36703-74ea-4ff8-9dfb-ad30ece7530d"
        ],
        "ParentArtifactId": 0,
        "WorkspaceId": 1020741,
        "Fields": [
          {
            "Name": "Doc Id Beg",
            "Value": "MTAYLOR_0008475",
            "ArtifactId": 1003667,
            "ArtifactGuids": [
              "2a3f1212-c8ca-4fa9-ad6b-f76c97f05438"
            ],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Email From",
            "Value": "Bob Shults",
            "ArtifactId": 1035366,
            "ArtifactGuids": [
              "12d841e2-d026-4e57-901a-0678b4b44d64"
            ],
            "FieldType": "FixedLengthText"
          }
        ]
      }
    ],
    "Window": [
      1038363,
      1038381,
      1038397,
      1038462,
      1038470,
      1038488,
      1038510,
      1039369,
      1040348,
      1040400,
      1040541,
      1040578,
      1040647,
      1040691,
      1040695,
      1040700,
      1040709,
      1040726,
      1040731,
      1041033
    ]
  }
}

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.

"Fields": [
          {
            "Name": "Boolean Field",
            "Value": true,
            "ArtifactId": 1368357,
            "ArtifactGuids": [],
            "FieldType": "YesNo"
          },
          {
            "Name": "Currency Field",
            "Value": -24.5,
            "ArtifactId": 1368804,
            "ArtifactGuids": [],
            "FieldType": "Currency"
          },
          {
            "Name": "Whole Number",
            "Value": 456,
            "ArtifactId": 1368739,
            "ArtifactGuids": [],
            "FieldType": "WholeNumber"
          },
          {
            "Name": "Decimal",
            "Value": 1238.99,
            "ArtifactId": 1368801,
            "ArtifactGuids": [],
            "FieldType": "Decimal"
          },
          {
            "Name": "Date Field",
            "Value": "2015-09-17T00:00:00",
            "ArtifactId": 1368748,
            "ArtifactGuids": [],
            "FieldType": "Date"
          },
          {
            "Name": "Fixed Length Text Field",
            "Value": "Some fixed length text value",
            "ArtifactId": 1368742,
            "ArtifactGuids": [],
            "FieldType": "FixedLengthText"
          },
          {
            "Name": "Long Text Field",
            "Value": "Here is the content of a long text field.",
            "ArtifactId": 1368745,
            "ArtifactGuids": [],
            "FieldType": "LongText"
          },
          {
            "Name": "File Field",
            "Value": {
              "FileId": 1,
              "FileFieldArtifactId": 1369088,
              "FileName": "File-Field.png"
            },
            "ArtifactId": 1369088,
            "ArtifactGuids": [],
            "FieldType": "File"
          },
          {
            "Name": "Single Choice Field",
            "Value": {
              "ArtifactID": 1368799,
              "ArtifactGuids": [],
              "Name": "Type 2"
            },
            "ArtifactId": 1368795,
            "ArtifactGuids": [],
            "FieldType": "SingleChoice"
          },
          {
            "Name": "Single Object Field",
            "Value": {
              "ArtifactTypeID": 29,
              "ArtifactID": 1302457,
              "ArtifactGuids": [],
              "Name": "Single Object 5"
            },
            "ArtifactId": 1369127,
            "ArtifactGuids": [],
            "FieldType": "SingleObject"
          },
          {
            "Name": "User Field",
            "Value": {
              "ArtifactID": 1234567,
              "Name": "User, Test"
            },
            "ArtifactId": 1368792,
            "ArtifactGuids": [],
            "FieldType": "User"
          },
          {
            "Name": "Multi Choice Field",
            "Value": [
              {
                "ArtifactID": 1368754,
                "ArtifactGuids": [],
                "Name": "Choice One"
              },
              {
                "ArtifactID": 1368756,
                "ArtifactGuids": [],
                "Name": "Choice Two"
              },
              {
                "ArtifactID": 1368755,
                "ArtifactGuids": [],
                "Name": "Choice Three"
              }
            ],
            "ArtifactId": 1368751,
            "ArtifactGuids": [],
            "FieldType": "MultipleChoice"
          },
          {
            "Name": "Multi Object Field",
            "Value": [
              {
                "ArtifactID": 1038278,
                "ArtifactGuids": [],
                "Name": "Object 1"
              },
              {
                "ArtifactID": 1038279,
                "ArtifactGuids": [],
                "Name": "Object 2"
              }
            ],
            "ArtifactId": 1368360,
            "ArtifactGuids": [],
            "FieldType": "MultipleObject"
          },
          {
           "Name":"Multi Reflected Multi Choice Field",
           "Value":[
              [
                 {
                    "ArtifactID":1158468,
                    "ArtifactGuids":[],
                    "Name":"Choice 1"
                 },
                 {
                    "ArtifactID":1158469,
                    "ArtifactGuids":[],
                    "Name":"Choice 2"
                 },
                 {
                    "ArtifactID":1158470,
                    "ArtifactGuids":[],
                    "Name":"Choice 3"
                 }
              ],
              [
                 {
                    "ArtifactID":1158470,
                    "ArtifactGuids":[],
                    "Name":"Choice 3"
                 }
              ]
           ],
           "ArtifactId":1368360,
           "ArtifactGuids":[],
           "FieldType":"MultipleChoice"
        }
       ]

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.
public async Task<List<string>> QueryUniqueFieldValuesAsync()
{
    List<string> uniqueFieldValues = null;

    using (var httpClient = new System.Net.Http.HttpClient())
    {
        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 c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

        //Initialize parameters.
        var parameters = new
        {
            workspaceId = 1234567,
            artifactTypeId = 10,
            fieldName = "Document Extension"
        };

        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 uniqueFieldValuesQueryUrl = "Relativity.Services.ObjectQuery.IObjectQueryModule/Object%20Query%20Manager/QueryUniqueFieldValuesAsync";

        //Make the HTTP request against the endpoint for the Object Query Manager service.
        System.Net.Http.HttpResponseMessage response = await httpClient.PostAsync(uniqueFieldValuesQueryUrl, parametersJson);

        bool success = response.StatusCode == System.Net.HttpStatusCode.OK;
        string result = await response.Content.ReadAsStringAsync();

        if (success)
        {
            //Deserialize the response string into a ObjectQueryUniqueFieldValuesResult object.
            ObjectQueryUniqueFieldValuesResult uniqueValuesResult = Newtonsoft.Json.JsonConvert.DeserializeObject<ObjectQueryUniqueFieldValuesResult>(result);

            //Retrieve unique field values
            uniqueFieldValues = uniqueValuesResult.UniqueValues;
        }

        return uniqueFieldValues;
    }
}

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 Instance settings 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"
  ]
}