Skip to content

docs: document per-organization export limits #737

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: document per-organization export limits #737

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -263,6 +263,7 @@
"references/workspace/user-impersonation",
"references/workspace/support-impersonation",
"references/workspace/managing-your-organization",
"references/workspace/export-limits",
"references/workspace/how-to-create-multiple-projects",
"references/workspace/customizing-the-appearance-of-your-project",
"references/workspace/adding-slack-integration",
Expand Down
49 changes: 49 additions & 0 deletions references/workspace/export-limits.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: "Export limits"
description: "Override the instance-wide query row and CSV/Excel cell limits on a per-organization basis from your admin settings."
---

The **Export limits** panel lets organization admins raise or lower the two values that bound how much data a query can return and how large a CSV or Excel export can be. Without an override, every organization inherits the instance defaults set by `LIGHTDASH_QUERY_MAX_LIMIT` and `LIGHTDASH_CSV_CELLS_LIMIT`.

Use this panel when a specific team needs to run wider or longer queries than the rest of the instance — for example, a single org on shared Cloud infrastructure that needs to export an 8M-cell CSV while keeping other orgs at the default.

<Note>
The panel is gated behind the `pro-limits` feature flag. Enforcement of any stored override is always active — only writing the limits requires the flag. Contact Lightdash to enable it for your organization, or self-hosters can set `LIGHTDASH_ENABLE_FEATURE_FLAGS=pro-limits`.
</Note>

## What you can configure

| Setting | What it controls | Inherits from |
| --- | --- | --- |
| **Maximum query rows** | The largest row limit a user can request from the explorer, SQL runner, or API. | `LIGHTDASH_QUERY_MAX_LIMIT` |
| **Maximum CSV/Excel cells** | The largest CSV or Excel export (rows × columns) before results are truncated. | `LIGHTDASH_CSV_CELLS_LIMIT` |

Both fields accept a positive integer. Leave a field empty to inherit the instance default.

The CSV/Excel cells value is capped server-side at the higher of `LIGHTDASH_CSV_MAX_LIMIT` (default 5,000,000) and the current `LIGHTDASH_CSV_CELLS_LIMIT`. The query rows value cannot exceed `LIGHTDASH_QUERY_MAX_LIMIT`. The panel shows the active ceiling next to each input.

The two limits are independent — raising the query-row limit does not change CSV export size, and vice versa.

## Set per-organization limits

1. Go to **Settings → Organization → Export limits**.
2. Enter a value for **Maximum query rows**, **Maximum CSV/Excel cells**, or both.
3. Click **Save**.

To revert to the instance default, clear the field and save.

Changes take effect immediately for new queries and exports. Existing scheduled deliveries pick up the new limit on their next run.

## How limits are enforced

| Surface | Behavior |
| --- | --- |
| Explorer and SQL runner row-limit selector | Maximum value is clamped to the org's effective query row limit. |
| CSV and Excel downloads from charts, dashboards, and underlying data | Truncated to the org's effective cell limit, with a banner shown when truncation happens. |
| Scheduled deliveries (CSV, Google Sheets, Excel) | Use the org's effective cell limit at run time. |
| API responses for `/api/v1/org/settings` | Return the resolved effective values, falling back to the instance defaults when no override is set. |

## Related

- [Environment variables](/self-host/customize-deployment/environment-variables) — the instance defaults that act as fallbacks.
- [Scheduled deliveries](/guides/how-to-create-scheduled-deliveries) — affected by the CSV/Excel cell limit.
5 changes: 3 additions & 2 deletions self-host/customize-deployment/environment-variables.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ This is a reference to all environment variables that can be used to configure a
| `INTERNAL_LIGHTDASH_HOST` | Internal Lightdash host for the Headless browser to send requests when your Lightdash instance is not accessible from the Internet. Needs to support `https` if `SECURE_COOKIES=true` (default=Same as `SITE_URL`) |
| `INTERNAL_LIGHTDASH_HOST_IGNORE_HTTPS_ERRORS`| When `true`, skips TLS certificate validation on screenshot traffic going to `INTERNAL_LIGHTDASH_HOST`. Use this if you need to terminate TLS in front of Lightdash on a fully internal hostname with a self-signed or otherwise untrusted certificate. Opt-in, default `false`. **Security trade-off:** disables TLS validation for that traffic, so only enable it when the network path is trusted (e.g. cluster-internal). See [Run Lightdash on a fully internal HTTPS network](/self-host/customize-deployment/enable-headless-browser-for-lightdash#run-lightdash-on-a-fully-internal-https-network). |
| `STATIC_IP` | Server static IP so users can add the IP to their warehouse allow-list. (default=http://localhost:8080) |
| `LIGHTDASH_QUERY_MAX_LIMIT` | Query max rows limit (default=5000) |
| `LIGHTDASH_QUERY_MAX_LIMIT` | Query max rows limit (default=5000). Organization admins can override this per-org from the [Export limits](/references/workspace/export-limits) panel. |
| `LIGHTDASH_QUERY_DEFAULT_LIMIT` | Default number of rows to return in a query (default=500) |
| `LIGHTDASH_QUERY_MAX_PAGE_SIZE` | Maximum page size for paginated queries (default=2500) |
| `SCHEDULER_ENABLED` | Enables/Disables the scheduler worker that triggers the scheduled deliveries. (default=true) |
Expand All @@ -36,7 +36,8 @@ This is a reference to all environment variables that can be used to configure a
| `SCHEDULER_SCREENSHOT_TIMEOUT` | Timeout in milliseconds for taking screenshots |
| `SCHEDULER_INCLUDE_TASKS` | Comma-separated list of scheduler tasks to include |
| `SCHEDULER_EXCLUDE_TASKS` | Comma-separated list of scheduler tasks to exclude |
| `LIGHTDASH_CSV_CELLS_LIMIT` | Max cells on CSV file exports (default=100000) |
| `LIGHTDASH_CSV_CELLS_LIMIT` | Max cells on CSV and Excel exports (default=100000). Organization admins can override this per-org from the [Export limits](/references/workspace/export-limits) panel. |
| `LIGHTDASH_CSV_MAX_LIMIT` | Server-side ceiling on the per-org CSV/Excel cell limit an admin can configure in the [Export limits](/references/workspace/export-limits) panel (default=5000000). |
| `LIGHTDASH_CHART_VERSION_HISTORY_DAYS_LIMIT` | Configure how far back the chart versions history goes in days (default=3) |
| `LIGHTDASH_PIVOT_TABLE_MAX_COLUMN_LIMIT` | Configure maximum number of columns in pivot table (default=200) |
| `GROUPS_ENABLED` | Enables/Disables groups functionality (default=false) |
Expand Down
Loading