AML Number Format

Note

To apply Number Format for your dimension/measure, ensure its type is number.

Introduction

To format your number fields, add a format property with a string pattern representing your chosen format.

dimension formatted_price {
  label: "Formatted Price"
  type: "number"
  format: "#,###[$$]"
}

Syntax

Modeling fields format

Fields created in models or datasets take format: String | FullNumberFormat.

At creation, a number field has no format, so it shows raw values. Users can define the format once here, and every viz referencing the field inherits it by default.

// Short-form syntax: format: String
dimension revenue {
  type: 'number'
  format: '#,###0.00'
}

// Long-form syntax: format: FullNumberFormat
dimension sales {
  type: 'number'
  format {
    pattern: '#,###0.00'
    groupSeparator: ' '
    decimalSeparator: '.'
  }
}

Viz fields format

Fields referenced inside a chart (x_axis, values, a series field, and so on) take format: FieldFormat.

By default, a viz field inherits the modeling format. Users can override the format for a specific field inside each viz.

  // Inherit format syntax
  field {
    ref: r(orders.id)
  }

  // Override format syntax: format: FieldFormat
  field {
    ref: r(users.id)
    format {
      type: 'number'
      pattern:'#,###0.00'
      group_separator: ' '
      decimal_separator: '.'
    }
  }

Parameter

Parameter name	Required	Description
pattern	Yes	The pattern that decides how the value is rendered.
groupSeparator	No	Separator for the integer part. Default ",". Accepts ",", " ", or ".".
decimalSeparator	No	Separator for the decimal part. Default ".". Accepts "." or ",".

Note

These are the names used in modeling. On a viz field the separators are snake_case: group_separator and decimal_separator. pattern is the same in both.

pattern

The number format follows the order below.

<currency_prefix><integer><fraction><percentage><abbreviation><currency_suffix>

To show a number with no formatting (raw data), use pattern: 'none' or pattern: ''.

currency (optional)

Note

abbreviation/currency cannot be used with percentage.

Syntax:

 [$<insert_your_currency_here>]

Description:

• To specify a currency, you must prefix it with the required $ marker. Use the format [$<currency>], such as [$EUR], [$$], or [\$€]. You can use $ and \$ interchangeably.

• The currency notation can only be placed in one of these places:

  • At the beginning of the string pattern.
  • At the end of the string pattern.

• Currently, we only support these currency types:

  '$'   // US Dollar / MEX Peso
  '€'   // Euro
  '¥'   // Yen
  '£'   // Pound
  '元'  // Renminbi
  '₺'   // Lira
  '₩'   // Won
  '₽'   // RUS Ruble
  '₹'   // IND Rupee
  '₨'   // PAK Rupee
  '₱'   // PHL Peso
  'A$'  // AUS Dollar
  'C$'  // CAN Dollar
  'S$'  // SGP Dollar
  'NZ$' // NZ Dollar
  'HK$' // HK Dollar
  '₪'   // Shekel
  'R$'  // Real
  '฿'   // Thai Baht
  'R'   // South African Rand
  'Fr'  // Franc
  'kr'  // Krona / Krone
  'Ft'  // Forint
  'Rp'  // Rupiah
  'RM'  // Ringgit
  'VND' // VN Dong
  'Tk'  // BGD Taka

If your currency isn't in the list, you can enter any custom symbol using the [$...] syntax (for example, [$₿] for Bitcoin, or [$USD] for displaying as USD).

Example:

Raw Value	Number Pattern	Displayed as
1236	[$$]#,###	$1,236
1236	#,###[$€]	1,236€
1236	#,###[$USD]	1,236USD

group separator for integer values (optional)

Note

Holistics will automatically apply a thousands separator for integers whether you specify this option or not.

Syntax:

#,###

Description:

