Inside CALCULAR: keeps only the top N rows by the expression — or the top N groups, if you provide the column. A tie at the boundary is included in full (may exceed N).
| Field | Value |
|---|---|
| Category | Context and filter |
| Type | Aggregation (operates on a set of rows) |
| Arity | 2 to 4 arguments |
| Compiles to SQL (calculated column) | No |
| Version | Formula engine v3. |
Aliases#
Canonical name: PRIMEIROS_N. Accepted aliases (case-insensitive): topn.
Syntax#
PRIMEIROS_N(expr; arg2; [arg3]; [arg4])All arguments are expressions.
Returns#
CALCULAR modifier (keeps the top N rows/groups).
Null handling#
When there is no row in the changed context, it returns blank (never zero) — a blank is more honest than a made-up zero.
Evaluation context#
Modifier — only makes sense INSIDE CALCULAR (or another context function that accepts it). Outside of that, it warns you instead of returning a wrong number.
Differences from DAX#
- DAX equivalent: TOPN
- Compatibility: Compatible with DAX
- Note: A tie at the boundary is included in full (may exceed N), same as TOPN. Used as a CALCULAR modifier.
Examples#
CALCULAR(SOMA(receita); TUDO(); PRIMEIROS_N(3; SOMA(receita); uf))Example with values#
Input: sum of the largest only (SP=60) between SP and RJ.
CALCULAR(SOMA(receita); PRIMEIROS_N(1; receita)) → 60Expected result: 60
Business example#
Comparative measure — share of total, ranking, change versus another period.
Common errors#
Typos in a column name, an incompatible type, or an invalid argument become a friendly message (pt-BR) — the engine never silently returns a wrong number.