Phials documentation
Developer docs

Link files with Relation properties

Relation properties let you attach wiki-style links from any file in a Vial to one or more files in any known Vial, including the same one. Stored links follow files even when you rename or move them inside their Vial. Incoming links appear in the Preview sidebar as Linked by.

Prerequisites

You must be browsing inside a Vial (see Create and manage a Vial). For links that point into another folder, that folder should be a Vial too, and both Vials should be registered as Known Vials so Phials can resolve paths and navigate between them smoothly.

For how property schemas work in general, see Properties in a Vial.

Create a Relation property

  1. On the Vial toolbar, open the Schema Editor: use + (Add property) or Configure properties (gear).
  2. In the property type picker, choose Relation.
  3. When prompted, pick the target Vial, the Vial whose files this property will link into. This can be the current Vial or a different one.
  4. Optionally change the property’s display name before saving.
  1. Select a file in the Vial (or open its row in Details view).
  2. In the Preview sidebar Properties section, or wherever that relation property appears, use the relation editor.
  3. Pick one or more target files from the configured target Vial. You can add more targets later or remove existing ones.

The picker is scoped to files Phials has indexed in the target Vial.

Every relation field can hold many targets at once. Each target shows a filename and resolves to the correct file because Phials tracks stable identifiers, so renaming or moving the source or target within its own Vial does not break the link.

When you select a file inside a Vial, the preview sidebar can show Linked by (N) below Properties (see File Previews).

  • The section lists other files in that same Vial that link to the selected file, and shows which relation property created each link.
  • It appears only when at least one such backlink exists.
  • Choosing a row jumps to that linking file’s Vial folder so you can open it from there.

Cross-Vial caveat: Linked by is built from the current Vial’s metadata. A relation on Vial A that points into Vial B stores its values on A’s files, so when you browse the target file only inside B, Linked by there will not list the linker on A. To follow that link in the other direction, open Vial A (register both as Known Vials if needed) or use the relation field on the source file. In practice you mostly use Linked by when both ends of the relationship live in the same Vial.

A relation stores which Vial you picked as the target using a stable Vial identity Phials saves with the property, so if the target Vial’s folder is moved or renamed on disk, links can still resolve (with the folder path used as a fallback where needed).

For navigation and pickers to work reliably across folders, register both the source and target Vials under Known Vials (see Create and manage a Vial).

Change or delete a Relation property

Rename, reorder, or remove relation properties from gear → Configure properties on the Vial toolbar. Step-by-step schema editing is covered in Properties in a Vial.

Deleting a relation property removes all stored link values for that property on every file in that Vial. Phials does not offer an undo for that; restore from backups if you need the old values back.

Tips / common questions

  • You can link a file to itself, to another file in the same Vial, or to files in other Vials, depending on how you configured the property’s target Vial.
  • Links survive renames and moves inside each Vial because Phials tracks stable file identities, not just paths on disk.
  • For smooth cross-Vial navigation, keep related folders registered as Known Vials.
  • If Linked by is missing a link you expect, confirm you are viewing the file from the Vial that owns the relation. Backlinks are listed per Vial, not globally across every folder.