Write an Entity Query - Nextedy Documentation

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:

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

Add a Filter with `where`

To restrict which entities are loaded, add a where clause to the query. The where clause uses filter predicates:

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:

# 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

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.

Add Sorting with `orderBy`

Control the default order in which the query returns entities by specifying property paths and directions:

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.

Add Expansion Paths

To load related entities (for multi-level hierarchical display), add an expand section to the source:

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:

expand:
  - name: systemRequirements
    title: System Requirements
    expand:
      - name: designRequirements
        title: Design Requirements

See Expand Navigation Properties for detailed guidance on multi-level expansion.

Limit Results with `take`

For performance, limit the number of entities returned:

sources:
  - id: userNeeds
    title: User Needs
    model: rtm-model
    query:
      from: UserNeed
      take: 100

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 for performance guidance.

Complete Example

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:

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

​Complete Example

​Verification

​See Also

Complete Example

Verification

See Also