Skip to content

🚀 Getting Started with Monggregate

📋 Overview

Monggregate is a Python library designed to simplify working with MongoDB aggregation pipelines. It provides an object-oriented interface that lets you focus on data transformation requirements rather than MongoDB syntax.

📥 Installation

Monggregate is available on PyPI:

1
pip install monggregate

✅ Requirements

  • Python 3.10 or higher
  • Dependencies: pydantic, pyhumps, and typing-extensions
  • A MongoDB driver for executing the query builder (e.g., pymongo)

📚 For a complete list of requirements, see the requirements files in the repository.

🧩 Basic Concepts

Monggregate's primary components:

  • 📚 Pipeline: The main class used to build and chain MongoDB aggregation operations
  • 🔄 Stages: Individual operations like match, group, sort, etc.
  • 🛠️ Operators: MongoDB operators implemented with intuitive Python syntax

⚡ Quick Start Example

Here's a simple example to get you started:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
import pymongo
from monggregate import Pipeline

# Connect to MongoDB
client = pymongo.MongoClient("<insert-your-connection-string>")
db = client["sample_database"]

# Create a pipeline
pipeline = Pipeline()

# Build your pipeline with chained operations
pipeline.match(
    category="electronics"
).sort(
    by="price", 
    descending=True
).limit(5)

# Execute the pipeline
results = list(db["products"].aggregate(pipeline.export()))
print(results)

🔧 Using the Pipeline Builder

💡 The recommended way to use Monggregate is through the Pipeline class.

1
2
3
4
5
6
7
8
9
from monggregate import Pipeline

# Initialize an empty pipeline
pipeline = Pipeline()

# Build your pipeline with autocomplete assistance
pipeline.match(...)
        .group(...)
        .sort(...)

When you type pipeline. in your IDE, you'll see all available aggregation stages through autocompletion:

autocompletion

🌟 Advanced Usage

Monggregate supports advanced MongoDB features like expressions and operators:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
from monggregate import Pipeline, S

pipeline = Pipeline()
pipeline.match(
    year=S.type_("number")  # Using operators
).group(
    by="year",
    query={
        "count": S.sum(1),
        "titles": S.push("$title")
    }
)

🔜 Next Steps