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

# Write an Entity Query

> Define a source query in your Nextedy POWERSHEET sheet configuration that fetches entities from the data model and populates the sheet with data.

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

<Steps>
  <Step title="Add a Source Entry">
    Open your sheet configuration YAML and add an entry to the `sources` array. Each source requires an `id`, `title`, `model`, and `query`:

    ```yaml theme={null}
    sources:
      - id: userNeeds
        title: User Needs
        model: rtm-model
        query:
          from: UserNeed
    ```

    | Property     | Purpose                                                                                      |
    | ------------ | -------------------------------------------------------------------------------------------- |
    | `id`         | Unique identifier for this data source                                                       |
    | `title`      | Display label shown in the sheet UI                                                          |
    | `model`      | Reference to the data model ID (defined in **Administration > Nextedy Powersheet > Models**) |
    | `query.from` | Entity type name from the data model to query                                                |

    The `from` value must match an entity type defined in your data model (e.g., `UserNeed`, `SystemRequirement`, `Hazard`).
  </Step>

  <Step title="Add a Filter with `where`">
    To restrict which entities are loaded, add a `where` clause to the query. The `where` clause uses filter predicates:

    ```yaml theme={null}
    sources:
      - id: userNeeds
        title: User Needs
        model: rtm-model
        query:
          from: UserNeed
          where:
            status:
              ne: deleted
    ```

    This loads only `UserNeed` entities whose `status` is not `deleted`.

    Common filter patterns:

    ```yaml theme={null}
    # Equality
    where:
      severity: critical

    # Not equal
    where:
      status:
        ne: deleted

    # Null check (has value)
    where:
      title:
        ne: null

    # Combined conditions (AND)
    where:
      and:
        - severity: critical
        - status: approved
    ```

    <Info title="Verify in application">
      The exact predicate syntax supported in `where` clauses depends on the query engine. Simple equality and comparison operators are widely supported. For complex predicate patterns, see [Use Predicates](/powersheet/guides/queries/use-predicates).
    </Info>
  </Step>

  <Step title="Add Sorting with `orderBy`">
    Control the default order in which the query returns entities by specifying property paths and directions:

    ```yaml theme={null}
    sources:
      - id: userNeeds
        title: User Needs
        model: rtm-model
        query:
          from: UserNeed
          orderBy:
            - id asc
    ```

    Append `desc` after the property path for descending order. The `orderBy` clause governs the order of results produced by the query itself, which also determines the default order in which pickers and other query consumers present entities.
  </Step>

  <Step title="Add Expansion Paths">
    To load related entities (for multi-level hierarchical display), add an `expand` section to the source:

    ```yaml theme={null}
    sources:
      - id: userNeeds
        title: User Needs
        model: rtm-model
        query:
          from: UserNeed
        expand:
          - name: systemRequirements
            title: System Requirements
    ```

    Expansion paths follow the navigation properties defined in your data model. For deeper hierarchies, nest expansions:

    ```yaml theme={null}
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: designRequirements
            title: Design Requirements
    ```

    See [Expand Navigation Properties](/powersheet/guides/queries/expand-navigation-properties) for detailed guidance on multi-level expansion.
  </Step>

  <Step title="Limit Results with `take`">
    For performance, limit the number of entities returned:

    ```yaml theme={null}
    sources:
      - id: userNeeds
        title: User Needs
        model: rtm-model
        query:
          from: UserNeed
          take: 100
    ```

    <Warning title="Large queries affect performance">
      Queries without a `take` limit or a `where` filter may load thousands of work items, causing slow sheet loading. Always apply appropriate filters for production configurations. See [Optimize Queries](/powersheet/guides/queries/optimize-queries) for performance guidance.
    </Warning>
  </Step>
</Steps>

## Complete Example

```yaml theme={null}
sources:
  - id: rtm-source
    title: Requirements Traceability
    model: rtm-model
    query:
      from: UserNeed
      where:
        status:
          ne: deleted
      orderBy:
        - id asc
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: designRequirements
            title: Design Requirements
```

## Verification

After saving the sheet configuration and opening the associated document:

1. You should now see the sheet populated with entities matching your query
2. Expanded relationships should display as nested rows beneath parent items
3. The row count should reflect the filter criteria in your `where` clause

## See Also

* [Use Predicates](/powersheet/guides/queries/use-predicates) -- advanced filtering with comparison and logical operators
* [Expand Navigation Properties](/powersheet/guides/queries/expand-navigation-properties) -- multi-level relationship expansion
* [Filter by Document](/powersheet/guides/queries/filter-by-document) -- scope queries to the current document
* [Configure Sources](/powersheet/guides/sheet-configuration/configure-sources) -- full source configuration reference
* [Add a Column](/powersheet/guides/sheet-configuration/add-column) -- configure sorting and column properties at the sheet level

<LastReviewed date="2026-07-02" />