Skip to content
Search! & Match! API
Save Results Service
latest

Save Results Service

Save Results ServiceπŸ”—

The save results service allows to manage saved results. It comes with methods to save, delete, and list them. All method are existing in two variants: one including user authentication, and another one requesting a valid access token.

All methods of this service can raise the following common errors. Method-specific errors are mentioned later. While the methods with user authentication can raise an INVALID_PASSWORD error, the versions requiring access tokens can instead return INVALID_ACCESS_TOKEN errors.

Common Error HandlingπŸ”—

Error Code Description
EMPTY_ARGUMENT One or more mandatory arguments are empty.
METHOD_NOT_AVAILABLE The service method is disable in the environment configuration.
INVALID_PASSWORD The password is incorrect - applies only to password authentication.
INVALID_ACCESS_TOKEN The token is not valid (possibly timed-out) - applies only to token authentication.
ENVIRONMENT_NOT_AVAILABLE The environment is not available (see log-file for possible errors).
DATABASE_ERROR Database communication failed (possibly a misconfiguration issue).
PROJECT_NOT_FOUND A project with projectID does not exist.
PROJECT_ACCESS_DENIED The project with projectID is not owned by the user.
SEARCHER_NOT_FOUND The searchEngine does not exist.
SEARCH_EXECUTION_ERROR An error occurred while querying the search index (while retrieving metadata).
SEARCHER_ACCESS_DENIED Save results enabled only for the searchers of type elasticsearch.

Method saveResultsπŸ”—

Method callπŸ”—

saveResults(environment, password, user, accessRoles, projectID, searchEngine, results) : saveResultsResponse

DescriptionπŸ”—

The save results service persists all results provided by the savedResults object. If the saveResults object contains no projectID, a default project is created for the user. This method can be called as:

ParametersπŸ”—

Parameter Name Type Description
environment string identifier of a search environment
password string password for the search environment
user string identifier for the current user
accessRoles List of Strings access roles of the current user
projectID string identifier for the project, may be null for default project
searchEngine string the searchEngine where the results are saved to. SearchEngine must be of type elasticsearch
results list of SavedResult See description of SavedResult in chapter Object Structures

ReturnsπŸ”—

Result Name Type Description
saveResultsResponse Integer The new revision number of the affected project

Pre-ConditionπŸ”—

  • The project with projectID exists if projectID is given.
  • The project with projectID is either owned by or shared with the user if projectID is given.
  • SearchEngine must be of type elasticsearch.

Post-ConditionπŸ”—

  • Each result is saved for the user’s project and searcher.
  • The results are saved in the same order as they are in the list.
  • If saved results existed with the same user’s project’s searcher’s docID their metadata is overwritten.
  • If the given projectID is null then a β€˜default project’ is created if it does not exist.

Error HandlingπŸ”—

See the description of common errors.

Method saveResultsWithTokenπŸ”—

Method callπŸ”—

saveResultsWithToken(accessToken, saveResults) : saveResultsResponse

DescriptionπŸ”—

Same as saveResults method but with accessToken instead of environment, password, and user.

Method deleteResultsπŸ”—

Method callπŸ”—

deleteResults(environment, password, user, accessRoles, projectID, searchEngine, docIDs) : deleteResultsResponse

DescriptionπŸ”—

The delete results service deletes all results specified as IDs stored under the project's searchEngine. Results requested for deletion but not found in the database are ignored. No error is reported in that case. This method can be called as:

ParametersπŸ”—

Parameter Name Type Description
environment string identifier of a search environment
password string password for the search environment
user string identifier for the current user
accessRoles List of Strings access roles of the current user
projectID string identifier for the project, may be null for default project
searchEngine string the searchEngine where the results belong to
docIDs list of strings the document IDs of results to be deleted

ReturnsπŸ”—

Result Name Type Description
deleteResultsResponse Integer The new revision number of the version

