mongo-pipebuilder 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

mongo_pipebuilder/__init__.py

@@ -9,6 +9,6 @@ Author: seligoroff
 
 from mongo_pipebuilder.builder import PipelineBuilder
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __all__ = ["PipelineBuilder"]
 

mongo_pipebuilder/builder.py

@@ -6,15 +6,14 @@ Builder Pattern implementation for safe construction of MongoDB aggregation pipe
 
 Author: seligoroff
 """
+import copy
+import difflib
 import json
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
-# For compatibility with Python < 3.11
-try:
-    from typing import Self
-except ImportError:
-    from typing_extensions import Self
+# For compatibility with Python < 3.11 and mypy with python_version 3.8
+from typing_extensions import Self
 
 
 class PipelineBuilder:
@@ -27,16 +26,16 @@ class PipelineBuilder:
     def match(self, conditions: Dict[str, Any]) -> Self:
         """
         Add a $match stage for filtering documents.
-        
+
         Args:
             conditions: Dictionary with filtering conditions
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If conditions is None or not a dictionary
-            
+
         Example:
             >>> builder.match({"status": "active", "age": {"$gte": 18}})
         """
@@ -48,6 +47,29 @@ class PipelineBuilder:
             self._stages.append({"$match": conditions})
         return self
 
+    def match_expr(self, expr: Dict[str, Any]) -> Self:
+        """
+        Add a $match stage with $expr condition (expression-based filter).
+
+        Args:
+            expr: The expression for $expr (e.g. {"$eq": ["$id", "$$teamId"]}).
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            TypeError: If expr is None or not a dict.
+
+        Example:
+            >>> builder.match_expr({"$eq": ["$id", "$$teamId"]})
+        """
+        if expr is None:
+            raise TypeError("expr cannot be None, use empty dict {} instead")
+        if not isinstance(expr, dict):
+            raise TypeError(f"expr must be a dict, got {type(expr)}")
+        self._stages.append({"$match": {"$expr": expr}})
+        return self
+
     def lookup(
         self,
         from_collection: str,
@@ -58,21 +80,21 @@ class PipelineBuilder:
     ) -> Self:
         """
         Add a $lookup stage for joining with another collection.
-        
+
         Args:
             from_collection: Name of the collection to join with
             local_field: Field in the current collection
             foreign_field: Field in the target collection
             as_field: Name of the field for join results
             pipeline: Optional nested pipeline for filtering
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If pipeline is not None and not a list, or if string fields are not strings
             ValueError: If required string fields are empty
