The Operator class is a versatile Python class that serves as a search engine agnostic query object. It stores all the information about a user query, allowing you to build complex query structures. This class is designed to be extensible and flexible, making it easy to create custom operators by inheriting from it.

Class Overview

Class Signature

class Operator(Generic[QPLOptionsType], metaclass=ABCMeta)

Constructor

The Operator class constructor initializes an instance of the class.

def __init__( self, type_: Union[str, OperatorType], operands: OperandOrOperands, options: QPLOptionsType, parent: Operator = None, boost: float = 1, fields: FIELDS_CONFIG_TYPE = None, slop: float = -1, **kwargs )



  • type_: The type of the query. It can be a string or an instance of the OperatorType enum.

  • operands: The operands of the query. It can be a single operand or a list of operands.

  • options: The options for the query.

  • parent: The parent query object. (Default: None)

  • boost: The boost value for the query. (Default: 1)

  • fields: The fields to be used when matching terms, phrases, spans, etc. (Default: None)

  • slop: The slop value for the query. (Default: -1)

  • kwargs: Additional keyword arguments.

Class Details

Context Class

The Operator class includes a nested Context class that represents the context of an operator. The Context class is a Pydantic BaseModel that provides useful information about the operator's current situation, such as whether it is inside a span query or the fields to be used when matching terms. The Context class has the following attributes:

  • in_span: Indicates if the operator is inside a span query. (Default: False)

  • minimum_or_match: Specifies the minimum or match value. (Default: 1)

  • fields: Specifies the fields to be used when matching terms, phrases, spans, etc. (Default: [])

Properties

The Operator class provides several properties that allow access to different aspects of the query:

  • ctx: Retrieves the context in which the operator is currently in, taking into account the context of its parent.

  • self_ctx: Retrieves the context in which the operator is currently in alone.

  • fields_or_defaults: Returns the fields from either the query declaration or the QPLOptions.

  • date_fields_or_defaults: Returns the date fields from either the query declaration or the QPLOptions.

  • range_fields_or_defaults: Returns the range fields from either the query declaration or the QPLOptions.

Methods

The Operator class provides various methods for manipulating and working with query objects:

  • update_context(ctx: Context): This method is meant to be overwritten in subclasses. It allows you to update the operator's context by providing a Context object that reflects the changes you want to make.

  • _flatten_op(): This method flattens nested boolean queries if any of the children shares the same type_, fields, and boost values of the current query.

  • _optimize(): This method optimizes the current query by merging multiple match queries into a single one containing multiple words, flattening nested boolean queries, and collapsing unnecessary query objects created by Lark.

  • _post_optimize(): This method is executed after the optimization process. It checks that all operands have their parent set to the current query.

  • add_operands(operands: OperandOrOperands): Adds one or more operands to the query.

  • add_operand(operand: OperatorOrStr): Adds a single operand to the query.

  • fields(*fields: str): Maps string field names to QPLFields and stores them in the context.

  • __str__(): Returns the string representation of the operator.

  • get_fields_str(): Returns a string representing the available fields in the context.

  • get_boost_str(): Returns a string representing the assigned boost.

  • get_slop_str(): Returns a string representing the assigned slop.

  • to_string(): Generates a string representation of the operator.

  • __op_to_string(operand) -> str: Returns the string representation of a query operand. Used for printing a query object.

  • factory(...) -> Operator: A factory method that generates a type-specific operator based on the provided parameters.

    The factory method should not be overwritten, since this could reflect the construction of the entire query

Customization

To create a subclass that inherits from the Operator class and customize its behavior, you can override specific methods to fit your needs. Here is a summary of the methods that you can overwrite:

  • update_context(self, ctx: Context): Override this method to update the operator's context. You can modify the context attributes or perform additional operations based on your requirements.

  • _optimize(self): Override this method to customize the optimization process. You can modify how match queries are merged, handle specific query types differently, or add additional optimizations.

  • _post_optimize(self): Override this method to define post-optimization operations. You can perform additional checks, modifications, or clean-up steps on the query structure.

  • add_operand(self, operand: OperatorOrStr): Override this method to customize how a single operand is added to the query. You can handle different operand types or perform additional validations. 

    The method add_operands, implements this method to add each operand individually

By overriding these methods, you can adapt the Operator class to suit your specific requirements and create custom query objects that align with your search engine or application's needs.

These are the method we recommend to modify when implementing a new operator


Example Usage

Here's an example of how you can create a custom subclass inheriting from the Operator class and override some of its methods:

from pyqpl.qpl import Operator

class CustomOperator(Operator):
    def update_context(self, ctx: Context):
        # Custom logic to update the operator's context
        pass
    
    def _optimize(self):
        # Custom logic for query optimization
        pass
    
    def _post_optimize(self):
        # Custom logic after query optimization
        pass
    
    def add_operand(self, operand: OperatorOrStr):
        # Custom logic for adding a single operand
        pass

By overriding these methods, you can define your own behavior and extend the functionality of the Operator class to meet your specific needs when creating custom query objects.

  • No labels