querysource 4.1.2__tar.gz → 4.1.3__tar.gz

{querysource-4.1.2 → querysource-4.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: querysource
-Version: 4.1.2
+Version: 4.1.3
 Summary: Aiohttp web service for querying several databases easily
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: BSD-3-Clause

{querysource-4.1.2 → querysource-4.1.3}/querysource/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '4.1.3.dev0+g02d9a887a.d20260407'
-__version_tuple__ = version_tuple = (4, 1, 3, 'dev0', 'g02d9a887a.d20260407')
+__version__ = version = '4.1.4.dev0+g3b71f7144.d20260408'
+__version_tuple__ = version_tuple = (4, 1, 4, 'dev0', 'g3b71f7144.d20260408')
 
-__commit_id__ = commit_id = 'g02d9a887a'
+__commit_id__ = commit_id = 'g3b71f7144'

{querysource-4.1.2 → querysource-4.1.3}/querysource/queries/multi/operators/Join.py

@@ -6,6 +6,7 @@ from ....exceptions import (
     DriverError,
     QueryException
 )
+from ....types.dt.filters import create_filter
 from .abstract import AbstractOperator
 
 
@@ -16,6 +17,14 @@ class Join(AbstractOperator):
         self._left = kwargs.pop('left', None)
         # Right Operator
         self._right = kwargs.pop('right', None)
+        # Join Conditions (column-to-column comparisons applied after merge)
+        self._join_conditions = kwargs.pop('join_conditions', None)
+
+        # Convert 'on' to 'using' for backward compatibility
+        # (allows JSON: "on": "user_id" to work)
+        if 'on' in kwargs:
+            kwargs['using'] = kwargs.pop('on')
+
         super(Join, self).__init__(data, **kwargs)
         self.data = data
 
@@ -113,6 +122,79 @@ class Join(AbstractOperator):
                 f"Unknown JOIN error {err!s}"
             ) from err
 
+    def _apply_join_conditions(self, df: DataFrame) -> DataFrame:
+        """Apply join conditions (column-to-column filters) to merged DataFrame.
+
+        Reuses the filter expression builder from filters module.
+        Join conditions are semantically part of the join, applied immediately
+        after the merge.
+
+        Args:
+            df: The merged DataFrame
+
+        Returns:
+            Filtered DataFrame with join conditions applied
+
+        Raises:
+            QueryException: If a column doesn't exist or condition is invalid
+        """
+        if not self._join_conditions:
+            return df
+
+        try:
+            # Convert join_conditions to filter format expected by create_filter
+            # join_conditions format: [{"left": col_a, "expression": ">=", "right": col_b}, ...]
+            # create_filter format: [{"column": col, "expression": ">=", "value": {"$column": col_b}}, ...]
+
+            filter_specs = []
+            for condition in self._join_conditions:
+                left_col = condition.get('left')
+                expression = condition.get('expression', '==')
+                right_col = condition.get('right')
+
+                if not left_col or not right_col:
+                    raise QueryException(
+                        "Join condition must have 'left', 'expression', and 'right' fields"
+                    )
+
+                # Transform to Filter format
+                filter_specs.append({
+                    'column': left_col,
+                    'expression': expression,
+                    'value': {'$column': right_col}
+                })
+
+            # Use create_filter to build the conditions
+            conditions = create_filter(filter_specs, df)
+
+            # Apply conditions with AND logic
+            condition_str = " & ".join(conditions)
+            df_filtered = df.loc[eval(condition_str)]
+
+            if df_filtered is None:
+                raise DataNotFound(
+                    "Error applying join conditions"
+                )
+
+            # Note: empty DataFrame after conditions is valid, not an error
+            # (a valid join might produce no rows based on the conditions)
+
+            logging.debug(
+                f"Applied {len(self._join_conditions)} join condition(s), "
+                f"result: {len(df_filtered)} rows"
+            )
+
+            return df_filtered
+
+        except DataNotFound:
+            raise
+        except QueryException:
+            raise
+        except Exception as err:
+            raise QueryException(
+                f"Error applying join conditions: {err!s}"
+            ) from err
+
     def _join(self, df1: DataFrame, df2: DataFrame, **kwargs):
         try:
             df = self._pd.merge(
@@ -140,5 +222,12 @@ class Join(AbstractOperator):
             inplace=True
         )
         df.reset_index(drop=True)