-            
+
         Example:
             >>> builder.lookup(
             ...     from_collection="users",
@@ -90,14 +112,14 @@ class PipelineBuilder:
             raise ValueError("foreign_field must be a non-empty string")
         if not isinstance(as_field, str) or not as_field:
             raise ValueError("as_field must be a non-empty string")
-        
+
         # Validate pipeline
         if pipeline is not None:
             if not isinstance(pipeline, list):
                 raise TypeError(f"pipeline must be a list, got {type(pipeline)}")
             if not all(isinstance(stage, dict) for stage in pipeline):
                 raise TypeError("All pipeline stages must be dictionaries")
-        
+
         lookup_stage: Dict[str, Any] = {
             "from": from_collection,
             "localField": local_field,
@@ -109,19 +131,133 @@ class PipelineBuilder:
         self._stages.append({"$lookup": lookup_stage})
         return self
 
+    def lookup_let(
+        self,
+        from_collection: str,
+        let: Dict[str, Any],
+        pipeline: Union[List[Dict[str, Any]], "PipelineBuilder"],
+        as_field: str,
+    ) -> Self:
+        """
+        Add a $lookup stage with let and pipeline (join by expression, variables from document).
+
+        Args:
+            from_collection: Name of the collection to join with.
+            let: Variables for the subpipeline (available in pipeline as $$key).
+            pipeline: Subpipeline as list of stages or PipelineBuilder (will call .build()).
+            as_field: Name of the field for join results.
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            TypeError: If from_collection, as_field are not strings; if let is not a dict;
+                if pipeline is None or not a list/PipelineBuilder; if pipeline list has non-dict stages.
+            ValueError: If from_collection or as_field are empty; if pipeline list is empty.
+
+        Example:
+            >>> builder.lookup_let(
+            ...     from_collection="teams",
+            ...     let={"teamId": "$idTeam"},
+            ...     pipeline=[{"$match": {"$expr": {"$eq": ["$_id", "$$teamId"]}}}],
+            ...     as_field="team"
+            ... )
+        """
+        if not isinstance(from_collection, str):
+            raise TypeError("from_collection must be a string")
+        if not from_collection:
+            raise ValueError("from_collection must be a non-empty string")
+        if let is None:
+            raise TypeError("let cannot be None")
+        if not isinstance(let, dict):
+            raise TypeError("let must be a dict")
+        if not isinstance(as_field, str):
+            raise TypeError("as_field must be a string")
+        if not as_field:
+            raise ValueError("as_field must be a non-empty string")
+        if pipeline is None:
+            raise TypeError("pipeline cannot be None")
+        if isinstance(pipeline, PipelineBuilder):
+            pipeline = pipeline.build()
+        if not isinstance(pipeline, list):
+            raise TypeError("pipeline must be a list or PipelineBuilder")
+        if not pipeline:
+            raise ValueError("pipeline cannot be empty")
+        if not all(isinstance(stage, dict) for stage in pipeline):
+            raise TypeError("All pipeline stages must be dictionaries")
+
+        lookup_stage: Dict[str, Any] = {
+            "from": from_collection,
+            "let": let,
+            "pipeline": pipeline,
+            "as": as_field,
+        }
+        self._stages.append({"$lookup": lookup_stage})
+        return self
+
+    def union_with(
+        self,
+        coll: str,
+        pipeline: Optional[Union[List[Dict[str, Any]], "PipelineBuilder"]] = None,
+    ) -> Self:
+        """
+        Add a $unionWith stage to combine documents from another collection.
+
+        Merges all documents from the current pipeline with documents from the
+        given collection. If pipeline is provided, it is run on the other
+        collection before merging; you can pass a list of stages or a
+        PipelineBuilder (its .build() is used internally).
+
+        Args:
+            coll: Name of the collection to union with.
+            pipeline: Optional subpipeline (list of stages or PipelineBuilder).
+                Defaults to [].
+
+        Returns:
+            Self for method chaining.
+
+        Raises:
+            TypeError: If coll is not a string; if pipeline is not None and not
+                a list or PipelineBuilder; if pipeline list contains non-dict
+                stages.
+            ValueError: If coll is empty.
+
+        Example:
+            >>> builder.union_with("other_coll")
+            >>> builder.union_with("logs", [{"$match": {"level": "error"}}])
+            >>> sub = PipelineBuilder().match({"source": "x"}).project({"n": 1})
+            >>> builder.union_with("stats", sub)
+        """
+        if not isinstance(coll, str):
+            raise TypeError("coll must be a string")
+        if not coll:
+            raise ValueError("coll must be a non-empty string")
+        pipeline_list: List[Dict[str, Any]] = []
+        if pipeline is not None:
+            if isinstance(pipeline, PipelineBuilder):
+                pipeline_list = pipeline.build()
+            elif isinstance(pipeline, list):
+                if not all(isinstance(stage, dict) for stage in pipeline):
+                    raise TypeError("All pipeline stages must be dictionaries")
+                pipeline_list = pipeline
+            else:
+                raise TypeError("pipeline must be a list or PipelineBuilder")
+        self._stages.append({"$unionWith": {"coll": coll, "pipeline": pipeline_list}})
+        return self
+
     def add_fields(self, fields: Dict[str, Any]) -> Self:
         """
         Add an $addFields stage for adding or modifying fields.
-        
+
         Args:
             fields: Dictionary with new fields and their expressions
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If fields is not a dictionary
-            
+
         Example:
             >>> builder.add_fields({
             ...     "fullName": {"$concat": ["$firstName", " ", "$lastName"]}
@@ -138,16 +274,16 @@ class PipelineBuilder:
     def project(self, fields: Dict[str, Any]) -> Self:
         """
         Add a $project stage for reshaping documents.
-        
+
         Args:
             fields: Dictionary with fields to include/exclude or transform
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If fields is not a dictionary
-            
+
         Example:
             >>> builder.project({"name": 1, "email": 1, "_id": 0})
         """
@@ -162,21 +298,21 @@ class PipelineBuilder:
     def group(self, group_by: Union[str, Dict[str, Any], Any], accumulators: Dict[str, Any]) -> Self:
         """
         Add a $group stage for grouping documents.
-        
+
         Args:
             group_by: Expression for grouping (becomes _id). Can be:
                      - A string (field path, e.g., "$category")
                      - A dict (composite key, e.g., {"category": "$category"})
                      - Any other value (null, number, etc.)
             accumulators: Dictionary with accumulators (sum, avg, count, etc.)
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If accumulators is not a dictionary
             ValueError: If both group_by and accumulators are empty (when group_by is dict/str)
-            
+
         Example:
             >>> builder.group(
             ...     group_by="$category",  # String field path
@@ -189,7 +325,31 @@ class PipelineBuilder:
         """
         if not isinstance(accumulators, dict):
             raise TypeError(f"accumulators must be a dict, got {type(accumulators)}")
-        
+
+        # Guard against a common mistake: passing {"_id": ...} as group_by.
+        # group_by should be the expression that becomes the $group _id.
+        # If users pass {"_id": expr}, MongoDB will create nested _id and later
+        # expressions like $first: "$_id" may fail because $_id becomes an object.
+        if isinstance(group_by, dict) and set(group_by.keys()) == {"_id"}:
+            inner = group_by["_id"]
+            raise ValueError(
+                "Invalid group_by: you passed a dict wrapper {'_id': ...} to PipelineBuilder.group().\n"
+                "PipelineBuilder.group(group_by=...) expects the expression that becomes $group._id.\n"
+                "\n"
+                "Did you mean one of these?\n"
+                f"- builder.group(group_by={inner!r}, accumulators=...)\n"
+                f"- builder.group(group_by={inner!r}, accumulators={{...}})  # same, explicit\n"
+                "\n"
+                "Examples:\n"
+                "- Array _id: builder.group(group_by=['$idSeason', '$idTournament'], accumulators={...})\n"
+                "- Field path: builder.group(group_by='$category', accumulators={...})\n"
+                "- Composite key: builder.group(group_by={'category': '$category'}, accumulators={...})\n"
+                "\n"
+                "Why this matters: {'_id': expr} would create a nested _id object in MongoDB, and later\n"
+                "operators like $first/$last on '$_id' may fail with: "
+                "\"$first's argument must be an array, but is object\"."
+            )
+
         # Validate empty cases
         # group_by can be None, empty string, empty dict, etc. - all are valid in MongoDB
         # But if it's a string and empty, or dict and empty, and accumulators is also empty,
@@ -200,7 +360,7 @@ class PipelineBuilder:
         elif isinstance(group_by, str):
             if not group_by and not accumulators:
                 raise ValueError("group_by and accumulators cannot both be empty")
-        
+
         group_stage = {"_id": group_by, **accumulators}
         self._stages.append({"$group": group_stage})
         return self
@@ -213,19 +373,19 @@ class PipelineBuilder:
     ) -> Self:
         """
         Add an $unwind stage for unwinding arrays.
-        
+
         Args:
             path: Path to the array field
             preserve_null_and_empty_arrays: Preserve documents with null/empty arrays
             include_array_index: Name of the field for array element index
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If path is not a string
             ValueError: If path is empty
-            
+
         Example:
             >>> builder.unwind("tags", preserve_null_and_empty_arrays=True)
             >>> builder.unwind("items", include_array_index="itemIndex")
@@ -234,7 +394,7 @@ class PipelineBuilder:
             raise TypeError(f"path must be a string, got {type(path)}")
         if not path:
             raise ValueError("path cannot be empty")
-        
+
         unwind_stage: Dict[str, Any] = {"path": path}
         if preserve_null_and_empty_arrays:
             unwind_stage["preserveNullAndEmptyArrays"] = True
@@ -246,16 +406,16 @@ class PipelineBuilder:
     def sort(self, fields: Dict[str, int]) -> Self:
         """
         Add a $sort stage for sorting documents.
-        
+
         Args:
             fields: Dictionary with fields and sort direction (1 - asc, -1 - desc)
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If fields is not a dictionary
-            
+
         Example:
             >>> builder.sort({"createdAt": -1, "name": 1})
         """
@@ -270,17 +430,17 @@ class PipelineBuilder:
     def limit(self, limit: int) -> Self:
         """
         Add a $limit stage to limit the number of documents.
-        
+
         Args:
             limit: Maximum number of documents
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If limit is not an integer
             ValueError: If limit is negative
-            
+
         Example:
             >>> builder.limit(10)
         """
@@ -295,17 +455,17 @@ class PipelineBuilder:
     def skip(self, skip: int) -> Self:
         """
         Add a $skip stage to skip documents.
-        
+
         Args:
             skip: Number of documents to skip
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If skip is not an integer
             ValueError: If skip is negative
-            
+
         Example:
             >>> builder.skip(20)
         """
@@ -320,24 +480,24 @@ class PipelineBuilder:
     def unset(self, fields: Union[str, List[str]]) -> Self:
         """
         Add a $unset stage to remove fields from documents.
-        
+
         Args:
             fields: Field name or list of field names to remove
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If fields is not a string or list of strings
             ValueError: If fields is empty
-            
+
         Example:
             >>> builder.unset("temp_field")
             >>> builder.unset(["field1", "field2", "field3"])
         """
         if fields is None:
             raise TypeError("fields cannot be None")
-        
+
         if isinstance(fields, str):
             if not fields:
                 raise ValueError("fields cannot be an empty string")
@@ -353,23 +513,23 @@ class PipelineBuilder:
             self._stages.append({"$unset": fields if len(fields) > 1 else fields[0]})
         else:
             raise TypeError(f"fields must be a string or list of strings, got {type(fields)}")
-        
+
         return self
 
     def replace_root(self, new_root: Dict[str, Any]) -> Self:
         """
         Add a $replaceRoot stage to replace the root document.
-        
+
         Args:
             new_root: Expression for the new root document (must contain 'newRoot' key)
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If new_root is not a dictionary
             ValueError: If new_root is empty or missing 'newRoot' key
-            
+
         Example:
             >>> builder.replace_root({"newRoot": "$embedded"})
             >>> builder.replace_root({"newRoot": {"$mergeObjects": ["$doc1", "$doc2"]}})
@@ -382,48 +542,48 @@ class PipelineBuilder:
             raise ValueError("new_root cannot be empty")
         if "newRoot" not in new_root:
             raise ValueError("new_root must contain 'newRoot' key")
-        
+
         self._stages.append({"$replaceRoot": new_root})
         return self
 
     def replace_with(self, replacement: Any) -> Self:
         """
         Add a $replaceWith stage (alias for $replaceRoot in MongoDB 4.2+).
-        
+
         Args:
             replacement: Expression for the replacement document
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             ValueError: If replacement is None
-            
+
         Example:
             >>> builder.replace_with("$embedded")
             >>> builder.replace_with({"$mergeObjects": ["$doc1", "$doc2"]})
         """
         if replacement is None:
             raise ValueError("replacement cannot be None")
-        
+
         self._stages.append({"$replaceWith": replacement})
         return self
 
     def facet(self, facets: Dict[str, List[Dict[str, Any]]]) -> Self:
         """
         Add a $facet stage for parallel execution of multiple sub-pipelines.
-        
+
         Args:
             facets: Dictionary where keys are output field names and values are
                    lists of pipeline stages for each sub-pipeline
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If facets is not a dictionary
             ValueError: If facets is empty or contains invalid values
-            
+
         Example:
             >>> builder.facet({
             ...     "items": [{"$skip": 10}, {"$limit": 20}],
@@ -436,31 +596,31 @@ class PipelineBuilder:
             raise TypeError(f"facets must be a dict, got {type(facets)}")
         if not facets:
             raise ValueError("facets cannot be empty")
-        
+
         # Validate that all values are lists of dictionaries
         for key, value in facets.items():
             if not isinstance(value, list):
                 raise TypeError(f"facet '{key}' must be a list, got {type(value)}")
             if not all(isinstance(stage, dict) for stage in value):
                 raise TypeError(f"all stages in facet '{key}' must be dictionaries")
-        
+
         self._stages.append({"$facet": facets})
         return self
 
     def count(self, field_name: str = "count") -> Self:
         """
         Add a $count stage to count documents.
-        
+
         Args:
             field_name: Name of the field for the count result
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If field_name is not a string
             ValueError: If field_name is empty
-            
+
         Example:
             >>> builder.match({"status": "active"}).count("active_count")
         """
@@ -470,26 +630,26 @@ class PipelineBuilder:
             raise TypeError(f"field_name must be a string, got {type(field_name)}")
         if not field_name:
             raise ValueError("field_name cannot be empty")
-        
+
         self._stages.append({"$count": field_name})
         return self
 
     def set_field(self, fields: Dict[str, Any]) -> Self:
         """
         Add a $set stage (alias for $addFields in MongoDB 3.4+).
-        
+
         Functionally equivalent to add_fields(), but $set is a more intuitive alias.
-        
+
         Args:
             fields: Dictionary with fields and their values/expressions
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If fields is not a dictionary
             ValueError: If fields is empty
-            
+
         Example:
             >>> builder.set_field({"status": "active", "updatedAt": "$$NOW"})
         """
@@ -500,20 +660,20 @@ class PipelineBuilder:
         if not fields:
             # Empty dict - valid case, skip (same as add_fields behavior)
             return self
-        
+
         self._stages.append({"$set": fields})
         return self
 
     def add_stage(self, stage: Dict[str, Any]) -> Self:
         """
         Add an arbitrary pipeline stage for advanced use cases.
-        
+
         Args:
             stage: Dictionary with an arbitrary MongoDB aggregation stage
-            
+
         Returns:
             Self for method chaining
-            
+
         Example:
             >>> builder.add_stage({
             ...     "$facet": {
@@ -529,10 +689,10 @@ class PipelineBuilder:
     def __len__(self) -> int:
         """
         Return the number of stages in the pipeline.
-        
+
         Returns:
             Number of stages
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).limit(10)
@@ -544,10 +704,10 @@ class PipelineBuilder:
     def __repr__(self) -> str:
         """
         Return a string representation of the builder for debugging.
-        
+
         Returns:
             String representation showing stage count and preview
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).limit(10)
@@ -557,7 +717,7 @@ class PipelineBuilder:
         stages_count = len(self._stages)
         if stages_count == 0:
             return "PipelineBuilder(stages=0)"
-        
+
         stage_types = [list(stage.keys())[0] for stage in self._stages[:3]]
         stages_preview = ", ".join(stage_types)
         if stages_count > 3:
@@ -567,10 +727,10 @@ class PipelineBuilder:
     def clear(self) -> Self:
         """
         Clear all stages from the pipeline.
-        
+
         Returns:
             Self for method chaining
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).clear()
@@ -583,10 +743,10 @@ class PipelineBuilder:
     def copy(self) -> "PipelineBuilder":
         """
         Create a copy of the builder with current stages.
-        
+
         Returns:
             New PipelineBuilder instance with copied stages
-            
+
         Example:
             >>> builder1 = PipelineBuilder().match({"status": "active"})
             >>> builder2 = builder1.copy()
@@ -603,17 +763,17 @@ class PipelineBuilder:
     def validate(self) -> bool:
         """
         Validate the pipeline before execution.
-        
+
         Checks that the pipeline is not empty and has valid structure.
         Validates critical MongoDB rules:
         - $out and $merge stages must be the last stage in the pipeline
-        
+
         Returns:
             True if pipeline is valid
-            
+
         Raises:
             ValueError: If pipeline is empty or has validation errors
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).validate()
@@ -623,20 +783,20 @@ class PipelineBuilder:
         """
         if not self._stages:
             raise ValueError("Pipeline cannot be empty")
-        
+
         # Validate that $out and $merge are the last stages (critical MongoDB rule)
         stage_types = self.get_stage_types()
-        
+
         # Check if $out or $merge exist
         has_out = "$out" in stage_types
         has_merge = "$merge" in stage_types
-        
+
         if has_out and has_merge:
             raise ValueError(
                 "Pipeline cannot contain both $out and $merge stages. "
                 "Only one output stage is allowed."
             )
-        
+
         # Check if $out or $merge exist and validate position
         for stage_name in ["$out", "$merge"]:
             if stage_name in stage_types:
@@ -646,16 +806,16 @@ class PipelineBuilder:
                         f"{stage_name} stage must be the last stage in the pipeline. "
                         f"Found at position {stage_index + 1} of {len(stage_types)}."
                     )
-        
+
         return True
 
     def get_stage_types(self) -> List[str]:
         """
         Get a list of stage types in the pipeline.
-        
+
         Returns:
             List of stage type strings (e.g., ["$match", "$lookup", "$limit"])
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).limit(10)
@@ -667,16 +827,16 @@ class PipelineBuilder:
     def has_stage(self, stage_type: str) -> bool:
         """
         Check if the pipeline contains a specific stage type.
-        
+
         Args:
             stage_type: Type of stage to check (e.g., "$match", "$lookup")
-            
+
         Returns:
             True if the stage type is present in the pipeline
-            
+
         Raises:
             TypeError: If stage_type is not a string
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).limit(10)
@@ -693,16 +853,16 @@ class PipelineBuilder:
     def prepend(self, stage: Dict[str, Any]) -> Self:
         """
         Add a stage at the beginning of the pipeline.
-        
+
         Args:
             stage: Dictionary with a MongoDB aggregation stage
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If stage is not a dictionary
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"})
@@ -721,18 +881,18 @@ class PipelineBuilder:
     def insert_at(self, position: int, stage: Dict[str, Any]) -> Self:
         """
         Insert a stage at a specific position in the pipeline.
-        
+
         Args:
             position: Index where to insert (0-based)
             stage: Dictionary with a MongoDB aggregation stage to insert
-            
+
         Returns:
             Self for method chaining
-            
+
         Raises:
             TypeError: If stage is not a dictionary
             IndexError: If position is out of range [0, len(stages)]
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).group({"_id": "$category"}, {})
@@ -746,28 +906,28 @@ class PipelineBuilder:
             raise TypeError(f"stage must be a dict, got {type(stage)}")
         if not stage:
             return self
-        
+
         if position < 0 or position > len(self._stages):
             raise IndexError(
                 f"Position {position} out of range [0, {len(self._stages)}]"
             )
-        
+
         self._stages.insert(position, stage)
         return self
 
     def get_stage_at(self, index: int) -> Dict[str, Any]:
         """
         Get a specific stage from the pipeline by index.
-        
+
         Args:
             index: Zero-based index of the stage to retrieve
-            
+
         Returns:
             Dictionary representing the stage at the given index
-            
+
         Raises:
             IndexError: If index is out of range
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).limit(10)
@@ -779,21 +939,22 @@ class PipelineBuilder:
             raise IndexError(
                 f"Index {index} out of range [0, {len(self._stages)}]"
             )
