From 71731e50dfa9f16b65b5dc44b43a2cac654bf4f3 Mon Sep 17 00:00:00 2001
From: Rafael Rego <rafael.rego@getenter.ai>
Date: Mon, 26 Jan 2026 14:53:30 -0300
Subject: [PATCH] docs(querymate): update join_type documentation

---
 README.md                   | 28 +++++++++++++++++++++++++++-
 docs/source/usage/index.rst |  8 +++++++-
 2 files changed, 34 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 2437dc4..b8cc824 100644
--- a/README.md
+++ b/README.md
@@ -464,7 +464,33 @@ querymate = Querymate(
 results = querymate.run(db, User)
 ```
 
-Note: QueryMate currently uses inner joins for relationships. Root rows without any matching related rows will be filtered out. If you need to include root rows with an empty related list, left outer joins are not yet configurable.
+### Join Types
+
+By default, QueryMate uses inner joins for relationships, excluding root records without matching related rows. Use `join_type` to change this behavior:
+
+```python
+# Inner join (default) - only users with posts
+querymate = Querymate(
+    select=["id", "name", {"posts": ["id", "title"]}],
+)
+results = querymate.run(db, User)
+
+# Left join - all users, posts=[] for those without
+querymate = Querymate(
+    select=["id", "name", {"posts": ["id", "title"]}],
+    join_type="left",
+)
+results = querymate.run(db, User)
+```
+
+Query parameter example:
+```text
+/users?q={"select":["id","name",{"posts":["title"]}],"join_type":"left"}
+```
+
+Available options:
+- `inner` (default): Excludes parent records without children
+- `left` or `outer`: Includes all parent records; children will be `[]` if none exist
 
 ---
 
diff --git a/docs/source/usage/index.rst b/docs/source/usage/index.rst
index c61d1ec..3348ffe 100644
--- a/docs/source/usage/index.rst
+++ b/docs/source/usage/index.rst
@@ -79,9 +79,15 @@ QueryMate accepts query parameters in JSON format through the ``q`` parameter. T
         "limit": 10,
         "offset": 0,
         "select": ["field1", "field2", {"relationship": ["field1", "field2"]}],
-        "group_by": "status"
+        "group_by": "status",
+        "join_type": "left"
     }
 
+The ``join_type`` parameter controls how relationships are joined:
+
+- ``inner`` (default): Excludes parent records without children
+- ``left`` or ``outer``: Includes all parent records; children will be ``[]`` if none exist
+
 For example:
 
 .. code-block:: text