> ## 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. # Document Filtering > Nextedy POWERSHEET supports document-level query filtering to scope data retrieval to work items within a specific Siemens Polarion ALM LiveDoc. 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

Last reviewed on {formatted}

; }; This reference covers the `applyCurrentDocumentTo` constraint, document scoping behavior for root and downstream entity types, and how filtering interacts with expansion paths and new entity creation. ## Document Filtering Overview diagram Document filtering is a constraint-based mechanism. When the `applyCurrentDocumentTo` constraint is defined on a data source, Powersheet automatically restricts results to items that belong to the LiveDoc in which the widget is rendered. The filter operates by matching the document's `moduleFolder` and `moduleName` properties against the current LiveDoc context. *** ## applyCurrentDocumentTo Constraint The `applyCurrentDocumentTo` property is defined within the `constraints` block of a data source configuration. It specifies which entity type should be restricted to only items contained within the current LiveDoc. | Property | Type | Default | Description | | ------------------------------------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `constraints.applyCurrentDocumentTo` | `string` | `null` | Entity type name that should be filtered to only include items belonging to the current document. When the Powersheet widget is rendered inside a LiveDoc, this constraint automatically restricts the named entity type to items within that document. | Use `applyCurrentDocumentTo` whenever the Powersheet widget is embedded in a LiveDoc and you want the sheet to display only items that belong to that specific document. Without this constraint, the query returns all matching items across the entire project. ### Constraint Properties Reference | Property | Type | Default | Description | | ------------------------------------ | -------- | --------------- | --------------------------------------------------------------------------------------------------------------- | | `constraints` | `object` | `null` | Container for all constraint definitions on a data source. | | `constraints.applyCurrentDocumentTo` | `string` | `null` | Entity type name to scope to the current document. Must match a valid entity type in the referenced data model. | | `constraints.project` | `string` | See application | Project constraint for filtering. Can use dynamic context labels for resolution. | | `constraints.document` | `string` | See application | Document constraint for filtering. Can use dynamic context labels for resolution. | Constraints on entity types combine with constraints defined on relationships. When both an entity type and a relationship define project or document constraints, they are merged with AND logic before query execution. *** ## Root Entity Filtering When `applyCurrentDocumentTo` matches the root entity type specified in `query.from`, the document filter applies directly to the primary query. This is the most common pattern: the sheet displays items of a single type that live in the current document. ```yaml theme={null} sources: - id: requirements title: System Requirements model: rtm query: from: SystemRequirement where: "type = 'UserNeed'" constraints: applyCurrentDocumentTo: SystemRequirement expand: - name: designRequirements title: Design Requirements expand: - name: designRequirement ``` In this configuration: * `SystemRequirement` is both the root query entity and the document-filtered entity * Only `SystemRequirement` items that belong to the current LiveDoc are returned * Expanded `DesignRequirement` items are fetched through the relationship regardless of which document they belong to ### How Root Filtering Works 1. The widget reads the current LiveDoc context (module folder and module name) 2. The constraint system detects that `applyCurrentDocumentTo` matches the `query.from` entity type 3. A document filter predicate is automatically injected into the query's where clause 4. The query returns only items from the specified document *** ## Downstream Entity Filtering When `applyCurrentDocumentTo` targets a related entity type (not the root `query.from` entity), the constraint applies to the downstream entity within the expansion path. The root entity type is queried without document restriction. ```yaml theme={null} sources: - id: needs title: User Needs model: rtm query: from: UserNeed where: "type = 'UserNeed'" constraints: applyCurrentDocumentTo: SystemRequirement expand: - name: systemRequirements title: System Requirements expand: - name: systemRequirement ``` In this configuration: * `UserNeed` is the root entity type and is **not** document-filtered * `SystemRequirement` is the downstream entity type scoped to the current document * The sheet shows all `UserNeed` items matching the where clause, but only expands to `SystemRequirement` items that belong to the current LiveDoc The entity type name specified in `applyCurrentDocumentTo` must be a valid entity type defined in the referenced data model. If the entity type is not found, the constraint is silently ignored and no document filtering is applied. ### Downstream Filtering Scenarios | Root Entity | Filtered Entity | Behavior | | ----------- | ------------------- | -------------------------------------------------------------------------------------------------------- | | `UserNeed` | `UserNeed` | Root filtering -- only `UserNeed` items in current document | | `UserNeed` | `SystemRequirement` | Downstream filtering -- all `UserNeed` items, but `SystemRequirement` expansion scoped to document | | `UserNeed` | `DesignRequirement` | Deep downstream -- `UserNeed` and `SystemRequirement` unfiltered, `DesignRequirement` scoped to document | | `Hazard` | `RiskControl` | Risk model -- all `Hazard` items shown, `RiskControl` expansion scoped to document | *** ## Document Context Variables When document filtering is active, the following context information is available for use within query expressions and dynamic value resolution: | Variable | Description | | ----------------------- | -------------------------------------------------------------------------------------- | | `document.moduleFolder` | The space (folder) of the current LiveDoc in Polarion (e.g., `Requirements`) | | `document.moduleName` | The name of the current LiveDoc (e.g., `SystemRequirements`) | | `document.id` | Full document path combining folder and name (e.g., `Requirements/SystemRequirements`) | These variables are automatically populated when the Powersheet widget is rendered inside a LiveDoc. They are used internally by the document filter and are also available via `$context.document.id` expressions in dynamic value configurations. The exact format of `document.id` depends on the Polarion space configuration. For documents in the default space (`_default`), the space prefix may be omitted from the document ID. *** ## Document Filtering with New Entities When `applyCurrentDocumentTo` is configured and a user creates a new entity through the sheet, the document constraint is automatically applied to the new item's initial values. This ensures newly created items are scoped to the current document without manual intervention. | Behavior | Description | | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | Automatic document assignment | New entities of the type specified in `applyCurrentDocumentTo` receive the current document's `documentId` as an initial property value | | Scope inheritance | The new entity is created within the same LiveDoc context as the current document, maintaining document-centric data integrity | | Constraint enforcement | If `applyCurrentDocumentTo` targets the root entity type, new items are automatically assigned to the current document | ```yaml theme={null} sources: - id: requirements title: Requirements model: rtm query: from: SystemRequirement constraints: applyCurrentDocumentTo: SystemRequirement expand: - name: designRequirements title: Design Requirements expand: - name: designRequirement ``` With this configuration, when a user adds a new `SystemRequirement` through the sheet, it is automatically placed in the current LiveDoc. *** ## Constraint Propagation Document constraints defined on entity types propagate to related navigation properties during query expansion. This propagation determines how document scoping applies across the full expansion path. | Source | Propagation Rule | | ------------------------------- | ----------------------------------------------------------------------------------------- | | Entity type constraints | Extracted from constraint annotations on the entity type | | Navigation property constraints | Merged from both the navigation property annotation and the target entity type annotation | | Combined result | AND-combined predicate validated against entity type metadata | When both an entity type and its relationship define document constraints, the system merges them. For many-to-many relationships traversed through association types, the constraint resolver unwraps the association to reach the target entity type and applies the combined constraint there. *** ## Data Model Constraint Configuration Document constraints can also be defined at the entity type level in the data model YAML, independent of the sheet configuration's `applyCurrentDocumentTo`. These constraints apply to all queries against the entity type across every sheet configuration that references the model. ```yaml theme={null} domainModelTypes: SystemRequirement: polarionType: systemRequirement constraints: load: document: moduleFolder: Requirements type: requirements_specification pick: document: moduleFolder: Requirements moduleName: Categorized ``` | Constraint Level | Purpose | Applied When | | ----------------- | ---------------------------------------------- | ------------------------------------------- | | `load.document` | Filters entities during initial data loading | Sheet loads data for display | | `pick.document` | Filters entities in picker dropdown selections | User opens a relationship picker | | `create.document` | Sets default document values for new entities | User creates a new entity through the sheet | Data model constraints (`load`, `pick`, `create`) define **static** document filters based on known folder or document names. In contrast, `applyCurrentDocumentTo` is **dynamic** -- it uses the current LiveDoc context at runtime. Both mechanisms can coexist; they are combined with AND logic. See [Constraints](/powersheet/reference/data-model/constraints) for the full constraint configuration reference. *** ## Complete YAML Example The following example demonstrates a full sheet configuration with document filtering applied to a requirements traceability matrix (RTM): ```yaml theme={null} sources: - id: user-needs title: User Needs model: rtm query: from: UserNeed where: "type = 'UserNeed'" constraints: applyCurrentDocumentTo: UserNeed expand: - name: systemRequirements title: System Requirements expand: - name: systemRequirement expand: - name: designRequirements title: Design Requirements expand: - name: designRequirement - id: hazards title: Hazards model: risk query: from: Hazard where: "type = 'UserNeed'" constraints: applyCurrentDocumentTo: Hazard expand: - name: riskControls title: Risk Controls expand: - name: riskControl columns: id: width: 80 sort: asc title: width: 300 hasFocus: true systemRequirements.systemRequirement.title: width: 250 systemRequirements.systemRequirement.severity: width: 100 ``` This configuration defines two data sources: 1. **User Needs** source with root-level document filtering on `UserNeed` and a three-level expansion path: `UserNeed` > `SystemRequirement` > `DesignRequirement` 2. **Hazards** source with root-level document filtering on `Hazard` and a single-level expansion to `RiskControl` Both sources restrict their root entity type to items within the current LiveDoc while allowing expanded entities to come from any document. *** ## Interaction with Other Constraints Document filtering via `applyCurrentDocumentTo` works alongside other constraint types defined in the data model and sheet configuration: | Constraint Type | Interaction with Document Filtering | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Project constraints | Applied independently. Both project and document constraints must be satisfied for an item to appear. | | Entity type constraints | Merged with AND logic. Data model constraints on the entity type combine with the document filter. | | Relationship constraints | Navigation property constraints on project or document are combined with entity-level constraints when expanding related items. | | Security permissions | Checked before any query execution. If the current user lacks read permission (`isReadOnly`) for the entity type, the query is rejected regardless of document filtering. | When both an entity type and its relationship define document constraints, the constraints are combined. Ensure that the constraint definitions do not conflict or create overly restrictive filters that return empty results. *** ## Constraint Resolution with Navigation Properties When document filtering targets a downstream entity type, the constraint must be resolved through the expansion path. The system resolves the path from the root entity type to the filtered entity type by traversing navigation properties defined in the data model. ```yaml theme={null} # Data model relationship (direct direction) relationships: - name: systemRequirements source: UserNeed target: SystemRequirement type: manyToMany ``` For the expansion path `UserNeed` > `systemRequirements` > `systemRequirement`, the constraint resolver: 1. Starts at the root entity type (`UserNeed`) 2. Follows the `systemRequirements` navigation property (direct direction) 3. Reaches `SystemRequirement` and applies the document filter The resolution supports multi-level dot-notation paths (e.g., `systemRequirements.systemRequirement.designRequirements`) for deep navigation hierarchies. *** ## Behavior Without Document Context When the Powersheet widget is rendered outside a LiveDoc context (for example, in a Wiki page or a standalone widget), the document filter has no effect: | Scenario | Behavior | | -------------------------- | ------------------------------------------------------------------------------------- | | Widget in LiveDoc | `applyCurrentDocumentTo` actively filters by current document | | Widget in Wiki page | No document context available; constraint is ignored, all matching items returned | | Widget with URL parameters | URL parameters (e.g., `masterItemId`) are applied independently of document filtering | When developing sheet configurations outside a LiveDoc, remember that document filtering is inactive. Validate filtering behavior by embedding the widget in the target LiveDoc. *** ## Related Pages * [EntityQuery](/powersheet/reference/query-api/entity-query) -- query structure and `from` clause reference * [Predicates](/powersheet/reference/query-api/predicates) -- where clause predicate syntax * [Expand Clause](/powersheet/reference/query-api/expand-clause) -- expansion path configuration * [Query Context](/powersheet/reference/query-api/query-context) -- context variables and parameter passing * [Constraints](/powersheet/reference/data-model/constraints) -- data model constraint definitions * [Sources](/powersheet/reference/sheet-config/sources) -- data source configuration reference * [Navigation Directions](/powersheet/reference/data-model/navigation-directions) -- direct and back relationship traversal ***