Annotating Search Results

Collaborative search applications, also known as social search applications, are search applications that enable you to add information to search results, annotating them so that they are more valuable to other users in subsequent searches. Being able to rate, comment on, vote on, and otherwise augment information that you found in your searches can make it easier for other users to identify relevant and valuable search results. Collaborative search applications continually enhance the value of enterprise search by adding the dimension of human knowledge to the sophisticated algorithms that are built into Watson™ Explorer Engine.

Watson Explorer Engine search applications support three general types of annotations (also commonly referred to as tags):

global: a single instance of this annotation can be assigned to each document by any user. An example of this type of annotation would be one that was intended to hold document state information, such as draft, reviewed, final, and so on. The API functions that support this type of annotation are annotation-global-set, annotation-express-global-set-doc-list, and annotation-express-global-set-query.
user: a single instance of this annotation can be assigned to each document by each user. An example of this type of annotation would be one that was intended to hold a vote or rating, where you want to prevent a single user from supplying multiple instances of that annotation. A user can still supply multiple values for a user annotation, but only the most recent value is saved with the document. The API functions that support this type of annotation are annotation-user-set, annotation-express-user-set-doc-list, and annotation-express-user-set-query.
standard: multiple instances of this annotation can be assigned to each document by each user. An example of this type of annotation is a comment or the type of tags used by the Watson Explorer Engine Auto-Classification capabilities. The API functions that support this type of annotation are annotation-add, annotation-delete, and annotation-update for adding, deleting, or updating a single annotation on a specified document, and annotation-express-add-doc-list, annotation-express-add-query, annotation-express-delete-doc-list, annotation-express-delete-query, annotation-express-update-doc-list, and annotation-express-update-query for adding, deleting, or updating the same standard annotation on multiple documents at the same time. The query functions add, delete, or update annotations on document elements that match a specified query.

The express functions enable the user to add the same tag to a large number of search results. Depending on the number of search results tagged, tagging multiple search results can be done instantly or as a background process that enables an application to continue while the tags are being applied.

In addition to the functions that add, delete, or update various types of annotations, Watson Explorer Engine provides two other annotation-related functions:

annotation-permissions: used internally by the annotation functions discussed in this section, this function generates the permissions that are necessary for users to view an annotation.
auto-classify-refresh-tags: when using the Watson Explorer Engine Auto-Classification capabilities, this function annotates documents with the tags present in the classification set that is passed as an argument. This function simplifies tag updates when new documents have been added to a collection and those documents match an annotation query that has already been processed.

The next few sections discuss how to add, delete, and update annotations using these functions.