sql-blocks 1.25.13__tar.gz → 1.25.51__tar.gz

{sql_blocks-1.25.13/sql_blocks.egg-info → sql_blocks-1.25.51}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sql_blocks
-Version: 1.25.13
+Version: 1.25.51
 Summary: Allows you to create objects for parts of SQL query commands. Also to combine these objects by joining them, adding or removing parts...
 Home-page: https://github.com/julio-cascalles/sql_blocks
 Author: Júlio Cascalles
@@ -15,6 +15,10 @@ License-File: LICENSE
 
 # SQL_Blocks
 
+## _SQL_Blocks_ is useful for building complex SQL commands through smaller query blocks:
+
+---
+
 ### 1 - You can assemble a simple object that will then be converted into an SQL command:
 
 > a = Select('Actor') # --> SELECT * FROM Actor act
@@ -52,6 +56,12 @@ You can specify your own alias:  `a = Select('Actor a')`
 ...should return: 
 **SELECT extract(year from due_date) as YEAR_ref...**
 
+Possible tags in ExpressionField:
+* {f} - The field name;
+* {af} - The field name preceded by the table alias;
+    > Can be written as {a.f} or %
+* {t} - The table name;
+* {a} - Only the table alias.
 ---
 
 ### 3 - To set conditions, use **Where**:
@@ -67,6 +77,16 @@ You can specify your own alias:  `a = Select('Actor a')`
 3.1 -- If you want to filter the field on a range of values:
 
 `a = Select( 'Actor a', age=Between(45, 69) )`
+...but if it is a time slot within the same day, you can do it like this:
+`Select(..., event_date=SameDay("2024-10-03"))`
+This results in
+```
+    SELECT ...
+    WHERE
+        event_date >= '2024-10-03 00:00:00' AND
+        event_date <= '2024-10-03 23:59:59'
+```
+---
 
 3.2 -- Sub-queries:
 ```
@@ -97,8 +117,10 @@ query = Select('Movie m', title=Field,
         genre=eq("Sci-Fi"),
         awards=contains("Oscar")
     )
+    AND=Options(
+        ..., name=startswith('Chris')
+    )
 ```
-> Could be AND=Options(...)
 
 3.4 -- Negative conditions use the _Not_ class instead of _Where_
 ```
@@ -110,6 +132,16 @@ based_on_book=Not.is_null()
 hash_tag=inside(['space', 'monster', 'gore'])
 ```
 
+3.6 -- Combining ExpressionField with Where condition:
+* The **formula** method allows you to write an expression as a condition:
+```
+query=Select(
+    'Folks f2',
+    id=Where.formula('({af} = a.father OR {af} = a.mother)')
+)
+```
+> Results: `WHERE...f2.id = a.father OR f2.id = a.mother`
+
 ---
 ### 4 - A field can be two things at the same time:
 
@@ -138,6 +170,35 @@ FROM
     JOIN Cast c ON (a.cast = c.id)    
 ```
 
+---
+**5.1  Multiple tables without JOIN**
+> Warning: This is **NOT** recommended!  ⛔
+
+
+#### Example:
+    singer = Select(
+        "Singer artist", id=PrimaryKey,
+        name=NamedField('artist_name')
+    )
+    album = Select (
+        "Album album",
+        name=NamedField('album_name'),
+        artist_id=Where.join(singer), #  <===== 👀
+    )
+**>> print(query)**    
+
+    SELECT
+            album.name as album_name,
+            artist.name as artist_name,
+            album.year_recorded
+    FROM
+            Album album
+            ,Singer artist
+    WHERE
+            (album.artist_id = artist.id)
+
+
+
 ---
 ### 6 - The reverse process (parse):
 ```
@@ -258,6 +319,30 @@ m = Select...
 >> **m + c => Ok!**
 
 
+---
+**8.3 Difference between queries**
+```
+    STATUS_DELIVERED_OK = 93
+    orders = Select('orders',
+        customer_id=ForeignKey('customers'),
+        status=eq(STATUS_DELIVERED_OK)
+    )
+    customers = Select('customers'
+        id=PrimaryKey, name=Field
+    )
+    gap = orders - customers
+```
+return _customers without orders_:
+
+    SELECT
+            c.name
+    FROM
+            customers c
+    WHERE
+            NOT c.id IN (
+                SELECT o.customer_id FROM orders o
+                WHERE o.status = 93
+            )
 ---
 
 ### 9 - Comparing objects
@@ -330,6 +415,31 @@ m2 = Select(
         )
     )
 