-        return self._stages[index].copy()
+        # Return a deep copy so callers can safely mutate nested structures
+        return copy.deepcopy(self._stages[index])
 
     def pretty_print(self, indent: int = 2, ensure_ascii: bool = False) -> str:
         """
         Return a formatted JSON string representation of the pipeline.
-        
+
         Useful for debugging and understanding pipeline structure.
-        
+
         Args:
             indent: Number of spaces for indentation (default: 2)
             ensure_ascii: If False, non-ASCII characters are output as-is (default: False)
-            
+
         Returns:
             Formatted JSON string of the pipeline
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).limit(10)
@@ -811,6 +972,36 @@ class PipelineBuilder:
         """
         return json.dumps(self._stages, indent=indent, ensure_ascii=ensure_ascii)
 
+    def pretty_print_stage(
+        self,
+        stage: Union[int, Dict[str, Any]],
+        indent: int = 2,
+        ensure_ascii: bool = False,
+    ) -> str:
+        """
+        Return a formatted JSON string representation of a single stage.
+
+        Args:
+            stage: Stage index (0-based) or a stage dict
+            indent: Number of spaces for indentation (default: 2)
+            ensure_ascii: If False, non-ASCII characters are output as-is (default: False)
+
+        Returns:
+            Formatted JSON string of the stage
+
+        Raises:
+            TypeError: If stage is not an int or dict
+            IndexError: If stage is an int out of range
+        """
+        if isinstance(stage, int):
+            stage_dict = self.get_stage_at(stage)
+        elif isinstance(stage, dict):
+            stage_dict = copy.deepcopy(stage)
+        else:
+            raise TypeError(f"stage must be an int index or a dict, got {type(stage)}")
+
+        return json.dumps(stage_dict, indent=indent, ensure_ascii=ensure_ascii)
+
     def to_json_file(
         self,
         filepath: Union[str, Path],
@@ -820,23 +1011,23 @@ class PipelineBuilder:
     ) -> None:
         """
         Save the pipeline to a JSON file.
-        
+
         Useful for debugging, comparison with other pipelines, or versioning.
-        
+
         Args:
             filepath: Path to the output JSON file (str or Path)
             indent: Number of spaces for indentation (default: 2)
             ensure_ascii: If False, non-ASCII characters are output as-is (default: False)
             metadata: Optional metadata to include in the JSON file
-            
+
         Raises:
             IOError: If file cannot be written
-            
+
         Example:
             >>> builder = PipelineBuilder()
             >>> builder.match({"status": "active"}).limit(10)
             >>> builder.to_json_file("debug_pipeline.json")
-            
+
             >>> # With metadata
             >>> builder.to_json_file(
             ...     "pipeline.json",
@@ -845,23 +1036,69 @@ class PipelineBuilder:
         """
         filepath = Path(filepath)
         filepath.parent.mkdir(parents=True, exist_ok=True)
