Everyday workflows

Relations & display templates

Connect fields to related documents and build readable labels with display templates.

What is a relation?

A relation tells Palryn how a value in one document refers to documents in another collection or view on the same saved connection. For example, shop.orders.customerId can refer to shop.customers._id.

Relations are local navigation definitions. They do not create MongoDB constraints or change either document. Definitions are shared across that connection's direct and named workspaces and follow Remember workspace state.

Define your first relation

  1. Right-click the source collection in Explorer and choose Collection tools → Relations…. For a view, use View tools → Relations….
  2. Choose Create relation and give it a name such as “Customer”.
  3. Set Source field path to customerId.
  4. Set the target database to shop, collection to customers, and Target field to _id.
  5. Optionally set Display template to {name} or {FirstName} {LastName}, then choose Save relation.

You can also right-click a result column, cell or expanded property and choose Define relation…. This pre-fills the source field path.

Show a readable name beside an ID

Display template replaces the former Display property field. Combine case-sensitive fields and literal text from the matching target document, such as {FirstName} {LastName}, {Name} ({Code}) or {profile.displayName} — {email}. Palryn appends the summary in square brackets using the selected theme's accent colour after the original relation value in both table cells and expanded document fields. Existing display property settings migrate automatically: profile.name becomes {profile.name}.

customerId: 12345 [Alice Smith]

The stored ID stays visible and unchanged. Leave Display template blank to turn off automatic display lookups. Missing placeholders are omitted, empty parentheses around missing fields are removed, and template whitespace is cleaned up as in object summaries. An empty summary, missing target or failed lookup leaves the original value without a label. Literal-only templates show their text when a target matches.

Repeated values share a bounded, memory-only lookup cache within a query result. Rerun the query to refresh the labels. If several target documents match, their display values are separated by semicolons; an ellipsis indicates more matches beyond the lookup limit. Dotted display paths traverse objects; array-valued properties use a compact summary.

Each field preview is limited to 80 characters and each target summary to 160, for up to 20 matching documents. Adding more fields does not add database requests. {$fieldCount} shows the target document's field count, and {["literal.key"]} selects a literal dotted field name. Templates never execute JavaScript. The relation's own Name is still its navigation label.

Preview and open referenced documents

When a field has one unambiguous mapping, its chain-link button opens Referenced documents. The popup shows Connection, Source and Relation, then automatically loads the matching documents. DBRef references show “DBRef” as the relation. The right-click menu offers Define relation… to configure a mapping; manage multiple mappings through the collection's Relations… dialog.

Use the footer to Close, Open in new tab or Open to side. The open actions run a filtered query for the referenced documents; the source document and any source draft remain in place. Loading, empty results and lookup errors are shown in the popup. Close and reopen it to retry a failed lookup.

A typed ObjectId or UUID does not identify its collection by itself. Use Define relation… to set up the destination, then follow the chain-link button. MongoDB DBRefs can supply their destination using $ref and optional $db.

Nested fields, arrays and reverse relations

Source pathMeaning
customerIdA top-level ID or an array of IDs.
items[].productIdThe product ID inside every object in the items array.
["literal.key"]A field whose name literally contains a dot.

For a reverse relation, map a customer's source _id to the target orders.customerId field: target collection orders, target field customerId. This can return many matching orders. Targets can be in another database on the same connection.

Lookups preserve BSON types and accept up to 100 scalar IDs or consistent DBRefs at a time. Previews show up to 20 matching documents within a byte/time budget; open a query tab to page through additional matches. Cross-profile joins and automatic guessing of target collections are not part of this workflow.

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