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

# Baseline and Revision Queries

> Nextedy POWERSHEET supports querying historical data from Siemens Polarion ALM baselines and revisions.

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

## Revision Query Flow

<Frame>
  <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/reference/query-api/baseline-and-revision-queries/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=bd25a25341bdd6a06cf476b8d016c022" alt="diagram" style={{ width: "520px", maxWidth: "100%" }} width="520" height="200" data-path="powersheet/diagrams/reference/query-api/baseline-and-revision-queries/diagram-1.svg" />
</Frame>

## Revision Parameter

| Parameter  | Type      | Default | Description                                                                    |
| ---------- | --------- | ------- | ------------------------------------------------------------------------------ |
| `revision` | `integer` | `null`  | Document revision number to query. `null` means HEAD (latest). Must be `>= 0`. |

### URL Parameter

The revision is specified via the `revision` URL query parameter:

```
/polarion/#/project/MyProject/powersheet?document=Requirements/SystemReqs&revision=42
```

| Value                   | Behavior                             |
| ----------------------- | ------------------------------------ |
| Not specified           | Shows latest data (HEAD)             |
| `0` or positive integer | Shows data at the specified revision |

### Setting Revision Programmatically

The revision can be changed without a full page reload. The URL parameters are updated and the data is re-fetched at the new revision.

<Tip title="Revision Picker">
  Use the revision picker in the Powersheet UI to navigate between document revisions. Pass `undefined` to clear the revision and return to HEAD.
</Tip>

## Read-Only Mode

Historical revisions are always displayed in read-only mode. The sheet enters read-only mode when any of these conditions is true:

| Condition                      | Description                         |
| ------------------------------ | ----------------------------------- |
| `revision` is set              | Viewing a historical revision       |
| `config.isReadOnly` is `true`  | Configuration flag forces read-only |
| User has `readOnly` permission | Permission-based restriction        |

<Warning title="No Editing on Historical Revisions">
  When viewing a historical revision, all editing operations (cell editing, row creation, row deletion, save) are disabled. The sheet displays data as it existed at the specified revision.
</Warning>

## Query Execution with Revision

The query processor handles revisions at two levels:

### 1. Query Parameter Revision

The `revision` parameter in the entity query controls which historical version of the data is queried:

| Parameter Source           | Priority | Description                               |
| -------------------------- | -------- | ----------------------------------------- |
| Query parameter `revision` | Highest  | Explicitly set on the query               |
| Context baseline           | Lower    | Inherited from the query context baseline |

### 2. Configuration Processing

When a revision is active, the configuration processor:

* Injects the `revision` parameter into the main data source query
* Appends the revision number to the document display name (e.g., `SystemReqs (Rev 42)`)
* Sets the sheet to read-only mode

## Document Context with Revision

| Property          | Type      | Description                                                        |
| ----------------- | --------- | ------------------------------------------------------------------ |
| `document.full`   | `string`  | Full document path (`folder/name`). Does not change with revision. |
| `document.folder` | `string`  | Document folder/space component                                    |
| `document.name`   | `string`  | Document name component                                            |
| `revision`        | `integer` | Current revision number, or `null` for HEAD                        |

The document display name includes the revision when viewing historical data:

```
SystemReqs (42)
```

## Configuration URL with Revision

The configuration URL includes a cache-busting timestamp. When the revision changes, the configuration is re-fetched to ensure the correct version of the sheet configuration is loaded.

<Info title="Verify in application">
  Configuration re-fetching on revision change depends on the server's handling of revision-aware configuration. Verify that your Polarion server supports revision-specific configuration retrieval.
</Info>

## Entity Metadata at Revision

Entity query results at a specific revision include standard metadata fields:

| Field       | Type       | Description                                           |
| ----------- | ---------- | ----------------------------------------------------- |
| `objectId`  | `string`   | Unique entity identifier                              |
| `id`        | `string`   | Polarion work item ID                                 |
| `title`     | `string`   | Work item title at the specified revision             |
| `updated`   | `datetime` | Last modification timestamp at or before the revision |
| `projectId` | `string`   | Project foreign key                                   |

## Baseline vs. Revision

| Concept      | Description                                                                  |
| ------------ | ---------------------------------------------------------------------------- |
| **Revision** | A specific SVN revision number representing a point in the project's history |
| **Baseline** | A named project baseline that maps to a specific revision number             |

The query processor supports both approaches. The revision can come from an explicit query parameter or from a project baseline associated with the query context.

<Info title="Verify in application">
  The relationship between Polarion project baselines and SVN revision numbers depends on your Polarion server configuration. Consult your administrator for baseline-to-revision mapping.
</Info>

## Complete YAML Example

```yaml theme={null}
sources:
  - id: requirements
    title: System Requirements
    model: rtm
    query:
      from: UserNeed
      where: "type = 'UserNeed'"
    constraints:
      applyCurrentDocumentTo: UserNeed
    expand:
      - name: systemRequirements
        title: System Requirements
        expand:
          - name: systemRequirement

columns:
  id:
    width: 80
    sort: asc
  title:
    width: 300
    hasFocus: true
  systemRequirements.systemRequirement.title:
    width: 250
  systemRequirements.systemRequirement.severity:
    width: 100
```

When this configuration is loaded with `?revision=42` in the URL, the query processor:

1. Fetches `UserNeed` entities as they existed at revision 42
2. Expands `systemRequirements.systemRequirement` at the same revision
3. Displays the sheet in read-only mode
4. Shows the document name with revision suffix

## Related Pages

* [Query Context](/powersheet/reference/query-api/query-context) -- query parameter reference
* [EntityQuery](/powersheet/reference/query-api/entity-query) -- query structure and parameters
* [Document Filtering](/powersheet/reference/query-api/document-filtering) -- document-level query constraints

***

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