# Chart Common

## Data Processing in Charts

### Dimensions and Metrics <a href="#dimension-metric" id="dimension-metric"></a>

Chart data aggregation uses the concepts of **dimensions** and **metrics**.

* **Dimension**: Values used to group data. Categories, dates, etc. - determines "what to group by"
* **Metric**: Aggregated numerical values. Sums, averages, counts, etc. - determines "what to measure"

In SQL terms, dimensions correspond to columns used in `GROUP BY`, while metrics correspond to columns calculated using aggregate functions like `SUM()` or `COUNT()`.

### Date Field Transformation (Truncate/Extract)

When selecting a date column for dimension fields in charts (X-axis, grouping, etc.), you can transform the date before using it.

* Configuration Method
  * In the chart edit screen "Basic Settings", select a date column and click "Edit". Choose the transformation mode and transformation unit.
* Transformation Modes
  * Truncate: Truncates the date to the specified unit
    * Example: 2025-01-15 truncated to MONTH → 2025-01-01
    * Use case: Monthly, weekly, or yearly aggregation
  * Extract: Extracts only a specific part from the date
    * Example: Extracting DAY from 2025-01-15 → 15
    * Use case: Pattern analysis by day within a month, time period analysis (same days from different months are aggregated)

### In-memory Processing <a href="#in-memory-processing" id="in-memory-processing"></a>

When the query result for chart data processing is within 1,000 rows and no custom SQL is used, equivalent processing is performed in the user's browser without issuing a new query.

This is called "in-memory processing". You can disable it from the chart's "Basic" > "Disable in-memory processing".

## Tips

### Frame Feature <a href="#frame-feature" id="frame-feature"></a>

In some charts, you can set a specific column as a frame to **split the chart by each value of that column**. The display mode can be selected from the "Frame Layout" option: either "Timeline" or "Grid".

The frame feature lets you visually explore time-series changes or compare categories across frames. For easier comparison across frames, the Y-axis range, bubble size scale, heatmap color scale, and similar settings are shared across all frames by default. You can change this behavior via "Advanced" > "Frame" > "Independent scale".

#### Timeline Layout

In timeline layout, frame controls appear at the bottom of the chart, allowing you to switch frames manually or play frame animation.

| <picture><source srcset="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-6d8153b3a49cf6f1ec9774589d65b982c40bb210%2Fxy-frame-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-b6b691112fe2ccdff240701df2f0b3fb53218745%2Fxy-frame-light.png?alt=media" alt="XY Frame Timeline"></picture> | <picture><source srcset="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-c8b5d67cad17c1f140d58cac6debe3c6cb1b3fea%2Fgraph-frame-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-22ae272614476950484179cbe4d17d41d85c6fd1%2Fgraph-frame-light.png?alt=media" alt="Graph Frame Timeline"></picture> |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Grid Layout

Grid layout displays all frames in a grid format (**up to 16 charts**).

The number of columns is automatically adjusted by default to produce a layout as close to square as possible (e.g., 3 charts → 2×2, 5 charts → 3×2). You can specify the number of columns via "Advanced" > "Frame" > "Columns" — note that the column count may be reduced automatically if there are fewer charts than columns specified.

| <picture><source srcset="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-a1e25679de4e21615e44d82759b17e7ed9e96a6a%2Fxy-frame-grid-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-06dc647befe927408213e1e091773af3d56b2775%2Fxy-frame-grid-light.png?alt=media" alt="XY Frame Grid"></picture> | <picture><source srcset="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-ce0a240fd94214970cfa68601efba4049312f897%2Fradial-frame-grid-dark.png?alt=media" media="(prefers-color-scheme: dark)"><img src="https://1875572357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FzP7hFWzU2Jj7xMbv2nyp%2Fuploads%2Fgit-blob-6ca65764a351389b151c9d1f5e0571747cdcb217%2Fradial-frame-grid-light.png?alt=media" alt="Radial Frame Grid"></picture> |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

#### Charts that support the frame feature

| Chart                                                                              | Support                                          |
| ---------------------------------------------------------------------------------- | ------------------------------------------------ |
| [XY Chart](https://docs.codatum.com/data-exploration/chart/xy-chart)               | Supported                                        |
| [Radial Chart](https://docs.codatum.com/data-exploration/chart/radial-chart)       | Supported                                        |
| [XYZ Chart](https://docs.codatum.com/data-exploration/chart/xyz-chart)             | Supported                                        |
| [Hierarchy Chart](https://docs.codatum.com/data-exploration/chart/hierarchy-chart) | Supported                                        |
| [Graph Chart](https://docs.codatum.com/data-exploration/chart/graph-chart)         | Partial ("Bar chart (drill-down)" not supported) |
| [Funnel Chart](https://docs.codatum.com/data-exploration/chart/funnel-chart)       | Supported                                        |
| [Waterfall Chart](https://docs.codatum.com/data-exploration/chart/waterfall-chart) | Supported                                        |
| [Word Cloud](https://docs.codatum.com/data-exploration/chart/word-cloud)           | Supported                                        |

### Value Formatting

By default, the format of values and labels displayed in charts is **optimized according to your account's language settings**. You can also change the formatter via the chart's "Advanced Settings." If a formatter is manually changed, the specific formatter settings will take precedence over the language settings.

#### Configuration Examples

For example, in the case of an XY Chart, you can specify formatters as follows:

* **X-axis/Y-axis Label Format**
  * Specify via "Advanced" > "X Axis / Y Axis" > "Value formatter"
* **Tooltip Format**
  * Specify via "Advanced" > "Series" > "(Series Name)" > "Value formatter"
* **Value Label Format** (if "Value label" are enabled)
  * Specify via "Advanced" > "Series" > "(Series Name)" > "Value label" > "Value label formatter"

#### Number Formatter

The number formatter uses [d3-format](https://d3js.org/d3-format) syntax for formatting.

For example, you can specify settings as shown below:

| Setting Value | Value        | Format Result |
| ------------- | ------------ | ------------- |
| `.0f`         | `12345.6789` | `12346`       |
| `,.1r`        | `12345.6789` | `10,000`      |
| `-.1%`        | `0.5`        | `50%`         |

Additionally, you can enclose the d3-format syntax in `{` and `}` to add prefixes or suffixes before or after the value.\
(Note: This is a custom extension, not standard d3-format syntax. Please refer to the examples below.)

| Setting Value   | Value     | Format Result |
| --------------- | --------- | ------------- |
| `{,d} USD`      | `12345.6` | `12,346 USD`  |
| `Approx. {,d}%` | `50`      | `Approx. 50%` |

#### Date Formatter

The date formatter uses [Day.js](https://day.js.org/docs/en/display/format) syntax for formatting.\
(In some cases, you can toggle between the Number Formatter and Date Formatter using the button on the left edge of the input field.)

For example, you can specify settings as shown below:

| Setting Value | Date         | Format Result  |
| ------------- | ------------ | -------------- |
| `YYYY-MM-DD`  | `2025-01-01` | `2025-01-01`   |
| `YY/M/D`      | `2025-01-01` | `25/1/1`       |
| `MMMM YYYY`   | `2025-01-01` | `January 2025` |

### Adjusting Axis Label Display Width

You can limit the display width of labels for each axis by setting the maximum width (px) of axis labels.

Enter a numeric value (e.g., `100`, `200`) in the chart settings screen "Advanced" > "Axis label max size(px)". This can be useful when you want to display long label text with ellipsis.