From 5714848da313fb699a6f6dc789cb84eaba913715 Mon Sep 17 00:00:00 2001 From: Lassaux Nicolas Date: Sun, 10 Dec 2023 13:04:42 +0100 Subject: [PATCH 1/2] Update 4_extending.rst Added a section dedicated to using a custom operator --- docs/4_extending.rst | 49 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/docs/4_extending.rst b/docs/4_extending.rst index 02c204ea..28adb73f 100644 --- a/docs/4_extending.rst +++ b/docs/4_extending.rst @@ -74,3 +74,52 @@ Similarly analytic functions can be defined by extending ``pypika.terms.Analytic SELECT ROW_NUMBER() OVER(PARTITION BY "foo" ORDER BY "date") FROM "abc" +Operators not included in PyPika +"""""""""""""""""""""""""""""""""""" + +PyPika may not include certain operators used in SQL, such as the ``<->``, ``<#>`` or ``<=>`` operators often used in extensions. To incorporate these operators, you can utilize a custom ``ArithmeticExpression`` from ``pypika.terms``. + +Custom Operator: ``<->`` for Distance Calculation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +For instance, consider a scenario where you want to use the ``<->`` operator in an ``ORDER BY`` clause for geographic distance calculation. You can define this operator using a custom ``ArithmeticExpression``. + +.. code-block:: python + + from pypika import CustomFunction, Field, Query + from pypika.terms import ArithmeticExpression + + # Wrapper class for the custom operator + class CustomOperator: + value: str = "<->" # Define your operator here + + # Custom SQL functions if needed + ST_SetSRID = CustomFunction("ST_SetSRID", ["geometry", "srid"]) + ST_MakePoint = CustomFunction("ST_MakePoint", ["longitude", "latitude"]) + + # Preparing the operands + left_operand = ST_SetSRID(ST_MakePoint(Field("longitude"), Field("latitude")), 4326) + right_operand = Field("point") + + # Creating the custom ArithmeticExpression + orderby_expression = ArithmeticExpression(CustomOperator, left_operand, right_operand) + +Using the Custom Operator in a Query +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With the custom operator defined, you can now incorporate it into your PyPika queries. For example: + +.. code-block:: python + + # Constructing the query with the custom ORDER BY clause + query = Query.from_("house").select("id").orderby(orderby_expression) + + # The resulting SQL query will be: + # SELECT "id" FROM "house" ORDER BY ST_SetSRID(ST_MakePoint("longitude", "latitude"), 4326) <-> "point" + +Adapting to Other Operators +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This method is not limited to the ``<->`` operator. You can adapt it for any other operator by changing the ``value`` in the ``CustomOperator`` class. This allows for a flexible approach to integrate various operators that are not natively supported in PyPika. + + From 0ff90acd8436546fdfba01f2ae2ec48165d8379f Mon Sep 17 00:00:00 2001 From: Lassaux Nicolas Date: Sun, 10 Dec 2023 13:12:08 +0100 Subject: [PATCH 2/2] Update 4_extending.rst Simplify the example --- docs/4_extending.rst | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/docs/4_extending.rst b/docs/4_extending.rst index 28adb73f..ee58909b 100644 --- a/docs/4_extending.rst +++ b/docs/4_extending.rst @@ -86,20 +86,16 @@ For instance, consider a scenario where you want to use the ``<->`` operator in .. code-block:: python - from pypika import CustomFunction, Field, Query + from pypika import Field, Query from pypika.terms import ArithmeticExpression # Wrapper class for the custom operator class CustomOperator: value: str = "<->" # Define your operator here - # Custom SQL functions if needed - ST_SetSRID = CustomFunction("ST_SetSRID", ["geometry", "srid"]) - ST_MakePoint = CustomFunction("ST_MakePoint", ["longitude", "latitude"]) - # Preparing the operands - left_operand = ST_SetSRID(ST_MakePoint(Field("longitude"), Field("latitude")), 4326) - right_operand = Field("point") + left_operand = Field("left_operand_field") + right_operand = Field("right_operand_field") # Creating the custom ArithmeticExpression orderby_expression = ArithmeticExpression(CustomOperator, left_operand, right_operand) @@ -112,10 +108,10 @@ With the custom operator defined, you can now incorporate it into your PyPika qu .. code-block:: python # Constructing the query with the custom ORDER BY clause - query = Query.from_("house").select("id").orderby(orderby_expression) + query = Query.from_("your_table").select("your_columns").orderby(orderby_expression) - # The resulting SQL query will be: - # SELECT "id" FROM "house" ORDER BY ST_SetSRID(ST_MakePoint("longitude", "latitude"), 4326) <-> "point" + # The resulting SQL query will be similar to: + # SELECT "your_columns" FROM "your_table" ORDER BY "left_operand_field" <-> "right_operand_field" Adapting to Other Operators ^^^^^^^^^^^^^^^^^^^^^^^^^^^