-        self._print_info(df)
+
+        # Apply join conditions if provided
+        if self._join_conditions:
+            df = self._apply_join_conditions(df)
+
+        # Print info only if DataFrame has data (avoid IndexError on empty frames)
+        if not df.empty:
+            self._print_info(df)
         return df

{querysource-4.1.2 → querysource-4.1.3}/querysource/version.py

@@ -6,7 +6,7 @@ __description__ = (
     'QuerySource Query parser and generator.'
     'Supports SQL, NoSQL, MongoDB, Cassandra, Elasticsearch, etc.'
 )
-__version__ = '4.1.2'
+__version__ = '4.1.3'
 __url__ = 'https://github.com/phenobarbital/querysource'
 __copyright__ = 'Copyright (c) 2018-2025 Jesus Lara'
 __author__ = 'Jesus Lara'

{querysource-4.1.2 → querysource-4.1.3}/querysource.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: querysource
-Version: 4.1.2
+Version: 4.1.3
 Summary: Aiohttp web service for querying several databases easily
 Author-email: Jesus Lara <jesuslarag@gmail.com>
 License: BSD-3-Clause

{querysource-4.1.2 → querysource-4.1.3}/querysource.egg-info/SOURCES.txt

@@ -1261,6 +1261,7 @@ tests/test_arangodb_parser.py
 tests/test_column_filters.py
 tests/test_elastic_parser.py
 tests/test_eval.py
+tests/test_join_conditions.py
 tests/test_join_with_column_filter.py
 tests/test_rss.py
 tests/test_rust_parsers.py

querysource-4.1.3/tests/test_join_conditions.py