+10.1 - If the labels used in the CASE are based on ranges of values ​​in sequence, you can use the **Range class**:
+
+        query = Select(
+            'People p',
+            age_group=Range('age',{  # <<---------- 
+                'adult': 50,
+                'teenager': 17,
+                'child': 10,
+                'elderly': 70,
+                'young': 21,
+            })
+        )
+is equivalent to...
+```
+        SELECT
+                CASE
+                    WHEN p.age BETWEEN 0 AND 10 THEN 'child'
+                    WHEN p.age BETWEEN 11 AND 17 THEN 'teenager'
+                    WHEN p.age BETWEEN 18 AND 21 THEN 'young'
+                    WHEN p.age BETWEEN 22 AND 50 THEN 'adult'
+                    WHEN p.age BETWEEN 51 AND 70 THEN 'elderly'
+                END AS age_group
+        FROM
+                People p
+```
 ---
 
 ### 11 - optimize method
@@ -363,6 +473,35 @@ m2 = Select(
 
 > The method allows you to select which rules you want to apply in the optimization...Or define your own rules!
 
+>> NOTE: When a joined table is used only as a filter, it is possible that it can be changed to a sub-query:
+
+    query = Select(
+        'Installments i', due_date=Field,  customer=Select(
+            'Customer c', id=PrimaryKey,
+            name=endswith('Smith')
+        )
+    )
+    print(query)
+    print('-----')
+    query.optimize([RuleReplaceJoinBySubselect])
+    print(query)
+```
+SELECT
+        i.due_date
+FROM
+        Installments i
+        JOIN Customer c ON (i.customer = c.id)
+WHERE
+        c.name LIKE '%Smith'
+-----
+SELECT
+        i.due_date
+FROM
+        Installments i
+WHERE
+        i.customer IN (SELECT c.id FROM Customer c WHERE c.name LIKE '%Smith')
+```
+
 ---
 
 ### 12 - Adding multiple fields at once
@@ -370,7 +509,7 @@ m2 = Select(
     query = Select('post p')
     query.add_fields(
         'user_id, created_at',
-        order_by=True, group_by=True
+        [OrderBy, GroupBy]
     )
 ```
 ...is the same as...
@@ -419,6 +558,7 @@ ORDER BY
 * `^` Put the field in the ORDER BY clause
 * `@` Immediately after the table name, it indicates the grouping field.
 * `$` For SQL functions like **avg**$_field_, **sum**$_field_, **count**$_field_...
+* `*` Sets the primary key field.
 
 
 ---
@@ -520,12 +660,18 @@ It consists of the inverse process of parsing: From a Select object, it returns
 ---
 ### 14 - Window Function
 
-Aggregation functions (Avg, Min, Max, Sum, Count) have the **over** method...
+Aggregation functions (Avg, Min, Max, Sum, Count) -- or Window functions (Lead, Lag, Row_Number, Rank) -- have the **over** method...
 
     query=Select(
         'Enrollment e',
         payment=Sum().over(
-            partition='student_id', order='due_date'
+            student_id=Partition, due_date=OrderBy,
+            # _=Rows(Current(), Following(5)), 
+               # ^^^-------> ROWS BETWEEN CURRENT ROW AND 5 FOLLOWING
+            # _=Rows(Preceding(3), Following()),
+               # ^^^-------> ROWS BETWEEN 3 PRECEDING AND UNBOUNDED FOLLOWING
+            # _=Rows(Preceding(3)) 
+               # ^^^-------> ROWS 3 PRECEDING
         ).As('sum_per_student')
     )
 
@@ -567,3 +713,176 @@ GROUP BY
 ORDER BY
         customer_count
 ```
+---
+### 16 - Function classes
+You may use this functions:
+* SubString
+* Round
+* DateDiff
+* Year
+* Current_Date
+* Avg
+* Min
+* Max
+* Sum
+* Count
+* Lag
+* Lead
+* Row_Number
+* Rank
+* Coalesce
+* Cast
+> Some of these functions may vary in syntax depending on the database.
+For example, if your query is going to run on Oracle, do the following:
+
+`Function.dialect = Dialect.ORACLE`
+
+
+>  Most of this functions you can use nested inside each other.
+*Example:*
+```
+    Select(...
+        event_date=Substring(
+            Cast("CHAR"), 12, 19 
+        ).As('time')
+    )
+```
+Results...
+```
+    SELECT ...
+    SubString(Cast(event_date As char), 12, 19) as time
+```
+
+>> `Function.auto_convert` option (default: True)
+
+- Put Cast(...) when there is a difference between the types of the parameter and the return of the nested function
+```
+birth=Round( DateDiff(Current_Date()) ).As('age')
+```
+...Returns...
+```
+SELECT
+    Round(
+        Cast(Current_Date() - p.birth As FLOAT)
+       /* ^^^  */
+    ) as age
+...
+```
+---
+
+### 17 - CTE and Recursive classes
+
+* **17.1 - _CTE class_**
+```
+    query = Select(
+        'SocialMedia s', post=Count, reaction=Sum, user=GroupBy
+    )
+    print( CTE('Metrics', [query]) )
+```
+The result is...
+```
+    WITH Metrics AS (
+            SELECT Count(s.post), Sum(s.reaction) FROM SocialMedia s GROUP BY user
+    )SELECT * FROM Metrics
+```
+
+* **17.2 - _Recursive class_**
+```
+q1 = Select(
+    'SocialMedia me', name=[ eq(MY_NAME), Field ]
+)
+q2 = Select(
+    'SocialMedia you' name=Field, id=Where.formula('{af} = n.friend')
+)
+print( Recursive('Network', [q1, q2]) )
+```
+The result is...
+```
+WITH RECURSIVE Network AS (
+        SELECT me.name FROM SocialMedia me WHERE 
+        me.name = 'Júlio Cascalles'
+UNION ALL
+        SELECT you.name FROM SocialMedia you , Network n
+        WHERE  you.id = n.friend
+)SELECT * FROM Network
+```
+
+* **17.2.1 - The `create` method** ... parameters :
+    - name: The name of the CTE
+    - pattern: A cypher script that defines the tables used
+    - formula: The format for `Where.formula` method _(*)_
+    - init_value: The value for the condition in the first table
+    - format (optional): If tables are files or internet hiperlinks, you may especify the extension and/or folder...
+> Example: 
+```
+    R = Recursive.create(
+        'Route R', 'Flyght(departure, arrival)',
+        '[2] = R.[1]',  'JFK',  format='.csv'
+    ) #                  ^^^--- Flyghts from JFK airport
+```
+_...Creates a recursive CTE called Route, using Flyght table, where the recursivity condition is Flyght.arrival equals to Route.departure_
+>> (*) -- Note that [1] and [2] refers to first field and second field. 😉
+
+Result:
+
+    WITH RECURSIVE Route AS (
+            SELECT f1.departure, f1.arrival
+            FROM Flyght.csv f1
+            WHERE f1.departure = 'JFK'
+    UNION ALL
+            SELECT f2.departure, f2.arrival
+            FROM Flyght.csv f2
+            , Route R
+            WHERE  f2.arrival = R.departure
+    )SELECT * FROM Route R
+
+**17.2.2 - The `join` method** 
+
+In the previous example, if you add this code...
+`R.join('Airport(*id,name)', 'departure, arrival', format='.csv')`
+
+...The result would be:
+
+    WITH RECURSIVE Route AS (
+        SELECT f1.departure, f1.arrival
+        FROM Flyght.csv f1
+        WHERE f1.departure = 'JFK'
+    UNION ALL
+        SELECT f2.departure, f2.arrival
+        FROM Flyght.csv f2
+        , Route R
+        WHERE  f2.arrival = R.departure
+    )SELECT
+        a1.name, a2.name
+    FROM
+        Route R
+        JOIN Airport.csv a2 ON (R.arrival = a2.id)
+        JOIN Airport.csv a1 ON (R.departure = a1.id)
+
+
+**17.2.3 - The `counter` method** 
+Adds an increment field in queries inside CTE:
+> Examples:
+* `R.counter('stops', 0)` # -- counter starts with 0 and increment +1
+* `R2.counter('generation', 5, '- 1')` # -- for the code below...
+```
+R2 = Recursive.create(
+    'Ancestors a', 'People(id,name,father,mother,birth)',
+    '(% = a.father OR % = a.mother)', 32630, '.parquet'
+)
+```
+...Results:
+
+    WITH RECURSIVE Ancestors AS (
+        SELECT p1.id, p1.name, p1.father, p1.mother, p1.birth,
+        5 AS generation  /* <<---- Most current generation ------------*/
+        FROM People.parquet p1 WHERE p1.id = 32630
+    UNION ALL
+        SELECT p2.id, p2.name, p2.father, p2.mother, p2.birth,
+        (generation- 1) AS generation /* <<-- Previous generation -----*/
+        FROM People.parquet p2 , Ancestors a WHERE  (p2.id = a.father OR p2.id = a.mother)
+    )SELECT * FROM Ancestors a
+
+
+>> Note: Comments added later.
+---