As said before Search API has normalization of parameters and responses, this allows us to make one piece of code making a search request to an connection of type we don't know, to a engine we don't care about, and be sure it will work.
To ease the process of creating generic request, Search API has different classes with well defined parameters
This request is one of the parameters expected by engine methods (search, multi_search, async_search and knn_search). SearchRequest holds all the possible parameters this methods could need, the implementation of this parameters depend on the engine specific implementation, and not all parameters are shared amongst all the methods
Property | Description | Default | Type | Required |
---|---|---|---|---|
q | Query String | "*" | string | No |
query | Accepts the search query structure in the specific engine's format | object | No | |
knn | Accepts the knn search structure in the the specific engine's format | object | No | |
rescore | The query rescorer executes a second query only on the Top-K results returned. Expected in the specific engine's format | object | No | |
size | Defines the number of hits to return | integer (minimum: 0) | No | |
start | Starting document offset. Needs to be non-negative | integer (minimum: 0) | No | |
scroll | Period to retain the search context for scrolling | string | No | |
sort | Engine string definition or generic SortEntry defining the sort order | array of objects | No | |
fetch_fields | List of fields to return in the response based on field values | array of strings | No | |
default_operator | The default operator for the query string query: AND or OR | "or" | string | No |
highlight | Highlighters enable you to get highlighted snippets from one or more fields in your search results so you can show users where the query matches are | object | No | |
filters | Tuple of engine-specific filters. The tuple must contain optional_negated_filters, optional_filters, required_negated_filters, required_filters | object | No | |
agg_filters | Tuple of engine-specific filters. The tuple must contain optional_negated_filters, optional_filters, required_negated_filters, required_filters | object | No | |
aggs | List of engine-specific aggregation implementations | object | No | |
exclude_fields | List of fields to exclude in the response based on field values | array of strings | No |
If you have a keen eye you notice several parameters are simple object types, opening up to a wide variety of options what it can receive, all this options are expecting engine specific format. This was done on propurse to allow the developer to tweak with the queries before sending them to the engine, to compensate for this non-agnostic approach Search API has agnostic tools
For the string parameter q, one approach available is the use of PyQPL, this library can translate query string to engine specific queries, here an example
from app.rest import connection_manager from pyqpl.parser import QPLParser from pyqpl.qpl import QPLOptions from pyqpl.translator import ElasticsearchTranslator, OpensearchTranslator from models.engines import EngineTypes # Get the conneciton_manager for access to the connection from app.rest import connection_manager # Get engine by name engine = connection_manager.get_engine(name=engine_name) # Based on the engine type, select the QPL Translator to use if engine.engine_type is EngineTypes.ELASTIC: translator = ElasticsearchTranslator() elif engine.engine_type is EngineTypes.OPENSEARCH: translator = OpensearchTranslator() # Create the QPL parser based on the provided configuration qpl_parser = QPLParser(options=qpl_config) # Use the parser to parse the string in the parameter q # Use the translator to transforma the QPLQuery from the parser to an engine specific format query = translator.to_engine_query(qpl_parser.parse_query(data=q))
This method allows you to have access to the
request: SearchRequest = SearchRequest( q=q, query=query, knn=knn, size=10, start=0, fetch_fields=['content', 'title'], exclude_fields=['date'], scroll=None, sort=SortEntry(field='title', order=SortOrder.ASC), default_operator=BoolOperation.OR, highlight=highlight, filters=filters, agg_filters=agg_filters, aggs=aggs, ) response = engine.search(index='my_index', data=request) if isinstance(response, ErrorResponse): raise ConnectionError(f'Error {response.status_code}) {response.error}') return response
Property | Description | Type | Required |
---|---|---|---|
field | Name of the field which will be used for sorting | string | Yes |
display_name | Display name for this sort entry. Only applicable for the user interface | string | No |
order | Sort order to be used. It can be one of the predefined SortOrder values or a custom object with additional properties | string or object | Yes |
An enumeration.
Value | Description |
---|---|
asc | Ascending sort order |
desc | Descending sort order |
Property | Description | Default | Type | Required |
---|---|---|---|---|
should_not | Filter which will act as a boolean operator NOR | [] | array of objects | No |
should | Filter which will act as a boolean operator OR | [] | array of objects | No |
must_not | Filter which will act as a boolean operator NAND | [] | array of objects | No |
must | Filter which will act as a boolean operator AND | [] | array of objects | No |
post_should_not | Filter which will act as a boolean operator NOR | [] | array of objects | No |
post_should | Filter which will act as a boolean operator OR | [] | array of objects | No |
post_must_not | Filter which will act as a boolean operator NAND | [] | array of objects | No |
post_must | Filter which will act as a boolean operator AND | [] | array of objects | No |