Add column limits documentation for pivot tables

references/chart-types/table.mdx

@@ -55,17 +55,66 @@ To add a pivot in your table, move a dimension to the `column` section of your t
   ![](/images/references/chart-types/pivoted-table-72daaf2e205221bd425e61dd1b6dc883.jpg)
 </Frame>
 
-You can move up to 3 dimensions as columns and there is a limit of 200 column values in your table (e.g. pivoting by a dimension with 30 months, and another with 8 statuses won't work because that will generate 8 x 30 = 240 column values).
+You can move up to 3 dimensions as columns.
 
-### Transposing your table
+### Column limits
 
-You can transpose your table so that your metrics become rows in your table instead of columns. This can be helpful if you want to compare a lot of metrics to each other (e.g. how my metrics are changing over time).
+Pivot tables have a default limit of 200 columns to ensure good performance. Large pivot tables with many columns can significantly slow down query execution and rendering times, so this limit helps keep your dashboards responsive.
 
-To move your metrics to rows in your table, you need to have at least 1 dimension as a column (i.e. at least one pivot) then, you can click on `show metrics as rows` in the table configuration.
+<Tip>
+  If you have a Lightdash Pro or Enterprise account, this limit can be increased at your request. If you are self-hosting, you can set the pivot column limit by updating the [`LIGHTDASH_PIVOT_TABLE_MAX_COLUMN_LIMIT`](/self-host/customize-deployment/environment-variables) environment variable.
+</Tip>
 
-<Frame>
-  ![](/images/references/chart-types/metrics-as-rows-b7ce13b31232fdf3bd7500c4c4d3c1e6.jpg)
-</Frame>
+The column limit works differently depending on whether you have metrics as rows or metrics as columns:
+
+#### When metrics are columns (default)
+
+When metrics are displayed as columns (the default behavior), each pivoted dimension value creates a column for **every metric**. This means the total number of columns equals the number of unique dimension values multiplied by the number of metrics.
+
+For example, if you pivot by `order_date_month` (with 36 months of data) and have 3 metrics:
+- Total columns: 36 months × 3 metrics = 108 columns which is within the column limit of 200
+
+The limit always applies to complete dimension values — a dimension value is either fully shown (with all of its metrics) or not shown at all. The number of dimension values displayed is determined by dividing the column limit by the number of metrics and rounding down.
+
+With a column limit of 200 and 3 metrics:
+- Maximum dimension values: `floor(200 / 3)` = 66 months
+
+Here's what a pivoted table looks like with `order_date_month` pivoted to columns and 3 metrics:
+
+<img src="/images/references/chart-types/table/pivot_column_limit_example_1_light.png" alt="Pivot column limit example" className="block dark:hidden" />
+<img src="/images/references/chart-types/table/pivot_column_limit_example_1_dark.png" alt="Pivot column limit example" className="hidden dark:block" />
+
+If too many columns are generated as a result of your pivot configuration, you will see a warning that your results may be incomplete. This often happens when you pivot by multiple dimensions.
+
+For example, if you pivot by both `order_date_month` and `browser` (with 6 distinct values) and have 3 metrics, the maximum number of months displayed is:
+- Maximum dimension values: `floor(200 / (6*3))` = 11 months
+
+The warning looks like this:
+<img src="/images/references/chart-types/table/column_limit_exceeded_light.png" alt="Pivot column limit exceeded" className="block dark:hidden" />
+<img src="/images/references/chart-types/table/column_limit_exceeded_dark.png" alt="Pivot column limit exceeded" className="hidden dark:block" />
+
+To reduce the number of pivot columns, you can: 
+- filter your data, e.g., filter your months to only show data from the last year
+- reduce the number of dimensions you are pivoting on, e.g., decide whether splitting your data by both `order_date_month` and `browser` is necessary
+- reduce the granularity of your pivot dimensions, e.g., pivot by `order_date_year` instead of `order_date_month`
+- show metrics as rows instead of columns (see below)
+
+#### When metrics are rows
+
+When you enable **Show metrics as rows**, each pivoted dimension value creates only **one column**, regardless of how many metrics you have. The metrics are displayed as separate rows instead.
+
+For example, if you have `partner_name` as a row dimension (with 5 partners), pivot by `order_date_month` (with 12 months of data), and have 3 metrics:
+- Total columns: 12 (one per month)
+- Each row is repeated once per metric — so you'll see 5 × 3 = 15 rows
+
+Here's what the same data looks like with metrics as rows, where the row dimension is `partner_name`:
+
+<img src="/images/references/chart-types/table/metrics_as_rows_light.png" alt="Metrics as rows" className="block dark:hidden" />
+<img src="/images/references/chart-types/table/metrics_as_rows_dark.png" alt="Metrics as rows" className="hidden dark:block" />
+
+With 12 months, this creates only 12 columns, compared to 36 columns when metrics are columns.
+
+This means you can display significantly more dimension values when using metrics as rows, which is useful when you have many metrics to compare across time periods or other dimensions.
 
 ## Totals