Keyword Search Manager service for saved searches

A keyword search (or SQL index search) is the default search engine in Relativity. You can use a keyword search to query a full text index and to interact with save searches. For more information, see Keyword search on the Relativity Documentation site.

The Keyword Search Manager API supports the create, read, update, delete, and query operations on a KeywordSearch DTO. It also includes helper methods to facilitate returning saved search parameters available to the user in the workspace, such as fields, search owners, search indexes are also provided. You can also generate email links to the search results.

Note: You can only use the POST method when interacting with the service.

You can programmatically execute keyword searches created with the Keyword Search Manager Service using the SavedSearchCondition class of the Relativity Services API or saved search query in the REST API.

You can also use the Keyword Search Manager service through .NET. For more information, see Keyword Search Manager API for saved searches.

This page contains the following information:

Client code sample

The following is an example of .NET REST client for creating a keyword saved search. The code can be used for all Keyword Search Manager Service operations with different endpoint URLs and input JSON values.

//Set up the client.
            
HttpClient httpClient = new HttpClient();
httpClient.BaseAddress = new Uri("http://localhost/");

//Set the required headers.
            
httpClient.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
httpClient.DefaultRequestHeaders.Add("Authorization", "Basic c2FtcGxlYWRtaW5AcmVsYXRpdml0eS5yZXN0OlMwbTNwQHNzdzByZA==");

//Call Create for a SavedSearch.
            
string url = "Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/Create";
StringContent content = new StringContent(CreateInputJSON, Encoding.UTF8, "application/json");
HttpResponseMessage response = httpClient.PostAsync(url, content).Result;
string result = response.Content.ReadAsStringAsync().Result;
bool success = HttpStatusCode.Created == response.StatusCode;

//Parse the result with Json.NET.
            
JObject resultObject = JObject.Parse(result);        

Create

Use this Keyword Search Manager Service URL to create a keyword search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/CreateSingleAsync

The request must include a workspace ID and valid JSON representation of a KeywordSearch DTO. For more information, see Saved search object properties in JSON representations.

Note: Required KeywordSearch DTO properties include ArtifactTypeID, Name, and Fields.

The response is an Artifact ID of the created search.

The following are JSON examples for creating keyword saved searches.

Search condition criteria

The CriteriaCondition object represents a condition for a single non-date Relativity field. The following table describes the allowed CriteriaCondition values for each type of field.

Field Type

CriteriaCondtionEnum

Value Type

Notes

Text

AnyOfThese

List<int> or int[]

 

Text

IsSet

null

 

Text

Is, IsLike, LessThan, GreaterThan, StartsWith, EndsWith

String

 

Text

Contains

String

Allowed when Include in Text is true and Open to Associations is false.

Yes/No

IsSet

null

 

Yes/No

Is

bool

 

Single Choice

IsSet

null

 

Single Choice

AnyOfThese

List<int> or int[]

List<Guid> or Guid[]

 

Multiple Choice

IsSet

null

 

Multiple Choice

AnyOfThese, AllOfThese

List<int> or int[]

List<Guid> or Guid[]

 

Single Object

IsSet

null

 

Single Object

AnyOfThese

List<int> or int[]

List<Guid> or Guid[]

 

Single Object

IsLike

String

 

Single Object

LessThan, GreaterThan

String

NotOperator cannot be set to true.

Multiple Object

In

CriteriaCollection

The value is another set of criteria defined by instantiating a new CriteriaCollection.

Batch

In

CriteriaCollection

The value is another set of criteria defined by instantiating a new CriteriaCollection.

Multiple Object, Batch condition value

IsSet

null

NotOperator cannot be set to true

Multiple Object, Batch condition value

AnyOfThese, AllOfThese

List<int> or int[]

List<Guid> or Guid[] (for Multiple Object)

 

Multiple Object, Batch condition value

IsLIke

String

 

Multiple Object, Batch

LessThan, GreaterThan

String

NotOperator cannot be set to true

Number (Whole Number, Currency, Decimal)

IsSet

null

 

