> Documentation index: https://www.gooddata.ai/docs/gooddata-ui/llms.txt lists every page of these docs as Markdown.

# IGranularityDescriptor

- Package: [@gooddata/sdk-model](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/index.md)
- Kind: interface
- Stability: alpha
- Source: https://github.com/gooddata/gooddata-ui-sdk/blob/rel/11.64/libs/sdk-model/src/base/granularityRegistry.ts

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Canonical, calendar-independent metadata for a single date granularity.

**Signature:**

```typescript
export interface IGranularityDescriptor 
```

## Remarks

This is the single source of truth for classification, ordering and standard/fiscal relations. It intentionally does NOT carry i18n labels — those stay in the consuming apps, keyed off this descriptor.

## Properties

| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [affinity](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptoraffinity) |  | [CalendarAffinity](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.calendaraffinity/index.md) | **_(ALPHA)_** Which calendar the granularity belongs to. |
| [chronologicalOrigin?](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptorchronologicalorigin) |  | [DateAttributeGranularity](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.dateattributegranularity/index.md) | **_(ALPHA)_** _(Optional)_ For generic granularities, the chronological granularity they are derived from (e.g. month\_in\_year → month). |
| [counterpart?](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptorcounterpart) |  | [DateAttributeGranularity](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.dateattributegranularity/index.md) | **_(ALPHA)_** _(Optional)_ Standard↔fiscal equivalent of the same period length (year↔fiscal\_year, …), when one exists. |
| [family](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptorfamily) |  | [GranularityFamily](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.granularityfamily/index.md) | **_(ALPHA)_** Structural family. |
| [granularity](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptorgranularity) |  | [DateAttributeGranularity](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.dateattributegranularity/index.md) | **_(ALPHA)_** The canonical SDK granularity token. |
| [headerTokens](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptorheadertokens) |  | readonly string[] | **_(ALPHA)_** Uppercase tokens that may appear on execution attribute headers for this granularity (`IAttributeDescriptorBody.granularity`). Catalog/filter paths convert via `toSdkGranularity`; headers often keep the raw backend token — include every accepted alias (e.g. `"DATE"` and `"DAY"`). Empty when the backend does not emit a header token for this granularity. |
| [offeredByDefault](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptorofferedbydefault) |  | boolean | **_(ALPHA)_** Whether the granularity is offered to users by default. `false` for tokens that exist in the type/backend but are not surfaced in any picker today (the `GDC.time.week` alias and the EU-week generic variants). Descriptors still exist for them so classification/lookup works; they are just excluded from [getGranularities()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.getgranularities/index.md) output unless explicitly requested. |
| [order](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptororder) |  | number | **_(ALPHA)_** Canonical coarse→fine display/drill-down order. Fiscal granularities are ranked immediately after their standard sibling, so filtering to a single calendar reproduces each consumer's historical order. |
| [timeScale](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.igranularitydescriptor/index.md#igranularitydescriptortimescale) |  | boolean | **_(ALPHA)_** Whether the granularity is at the time-of-day scale (hour/minute/second and their generic forms). |

## Property details

### IGranularityDescriptor.affinity

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Which calendar the granularity belongs to.

**Signature:**

```typescript
affinity: CalendarAffinity;
```

### IGranularityDescriptor.chronologicalOrigin

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

For generic granularities, the chronological granularity they are derived from (e.g. month\_in\_year → month).

**Signature:**

```typescript
chronologicalOrigin?: DateAttributeGranularity;
```

### IGranularityDescriptor.counterpart

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Standard↔fiscal equivalent of the same period length (year↔fiscal\_year, …), when one exists.

**Signature:**

```typescript
counterpart?: DateAttributeGranularity;
```

### IGranularityDescriptor.family

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Structural family.

**Signature:**

```typescript
family: GranularityFamily;
```

### IGranularityDescriptor.granularity

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

The canonical SDK granularity token.

**Signature:**

```typescript
granularity: DateAttributeGranularity;
```

### IGranularityDescriptor.headerTokens

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Uppercase tokens that may appear on execution attribute headers for this granularity (`IAttributeDescriptorBody.granularity`). Catalog/filter paths convert via `toSdkGranularity`; headers often keep the raw backend token — include every accepted alias (e.g. `"DATE"` and `"DAY"`). Empty when the backend does not emit a header token for this granularity.

**Signature:**

```typescript
headerTokens: readonly string[];
```

### IGranularityDescriptor.offeredByDefault

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Whether the granularity is offered to users by default. `false` for tokens that exist in the type/backend but are not surfaced in any picker today (the `GDC.time.week` alias and the EU-week generic variants). Descriptors still exist for them so classification/lookup works; they are just excluded from [getGranularities()](https://www.gooddata.ai/docs/gooddata-ui/latest/api-reference/sdk-model/sdk-model.getgranularities/index.md) output unless explicitly requested.

**Signature:**

```typescript
offeredByDefault: boolean;
```

### IGranularityDescriptor.order

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Canonical coarse→fine display/drill-down order. Fiscal granularities are ranked immediately after their standard sibling, so filtering to a single calendar reproduces each consumer's historical order.

**Signature:**

```typescript
order: number;
```

### IGranularityDescriptor.timeScale

> **Alpha API.** Initial API, highly likely to change outside SemVer. Don't build on it in production. See [API maturity](https://www.gooddata.ai/docs/gooddata-ui/latest/integrations/platform/api-maturity/index.md).
> 

Whether the granularity is at the time-of-day scale (hour/minute/second and their generic forms).

**Signature:**

```typescript
timeScale: boolean;
```