Fetching Documents

Fetching documents using Mongez Aggregate class.

Introduction

As we saw, Aggregate is a pipeline that hold multiple stages, we saw how to build the pipeline, now let's see how to fetch the documents.

Using get method

This is the most common method to fetch documents, it will return an array of documents.

Let's see an example

import { Aggregate } from "@warlock.js/cascade";

const users = await new Aggregate("users").where("id", ">", 1500).get();

This will return list of documents for the users collection.

If we want to map the date before final return, we can pass a callback to the get method.

const users = await new Aggregate("users").get((user) => {
  user.age = new Date().getFullYear() - user.birthYear;
  return user;
});

Get first document

To fetch only first matched document, we can use first method.

const user = await new Aggregate("users").where("id", 1500).first();

If no results found, null will be returned.

Get last document

Return last matched document.

const user = await new Aggregate("users").where("id", 1500).last();

Pagination

Another powerful feature of Aggregate is pagination, we can use paginate method to paginate the results.

const results = await new Aggregate("users").paginate(1, 10);

The first argument is the page number, and the second argument is the limit.

The results contains an object with the following structure:

export type PaginationInfo = {
  /**
   * Limit of the query
   */
  limit: number;
  /**
   * Results of the query
   */
  result: number;
  /**
   * Current page of the query
   */
  page: number;
  /**
   * total results of the query
   */
  total: number;
  /**
   * total pages of the query
   */
  pages: number;
};
/**
 * The result of the paginate query
 */
export type PaginationListing<T> = {
  /**
   * Results of the query
   */
  documents: T[];
  /**
   * The pagination results
   */
  paginationInfo: PaginationInfo;
};

So basically, it returns documents and paginationInfo object, the documents is an array of documents, and the paginationInfo contains the pagination information.

Count documents

To count the number of documents, we can use count method.

const count = await new Aggregate("users").count();

Chunks

The chunk concept is to split the documents into multiple chunks, this will reduce the loaded documents in the memory especially if we have a large number of documents.

To use chunks, we can use chunk method, it receives the limit of documents per chunk and a callback to handle the chunk.

await new Aggregate("users").chunk(100, (users) => {
  // handle the chunk
});

You can also receive the pagination information in the second callback argument:

await new Aggregate("users").chunk(100, (users, pagination) => {
  // handle the chunk
});

danger

If you want to stop the chunking process, you can return false from the callback.

Explain

Sometimes we need to know how the query is executed, we can use explain method to get the execution plan of the query.

const results = await new Aggregate("users").explain();

See explain for more information.

Get certain field values

To get certain field values, we can use values method.

const results = await new Aggregate("users").values("name");

This will return all values from all documents for the name field.

tip

Please note that the values method will return an array of values, not an array of documents.

info

The returned values may return duplicated values, to get unique values, use unique method.

Get Unique/Distinct values for a field

To get unique values for a given field, we can use unique method.

const results = await new Aggregate("users").unique("name");

You can use distinct method as an alias for unique method.

Get Heavy Unique/Distinct values for a field

In some scenarios, the unique values may contain null value, to ensure only a non-null values are returned, we can use uniqueHeavy method.

const results = await new Aggregate("users").uniqueHeavy("name");

You can use distinctHeavy method as an alias for uniqueHeavy method.