Everyday workflows

Relations & display properties

Connect fields to related documents and show readable labels beside reference values.

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

Right-click the source collection in Explorer and choose Collection tools → Relations…. For a view, use View tools → Relations….
Choose Create relation and give it a name such as “Customer”.
Set Source field path to customerId.
Set the target database to shop, collection to customers, and Target field to _id.
Optionally set Display property to name, 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

A display property is an optional field from the matching target document, such as name or profile.displayName. Palryn appends its value in teal square brackets after the original relation value in both table cells and expanded document fields.

customerId: 12345 [Alice Smith]

The stored ID stays visible and unchanged. Leave Display property blank to turn off automatic display lookups. Missing target documents, missing properties and failed lookups leave the original value without a label.

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.

Preview and open referenced documents

When a field has one unambiguous mapping, its chain-link button opens a reference preview. With multiple mappings, choose a named relation from the field's context menu. The preview shows the target and generated lookup filter.

Choose Open in new tab or Open to side to run a filtered query for the referenced documents. The source document and any source draft remain in place.

A typed ObjectId or UUID does not identify its collection by itself. Use Preview referenced documents…, choose the destination, then choose Preview. Save as relation… turns that choice into a reusable mapping. MongoDB DBRefs can supply their destination using $ref and optional $db.

Nested fields, arrays and reverse relations

Source path	Meaning
`customerId`	A top-level ID or an array of IDs.
`items[].productId`	The 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.