> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Dynamic Expressions

> Use dynamic expressions in Nextedy POWERSHEET sheet configurations and data models to resolve values at runtime based on the current document, user, URL parameters, or entity properties.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Prerequisites

* A working sheet configuration YAML file
* Familiarity with the [sheet configuration reference](/powersheet/reference/sheet-config/index) and [data model reference](/powersheet/reference/data-model/index)

## Understand the Two Expression Notations

Powersheet supports two distinct expression syntaxes, each used in a different configuration context:

| Notation               | Syntax                   | Used In                                            |
| ---------------------- | ------------------------ | -------------------------------------------------- |
| **Context expression** | `$context.property.path` | Data model configuration (constraints)             |
| **Dynamic value**      | `() => expression`       | Sheet configuration (where, formula, render, etc.) |

<Tip title="Rule of Thumb">
  If you are editing a **data model** YAML file (entity types, relationships), use `$context`. If you are editing a **sheet configuration** YAML file (sources, columns, formatters), use `() =>`.
</Tip>

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/guides/sheet-configuration/configure-dynamic-expressions/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=67d9bff79eb238a0545e31ac93fa9f48" alt="diagram" style={{ width: "620px", maxWidth: "100%" }} width="620" height="180" data-path="powersheet/diagrams/guides/sheet-configuration/configure-dynamic-expressions/diagram-1.svg" />
</Frame>

<Steps>
  <Step title="Add a Dynamic Where Clause to a Source Query">
    Dynamic where clauses let you filter source data using runtime values such as the current document or the current date.

    **Filter by the current document:**

    ```yaml theme={null}
    sources:
      - id: opportunities
        query:
          from: Opportunity
          where:
            Module:
              "==": "() => context.document.moduleName"
    ```

    When the sheet loads inside a LiveDoc, only records whose `Module` equals the current `moduleName` are returned.

    **Filter by today's date (show only future items):**

    ```yaml theme={null}
    sources:
      - id: tasks
        query:
          from: Task
          where:
            DueDate:
              ">": "() => new Date().toISOString()"
    ```

    <Warning title="Date Format Requirement">
      Dynamic date values must return ISO 8601 format. Always call `.toISOString()` on Date objects. Returning a raw Date object will cause the query to fail silently.
    </Warning>

    **Combine multiple document properties using template literals:**

    ```yaml theme={null}
    sources:
      - id: filtered
        query:
          from: EntityType
          where:
            Scope:
              "==": "() => `${context.document.moduleFolder}/${context.document.moduleName}`"
    ```
  </Step>

  <Step title="Set Dynamic Default Values with Entity Factory">
    Use `entityFactory` to pre-populate fields on newly created items with values resolved at runtime:

    ```yaml theme={null}
    sources:
      - id: userNeeds
        query:
          from: UserNeed
        entityFactory:
          type: "() => context.source.type + '_VerificationTestCase'"
          Status: Planned
    ```

    In this example, `type` is derived from the source entity's type at runtime (for instance, a `SystemRequirement` source yields `SystemRequirement_VerificationTestCase`), while `Status` receives the static value `Planned`.
  </Step>

  <Step title="Add a Calculated Column with Formula">
    The `formula` property computes a value from other properties on the current entity. The computed value is **persisted** back to the data source on save.

    ```yaml theme={null}
    columns:
      totalPrice:
        formula: "() => context.item.quantity * context.item.unitPrice"
        title: Total Price
        isReadOnly: true
        format: "c0$"
    ```

    The expression accesses entity properties through `context.item`. In this case it multiplies `quantity` by `unitPrice` each time the sheet refreshes.

    <Warning title="Formula vs. Render">
      `formula` modifies the **underlying data** -- the calculated value is saved. If you only need to change how a value is displayed without modifying stored data, use `render` instead.
    </Warning>
  </Step>

  <Step title="Add a Custom Renderer">
    Renderers produce custom HTML output for cell display. They do not affect persisted data.

    **Inline render expression on a column:**

    ```yaml theme={null}
    columns:
      Priority:
        render: "() => '<b>' + context.value + '</b>'"
        title: Priority
    ```

    **Named renderer definition (reusable across columns):**

    ```yaml theme={null}
    renderers:
      linkedItems: "() => context.value.map((item) => `<b>${item.name}</b>`).join(', ')"

    columns:
      relatedItems:
        render: linkedItems
        title: Related Items
    ```

    Named renderers are defined in the top-level `renderers` section and referenced by name in the column `render` property.
  </Step>

  <Step title="Configure Conditional Formatting">
    Formatters apply styles to cells based on a boolean expression. Unlike `formula` and `render`, formatter expressions use **simplified syntax** -- they do not start with `() =>`.

    ```yaml theme={null}
    formatters:
      criticalHighlight:
        expression: "context.item.Probability <= 99"
        style: warningStyle

    styles:
      warningStyle:
        color: red700
        backgroundColor: red100
        textDecoration: line-through
    ```

    Apply the formatter to a column:

    ```yaml theme={null}
    columns:
      Probability:
        title: Probability
        formatter: criticalHighlight
    ```

    The formatter context provides access to `context.document`, `context.item`, and `context.value`.
  </Step>

  <Step title="Use Context Expressions in Data Model Constraints">
    In data model YAML files, use the `$context` notation to create dynamic constraints that filter relationship data based on the source entity's properties.

    **Filter linked items to the same document component:**

    ```yaml theme={null}
    relationships:
      - from: DesignRequirement
        to: SystemRequirement
        back:
          name: designRequirements
          constraints:
            load:
              document:
                component: $context.source.document.component
    ```

    When viewing a `SystemRequirement` from the "Braking" component, only `DesignRequirement` items from "Braking" documents are loaded.

    **Filter by document name and folder:**

    ```yaml theme={null}
    constraints:
      load:
        document:
          moduleName: $context.source.document.moduleName
          moduleFolder: $context.source.document.moduleFolder
    ```

    **Constrain picker to same document type:**

    ```yaml theme={null}
    constraints:
      pick:
        document:
          type: $context.source.document.type
    ```

    <Tip title="Per-Row Evaluation">
      `$context` constraints are evaluated **per row**. Different rows can produce different constraint values depending on their source entity's properties. This enables context-sensitive filtering without separate configurations.
    </Tip>
  </Step>
