rdt documentation

README.md

@@ -704,7 +704,7 @@ Returns a `conn` and the list of `tablenames` that exist in the database. The me
 
 ### CRUD Operations with Dataloom
 
-In this section of the documentation, we will illustrate how to perform basic `CRUD` operations using `dataloom` on simple `Models`. Please note that in the following code snippets, I will be utilizing `sqlite_loom`. However, it's important to highlight that you can use any `loom` of your choice to follow along.
+In this section of the documentation, we will illustrate how to perform basic `CRUD` operations using `dataloom` on simple `Models`. Please note that in the following code snippets, I will be utilizing `sqlite_loom`, `mysql_loom`, `pg_loom` or `loom` interchangeably. However, it's important to highlight that you can use any `loom` of your choice to follow along.
 
 #### 1. Creating a Record
 
@@ -846,7 +846,7 @@ The `find_many()` method takes in the following arguments:
 
 ##### 3. `find_one()`
 
-Here is an example showing you how you can use `find_by_pk()` locate a single record in the database.
+Here is an example showing you how you can use `find_one()` locate a single record in the database.
 
 ```py
 user = mysql_loom.find_one(
@@ -1040,8 +1040,11 @@ To mitigate the potential risks associated with `delete_bulk()`, follow these gu
    - When calling `delete_bulk()`, make sure to provide a filter to specify the subset of records to be deleted. This helps prevent unintentional deletions.
 
    ```python
