DQ Class Documentation

Home documentation

Overview

The DQ class is a utility designed to simplify the construction of MongoDB queries in Dart applications. It provides a set of static methods that generate MongoDB-compatible query objects in a structured and readable manner. This class is particularly useful when you need to build complex queries involving equality checks, logical operations, pattern matching, and aggregation commands.

Key Features

• Equality Checks: Create queries that match exact values.
• Logical Operations: Combine multiple conditions using logical operators like $or and $and.
• Pattern Matching: Use regular expressions to match patterns in string fields.
• Aggregation: Perform operations like grouping and sorting in MongoDB collections.

How to Use

1. Import the Required Packages

Before using the DQ class, make sure to import the necessary packages in your Dart file:

import 'package:webapp/wa_model.dart';

2. Basic Equality Check

The DQ.eq() method allows you to check for equality. This is useful for simple queries where you want to match a specific value.

Example:

var query = DQ.field('name', DQ.eq('John'));
// Produces: { 'name': 'John' }

3. Logical OR Query

Use the DQ.or() method to combine multiple conditions with a logical OR operation.

Example:

var query = DQ.or([
  DQ.field('name', DQ.eq('John')),
  DQ.field('age', DQ.eq(25)),
]);
// Produces: { '\$or': [{ 'name': 'John' }, { 'age': 25 }] }

4. ObjectId Matching

The DQ.oid() and DQ.id() methods are used for matching documents based on their MongoDB ObjectId.

Example with ObjectId:

var query = DQ.oid(ObjectId.parse('507f191e810c19729de860ea'));
// Produces: { '_id': ObjectId('507f191e810c19729de860ea') }

Example with String ID:

var query = DQ.id('507f191e810c19729de860ea');
// Produces: { '_id': ObjectId('507f191e810c19729de860ea') }

5. Logical AND Query

The DQ.and() method allows you to combine multiple conditions with a logical AND operation.

Example:

var query = DQ.and([
  DQ.field('status', DQ.eq('active')),
  DQ.field('age', DQ.eq(25)),
]);
// Produces: { '\$and': [{ 'status': 'active' }, { 'age': 25 }] }

6. Pattern Matching with Regular Expressions

The DQ.like() method helps match documents based on a regular expression pattern.

Example:

var query = DQ.field('name', DQ.like('^John', options: 'i'));
// Produces: { 'name': { '\$regex': '^John', '\$options': 'i' } }

7. Aggregation: Grouping and Summing

You can use the DQ.group() and DQ.sum() methods to create aggregation pipelines.

Example for Grouping:

var query = DQ.group({
  '_id': '\$category',
  'total': DQ.sum('price'),
});
// Produces: { '\$group': { '_id': '\$category', 'total': { '\$sum': '\$price' } } }

8. Sorting Documents

The DQ.order() method allows you to sort the documents based on a specific field.

Example:

var query = DQ.order('createdAt', true);
// Produces: { 'createdAt': -1 } // Sort by createdAt in descending order

9. Using the Queries in MongoDB Operations

Once you've constructed a query using the DQ class, you can use it in MongoDB operations like find, aggregate, etc.

Example:

var query = DQ.and([
  DQ.field('name', DQ.like('John')),
  DQ.field('age', DQ.eq(25)),
]);

var result = await collection.find(query).toList();
// This will find all documents where the name matches 'John' and the age is 25.

Summary

The DQ class is a powerful tool for building MongoDB queries in Dart. By using the provided methods, you can construct complex queries in a clear and concise manner, making your code more readable and maintainable. Whether you need to filter documents, apply logical operations, or perform aggregations, DQ simplifies the process while ensuring compatibility with MongoDB’s query syntax.