The Execute Query Stage is a crucial component in GAIA API that enables you to perform powerful search queries on an index or alias. It provides a wide range of options and parameters to customize and fine-tune your search.

With the Execute Query Stage, you can specify the fields to be used for matching terms, phrases, spans, date ranges, and ranges. This allows you to define precisely how your search results are retrieved and filtered based on your specific requirements.

One of the key features of the Query Stage is the ability to leverage PyQPL (Query Parser Language) to create complex and advanced queries. PyQPL provides a flexible syntax that allows you to construct intricate search conditions, combine multiple search criteria, and define custom operators for precise control over your search results.


The Execute Query Stage also supports various additional functionalities to enhance your search experience. These include pagination, sorting, highlighting (to emphasize search terms in the results), filters (to narrow down search results based on specific criteria), aggregations (to obtain statistical insights from search results), and the ability to fetch specific fields to optimize performance and reduce data transfer.

Properties

PropertyDescriptionDefaultTypeRequiredQPL Config?
typeStage class name-stringYesNo
enableEnable stage for executiontruebooleanNoNo
nameName for this specific stage"search"stringNoNo
save_to_intermediateIf true, the result of the stage will be stored in the intermediate instead of the final sectionfalsebooleanNoNo
expand_resultIndicates if the result of this stage should be expanded into the final data dictionary instead of being appended as usualfalsebooleanNoNo
ui_onlySection specific for UI configuration that affects the process of the stageQueryStageUIConfigNo
No
halt_on_exceptionIndicates if the pipeline should be interrupted in case of an exceptiontruebooleanNoNo
indexName of the index or alias in which to perform the query-string or array of stringsYesNo
engine_nameName of the engine to use for this query. If none is provided, the default engine will be usedstringNo
No
queryJSON Query DSL as a string representation or a dictionarystring or objectNo
No
sizeNumber of hits to return per requestintegerNo
No
sortSort configuration for the query resultsarray or objectNo
No
page_size_defaultDefault page size for pagination25integerNoNo
operatorThe default operator for query string query: AND or OR"or"stringNoNo
highlightName of the key in which the highlights will be stored in the intermediate"highlight"stringNoNo
filtersName of the key in which the filters will be stored in the intermediate"filters"stringNoNo
aggregationsName of the key in which the engine specific aggregations will be stored in the intermediate"aggregations"stringNoNo
aggregations_filtersName of the key in which the engine specific aggregation filters will be stored in the intermediate"aggregations_filters"stringNoNo
fetch_fieldsList of fields to fetcharray of stringsNo

exclude_fieldsList of fields to excludearray of stringsNo

qpl_enableEnable QPL to parse the "q" parameter into an engine query with pyQPLfalsebooleanNoYes
implicit_operatorDefault operator to use when the relationship between two operands is ambiguous"or"stringNoYes
fieldsFields to be used for matching terms, phrases, spans, etc.array, object, or stringYes
Yes
date_fieldsFields to be used for date rangesarray, object, or stringNo
Yes
range_fieldsFields to be used for rangesarray, object, or stringNo
Yes
date_formatDate format used to convert date values in the querystringNo
Yes
slop_nearSlop value used for the NEAR operator10numberNoYes
slop_beforeSlop value used for the BEFORE operator2numberNoYes
slop_adjSlop value used for the ADJ operator0numberNoYes
slop_span_notSlop value used for the SPAN NOT operator0numberNoYes
timezoneCoordinated Universal Time (UTC) offset or IANA time zone used to convert date values in the query to UTCstringNo
Yes
wildcardUse wildcard operatorsfalsebooleanNoYes
grammarFile path or raw string representing the grammar for parsing text into QPLstringNo
Yes
custom_operatorsDictionary of custom operators with their names as keys and corresponding logic classes as valuesobjectNo
Yes

synonyms_call

Function returning requested synonyms for the specified string


Callable(accepts: string, returns: list of string, or None )NoYes


Execute Query Stage Intermediate Parameters

The Execute Query Stage offers a range of parameters that can be passed via the intermediate input to customize your search request or modify the configuration of the current stage. These parameters provide flexibility and control over the search process.


