Database tools

Aggregation pipelines

Build a read-only aggregation pipeline, preview stages and use results to add new stages.

Open an aggregation tab

Right-click a collection or view and choose Open aggregation. The tab is tied to that connection and namespace. It can be renamed, duplicated and moved between editor groups like a query tab.

Use Stages for an ordered outline and a focused stage editor, or Source to edit the enabled pipeline as an array. Pipeline drafts follow Remember workspace state; results remain in memory.

Build your first pipeline

For an example orders collection, this pipeline totals pending orders by customer. Paste it into Source, substituting your field names:

[
  { $match: { status: "pending" } },
  { $group: {
      _id: "$customerId",
      orderCount: { $sum: 1 },
      totalValue: { $sum: "$total" }
  } },
  { $sort: { totalValue: -1 } }
]
  1. Choose an output limit.
  2. Choose Run pipeline, or press Ctrl/Command + Enter.
  3. Expand result rows to inspect the grouped values.

The output limit is applied after the executed stages. It does not limit the input before grouping, so MongoDB may still process the full collection.

Work with stages

In Stages, use the filterable Add stage control to find a stage by operator or description. Suggestions take the reported MongoDB version into account. Select a stage to edit its BSON body, move it up or down, duplicate it, disable it or remove it.

The outline shows each stage's purpose and a short BSON source preview, plus the total and enabled stage counts. Drag a stage above or below another stage; the insertion line shows where it will go. For keyboard reordering, focus a stage and press Alt + ↑/↓, or use Move up and Move down in the selected stage's editor.

Reordering preserves stage source and disabled drafts. It changes the pipeline draft without running it; existing results remain until you explicitly run or preview again.

Disabled stages stay in the draft but are omitted from execution and copied source. A custom stage lets you enter a read-only stage that is not in the suggestion catalog. Server capabilities, privileges and placement still determine whether MongoDB accepts it.

Preview through this stage executes the enabled prefix ending at the selected stage. Results show the scope that was actually run. Merely selecting another stage does not update those results.

Edit common stages visually

Select a stage and choose Visual form. Forms are available for $match, $project, $set, $group, $sort, $unwind, $skip and $limit. Opening a form does not change the source or run the pipeline.

  • Match uses the familiar visual conditions and filter chips.
  • Project and set use field rows, with inclusion/exclusion or editable BSON expressions.
  • Group provides a group-key expression and named accumulators such as sum, average and count (sum of 1). Compound keys and custom accumulators remain editable as BSON expressions.
  • Sort provides field/direction rows; unwind provides an array path, empty/null preservation and optional array-index field.
  • Skip and limit accept whole-number counts without rounding large integers.

Changes update your draft immediately; run or preview explicitly to refresh results. Incomplete expressions remain available in Stage source. Unsupported stages, metadata sorts and unrecognized options stay in Source rather than being simplified.

Field suggestions follow the earlier enabled stages: for example, a group stage replaces the incoming field names with its group key and accumulator outputs. Suggestions also use sampled collection fields where available. Unknown transformations clear inherited suggestions; you can always enter fields manually.

Compare a stage's input and output

Select an enabled stage in Stages mode, then choose Compare stage input/output. Input shows the pipeline prefix before that stage; Output includes the selected stage. For the first enabled stage, Input shows collection or view documents. Disabled stages are skipped.

Both panes offer a read-only document table with expandable rows and a folding BSON-source view. They appear side by side, or stacked in a narrow pane. Each side uses the output limit and result-size budget independently. Limits apply after each prefix, so an output group or sort still processes all of its upstream input.

The two sides are separate reads, not matching row pairs or a shared database snapshot. Data, ordering and stages such as grouping, unwinding or sampling can produce different sets. Loaded counts are bounded previews, not exact totals.

Your main pipeline results remain in place. Stop comparison cancels both reads while retaining loaded partial results; each pane identifies its own completion, limit or error. Changing the selected stage, pipeline, limits or connection state stops ongoing comparison reads and marks the old comparison stale. Compare again explicitly to refresh it.