Number (Whole Number, Currency, Decimal)

Is, GreaterThan, LessThan

A valid number.

 

User

IsLoggedInUser

null

NotOperator cannot be set to true

User

IsSet

null

 

User

AnyOfThese

List<int> or int[]

 

Extracted Text or Full Text

Contains

String

 

Saved Search

In

int

 

The CriteriaDateCondition object represents a condition for a single date-type Relativity field. The following table presents value types corresponding to CriteriaDateCondition.

CriteriaDateConditionEnum

Value Type

Notes

IsSet

null

 

Is, IsBefore, IsBeforeOrOn, IsAfter, IsAfterOrOn

DateTime

 

Between

List<DateTime> or DateTime[]

Must contain two DateTime objects.

In

DateTimeRange enumeration

If DateTimeRange = MonthOf then Month must be set from the Month enumeration.

Read

Use this Keyword Search Manager Service URL to read a keyword search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/ReadSingleAsync   

The request must include the workspace ID and the keyword saved search Artifact ID.

{
  "workspaceArtifactID": 1030160,
  "searchArtifactID": 1038891
}  

The response returns a JSON representation of a KeywordSearch DTO.

Update

Use this Keyword Search Manager Service URL to update a keyword search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/UpdateSingleAsync

The request must include a workspace ID and a valid JSON representation of a KeywordSearch DTO.

Note: You must include all DTO field information in the update. You cannot update individual fields because fields left empty will be cleared on the update. All DTO fields are required except for system/user created by/created on.

The following JSON sample illustrates how to add fields and sort to the keyword search created in a previous example.

{
  "workspaceArtifactID": 1030160,
  "searchDTO": {
    "ArtifactID": 1038573,
	"ArtifactTypeID": 10,
    "Name": "My New Keyword Search",
    "Fields": [
      {
        "Name": "Doc ID Beg"
      },
      {
        "Name": "Author"
      },
      {
        "Name": "Extracted Text"
      }
    ],
    "Sorts": [
      {
        "FieldIdentifier": {
          "Name": "Doc ID Beg"
        },
        "Order": 0,
        "Direction": 1
      }
    ]

  }
}

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Delete

Use this Keyword Search Manager Service URL to update a keyword search:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/DeleteSingleAsync   

The request must include the workspace ID and the keyword saved search Artifact ID.

{
  "workspaceArtifactID": 1030160,
  "searchArtifactID": 1038661
}  

The response does not contain any data. Success or failure are indicated by the HTTP status code. For more information, see HTTP status codes.

Query

The Keyword Search Manager Service URL for querying keyword searches:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/QueryAsync

The request must include the workspace ID, the query, and length (the number of results to be returned) specified as an integer.

{
  "workspaceArtifactID": 1030160,
  "query": {
    "Condition": "'Name' STARTSWITH 'My'",
    "Sorts": [
      {
        "FieldIdentifier": {
          "ArtifactID": 0,
          "ViewFieldID": 0,
          "Guids": [],
          "Name": "ArtifactID"
        },
        "Order": 0,
        "Direction": 1
      }
    ]
  },
  "length": 5
}

If more results are available than initially specified in the length property, the query returns a token value that is not null. The results can subsequently be retrieved by a call to the QuerySubsetAsync operation.

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/QuerySubsetAsync

Note that the QuerySubsetAsync request can specify the starting index of the result subset and the number of results to be returned.

{
  "workspaceArtifactID": 1030160,
  "queryToken": "d0aff8bf-321d-4600-8240-dba2f0173b1d",
  "start": 6,
  "length": 5
}

Move

You can move a keyword saved search to a different folder. Send a request to this Keyword Search Manager service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/MoveAsync

The request must contain the following fields:

  • workspaceArtifactID – the Artifact ID for the workspace where the search resides.
  • artifactID – the Artifact ID of the search.
  • destinationContainerID - the Artifact ID of the target saved search folder.

Note: You must have delete permission for saved search and search folder on the source search folder and add permissions for saved search and search folder on destination folder. If any of those is not met then a validation error is returned.

