Dimension Set Entries Realtime-enabled
GETTable: Dimension Set Entry
Read-only. Resolves a dimensionSetId into the dimensions it holds, with codes and names. This is what makes dimensional reporting possible: every document, line, journal line and ledger entry publishes a dimensionSetId, and one join on it returns that record's complete dimension picture however many dimensions the company uses.
Why you need it
Business Central does not store a document's dimensions on the document. It stores a Dimension Set ID - an integer naming a set of (dimension, value) pairs - and the pairs live in this feed.
Without it, the only dimension data available to a reader is the eight flat shortcutDimension1Code..shortcutDimension8Code columns. Those exist for a reason and are not going away: a flat column per value is what an integration can send, so they are the write path, and they filter well. But as a reporting source they have three limits:
- they stop at eight, so a company using a ninth dimension has data you cannot see
- they carry codes only, no names
- which dimension sits in which slot is a per-company setup choice, so
shortcutDimension3Codemeans something different at every customer
Reading through dimensionSetId has none of those problems, and a company that adds a dimension needs no change at either end.
The join
GET salesOrders?$select=number,dimensionSetId
GET dimensionSetEntries?$filter=dimensionSetId eq 1043One row comes back per dimension on the set:
| dimensionSetId | dimensionCode | dimensionName | dimensionValueCode | dimensionValueName | globalDimensionNumber |
|---|---|---|---|---|---|
| 1043 | DEPARTMENT | Department | SALES | Sales Department | 1 |
| 1043 | AREA | Area | 30 | Europe North | 2 |
| 1043 | PROJECT | Project | ALPHA | Project Alpha | 0 |
globalDimensionNumber is the slot the dimension occupies among the company's eight shortcuts, or 0 when it is not one of them. It is the column that lines this feed up with the flat shortcutDimensionNCode values, and the one that tells you a dimension exists outside them.
Both names are denormalized onto every row, so a report needs no second lookup against dimensions or dimension values.
Sets are immutable
Changing a document's dimensions does not edit its set. Business Central finds or creates a set matching the new combination and points the document at it. So entries are never updated and never deleted, the feed is append-only, and a row you have already read never needs re-reading.
That also means dimensionSetId is not stable across documents in any meaningful way beyond "these two records carry the same dimensions" - which is exactly what you want for grouping.
Not the same as dimensionSetLines
dimensionSetLines is the write collection: it sets dimensions beyond the eight shortcuts on one document line, and it is keyed by that line's record id. It is not a lookup, and you cannot resolve a dimensionSetId through it. Use this endpoint for reading and that one for writing.
Volume
One row per dimension per distinct combination, so the row count tracks how many different dimension combinations the company has ever used rather than how many documents it has. In practice that is thousands, not millions, and it only grows when a genuinely new combination is posted.