</Steps>

## Context Object Reference

The `context` object provides different properties depending on where the expression is evaluated:

| Usage Location         | `.user` | `.sources` | `.document` | `.item` | `.value` | `.source` | `.entity` |
| ---------------------- | ------- | ---------- | ----------- | ------- | -------- | --------- | --------- |
| `where`                | ✅       | ✅          | ✅           | --      | --       | --        | --        |
| `entityFactory`        | ✅       | ✅          | --          | --      | --       | ✅         | --        |
| `formula`              | ✅       | ✅          | --          | ✅       | ✅        | ✅         | ✅         |
| `render` / `renderers` | --      | --         | --          | ✅       | ✅        | --        | --        |
| `formatter`            | --      | --         | ✅           | ✅       | ✅        | --        | --        |
| `display`              | --      | --         | --          | ✅       | ✅        | ✅         | --        |

Key context properties:

* **`context.user`** -- Current logged-in user (`id`, `name`)
* **`context.document`** -- Current document information (`title`, `type`, `id`, `moduleName`, `moduleFolder`, `component`)
* **`context.item`** -- Current entity with all its properties, e.g., `context.item.StoryPoints`
* **`context.source`** -- Parent/source entity in relationship contexts, including its `type`
* **`context.value`** -- Current cell's display value

## Verification

After saving your configuration changes:

1. Reload the sheet in Polarion
2. For **where clauses**: verify that only matching records appear (try opening the sheet inside different documents)
3. For **formulas**: confirm the calculated column shows correct values and updates when source fields change
4. For **renderers**: inspect cells for the expected HTML rendering
5. For **formatters**: verify that styling applies when the condition is met and disappears when it is not
6. For **\$context constraints**: expand a relationship and confirm that only items matching the source entity's document properties are loaded

You should now see dynamic values resolving correctly at runtime across all configured expression locations.

## See Also

* [Configure Sources](/powersheet/guides/sheet-configuration/configure-sources) -- set up data source queries including where clauses
* [Configure a Formatter](/powersheet/guides/sheet-configuration/configure-formatter) -- conditional styling reference
* [Apply Column Styles](/powersheet/guides/sheet-configuration/apply-style) -- define reusable style objects
* [Configure Constraints](/powersheet/guides/data-model/configure-constraints) -- full constraint configuration including `$context` patterns
* [Sheet Configuration Reference](/powersheet/reference/sheet-config/index) -- complete property reference for sheet YAML
* [Data Model Reference](/powersheet/reference/data-model/index) -- entity types, relationships, and constraint configuration

<LastReviewed date="2026-06-08" />