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