MongoDB $redact Stage

What Is $redact?

$redact is a MongoDB aggregation stage that restricts document content based on an expression. At each level, the expression must resolve to $$KEEP, $$PRUNE, or $$DESCEND.

$redact = conditional keep / prune / descend

{ $redact: <expression → $$KEEP | $$PRUNE | $$DESCEND> }

$$KEEP    → keep this level; stop inspecting nested content
$$PRUNE   → remove this level entirely
$$DESCEND → keep this level; check nested docs/arrays next

Usually wrapped in $cond
vs $match  → whole document vs nested levels
vs $project → fixed field list vs access rules

How to Use $redact in MongoDB

Store access hints in the document, write a condition, then map true/false to system variables.

1. Put access data on each level you care about (for example level or tags).
2. Optional: $match first to reduce documents.
3. Add $redact with a $cond that returns $$KEEP, $$PRUNE, or $$DESCEND.
4. Choose $$DESCEND when nested levels need their own checks; use $$KEEP when the whole subtree is allowed as-is.

Pseudocode

function redact(node):
    decision = evaluate(expression on node)
    if decision is $$PRUNE:
        remove this node
    else if decision is $$KEEP:
        keep this node as-is (no nested checks)
    else if decision is $$DESCEND:
        keep this node's fields
        for each embedded document / array element:
            redact(child)

Cheat Sheet

Keep these facts handy while writing access rules.

Live Preview

Choose a redaction rule and see how a nested account document is trimmed.

$redact: if level == 5 → $$PRUNE else $$DESCEND

root level 1 → DESCEND
cc level 5 → PRUNE

output:
  { _id: 1, level: 1, acct_id: "xyz123", status: "A" }

Worked Walkthrough — Prune Level 5

An account has a nested cc object at level: 5. Goal: remove any level equal to 5, keep everything else.

Document in:
  {
    _id: 1,
    level: 1,
    acct_id: "xyz123",
    cc: { level: 5, type: "yy", num: "0000" },
    status: "A"
  }

Rule:
  if level == 5 → $$PRUNE
  else → $$DESCEND

root: level 1 → $$DESCEND (keep fields; check children)
cc:   level 5 → $$PRUNE  (drop entire cc)

Document out:
  { _id: 1, level: 1, acct_id: "xyz123", status: "A" }

MongoDB Examples

Insert a sample account, prune by level, then redact by tags. Run these in mongosh in order.

db.accounts.insertOne({
  _id: 1,
  level: 1,
  acct_id: "xyz123",
  cc: {
    level: 5,
    type: "yy",
    num: "000000000000"
  },
  status: "A"
});

db.accounts.find()

[
  {
    _id: 1,
    level: 1,
    acct_id: "xyz123",
    cc: {
      level: 5,
      type: "yy",
      num: "000000000000"
    },
    status: "A"
  }
]

db.accounts.aggregate([
  { $match: { status: "A" } },
  {
    $redact: {
      $cond: {
        if: { $eq: ["$level", 5] },
        then: "$$PRUNE",
        else: "$$DESCEND"
      }
    }
  }
]);

[
  {
    _id: 1,
    level: 1,
    acct_id: "xyz123",
    status: "A"
  }
]

db.forecasts.insertOne({
  _id: 1,
  title: "Department Report",
  tags: ["G", "STLW"],
  year: 2014,
  subsections: [
    {
      subtitle: "Overview",
      tags: ["SI", "G"],
      content: "Public overview."
    },
    {
      subtitle: "Budget",
      tags: ["TK"],
      content: "Restricted budget."
    }
  ]
});

var userAccess = ["STLW", "G"];

db.forecasts.aggregate([
  { $match: { year: 2014 } },
  {
    $redact: {
      $cond: {
        if: {
          $gt: [
            {
              $size: {
                $setIntersection: ["$tags", userAccess]
              }
            },
            0
          ]
        },
        then: "$$DESCEND",
        else: "$$PRUNE"
      }
    }
  }
]);

[
  {
    _id: 1,
    title: "Department Report",
    tags: ["G", "STLW"],
    year: 2014,
    subsections: [
      {
        subtitle: "Overview",
        tags: ["SI", "G"],
        content: "Public overview."
      }
    ]
  }
]

Performance Notes

Prefer $match early. $redact with $$DESCEND walks nested structure, so keep documents and nesting as shallow as your security model allows.

Key Takeaways