@@ -0,0 +1,351 @@
+"""Unit tests for Join operator with join_conditions."""
+import pandas as pd
+import pytest
+from querysource.queries.multi.operators.Join import Join
+from querysource.exceptions import QueryException, DataNotFound
+
+
+class TestJoinWithJoinConditions:
+    """Test suite for join_conditions feature in Join operator."""
+
+    def setup_method(self):
+        """Setup test DataFrames."""
+        self.calls_df = pd.DataFrame({
+            'id_llamada': [1, 2, 3, 4],
+            'usuario_id': [100, 101, 100, 102],
+            'call_date': pd.to_datetime([
+                '2024-01-15', '2024-01-20', '2024-02-01', '2024-02-10'
+            ]),
+            'call_duration': [45, 30, 60, 25],
+        })
+
+        self.podcasts_df = pd.DataFrame({
+            'id_podcast': [200, 201, 202, 203],
+            'usuario_id': [100, 101, 100, 102],
+            'podcast_date': pd.to_datetime([
+                '2024-01-10', '2024-01-25', '2024-02-02', '2024-02-05'
+            ]),
+            'podcast_duration': [90, 45, 60, 120],
+        })
+
+    def test_join_with_single_condition(self):
+        """Test join with a single join_condition."""
+        # Join: calls x podcasts on user_id
+        # WHERE: call_date >= podcast_date
+
+        join_op = Join(
+            data={
+                'calls': self.calls_df.copy(),
+                'podcasts': self.podcasts_df.copy()
+            },
+            left='calls',
+            right='podcasts',
+            on='usuario_id',
+            type='inner',
+            join_conditions=[
+                {
+                    'left': 'call_date',
+                    'expression': '>=',
+                    'right': 'podcast_date'
+                }
+            ]
+        )
+
+        result = join_op.data
+        import asyncio
+        output = asyncio.run(join_op.run())
+
+        # Get the merged dataframe
+        df = list(output.values())[0] if isinstance(output, dict) else output
+
+        # All rows should have call_date >= podcast_date
+        for _, row in df.iterrows():
+            assert row['call_date'] >= row['podcast_date']
+
+    def test_join_with_multiple_conditions(self):
+        """Test join with multiple join_conditions (AND logic)."""
+        join_op = Join(
+            data={
+                'calls': self.calls_df.copy(),
+                'podcasts': self.podcasts_df.copy()
+            },
+            left='calls',
+            right='podcasts',
+            on='usuario_id',
+            type='inner',
+            join_conditions=[
+                {
+                    'left': 'call_date',
+                    'expression': '>=',
+                    'right': 'podcast_date'
+                },
+                {
+                    'left': 'call_duration',
+                    'expression': '<',
+                    'right': 'podcast_duration'
+                }
+            ]
+        )
+
+        import asyncio
+        output = asyncio.run(join_op.run())
+        df = list(output.values())[0] if isinstance(output, dict) else output
+
+        # All rows should satisfy BOTH conditions
+        for _, row in df.iterrows():
+            assert row['call_date'] >= row['podcast_date']
+            assert row['call_duration'] < row['podcast_duration']
+
+    def test_join_conditions_reduce_result_set(self):
+        """Test that join_conditions reduce the result size."""
+        # Without conditions
+        join_op_no_cond = Join(
+            data={
+                'calls': self.calls_df.copy(),
+                'podcasts': self.podcasts_df.copy()
+            },
+            left='calls',
+            right='podcasts',
+            on='usuario_id',
+            type='inner'
+        )
+
+        import asyncio
+        output_no_cond = asyncio.run(join_op_no_cond.run())
+        df_no_cond = list(output_no_cond.values())[0] if isinstance(output_no_cond, dict) else output_no_cond
+        rows_without_conditions = len(df_no_cond)
+
+        # With conditions
+        join_op_with_cond = Join(
+            data={
+                'calls': self.calls_df.copy(),
+                'podcasts': self.podcasts_df.copy()
+            },
+            left='calls',
+            right='podcasts',
+            on='usuario_id',
+            type='inner',
+            join_conditions=[
+                {
+                    'left': 'call_date',
+                    'expression': '>=',
+                    'right': 'podcast_date'
+                }
+            ]
+        )
+
+        output_with_cond = asyncio.run(join_op_with_cond.run())
+        df_with_cond = list(output_with_cond.values())[0] if isinstance(output_with_cond, dict) else output_with_cond
+        rows_with_conditions = len(df_with_cond)
+
+        # Conditions should reduce or equal the result set
+        assert rows_with_conditions <= rows_without_conditions
+
+    def test_join_conditions_all_operators(self):
+        """Test join_conditions with all comparison operators."""
+        operators = ['<', '<=', '>', '>=', '==', '!=']
+
+        for op in operators:
+            join_op = Join(
+                data={
+                    'calls': self.calls_df.copy(),
+                    'podcasts': self.podcasts_df.copy()
+                },
+                left='calls',
+                right='podcasts',
+                on='usuario_id',
+                type='inner',
+                join_conditions=[
+                    {
+                        'left': 'call_duration',
+                        'expression': op,
+                        'right': 'podcast_duration'
+                    }
+                ]
+            )
+
+            import asyncio
+            output = asyncio.run(join_op.run())
+
+            # Should not crash and return a DataFrame
+            assert output is not None
+
+    def test_join_without_conditions_unchanged(self):
+        """Test that join without conditions works as before."""
+        join_op = Join(
+            data={
+                'calls': self.calls_df.copy(),
+                'podcasts': self.podcasts_df.copy()
+            },
+            left='calls',
+            right='podcasts',
+            on='usuario_id',
+            type='inner'
+            # No join_conditions specified
+        )
+
+        import asyncio
+        output = asyncio.run(join_op.run())
+
+        # Should return result without filtering
+        assert output is not None
+
+    def test_join_condition_nonexistent_column(self):
+        """Test that join_conditions validate column existence."""
+        join_op = Join(
+            data={
+                'calls': self.calls_df.copy(),
+                'podcasts': self.podcasts_df.copy()
+            },
+            left='calls',
+            right='podcasts',
+            on='usuario_id',
+            type='inner',
+            join_conditions=[
+                {
+                    'left': 'nonexistent_column',
+                    'expression': '>=',
+                    'right': 'podcast_date'
+                }
+            ]
+        )
+
+        import asyncio
+        with pytest.raises(QueryException):
+            asyncio.run(join_op.run())
+
+    def test_join_condition_missing_fields(self):
+        """Test that join_conditions require left, expression, and right."""
+        join_op = Join(
+            data={
+                'calls': self.calls_df.copy(),
+                'podcasts': self.podcasts_df.copy()
+            },
+            left='calls',
+            right='podcasts',
+            on='usuario_id',
+            type='inner',
+            join_conditions=[
+                {
+                    'left': 'call_date',
+                    # Missing 'expression' and 'right'
+                }
+            ]
+        )
+
+        import asyncio
+        with pytest.raises(QueryException):
+            asyncio.run(join_op.run())
+
+    def test_join_conditions_semantic_clarity(self):
+        """Test that join_conditions document the intent clearly."""
+        # This is more of a documentation test
+        # The intent is clear: join conditions are PART OF the join, not post-filtering
+
+        join_config = {
+            'left': 'calls',
+            'right': 'podcasts',
+            'on': 'usuario_id',
+            'join_conditions': [
+                {
+                    'left': 'call_date',
+                    'expression': '>=',
+                    'right': 'podcast_date'
+                }
+            ]
+        }
+
+        # The intent is crystal clear:
+        # "Join calls and podcasts on user_id WHERE call_date >= podcast_date"
+        assert 'join_conditions' in join_config
+        assert join_config['join_conditions'][0]['expression'] == '>='
+
+
+class TestJoinConditionsVsFilter:
+    """Compare join_conditions vs separate Filter operator."""
+
+    def setup_method(self):
+        """Setup test data."""
+        self.df1 = pd.DataFrame({
+            'id': [1, 2, 3],
+            'key': ['a', 'b', 'a'],
+            'val1': [10, 20, 30],
+        })
+
+        self.df2 = pd.DataFrame({
+            'key': ['a', 'b', 'a'],
+            'val2': [5, 15, 25],
+        })
+
+    def test_join_conditions_semantic_equivalence(self):
+        """Test that join_conditions produce same result as Join + Filter.
+
+        Note: Both should produce identical results, but join_conditions
+        communicate intent more clearly.
+        """
+        # Using join_conditions
+        join_op = Join(
+            data={
+                'table1': self.df1.copy(),
+                'table2': self.df2.copy()
+            },
+            left='table1',
+            right='table2',
+            on='key',
+            type='inner',
+            join_conditions=[
+                {
+                    'left': 'val1',
+                    'expression': '>',
+                    'right': 'val2'
+                }
+            ]
+        )
+
+        import asyncio
+        output = asyncio.run(join_op.run())
+        df_with_conditions = list(output.values())[0] if isinstance(output, dict) else output
+
+        # Both approaches should produce result where val1 > val2
+        for _, row in df_with_conditions.iterrows():
+            assert row['val1'] > row['val2']
+
+    def test_join_conditions_range_check(self):
+        """Test range checking with multiple join_conditions."""
+        df_ranges = pd.DataFrame({
+            'id': [1, 2, 3, 4],
+            'value': [15, 25, 35, 45],
+            'min_allowed': [10, 20, 30, 40],
+            'max_allowed': [20, 30, 40, 50],
+        })
+
+        join_op = Join(
+            data={
+                'data': df_ranges.copy(),
+                'dummy': pd.DataFrame({'id': [1]}),  # Dummy for join
+            },
+            left='data',
+            right='dummy',
+            on='id',
+            type='inner',
+            join_conditions=[
+                {
+                    'left': 'value',
+                    'expression': '>=',
+                    'right': 'min_allowed'
+                },
+                {
+                    'left': 'value',
+                    'expression': '<=',
+                    'right': 'max_allowed'
+                }
+            ]
+        )
+
+        import asyncio
+        output = asyncio.run(join_op.run())
+        df = list(output.values())[0] if isinstance(output, dict) else output
+
+        # All values should be within range
+        for _, row in df.iterrows():
+            assert row['min_allowed'] <= row['value'] <= row['max_allowed']