Thrift module: search

Module Services Data types Constants
search SearchService
SearchProxyService
FeedbackService
SearchCapability
SearchFeedback
SearchQuery
SearchResult
SearchResultItem
SearchType

Enumerations

Enumeration: SearchType 

What are we searching over


COMMUNICATIONS 0
SECTIONS 1
SENTENCES 2
ENTITIES 3
ENTITY_MENTIONS 4
SITUATIONS 5
SITUATION_MENTIONS 6

Enumeration: SearchFeedback 

Feedback values


NEGATIVE -1
NONE 0
POSITIVE 1

Data structures

Struct: SearchCapability

Key Field Type Description Requiredness Default value
1 type SearchType A type of search supported by the search provider required
2 lang string Language that the search provider supports. Use ISO 639-2/T three letter codes. required 

A search provider describes its capabilities with a list of search type and language pairs.

Struct: SearchQuery

Key Field Type Description Requiredness Default value
1 terms list< string > Individual words, or multiword phrases, e.g., 'dog', 'blue cheese'. It is the responsibility of the implementation of Search* to tokenize multiword phrases, if so-desired. Further, an implementation may choose to support advanced features such as wildcards, e.g.: 'blue*'. This specification makes no committment as to the internal structure of keywords and their semantics: that is the responsibility of the individual implementation. optional
2 questions list< string > e.g., "what is the capital of spain?" questions is a list in order that possibly different phrasings of the question can be included, e.g.: "what is the name of spain's capital?" optional
3 communicationId string Refers to an optional communication that can provide context for the query. optional
4 tokens structure.TokenRefSequence Refers to a sequence of tokens in the communication referenced by communicationId. optional
5 rawQuery string The input from the user provided in the search box, unmodified optional
6 auths string optional authorization mechanism optional
7 userId string Identifies the user who submitted the search query optional
8 name string Human readable name of the query. optional
9 labels list< string > Properties of the query or user. These labels can be used to group queries and results by a domain or group of users for training. An example usage would be assigning the geographical region as a label ("spain"). User labels could be based on organizational units ("hltcoe"). optional
10 type SearchType This search is over this type of data (communications, sentences, entities) required
11 lang string The language of the corpus that the user wants to search. Use ISO 639-2/T three letter codes. optional
12 corpus string An identifier of the corpus that the search is to be performed over. optional
13 k i32 The maximum number of candidates the search service should return. optional
14 communication communication.Communication An optional communication used as context for the query. If both this field and communicationId is populated, then it is assumed the ID of the communication is the same as communicationId. optional 

Wrapper for information relevant to a (possibly structured) search.

Struct: SearchResultItem

Key Field Type Description Requiredness Default value
1 communicationId string optional
2 sentenceId uuid.UUID The UUID of the returned sentence, which appears in the communication referenced by communicationId. optional
3 score double Values are not restricted in range (e.g., do not have to be within [0,1]). Higher is better. optional
4 tokens structure.TokenRefSequence If SearchType=ENTITY_MENTIONS then this field should be populated. Otherwise, this field may be optionally populated in order to provide a hint to the client as to where to center a visualization, or the extraction of context, etc. optional
5 entity entities.Entity If SearchType=ENTITIES then this field should be populated. optional 

An individual element returned from a search.  Most/all methods
will return a communicationId, possibly with an associated score.
For example if the target element type of the search is Sentence
then the sentenceId field should be populated.

Struct: SearchResult

Key Field Type Description Requiredness Default value
1 uuid uuid.UUID Unique identifier for the results of this search. required
2 searchQuery SearchQuery The query that led to this result. Useful for capturing feedback or building training data. required
3 searchResultItems list< SearchResultItem > The list is assumed sorted best to worst, which should be reflected by the values contained in the score field of each SearchResult, if that field is populated. optional
4 metadata metadata.AnnotationMetadata The system that provided the response: likely use case for populating this field is for building training data. Presumably a system will not need/want to return this object in live use. optional
5 lang string The dominant language of the search results. Use ISO 639-2/T three letter codes. Search providers should set this when possible to support downstream processing. Do not set if it is not known. If multilingual, use the string "multilingual". optional 

Single wrapper for results from all the various Search* services.

Services

Service: SearchService

extends services.Service 
SearchResult search(SearchQuery query)
    throws services.ServicesException

Perform a search specified by the query

Function: SearchService.getCapabilities 

list<SearchCapability> getCapabilities()
    throws services.ServicesException

Get a list of search type-language pairs

Function: SearchService.getCorpora 

list<string> getCorpora()
    throws services.ServicesException

Get a corpus list from the search provider

Service: SearchProxyService

extends services.Service 
The search proxy service provides a single interface to multiple search providers


SearchResult search(SearchQuery query,
                    string provider)
    throws services.ServicesException

Specify the search provider when performing a search

Function: SearchProxyService.getProviders 

list<string> getProviders()
    throws services.ServicesException

Get a list of search providers behind the proxy

Function: SearchProxyService.getCapabilities 

list<SearchCapability> getCapabilities(string provider)
    throws services.ServicesException

Get a list of search type and language pairs for a search provider

Function: SearchProxyService.getCorpora 

list<string> getCorpora(string provider)
    throws services.ServicesException

Get a corpus list for a search provider

Service: FeedbackService

extends services.Service

Function: FeedbackService.startFeedback 

void startFeedback(SearchResult results)
    throws services.ServicesException

Start providing feedback for the specified SearchResults.
This causes the search and its results to be persisted.

Function: FeedbackService.addCommunicationFeedback 

void addCommunicationFeedback(uuid.UUID searchResultsId,
                              string communicationId,
                              SearchFeedback feedback)
    throws services.ServicesException

Provide feedback on the relevance of a particular communication to a search

Function: FeedbackService.addSentenceFeedback 

void addSentenceFeedback(uuid.UUID searchResultsId,
                         string communicationId,
                         uuid.UUID sentenceId,
                         SearchFeedback feedback)
    throws services.ServicesException

Provide feedback on the relevance of a particular sentence to a search