Package nzilbb.labbcat.server.api

Class Search

  • public class Search
extends APIRequestHandler
    /api/search : Starts a search task to identify matches for the given search matrix.

    The search matrix defines a pattern of annotations to identify, which transcripts to search, and which participant's utterances to target. Additional search parameters can also be defined; whether to return only aligned matches, whether main-participants only are being targeted, etc.

    Input HTTP parameters:

    • searchJson - A JSON-encoded reprentation of the search matrix.
    • search - An alternative to searchJson, this encodes an orthography-layer-only search as a plain-text string.
    • mainParticipantOnly - Optional: specify a value (e.g. "true") if only main-participant utterances should be searched, absent otherwise.
    • offsetThreshold - Optional minimum alignment confidence for matching word or segment annotations. A value of 50 means that annotations that were at least automatically aligned will be returned. Use 100 for manually-aligned annotations only, and 0 or no value to return all matching annotations regardless of alignment confidence.
    • matchesPerTranscript - Optional maximum number of matches per transcript to return, or absent to return all matches in each transcript.
    • overlapThreshold - Optional (integer) percentage overlap with other utterances before simultaneous speech is excluded, or absent to include overlapping speech.
    • maxMatches - Optional maximum number of transcripts to include results for.
    • suppressResults - Optional: Specify a value (e.g. "true") to return a summary of results only, instead of listing specific matches.
    • participantQuery - Optional AGQL expression for defining which participants to search the utterances of, e.g. first('participant_gender').label == 'NB'
    • participant_expression - Deprecated synonym for participantQuery.
    • transcriptQuery - Optional AGQL expression for defining which transcript to search, e.g. ['CC','IA'].includesAny(labels('corpus'))
    • transcript_expression - Deprecated synonymn for transcriptQuery.
    • only_main_speaker - Deprecated synonym for mainParticipantOnly.
    • matches_per_transcript - Deprecated synonym for matchesPerTranscript.
    • overlap_threshold - Deprecated synonym for overlapThreshold.
    • num_transcripts - Deprecated synonym for maxMatches.
    • suppress_results - Deprecated synonym for suppressResults.
    • only_aligned - Deprecated: specifying a value (e.g. "true") is equivalent to specifying offsetThreshold with a value of "50".

    Output: a JSON-encoded response object of the usual structure for which the "model" is an object with a "threadId" attribute, which is the ID of the server task to monitor for results. e.g. 
    {
    "title":"search",
    "version" : "20230502.0924",
    "code" : 0,
    "errors" : [],
    "messages" : [],
    "model" : {
        "threadId" : "80"
    }
 }

    The task, when finished, will output a URL for accessing the matches of the search.
    Author:
    Robert Fromont

    • Constructor Detail

      • Search

        public Search()
        Constructor

    • Method Detail

      • get

        public javax.json.JsonObject get​(RequestParameters parameters,
                                 Consumer<Integer> httpStatus)
        The GET method for the servlet.
        Parameters:
        parameters - Request parameter map.
        httpStatus - Receives the response status code, in case or error.
        Returns:
        A JSON object as the request response.