ParameterDescription
qA string query for performing a search. Can be transformed into engine-specific queries using PyQPL (Query Parser Language).
queryEngine-specific queries for the search.
knnEngine-specific queries specifically for k-nearest neighbor (KNN) searches.
sizeNumber of results to return from the search request. Overrides the size specified in the configuration.
from/startIndicates the starting point for retrieving search results. Can be used interchangeably with the page parameter.
pageIt can be an alternative to from/start. It calculates the start based on the size parameter
fetch_fieldsList of fields to fetch for each search result. Overrides the fields specified in the configuration.
exclude_fieldsList of fields to exclude from the search results. Overrides the fields specified in the configuration.
scrollScroll ID used to retrieve large numbers of results from a single search request, similar to a cursor in a traditional database.
operatorThe default operator for query string queries: AND or OR. Overrides the default operator specified in the configuration.

Remember that the intermediate can be fill with either other stages or the original request body that trigger the pipeline, making this essentially REST API parameters

Additional Classes for Configuration

ExecuteQueryStageUIConfig 

The ExecuteQueryStageUIConfig is a configuration object that provides UI-specific settings for the QueryStage.

ExecuteQueryStageUIConfig Properties

PropertyDescriptionDefaultType
page_sizeConfiguration for page size settings in the UIPageSizeConfigNo
sortConfiguration for sort settings in the UISortConfigNo

PageSizeConfig Properties 

PropertyDescriptionDefaultType
defaultDefault page size value25integer
optionsAvailable page size options[25, 50, 100]array of integers

SortConfig Properties 

PropertyDescriptionTypeRequired
defaultDefault sort entrySortEntryYes
optionsAvailable sort optionsarray of SortEntryYes

SortEntry Properties 

PropertyDescriptionTypeRequired
fieldName of the field to be used for sortingstringYes
display_nameDisplay name for this sort entry (only applicable for user interface)stringNo
orderSort order to be usedSortOrder or objectYes

SortOrder Enum 

Enum ValueDescription
"asc"Ascending sort order
"desc"Descending sort order



Example Configuration

synonyms = {
            'cancer': ['cancer', 'malignancy', '363346000', 'cancers', 'malignancies', '"malignant growth"',
                       '"malignant neoplasm"', '"malignant neoplasms"', '"malignant neoplastic disease"',
                       '"malignant tumor"', '"malignant tumors"', '"neoplasm malignant"', '"neoplasm/cancer"',
                       '"tumor, malignant"'],
            'headache': ['headache', '25064002', 'cephalalgia', 'cephalgia', 'cephalgias', '"cranial pain"',
                         '"have headaches"', '"head ache"', '"head pain"', '"head pain cephalgia"', '"head pains"',
                         'headaches', '"mild global headache"', '"mild headache"', '"pain head"', '"pain in head"',
                         '"pain, head"']
        }

_query_stage = ExecuteQueryStage(
    engine_name=DEFAULT_ENGINE_NAME,
    enable=True,
    qpl_enable=True,
    name=SEARCH_STAGE_NAME,
    index='movies',
    synonyms_call= lambda x: self.synonyms.get(x, None), # Simple synonym implementation
    wildcard=False,
    fields=['title', 'overview', 'url', 'status', 'metadata', 'metadata.production_companies',
            'metadata.cast',
            'metadata.directors'],
    range_fields=['metadata.budget'],
    date_fields=['release_date'],
    fetch_fields=['title', 'adult', 'overview', 'url', 'release_date', 'status', 'video', 'metadata',
                  'metadata.production_companies', 'metadata.cast', 'metadata.directors'],
    exclude_fields=None,
    implicit_operator='or',
    page_size_default=25,
    sort=SortEntry(
        field='_score',
        order=SortOrder.DESC
    ),
    aggregations=_aggregation_stage.name,
    aggregations_filters=_aggregation_stage.filters_name,
    highlight=_highlight_stage.name,
    filters=_filter_stage.name,
    ui_only=ExecuteQueryStageUIConfig(
        sort=SortConfig(
            default=SortEntry(
                field='_score',
                display_name='Score',
                order=SortOrder.DESC
            ),
            options=[
                SortEntry(
                    field='_score',
                    display_name='Score',
                    order=SortOrder.DESC
                ),
                SortEntry(
                    field='release_date',
                    display_name='Release Date',
                    order=SortOrder.ASC
                ),
                SortEntry(
                    field='metadata.budget',
                    display_name='Budget',
                    order=SortOrder.DESC
                )
            ]
        ),
        page_size=PageSizeConfig(
            default=25,
            options=[25, 50, 100]
        )
    )
)
  • No labels