René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Clarify or fix composite filter boolean semantics","articleBody":"## Problem\n\nThe SDK currently exposes filter composition with `\u0026`, `|`, and repeated `.filter()` calls, but the behavior for mixed boolean logic does not preserve the semantics users would reasonably expect from the Python expression.\n\nThis came up while reviewing #22. That PR correctly enables multiple rules on the same field for flat same-field filters, but it also made the broader filter API easier to trust for range and cohort workflows. The remaining issue is that mixed AND/OR expressions can silently serialize differently from the expression a data scientist wrote.\n\n## Repro cases\n\n### Repeated `.filter()` calls after an OR composite\n\nThe query docs say multiple `.filter()` calls are combined with AND logic:\n\n```python\nquery = (\n    model.query()\n    .filter((model.dimensions.status == \"active\") | (model.dimensions.status == \"pending\"))\n    .filter(model.dimensions.status != \"deleted\")\n)\n```\n\nExpected logical shape:\n\n```text\n(status = active OR status = pending) AND status != deleted\n```\n\nCurrent behavior preserves the existing `or` aggregation when appending a single filter, producing the equivalent of:\n\n```text\nstatus = active OR status = pending OR status != deleted\n```\n\nThe relevant path is `Query.filter()` when `self._filters` already exists and the new filter is a `DimensionFilter`.\n\n### Nested boolean expressions flatten precedence\n\nThe docs currently show a complex filter example like:\n\n```python\nf = (\n    (model.dimensions.country == \"USA\") \u0026\n    ((model.dimensions.amount \u003e 1000) | (model.dimensions.priority == \"high\"))\n)\n```\n\nExpected logical shape:\n\n```text\ncountry = USA AND (amount \u003e 1000 OR priority = high)\n```\n\nCurrent behavior flattens the filters into a single aggregation, so the nested precedence is not represented in the serialized payload.\n\n## Why this matters\n\nFor exploratory analysis and notebook workflows, users often write cohort filters, date windows, and exclusion rules in Python expressions. If the SDK silently changes OR/AND semantics, a query can return a materially different population without an obvious failure. That is especially risky for data scientists using this SDK to build analysis datasets.\n\n## Possible resolutions\n\n1. Implement nested composite serialization if the Lightdash API supports nested boolean filter groups.\n2. If the API only supports flat `and`/`or` groups, reject mixed nested expressions early with a clear error.\n3. Update docs to avoid advertising unsupported complex combinations until the behavior is implemented.\n4. Fix repeated `.filter()` calls so they are actually AND-ed, or document the exact current behavior if preserving aggregation is intentional.\n\n## Acceptance criteria\n\n- Mixed `AND`/`OR` filter expressions either serialize with correct precedence or raise an explicit unsupported-operation error.\n- Multiple `.filter()` calls always behave as documented, especially when the first filter is an OR composite.\n- Tests cover:\n  - `(a | b).filter(c)` style chaining through `Query.filter()`.\n  - `a \u0026 (b | c)` nested expression behavior.\n  - The documented complex combination example.\n- `docs/SDK_GUIDE.md` matches the actual supported filter semantics.","author":{"url":"https://github.com/jpetey75","@type":"Person","name":"jpetey75"},"datePublished":"2026-06-16T19:51:56.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/23/python-sdk/issues/23"}