> ## 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 Sources

> Define data sources in your Nextedy POWERSHEET sheet configuration to control which entities are loaded, how they are filtered, and which relationships are expanded for display in the sheet.

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>;
};

## Define a Basic Source

The `sources` section is an array at the root level of your sheet configuration YAML. Each source specifies a unique identifier, the data model it queries against, a query targeting an entity type, and optional expansion paths:

```yaml theme={null}
sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
```

| Property        | Required | Description                                                                    |
| --------------- | -------- | ------------------------------------------------------------------------------ |
| `id`            | Yes      | Unique identifier for the source, referenced from tool settings                |
| `model`         | Yes      | Data model name the source queries (must match a configured model, e.g. `rtm`) |
| `query.from`    | Yes      | Root entity type to query (must exist in the data model)                       |
| `query.where`   | No       | Filter predicate to restrict which entities are loaded                         |
| `query.orderBy` | No       | Server-side sort order for the query results                                   |
| `query.take`    | No       | Maximum number of root entities to load                                        |
| `expand`        | No       | Array of expansion paths for loading related entities                          |
| `entityFactory` | No       | Default property values applied when creating new entities                     |

<Tip title="Use the Model Helper to verify bindings">
  The Model Helper widget visualizes the data model structure and correct expansion paths. See [Use Model Helper Widget](/powersheet/guides/customization/use-model-helper) for details.
</Tip>

## Expand Relationships

The `expand` array defines which related entities are loaded alongside the root entity. Each entry uses the `name` property corresponding to a navigation property from your data model relationships:

```yaml theme={null}
sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement
```

Nested `expand` entries create multi-level hierarchies. The expansion path structure must match the `direct` and `back` navigation property names defined in your data model relationships.

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

<Warning title="Start simple, extend incrementally">
  Begin with a single-level expansion and verify it loads correctly before adding deeper levels. Jumping straight to complex multi-level expansions leads to hard-to-diagnose errors that are difficult to trace.
</Warning>

### Expansion by Cardinality

The cardinality of a relationship determines the expand pattern and how columns bind to expanded data:

| Cardinality            | Model Direction          | Source Expand                                                 | Column Binding                         | UI Behavior                   |
| ---------------------- | ------------------------ | ------------------------------------------------------------- | -------------------------------------- | ----------------------------- |
| **N:1** (many-to-one)  | `direct` name (singular) | `- name: chapter`                                             | `chapter`, `chapter.title`             | Single-value reference picker |
| **1:N** (one-to-many)  | `back` name (plural)     | `- name: userNeeds`                                           | `userNeeds`                            | Child rows (new sheet level)  |
| **M:N** (many-to-many) | `back` name (plural)     | `- name: systemRequirements` then `- name: systemRequirement` | `systemRequirements.systemRequirement` | Multi-item reference picker   |

For many-to-many relationships, the expand must go through the association entity first, then to the target entity. This two-level expand pattern is required:

```yaml theme={null}
expand:
  - name: systemRequirements       # association collection
    expand:
      - name: systemRequirement    # target entity
```

For a complete walkthrough of expansion patterns, see [Expand Navigation Properties](/powersheet/guides/queries/expand-navigation-properties).

## Filter with a WHERE Clause

Use the `query.where` property to restrict which entities are loaded. The where clause uses predicate syntax:

```yaml theme={null}
sources:
  - id: active_needs
    model: rtm
    query:
      from: UserNeed
      where:
        severity:
          "!=": "low"
    expand:
      - name: systemRequirements
```

You can also use dynamic value expressions with the `() =>` arrow function syntax to build runtime-evaluated filters. For example, to filter by a date or a document parameter:

```yaml theme={null}
sources:
  - id: recent_items
    model: rtm
    query:
      from: UserNeed
      where:
        dueDate:
          ">": "() => new Date().toISOString()"
```

```yaml theme={null}
sources:
  - id: filtered_by_param
    model: rtm
    query:
      from: UserNeed
      where:
        Client:
          "==": "() => `${context.parameters.client}`"
```

<Note title="Dynamic expression format">
  The `() =>` notation evaluates at runtime. For date predicates, ensure the expression returns an ISO string using `.toISOString()`. For parameters, use `context.parameters.<name>` to inject values from the document configuration.
</Note>

## Set Default Values with Entity Factory

The `entityFactory` property defines default property values applied when a user creates a new entity from the sheet. This works at any expand level:

```yaml theme={null}
sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
    entityFactory:
      Status: "Planned"
      Priority: "Medium"
    expand:
      - name: systemRequirements
        entityFactory:
          Status: "Draft"
        expand:
          - name: systemRequirement
```

Entity factory values can also use dynamic expressions:

```yaml theme={null}
entityFactory:
  Client: "() => context.parameters.client"
```

## Configure Multiple Sources

A sheet configuration can define multiple sources. Each source must have a unique `id` and reference a `model`:

```yaml theme={null}
sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement

  - id: hazards
    model: rtm
    query:
      from: Hazard
    expand:
      - name: riskControls
        expand:
          - name: riskControl
```

Multiple sources allow a single sheet to display data from different parts of the data model, each with its own query filters and expansion hierarchy.

## Limit Results with Take

Use `query.take` to cap the number of root entities returned by a source. This is useful for large datasets where loading all entities would impact performance:

```yaml theme={null}
sources:
  - id: top_items
    model: rtm
    query:
      from: UserNeed
      take: 100
      orderBy: severity desc
    expand:
      - name: systemRequirements
```

<Tip title="Combine take with orderBy">
  When using `take` to limit results, pair it with `orderBy` so you control which entities are included. Without ordering, the subset returned is unpredictable.
</Tip>

## Complete Configuration Example

Here is a full sources section for a requirements traceability matrix that queries user needs, expands through system requirements to design requirements, and sets default values for new entities:

```yaml theme={null}
sources:
  - id: user_needs
    model: rtm
    query:
      from: UserNeed
      where:
        severity:
          "!=": "low"
      orderBy: title asc
    entityFactory:
      Status: "Planned"
    expand:
      - name: systemRequirements
        expand:
          - name: systemRequirement
            entityFactory:
              Status: "Draft"
            expand:
              - name: designRequirements
                expand:
                  - name: designRequirement
```

## Verify Your Configuration

After saving your sheet configuration YAML:

1. Open the Powersheet document in Polarion
2. The sheet should load and display the root entities defined by `query.from`
3. Verify that expansion arrows appear on rows -- clicking them loads related entities at each level
4. Create a new entity to confirm `entityFactory` defaults are applied correctly
5. If using `where` filters, confirm that only matching entities appear

You should now see the sheet populated with your source data and the expansion hierarchy matching your data model relationships.

## See Also

* [Expand Navigation Properties](/powersheet/guides/queries/expand-navigation-properties) -- detailed guide on expansion paths and cardinality patterns
* [Add a Column](/powersheet/guides/sheet-configuration/add-column) -- bind columns to properties from your expanded sources
* [Configure a Relationship](/powersheet/guides/data-model/configure-relationship) -- set up `direct` and `back` navigation properties in the data model
* [Use Model Helper Widget](/powersheet/guides/customization/use-model-helper) -- visual tool for exploring data model structure
* [Configure Dynamic Expressions](/powersheet/guides/sheet-configuration/configure-dynamic-expressions) -- full reference on `() =>` expression syntax and the context object
* [Write an Entity Query](/powersheet/guides/queries/write-entity-query) -- query syntax for `from`, `where`, and `orderBy` clauses

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