Dimensions and Row Shape

Dimensions divide an agent’s output into repeatable, structured results.

On this page

How dimensions change results

Without a dimension, an agent produces one resolved value for the whole project. Attach a dimension when the same value should be produced for several entities.

For example:

  • Revenue without a dimension produces one project-wide answer.
  • Revenue with a Year dimension produces one answer per year.
  • Invoice total with the system Document dimension produces one answer per invoice file.
  • Risk rating with Company and Year produces one answer for each company-and-year combination found by the agent.

Agents that describe the same underlying rows should share the same dimensions. This lets their results line up in the Table view.

Custom dimensions

Create a custom dimension from an agent’s Configure Output Structure step or through Manage Dimensions on the Agents page.

Custom dimensions can be:

  • Static: you provide the allowed values. Use this when the complete list is known, such as Q1, Q2, Q3, and Q4.
  • Dynamic: agents discover values from the documents. Use this for open-ended lists such as companies, policies, or clauses.

Give each dimension a description that explains what constitutes one instance. Clear descriptions help agents distinguish similar values and reuse the same row identity across agents.

The Document dimension

Document is a system-managed dimension whose values mirror the files in the project. Attach it to agents that should return a separate value for every source document.

Use it for batches of independent documents, such as invoices, claims, applications, or receipts. Do not attach it merely because a value has citations in several files: if those files collectively describe one subject, a consolidated result is usually more useful.

The Document dimension is configured per agent. In Manage Dimensions you can attach it to all current agents and choose whether new agents should receive it automatically.

Tag dimensions

Each document tag key becomes a system-managed dimension. Its values stay synchronized with the tag values assigned on the Documents page.

For example, documents tagged with region: EMEA and region: APAC make a region dimension available to agents. Attach that dimension to produce separate results for those groups.

When an agent has both a tag dimension and the Document dimension, the dimensions intersect: each row represents a document with its matching tag value.

Choose the right row shape

Use these rules of thumb:

  • No dimension when all documents contribute to one project-level answer.
  • Custom dimension when values repeat for semantic entities inside the documents.
  • Document dimension when each uploaded file is an independent subject.
  • Tag dimension when document metadata already defines the groups you need.

Prefer semantic dimensions such as Financial year or Company when users need to compare the same entity across files. Prefer Document when filenames themselves identify the rows.

Manage dimensions across agents

Open the Agents page actions menu and select Manage Dimensions to:

  • Attach a dimension to every agent.
  • Remove a dimension from all agents.
  • Automatically attach a dimension to agents created later.

You can still override the structure on an individual agent. Before applying a dimension broadly, check that every affected agent should produce the same row shape.

Changes that clear results

Attaching or detaching a dimension changes the identity of an agent’s results. Parsewise therefore clears the affected agent’s existing extractions and requires a new run.

Changes to a shared custom dimension can affect every agent that uses it. In particular, removing static values or switching between static and dynamic values can invalidate existing extractions. Review the confirmation dialog before saving, then relaunch affected agents.

Changing an agent’s dimensions also causes downstream derived agents to become pending and recompute after their dependencies finish.

Project-creation API flags

The API exposes per_document_mode and per_tag_mode when a project is created. These configure an initial project-wide row shape and are mutually exclusive. They cannot safely be flipped later with a normal project update because existing results already use the original shape.

In the app, use per-agent system dimensions for finer control. For API details, see the API FAQ.