-        
+
         output: Dict[str, Any] = {
             "pipeline": self._stages,
         }
         if metadata:
             output["metadata"] = metadata
-        
+
         with open(filepath, "w", encoding="utf-8") as f:
             json.dump(output, f, indent=indent, ensure_ascii=ensure_ascii)
 
+    def compare_with(self, other: "PipelineBuilder", context_lines: int = 3) -> str:
+        """
+        Compare this pipeline with another pipeline and return a unified diff.
+
+        This is useful when migrating legacy pipelines (e.g., templates) to builder code.
+
+        Args:
+            other: Another PipelineBuilder instance to compare with
+            context_lines: Number of context lines in the unified diff (default: 3)
+
+        Returns:
+            Unified diff as a string. Returns "No differences." if pipelines are identical.
+
+        Raises:
+            TypeError: If other is not a PipelineBuilder
+            ValueError: If context_lines is negative
+
+        Example:
+            >>> legacy = PipelineBuilder().match({"a": 1})
+            >>> new = PipelineBuilder().match({"a": 2})
+            >>> print(new.compare_with(legacy))
+        """
+        if not isinstance(other, PipelineBuilder):
+            raise TypeError(f"other must be a PipelineBuilder, got {type(other)}")
+        if not isinstance(context_lines, int):
+            raise TypeError(f"context_lines must be an int, got {type(context_lines)}")
+        if context_lines < 0:
+            raise ValueError("context_lines cannot be negative")
+
+        a = json.dumps(
+            self.build(),
+            indent=2,
+            ensure_ascii=False,
+            sort_keys=True,
+        ).splitlines(keepends=True)
+        b = json.dumps(
+            other.build(),
+            indent=2,
+            ensure_ascii=False,
+            sort_keys=True,
+        ).splitlines(keepends=True)
+
+        diff = difflib.unified_diff(a, b, fromfile="new", tofile="other", n=context_lines)
+        out = "".join(diff)
+        return out if out else "No differences."
+
     def build(self) -> List[Dict[str, Any]]:
         """
         Return the completed pipeline.
-        
+
         Returns:
             List of dictionaries with aggregation pipeline stages
-            
+
         Example:
             >>> pipeline = builder.build()
             >>> collection.aggregate(pipeline)

{mongo_pipebuilder-0.3.0.dist-info → mongo_pipebuilder-0.4.0.dist-info}/METADATA

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: mongo-pipebuilder
-Version: 0.3.0
+Version: 0.4.0
 Summary: Type-safe, fluent MongoDB aggregation pipeline builder
 Author-email: seligoroff <seligoroff@gmail.com>
-License: MIT
+License-Expression: MIT
 Project-URL: Homepage, https://github.com/seligoroff/mongo-pipebuilder
 Project-URL: Documentation, https://github.com/seligoroff/mongo-pipebuilder#readme
 Project-URL: Repository, https://github.com/seligoroff/mongo-pipebuilder
@@ -11,7 +11,6 @@ Project-URL: Issues, https://github.com/seligoroff/mongo-pipebuilder/issues
 Keywords: mongodb,aggregation,pipeline,builder,query
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
@@ -98,6 +97,15 @@ Adds a `$match` stage to filter documents.
 .match({"status": "active", "age": {"$gte": 18}})
 ```
 
+##### `match_expr(expr: Dict[str, Any]) -> Self`
+
+Adds a `$match` stage with an `$expr` condition (expression-based filter; useful for comparing fields or using variables from `let` in subpipelines).
+
+```python
+.match_expr({"$eq": ["$id", "$$teamId"]})
+.match_expr({"$and": [{"$gte": ["$field", "$other"]}, {"$lte": ["$score", 100]}]})
+```
+
 ##### `lookup(from_collection: str, local_field: str, foreign_field: str, as_field: str, pipeline: Optional[List[Dict[str, Any]]] = None) -> Self`
 
 Adds a `$lookup` stage to join with another collection.
@@ -112,6 +120,43 @@ Adds a `$lookup` stage to join with another collection.
 )
 ```
 
+##### `lookup_let(from_collection: str, let: Dict[str, Any], pipeline: Union[List[Dict[str, Any]], PipelineBuilder], as_field: str) -> Self`
+
+Adds a `$lookup` stage with `let` and `pipeline` (join by expression; variables from the current document are available in the subpipeline as `$$var`). Use this when the join condition is an expression (e.g. `$expr`) rather than equality of two fields.
+
+```python
+# With list of stages
+.lookup_let(
+    from_collection="teams",
+    let={"teamId": "$idTeam"},
+    pipeline=[
+        {"$match": {"$expr": {"$eq": ["$_id", "$$teamId"]}}},
+        {"$project": {"name": 1, "_id": 0}}
+    ],
+    as_field="team"
+)
+
+# With PipelineBuilder for the subpipeline (optionally using match_expr)
+sub = PipelineBuilder().match_expr({"$eq": ["$_id", "$$teamId"]}).project({"name": 1, "_id": 0})
+.lookup_let("teams", {"teamId": "$idTeam"}, sub, as_field="team")
+```
+
+##### `union_with(coll: str, pipeline: Optional[Union[List[Dict[str, Any]], PipelineBuilder]] = None) -> Self`
+
+Adds a `$unionWith` stage to combine documents from the current pipeline with documents from another collection. Optionally runs a subpipeline on the other collection before merging.
+
+```python
+# Union with another collection (no subpipeline)
+.union_with("other_coll")
+
+# With subpipeline as list of stages
+.union_with("logs", [{"$match": {"level": "error"}}, {"$limit": 100}])
+
+# With PipelineBuilder for the subpipeline
+sub = PipelineBuilder().match({"source": "individual"}).project({"name": 1})
+.union_with("sso_individual_statistics", sub)
+```
+
 ##### `add_fields(fields: Dict[str, Any]) -> Self`
 
 Adds a `$addFields` stage to add or modify fields.
@@ -252,7 +297,7 @@ builder.prepend({"$match": {"deleted": False}})
 Inserts a stage at a specific position (0-based index) in the pipeline.
 
 ```python
-builder.match({"status": "active"}).group({"_id": "$category"}, {"count": {"$sum": 1}})
+builder.match({"status": "active"}).group("$category", {"count": {"$sum": 1}})
 builder.insert_at(1, {"$sort": {"name": 1}})
 # Pipeline: [{"$match": {...}}, {"$sort": {...}}, {"$group": {...}}]
 ```
@@ -327,6 +372,15 @@ print(builder.pretty_print())
 # ]
 ```
 
+##### `pretty_print_stage(stage: Union[int, Dict[str, Any]], indent: int = 2, ensure_ascii: bool = False) -> str`
+
+Returns a formatted JSON string representation of a single stage (by index or by dict).
+
+```python
+builder = PipelineBuilder().match({"status": "active"}).limit(10)
+print(builder.pretty_print_stage(0))  # Prints the $match stage
+```
+
 ##### `to_json_file(filepath: Union[str, Path], indent: int = 2, ensure_ascii: bool = False, metadata: Optional[Dict[str, Any]] = None) -> None`
 
 Saves the pipeline to a JSON file. Useful for debugging, comparison, or versioning.
@@ -345,6 +399,17 @@ builder.to_json_file(
 )
 ```
 
+##### `compare_with(other: PipelineBuilder, context_lines: int = 3) -> str`
+
+Returns a unified diff between two pipelines (useful for comparing “new” builder pipelines vs legacy/template pipelines).
+
+```python
+legacy = PipelineBuilder().match({"status": "active"}).limit(10)
+new = PipelineBuilder().match({"status": "inactive"}).limit(10)
+
+print(new.compare_with(legacy))
+```
+
 ##### `build() -> List[Dict[str, Any]]`
 
 Returns the complete pipeline as a list of stage dictionaries.
@@ -391,6 +456,31 @@ pipeline = (
 )
 ```
 
+### Lookup by expression (lookup_let)
+
+When the join condition is an expression (e.g. `$expr`) rather than matching two fields, use `lookup_let`. The subpipeline can be built with `match_expr()`:
+
+```python
+sub = (
+    PipelineBuilder()
+    .match_expr({"$eq": ["$_id", "$$teamId"]})
+    .project({"name": 1, "slug": 1, "_id": 0})
+)
+pipeline = (
+    PipelineBuilder()
+    .match({"status": "active"})
+    .lookup_let(
+        from_collection="teams",
+        let={"teamId": "$idTeam"},
+        pipeline=sub,
+        as_field="team"
+    )
+    .unwind("team", preserve_null_and_empty_arrays=True)
+    .project({"title": 1, "teamName": "$team.name"})
+    .build()
+)
+```
+
 ### Aggregation with Grouping
 
 ```python
@@ -500,11 +590,39 @@ base = get_base_pipeline(user_id)
 # Create multiple queries from cached base
 recent = base.copy().sort({"createdAt": -1}).limit(10).build()
 by_category = base.copy().match({"category": "tech"}).build()
-with_stats = base.copy().group({"_id": "$category"}, {"count": {"$sum": 1}}).build()
+with_stats = base.copy().group("$category", {"count": {"$sum": 1}}).build()
 
 # Base pipeline is safely cached and reused
 ```
 
+## Best Practices
+
+### Array `_id` after `$group`: prefer `$arrayElemAt` and materialize fields
+
+If you use `$group` with an array `_id` (e.g. `["_idSeason", "_idTournament"]`), avoid relying on `$_id` later in the pipeline.
+Instead, **extract elements with `$arrayElemAt` and store them into explicit fields**, then use those fields in subsequent stages.
+
+```python
+pipeline = (
+    PipelineBuilder()
+    .group(
+        group_by=["$idSeason", "$idTournament"],
+        accumulators={"idTeams": {"$addToSet": "$idTeam"}},
+    )
+    .project({
+        "idSeason": {"$arrayElemAt": ["$_id", 0]},
+        "idTournament": {"$arrayElemAt": ["$_id", 1]},
+        "idTeams": 1,
+        # Optional: preserve array _id explicitly if you really need it later
+        # "_id": "$_id",
+    })
+    .build()
+)
+```
+
+This pattern reduces surprises and helps avoid errors like:
+`$first's argument must be an array, but is object`.
+
 #### Example: Pipeline Factories
 
 ```python

mongo_pipebuilder-0.4.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+mongo_pipebuilder/__init__.py,sha256=3iWmQvRAT2QZHXURN9AHoMPn-7FjwH9ig8QyTUCVLh4,336
+mongo_pipebuilder/builder.py,sha256=_c-5uuNwWJigKzzIcOXXkPY9oD_UOC0lomhx03yJz9U,38834
+mongo_pipebuilder-0.4.0.dist-info/licenses/LICENSE,sha256=-ZkZpDLHDQAc-YBIojJ6eDsMwxwx5pRuQz3RHnl9Y8w,1104
+mongo_pipebuilder-0.4.0.dist-info/METADATA,sha256=IAtv0lDGEIiQ-OlFLn1LR6fDFtgC1xj_PSH3Ak31lE4,20002
+mongo_pipebuilder-0.4.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mongo_pipebuilder-0.4.0.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
+mongo_pipebuilder-0.4.0.dist-info/RECORD,,

{mongo_pipebuilder-0.3.0.dist-info → mongo_pipebuilder-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

mongo_pipebuilder-0.3.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-mongo_pipebuilder/__init__.py,sha256=pP27GA8G6dttP-gMq9uNCJoS66-cb3JJiVVdI340er4,336
-mongo_pipebuilder/builder.py,sha256=oQxRYL9ycjYCv2ErP_YHz-Uoo2pPRaRBaaaCLEsL5Mo,30286
-mongo_pipebuilder-0.3.0.dist-info/licenses/LICENSE,sha256=-ZkZpDLHDQAc-YBIojJ6eDsMwxwx5pRuQz3RHnl9Y8w,1104
-mongo_pipebuilder-0.3.0.dist-info/METADATA,sha256=KkgWrj5TD22yDj915Jrri_JftYMEpTz6hXSeHKEM7mk,15850
-mongo_pipebuilder-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mongo_pipebuilder-0.3.0.dist-info/top_level.txt,sha256=wLn7H_v-qaNIws5FeBbKPZBCmYFYgFEhPaLjoCWcisc,18
-mongo_pipebuilder-0.3.0.dist-info/RECORD,,