# Field Metadata
URL: https://pro.rv-grid.com/guides/pivot/concepts/field-metadata/
Source: src/content/docs/guides/pivot/concepts/field-metadata.mdx
Description: Configure Pivot field labels, hidden dimensions, empty group labels, measure aliases, and selective subtotals.
Field metadata is the information Pivot uses to describe fields before they become row groups, column groups, filters, or measures. Use it to give users clearer labels, keep internal fields out of normal field lists, and make generated totals easier to read.

## Hidden Dimensions

Mark a dimension as `hidden` when it should still be available to the Pivot config but should not appear in normal field lists.

```ts
const dimensions = [
  { prop: 'region', name: 'Region' },
  { prop: 'quarter', name: 'Quarter' },
  {
    prop: 'internalSegment',
    name: 'Internal Segment',
    description: 'Internal reporting segment.',
    hidden: true,
  },
];

const pivot = {
  dimensions,
  rows: ['region'],
  columns: ['quarter', 'internalSegment'],
  filters: ['internalSegment'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
};
```

Hidden does not remove the field from the Pivot engine. In this example, `internalSegment` can still be used in `columns` and `filters`; it is only hidden from helper-driven field lists unless you explicitly show hidden fields.

## Show Hidden Fields In Search

Use `filterPivotDimensions` for searchable field lists. Hidden dimensions are omitted by default. Pass `{ showHidden: true }` when you want an admin or advanced-user mode that reveals them.

```ts
import { filterPivotDimensions } from '@revolist/revogrid-enterprise';

const visibleFields = filterPivotDimensions(dimensions, searchText);

const allFields = filterPivotDimensions(dimensions, searchText, {
  showHidden: true,
});
```

The helper searches `prop`, `name`, and `description`, so descriptions are useful for discovery even when the visible label is short.

## Empty And Null Group Labels

Real data often contains empty strings, `null`, or `undefined`. Pivot can replace those values with user-facing labels in row and column groups.

```ts
const pivot = {
  rows: ['region', 'channel'],
  columns: ['quarter'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  groupLabels: {
    empty: '(Empty)',
    null: '(No value)',
  },
};
```

`groupLabels.empty` is used for empty strings (`''`). `groupLabels.null` is used for `null` and `undefined`. Without these options, the current implementation displays empty labels for those group members.

## Measure Aliases

Each value can have its own display label. Use `label` for the preferred generated measure name. Use `name` as a fallback when `label` is not set.

```ts
const pivot = {
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue $' },
    { prop: 'units', aggregator: 'sum', name: 'Units Sold' },
  ],
};
```

Aliases are useful when the source field name is technical, abbreviated, or shared by multiple reports.

## Disabled Subtotals

Global subtotals can stay enabled while specific subtotal rows or subtotal columns are skipped. Target subtotals by axis field or by zero-based axis level.

```ts
const pivot = {
  rows: ['region', 'channel', 'product'],
  columns: ['quarter', 'internalSegment'],
  values: [{ prop: 'revenue', aggregator: 'sum' }],
  totals: {
    grandTotal: true,
    subtotals: true,
    disabledSubtotals: {
      rows: {
        fields: ['channel'],
      },
      columns: {
        levels: [0],
      },
    },
  },
};
```

In this example, Pivot keeps subtotal generation enabled overall, skips row subtotals for the `channel` field, and skips column subtotals at level `0`.

## Complete Config

```ts
const pivot = {
  dimensions: [
    { prop: 'region', name: 'Region', description: 'Sales territory.' },
    { prop: 'channel', name: 'Channel', description: 'Go-to-market channel.' },
    { prop: 'product', name: 'Product' },
    { prop: 'quarter', name: 'Quarter' },
    { prop: 'internalSegment', name: 'Internal Segment', hidden: true },
    { prop: 'revenue', name: 'Revenue' },
    { prop: 'units', name: 'Units' },
  ],
  rows: ['region', 'channel', 'product'],
  columns: ['quarter', 'internalSegment'],
  filters: ['internalSegment'],
  values: [
    { prop: 'revenue', aggregator: 'sum', label: 'Revenue $' },
    { prop: 'units', aggregator: 'sum', name: 'Units Sold' },
  ],
  groupLabels: {
    empty: '(Empty)',
    null: '(No value)',
  },
  totals: {
    grandTotal: true,
    subtotals: true,
    disabledSubtotals: {
      rows: { fields: ['channel'] },
      columns: { levels: [0] },
    },
  },
};
```

## Common Mistakes

- Expecting `hidden: true` to prevent a field from being used in `rows`, `columns`, `filters`, or `values`. It only affects field-list helpers.
- Passing `{ showHidden: true }` to the Pivot config. It belongs to `filterPivotDimensions`, not `pivot`.
- Using only `groupLabels.empty` when the source data contains `null` or `undefined`.
- Disabling `totals.subtotals` and then expecting `disabledSubtotals` to do anything. Selective disabling only matters when `subtotals: true`.