Clear comparison discards its temporary results. Leaving or closing the aggregation editor also cancels and clears the comparison.

Build from result properties

Right-click a result column, cell or expanded property for context-sensitive shortcuts:

  • Keep matching documents or Exclude matching documents prepares a match stage.
  • Group by this property prepares a grouping key and calculations.
  • Summarize this property prepares a numeric calculation where applicable.
  • Unwind this array prepares array expansion.
  • Sort actions prepare an ordered result, and Keep selected properties prepares a projection.

Each shortcut opens a configuration dialog with a stage preview and an insertion position. Choose Add stage to change the draft, then run the pipeline explicitly. Suggestions come from the displayed output, which can have different fields from the source collection.

Copy a pipeline or save a view

Copy either the enabled pipeline array or a complete aggregate(...) command. The copied command omits Palryn's output cap and stage-preview prefix. Use Save as view… to create a standard MongoDB view from the enabled pipeline.

Execution boundaries

This editor runs bounded, read-only, collection-scoped aggregations. $out and $merge are rejected. Results are read-only and do not use the ordinary collection-query pager. The current pipeline execution has a five-second server limit as well as result-size and batch time limits.

Use Stop to end loading. Changing a draft keeps the old results with a changed notice; rerun to see the new pipeline. Use Shell for workflows that require real mongosh execution rather than this bounded editor.

Export results

Both export actions also offer Excel workbook (.xlsx), using the same columns as CSV. Numeric and boolean cells are used where precision permits; large/high-precision numbers stay as text. See Excel workbook export for value mapping and worksheet/cell limits.

Choose Export loaded results… after loading finishes. The dialog shows the number of loaded documents and whether the output came from a full-pipeline run or a preview. It also identifies results from an older draft or a partial run.

Choose JSON array (Extended JSON), JSON Lines (Extended JSON) or CSV, then Choose file and export. This saves the loaded snapshot without rerunning the pipeline. CSV defaults to plain spreadsheet values: strings, numbers, booleans, dates and ObjectIds have no BSON type wrappers. Nested and other BSON values use Extended JSON. Optional typed CSV preserves BSON types. All loaded top-level fields are included, nested values stay in one cell, and missing fields are empty. JSON can also export an empty result.

Export full results… reruns the last executed pipeline or preview prefix from the beginning, without the grid output limit or display memory budget. Draft edits do not change the export; explicit $limit stages still apply. Concurrent database changes may affect the results. Full exports have a 30-second server time limit.

Choose the same JSON or CSV formats as ordinary query export. CSV columns start with the loaded top-level fields; add fields that appear only in later results if needed. Only listed CSV columns are exported; JSON includes all fields. Choose a new file and Start export. Follow progress or Stop in Background jobs. Results stream directly to disk; failed or cancelled exports do not publish a partial file.

The save operation reports completion and the destination path. If encoding or writing fails, an existing destination file is preserved.

Understand aggregation errors

Failed runs and comparison panes show guidance tailored to the failure, such as an invalid expression or input type, missing permissions, an unsupported operator, a time limit, or an interrupted connection. MongoDB command errors show their numeric code and code name. Expand MongoDB message for the server's details; long messages are explicitly marked as shortened.

When the server mentions a stage operator, Palryn lists matching enabled stage positions in the pipeline prefix that actually ran. These are hints rather than a guaranteed failing position: the operator may appear more than once or inside a nested pipeline. Error codes are never interpreted as stage numbers.

If a new run is rejected before returning its first batch, Palryn restores the earlier results and labels them as retained. Your pipeline draft stays intact. Export still uses those earlier results. If a later batch fails, the new partial results remain visible with an incomplete-read notice. Fix the issue and run explicitly to retry.

An output limit does not reduce work in earlier grouping or sorting stages. For timeouts, consider a narrower early match and appropriate indexes. For permission errors, check the saved connection's roles and the permissions required by the stages.

Palryn · Explore your data.
These guides describe Palryn v0.7.0. Available controls may differ in older versions.