{
   "workspaceArtifactID": 1015024,
   "artifactID": 1039180,
   "destinationContainerID": 1039178
}

The response returns the following fields:

  • ProcessState - a message that indicates the current operation executing on the search being moved. The values can include:
    • Moving saved searches.
    • Error
    • Completed
  • TotalOperations - equals the sum of the number of moved objects.
  • OperationsCompleted - indicates the number of operations that have been executed.
{
   "TotalOperations": 1,
   "ProcessState": "Completed",
   "OperationsCompleted": 1
}

Note: Unlike the Services API, the Keyword Search Manager Service doesn’t support use of progress indicators or cancellation tokens.

Copy

You can create a copy of an existing keyword saved search in the same saved search folder. Send a request to this Keyword Search Manager service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/CopySingleAsync

The request must contain the following fields:

  • workspaceArtifactID – the Artifact ID for the workspace where the saved search resides.
  • artifactID – the Artifact ID of the search
{
   "workspaceArtifactID": 1015024,
   "searchArtifactID": 1036361
}

This creates a copy of an existing search in the same location. The name of the copy is based on the name of the original with an incremented number in brackets, for example New Case Documents (3).

The response returns the saved search reference object the with following fields:

  • ArtifactID - the Artifact ID of the copy.
  • Name - the name of the copy.
{
    "ArtifactID": 1041178,
    "Name": "New Case Documents (3)"
}

Helper operations

The Keyword Search Manager Service provides the following helper operations for retrieving search properties:

GetEmailToLinkUrlAsync

The Keyword Search Manager Service URL for retrieving an email link to keyword search results:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/GetEmailToLinkUrlAsync

The request must include the workspace ID and the search Artifact ID.

{
  "workspaceArtifactID": 1030160,
  "searchArtifactID": 1039106
}

The response is the string value of the email link.

"mailto:?subject=Relativity%20Review%20-%20Integration%20Tests%20-%20My%20New%20Keyword%20Search%20With%20Two%20Conditions&body=http%3a%2f%2fmyhost%2frelativity%2fsearchlink.aspx%3fSelectedSearchArtifactID%3d1039106%26AppID%3d1275015"

GetFieldsForCriteriaConditionAsync

The Keyword Search Manager Service URL for retrieving all workspace fields available to the user that can be included in a saved search conditions criteria:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/GetFieldsForCriteriaConditionAsync

The request must include the workspace ID and the search artifact type ID.

{
  "workspaceArtifactID": 1275015,
  "artifactTypeID": 10
}

Note: Currently only Document can be specified as the artifact type.

The response is a collection of Field objects. For more information about Field object properties, see JSON representations.

GetFieldsForObjectCriteriaCollectionAsync

The request must include the workspace ID, a multi-object Field, and the search artifact type ID.

{
  "workspaceArtifactID": 1275015,
  "field":{"Name": "Batch"},
  "artifactTypeID": 10
}

The response is a collection of Field objects. For more information about Field object properties, see JSON representations.

[
  {
    "ArtifactID": 1035250,
    "ViewFieldID": 1000422,
    "Guids": [
      "d7a9d9fd-68fc-4c85-ad44-ba524a0ca872"
    ],
    "Name": "Batch"
  },
  {
    "ArtifactID": 1035251,
    "ViewFieldID": 1000423,
    "Guids": [
      "8c3ea95d-6c72-4463-8696-1b6859c0e00e"
    ],
    "Name": "Batch::Batch Set"
  },
  {
    "ArtifactID": 1035252,
    "ViewFieldID": 1000424,
    "Guids": [
      "3e62303c-b955-4a93-b82a-894ce40b5563"
    ],
    "Name": "Batch::Assigned To"
  },
  {
    "ArtifactID": 1035253,
    "ViewFieldID": 1000425,
    "Guids": [
      "70e1751f-4f6b-4c1d-abd7-8a6328750175"
    ],
    "Name": "Batch::Status"
  }
]

GetFieldsForSearchResultViewAsync