Pre-ConditionπŸ”—

  • The project with projectID exists if projectID is given.
  • The project with projectID is either owned by or shared with the user if projectID is given.

Post-ConditionπŸ”—

Each saved result is deleted from the database if it exists.

Error HandlingπŸ”—

See the description of common errors.

Method deleteResultsWithTokenπŸ”—

Method callπŸ”—

deleteResultsWithToken(accessToken, saveResults) : deleteResultsResponse

DescriptionπŸ”—

Same as deleteResults method but with accessToken instead of environment, password, and user.

Method listResultsπŸ”—

Method callπŸ”—

listResults(environment, password, user, accessRoles, projectID) : listResultsResponse

DescriptionπŸ”—

The save results service gets all saved results from the database associated with project defined by projectID. If the projectID is not specified the results of the user's default project are listed.

The response contains only the document IDs (metadata field is empty). The retrieveMetadata service retrieves the metadata belonging to the saved results.

ParametersπŸ”—

Parameter Name Type Description
environment string identifier of a search environment
password string password for the search environment
user string identifier for the current user
accessRoles List of Strings access roles of the current user
projectID string identifier for project the search belongs to, null for default project

ReturnsπŸ”—

Result Name Type Description
listResultsResponse SavedResults object the saved results for each searcher. The results contain only doc ID, the metadata is empty. See description of SavedResults in chapter Object Structures

Pre-ConditionπŸ”—

  • The project with projectID exists if projectID is given.
  • The project with projectID is either owned by or shared with the user if projectID is given.
  • For the service to return saved results they must have been saved to the database by the given user.

Post-ConditionπŸ”—

None.

Error HandlingπŸ”—

See the description of common errors.

Method listResultsWithTokenπŸ”—

Method callπŸ”—

listResultsWithToken(accessToken, projectID) : listResultsResponse

DescriptionπŸ”—

Same as listResults method but with accessToken instead of environment, password, and user.

Method retrieveMetadataπŸ”—

Method callπŸ”—

retrieveMetadata(environment, password, user, accessRoles, accessOptions, projectID, searchEngine, docIDs, language) : retrieveMetadataResponse

DescriptionπŸ”—

This method gets the metadata for the provided documentIDs by looking in the database and the index - except for external searchers for which only the database is queried.

As a side effect, if data from the index is different from the data in the database (and the user is owner of the project), the database will be immediately updated. If no data is found in the database, the index check is skipped and no metadata is returned. If no data is found in the index, the database value is returned.

If "deleteStale" setting is set to true and no data is found in the index, then the result is immediately removed from the database and no metadata is returned instead of returning what is found in the database.

ParametersπŸ”—

Parameter Name Type Description
environment string identifier of a search environment
password string password for the search environment
user string identifier for the current user
accessRoles List of Strings access roles of the current user
projectID string identifier for the project, may be null for default project
searchEngine string the searchEngine where the results are saved to. SearchEngine must be of type elasticsearch
docIDs list of strings the document IDs of results to be deleted
language string The language of the search result translations (codes, field labels, and date strings).

ReturnsπŸ”—

Result Name Type Description
retrieveMetadataResponse Map of string to string Map of documentID to saved result metadata json

Pre-ConditionπŸ”—

  • The project with projectID exists if projectID is given.
  • The project with projectID is either owned by or shared with the user if projectID is given.

Post-ConditionπŸ”—

  • The metadata in the database is updated if the result is different in the index and the user owns the project.
  • If the results were found in the database, but not in the index, the requesting user is the owner of the project and "deleteStale" configuration parameter is set to true, the saved results corresponding to the projectID and documentIDs are deleted from the database.

Error HandlingπŸ”—

See the description of common errors.

Method retrieveMetadataWithTokenπŸ”—

Method callπŸ”—

retrieveMetadataWithToken(accessToken, projectID, searchEngine, docIDs, language) : retrieveMetadataResponse

DescriptionπŸ”—

Same as retrieveMetadata method but with accessToken instead of environment, password, user, and accessRoles.