-   # Example: Delete records where 'status' is 'inactive'
-   sqlite_loom.delete_bulk(filter={'status': 'inactive'})
+    # Example: Delete records where 'status' is 'inactive'
+    affected_rows = mysql_loom.delete_bulk(
+        instance=User,
+        filters=Filter(column="status",  value='inactive'),
+    )
    ```
 
 2. **Consider Usage When Necessary:**

docs/source/api/qb.rst

@@ -0,0 +1,92 @@
+
+Query Builder
++++++++++++++
+
+``Dataloom`` exposes a method called ``getQueryBuilder``, which allows you to obtain a ``qb`` object. This object enables you to execute SQL queries directly from SQL scripts.
+
+.. code-block:: 
+
+    qb = loom.getQueryBuilder()
+    print(qb) # ? = Loom QB<mysql>
+
+
+The ``qb`` object contains the method called ``run``, which is used to execute SQL scripts or SQL queries.
+
+.. code-block:: 
+
+    ids = qb.run("select id from posts;", fetchall=True)
+    print(ids) # ? = [(1,), (2,), (3,), (4,)]
+
+
+You can also execute SQL files. In the following example, we will demonstrate how you can execute SQL scripts using the ``qb``. Let's say we have an SQL file called ``qb.sql`` which contains the following SQL code:
+
+.. code-block:: SQL
+    -- qb.sql
+
+    SELECT id, title FROM posts WHERE id IN (1, 3, 2, 4) LIMIT 4 OFFSET  1;
+    SELECT COUNT(*) FROM (
+        SELECT DISTINCT `id`
+        FROM `posts`
+        WHERE `id` < 5
+        LIMIT 3 OFFSET 2
+    ) AS subquery;
+
+
+We can use the query builder to execute the SQL as follows:
+
+.. code-block:: 
+
+    with open("qb.sql", "r") as reader:
+        sql = reader.read()
+    res = qb.run(
+        sql,
+        fetchall=True,
+        is_script=True,
+    )
+    print(res)
+
+
+.. tip:: 👍 **Pro Tip:** Executing a script using query builder does not return a result. The result value is always ``None``.
+
+The ``run`` method takes the following as arguments:
+
+.. rst-class:: my-table
+
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| Argument          | Description                                                                              | Type                                                             | Required | Default   |
++===================+==========================================================================================+==================================================================+==========+===========+
+| ``sql``           | SQL query to execute.                                                                    | ``str``                                                          | `Yes`    |           |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``args``          | Parameters for the SQL query.                                                            | ``Any`` or ``None``                                              | ``No``   | ``None``  |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``fetchone``      | Whether to fetch only one result.                                                        | ``bool``                                                         | ``No``   | ``False`` |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``fetchmany``     | Whether to fetch multiple results.                                                       | ``bool``                                                         | ``No``   | ``False`` |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``fetchall``      | Whether to fetch all results.                                                            | ``bool``                                                         | ``No``   | ``False`` |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``mutation``      | Whether the query is a mutation (insert, update, delete).                                | ``bool``                                                         | ``No``   | ``True``  |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``bulk``          | Whether the query is a bulk operation.                                                   | ``bool``                                                         | ``No``   | ``False`` |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``affected_rows`` | Whether to return affected rows.                                                         | ``bool``                                                         | ``No``   | ``False`` |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``operation``     | Type of operation being performed.                                                       | ``'insert'``, ``'update'``, ``'delete'``, ``'read'`` or ``None`` | ``No``   | ``False`` |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``verbose``       | Verbosity level for logging . Set this option to ``0`` if you don't want logging at all. | ``int``                                                          | ``No``   | ``1``     |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+| ``is_script``     | Whether the SQL is a script.                                                             | ``bool``                                                         | ``No``   | ``False`` |
++-------------------+------------------------------------------------------------------------------------------+------------------------------------------------------------------+----------+-----------+
+
+
+Why Use Query Builder?
+----------------------
+
+- The query builder empowers developers to seamlessly execute ``SQL`` queries directly.
+- While Dataloom primarily utilizes ``subqueries`` for eager data fetching on models, developers may prefer to employ JOIN operations, which are achievable through the ``qb`` object.
+
+.. code-block:: 
+    qb = loom.getQueryBuilder()
+    result = qb.run("SELECT * FROM table1 INNER JOIN table2 ON table1.id = table2.table1_id;")
+    print(result)
+  

docs/source/api/tables/index.rst

@@ -11,17 +11,17 @@ Syncing tables involves the process of creating tables from models and saving th
 
 .. rst-class:: my-table
 
-+----------+----------------------------------------------------------------------------------------------------------------------------+-------+---------+
-| Argument | Description                                                                                                                | Type  | Default |
-+==========+============================================================================================================================+=======+=========+
-| models   | A collection or a single instance(s) of your table classes that inherit from the Model class.                              | Model | []      |
-+----------+----------------------------------------------------------------------------------------------------------------------------+-------+---------+
-| drop     | Whether to drop tables during syncing or not.                                                                              | bool  | False   |
-+----------+----------------------------------------------------------------------------------------------------------------------------+-------+---------+
-| force    | Forcefully drop tables during syncing. In mysql this will temporarily disable foreign key checks when dropping the tables. | bool  | False   |
-+----------+----------------------------------------------------------------------------------------------------------------------------+-------+---------+
-| alter    | Alter tables instead of dropping them during syncing or not.                                                               | bool  | False   |
-+----------+----------------------------------------------------------------------------------------------------------------------------+-------+---------+
++------------+----------------------------------------------------------------------------------------------------------------------------+-----------+-----------+
+| Argument   | Description                                                                                                                | Type      | Default   |
++============+============================================================================================================================+===========+===========+
+| ``models`` | A collection or a single instance(s) of your table classes that inherit from the ``Model`` class.                          | ``Model`` | ``[]``    |
++------------+----------------------------------------------------------------------------------------------------------------------------+-----------+-----------+
+| ``drop``   | Whether to drop tables during syncing or not.                                                                              | ``bool``  | ``False`` |
++------------+----------------------------------------------------------------------------------------------------------------------------+-----------+-----------+
+| ``force``  | Forcefully drop tables during syncing. In mysql this will temporarily disable foreign key checks when dropping the tables. | ``bool``  | ``False`` |
++------------+----------------------------------------------------------------------------------------------------------------------------+-----------+-----------+
+| ``alter``  | Alter tables instead of dropping them during syncing or not.                                                               | ``bool``  | ``False`` |
++------------+----------------------------------------------------------------------------------------------------------------------------+-----------+-----------+
 
 .. tip:: 🥇 We recommend you to use ``drop`` or ``force`` if you are going to change or modify ``foreign`` and ``primary`` keys. This is because setting the option ``alter`` does not have an effect on ``primary`` key columns.
 

docs/source/examples/associations/bi_directional.rst

@@ -0,0 +1,83 @@
+4. What about ``bidirectional`` queries?
+++++++++++++++++++++++++++++++++++++++++
+
+In ``Dataloom``, we support bidirectional relations with eager loading on-the-fly. You can query from a ``parent`` to a ``child`` and from a ``child`` to a ``parent``. You just need to know how the relationship is mapped between these two models. In this case, the `has` option is very important in the `Include` class. Here are some examples demonstrating bidirectional querying between `user` and `post`, where the `user` is the parent table and the `post` is the child table in this case.
+
+1. Child to Parent
+==================
+
+Here is an example illustrating how we can query a parent from child table.
+
+.. code-block:: 
+
+    posts_users = mysql_loom.find_many(
+        Post,
+        limit=2,
+        offset=3,
+        order=[Order(column="id", order="DESC")],
+        select=["id", "title"],
+        include=[
+            Include(
+                model=User,
+                select=["id", "username"],
+                has="one",
+                include=[Include(model=Profile, select=["id", "avatar"], has="one")],
+            ),
+            Include(
+                model=Category,
+                select=["id", "type"],
+                order=[Order(column="id", order="DESC")],
+                has="many",
+                limit=2,
+            ),
+        ],
+    )
+    print(posts_users) # ? = [{'id': 1, 'title': 'Hey', 'user': {'id': 1, 'username': '@miller', 'profile': {'id': 1, 'avatar': 'hello.jpg'}}, 'categories': [{'id': 4, 'type': 'sport'}, {'id': 3, 'type': 'tech'}]}]
+
+
+2. Parent to Child
+==================
+
+Here is an example of how we can query a child table from parent table
+
+.. code-block:: 
+
+    user_post = mysql_loom.find_by_pk(
+        User,
+        pk=userId,
+        select=["id", "username"],
+        include=[
+            Include(
+                model=Post,
+                limit=2,
+                offset=3,
+                order=[Order(column="id", order="DESC")],
+                select=["id", "title"],
+                include=[
+                    Include(
+                        model=User,
+                        select=["id", "username"],
+                        has="one",
+                        include=[
+                            Include(model=Profile, select=["id", "avatar"], has="one")
+                        ],
+                    ),
+                    Include(
+                        model=Category,
+                        select=["id", "type"],
+                        order=[Order(column="id", order="DESC")],
+                        has="many",
+                        limit=2,
+                    ),
+                ],
+            ),
+            Include(model=Profile, select=["id", "avatar"], has="one"),
+        ],
+    )
+
+
+    print(user_post) """ ? =
+    {'id': 1, 'username': '@miller', 'user': {'id': 1, 'username': '@miller', 'profile': {'id': 1, 'avatar': 'hello.jpg'}}, 'categories': [{'id': 4, 'type': 'sport'}, {'id': 3, 'type': 'tech'}], 'posts': [{'id': 1, 'title': 'Hey', 'user': {'id': 1, 'username': '@miller', 'profile': {'id': 1, 'avatar': 'hello.jpg'}}, 'categories': [{'id': 4, 'type': 'sport'}, {'id': 3, 'type': 'tech'}]}], 'profile': {'id': 1, 'avatar': 'hello.jpg'}}
+    """
+
+

docs/source/examples/associations/index.rst

@@ -0,0 +1,25 @@
+Associations
+++++++++++++
+
+In dataloom you can create association using the ``foreign-keys`` column during model creation. You just have to specify a single model to have a relationship with another model using the ``ForeignKeyColum``. Just by doing that ``dataloom`` will be able to learn bidirectional relationship between your models. Let's have a look at the following examples:
+
+#. `One to One Association <one_to_one.html>`_ 
+#. `One to Many Association <one_to_n.html>`_ 
+#. `Many to One Association <n_to_one.html>`_ 
+#. `What about bidirectional queries? <bi_directional.html>`_ 
+#. `Self Association <self_relations.html>`_ 
+#. `Many to Many Association <n_to_n.html>`_ 
+
+
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   one_to_one
+   one_to_n
+   n_to_one
+   bi_directional
+   self_relations
+   n_to_n
+