If the request includes the workspace ID and the artifact type ID, the service returns all workspace fields available to the user as a collection of Field objects in the FieldsNotIncluded property.

{
  "workspaceArtifactID": 1030160,
  "artifactTypeID": 10
}

If the request includes the workspace ID, the artifact type ID, and the Artifact ID of a keyword saved search, the service returns the fields included in the specified search as a collection of Field objects in the FieldsIncluded property. Workspace fields available to be included in the search are returned in the FieldsNotIncluded property.

{
  "workspaceArtifactID": 1030160,
  "artifactTypeID": 10,
  "searchArtifactID": 1039076
}

GetSearchIncludesAsync

To return all relational fields available to the user in the workspace, use this Keyword Search Manager Service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/GetSearchIncludesAsync

The request must include a workspace ID.

{
  "workspaceArtifactID": 1030160
}

The response includes a collection of Field objects.

[
  {
    "ArtifactID": 0,
    "ViewFieldID": 0,
    "Guids": [],
    "Name": ""
  },
  {
    "ArtifactID": 1035456,
    "ViewFieldID": 1000643,
    "Guids": [
      "14ffb8be-42d1-419e-b72c-645484a78a83"
    ],
    "Name": "Include Conversation Family"
  },
  {
    "ArtifactID": 1003669,
    "ViewFieldID": 1000188,
    "Guids": [
      "a426bc5e-3420-47b4-a293-4c4848a237d7"
    ],
    "Name": "Include Duplicates"
  },
  {
    "ArtifactID": 1036396,
    "ViewFieldID": 1000671,
    "Guids": [
      "c0aa4323-45d5-4db3-bf00-71094792901b"
    ],
    "Name": "Include Emailset"
  },
  {
    "ArtifactID": 1036394,
    "ViewFieldID": 1000670,
    "Guids": [
      "ff4e3c74-d1e0-4c0c-bb58-b50dd7ee8dfa"
    ],
    "Name": "Include EquiSet"
  },
  {
    "ArtifactID": 1003671,
    "ViewFieldID": 1000190,
    "Guids": [
      "1f036749-a691-4aa8-8cf7-5eeb80c36caf"
    ],
    "Name": "Include Family"
  }
]

GetSearchOwnersAsync

To return all users in the workspace with permissions to view saved searches, use this Keyword Search Manager Service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/GetSearchIncludesAsync

The request must include a workspace ID.

{
  "workspaceArtifactID": 1030160
}

The response includes a collection of User objects.

[
  {
    "ArtifactID": 0,
    "Name": "Public, Joe"
  },
  {
    "ArtifactID": 9,
    "Name": "Admin, Relativity"
  },
  {
    "ArtifactID": 1000000392,
    "Name": "Admin, Relativity"
  },
  {
    "ArtifactID": 1271248,
    "Name": "Doe, Jane"
  }
]

GetAccessStatusAsync

The GetAccessStatusAsync endpoint returns the information about the user‘s ability to access the saved search.

To return the access status, use this Keyword Search Manager Service URL:

/Relativity.REST/api/Relativity.Services.Search.ISearchModule/Keyword%20Search%20Manager/GetAccessStatusAsync

The request must include these fields:

  • workspaceArtifactID – the Artifact ID for the workspace where the search resides.
  • artifactID – the Artifact ID of the search.
  • ancestorArtifactIDs – a collection of Artifact IDs representing the folder path where the search resides.
{
    "workspaceArtifactID": 1015024,
    "artifactID": 1038050,
    "ancestorArtifactIDs":[1036361, 1035243]        
}

The response returns an access status object with the following fields:

  • Exists – indicates whether the search exists relative to the specified folder path.
  • CanView – indicates whether the user has view permissions to the search.
  • CanAccessSearchProvider – indicates whether the user has view permissions to the search provider used in the search.
  • CanViewCriteriaFields – indicates whether the user has view permissions to all of the fields used in the search.
{
    "Exists": true,
    "CanView": true,
    "CanAccessSearchProvider": false,
    "CanViewCriteriaFields": false
}