• Use this pattern to group your integer digits. Only thousands grouping is supported (a separator every three digits). There is no separate millions or billions grouping mode.
• In shorthand syntax the separator is always a comma (,). Writing the pattern with a different character (such as #.###) does not change the separator. To use a space or a dot, switch to the full syntax and set groupSeparator.

Example:

Raw Value	Number Pattern	Displayed as
586347	#,###	586,347
1234	#,###	1,234

fraction (optional)

0.0 

Add more 0s when more decimal places are needed.

Description:

• Specify how many digits should be included in the fraction format.
• The default separator is a dot (.). To specify another separator, refer to decimalSeparator.
• To show no decimal places, leave the 0 out of the pattern entirely, e.g. #,### instead of #,###0.

Example:

Raw Value	Number Pattern	Displayed as
123456789.0123	0.00	123,456,789.01
123456789.0123	#,###	123,456,789

percentage (optional)

Note

abbreviation/currency cannot be used with percentage.

Syntax:

% or \\%

Description:

• % converts a number to percentage format by multiplying the original value by 100.
• \\% converts a number to percentage format without modifying the original value.

Example:

Raw Value	Number Pattern	Displayed as
12.3456	#,###0.0%	1,234.6%
12.3456	#,###0.0\\%	12.3%

abbreviation (optional)

Note

abbreviation/currency cannot be used with percentage.

Syntax:

Pick one of the following tokens to abbreviate long numeric values:

• "A": auto-select (K, M, or B based on the value)
• ,"K": thousand
• ,,"M": million
• ,,,"B": billion

Description:

• If your string pattern is wrapped in single quotes (’ ‘), you will not need to wrap your abbreviation with escape characters (\ \). For example, this is a valid pattern: format: '<other_format_part>,"K"'
• If your string pattern is wrapped in double quotes (” “), you will have to wrap your abbreviation with escape characters (\ \). For example, this is a valid pattern: format: "<other_format_part>,\"K\""

Example:

Raw Value	Number Pattern	Displayed as
4382296	'[$$]#,###,"K"'	$4,382K
124412.4	'#,###0.000,"K"'	124.412K
157698	'#,###0.000,,"M"'	0.158M

groupSeparator

Selects a custom separator for your integer values.

Syntax:

format {
  pattern: "#,###"
  groupSeparator: "," // or `group_separator` for viz fields
}

Description:

• By default, the group separator for integer values is a comma ,. To opt for another separator, add this option to your format field.
• Selectable separators include:
  • ",": comma separator (default)
  • " ": space separator
  • ".": dot separator

Example:

Raw Value	Option	Displayed as
543213	groupSeparator: " "	543 213
12345.1	groupSeparator: ","	12,345.1

decimalSeparator

Selects a custom separator for your decimal values.

Syntax:

format {
  pattern: "0.00"
  decimalSeparator: "."  // or `decimal_separator` for viz fields
}

Description:

• By default, the decimal separator is a dot .. To opt for another separator, add this option to your format field.
• Selectable separators include:
  • ".": dot separator (default)
  • ",": comma separator

Example:

Raw Value	Option	Displayed as
54.123	decimalSeparator: ","	54,123

Advanced syntax

Date parts

When you extract a date part from a datetime, Holistics automatically:

• Applies the date_part <time_part> transformation and uses the number format type.
• Assigns the matching number-format pattern for the selected time part.

VizFieldFull {
  ref: r(annotated_time_series_csv.date)
  transformation: 'date_part quarter'
  format {
    type: 'number'
    pattern: 'Qq'
  }
}

Every time part supported by date_part is listed below. Parts with a pattern display as a label. Parts marked none have no pattern, so they display as plain numbers.

Time part	date_part value	Number pattern	Raw value	Displayed as
Year (e.g., 2021)	year	none	2021	2021
Quarter of Year (e.g., Q1, Q2)	quarter	Qq	1	Q1
Month of Year (e.g., January, February)	month	MMMM	1	January
ISO Week (W1-W53)	week	'W'WW	1	W01
Day of Week (e.g., Monday, Tuesday)	dayofweek, dow	dddd	1	Monday
Day of Month (1-31)	day	none	10	10
Hour of Day (0-23)	hour	none	14	14
Minute of Hour (0-59)	minute	none	30	30
Second of Minute (0-59)	second	none	39	39