diff --git a/data-apps/external-connections.mdx b/data-apps/external-connections.mdx index 45ffbe42..7a53adab 100644 --- a/data-apps/external-connections.mdx +++ b/data-apps/external-connections.mdx @@ -9,7 +9,7 @@ A data app can also fetch from third-party HTTP APIs — for example, your own p External connections are managed under **Project Settings → Data app connections** on the project. -[Project chart types](/explore/chart-types/custom-project-charts#linking-external-connections) link connections the same way, so a chart type can call an API or show images from a URL field. +[Custom chart types](/explore/chart-types/custom-project-charts#linking-external-connections) link connections the same way, so a chart type can call an API or show images from a URL field. ## Configuring a connection diff --git a/explore/chart-types.mdx b/explore/chart-types.mdx index a31a376a..cb3d9e4d 100644 --- a/explore/chart-types.mdx +++ b/explore/chart-types.mdx @@ -6,10 +6,19 @@ doc-type: reference In Lightdash, the data in your results tables can be visualized in a bunch of different ways. -**Custom** is one entry in the chart type menu covering two kinds of chart. A [Vega chart](/explore/chart-types/custom-vega-charts) is a one-off spec written in a JSON editor and belongs to that chart alone. A [project chart type](/explore/chart-types/custom-project-charts) is reusable: you describe the chart you want, Lightdash builds it, and anyone in the project can then apply it like a built-in chart type. +**Custom** is one entry in the chart type menu covering two kinds of chart. A [Vega chart](/explore/chart-types/custom-vega-charts) is a one-off spec written in a JSON editor and belongs to that chart alone. A [custom chart type](/explore/chart-types/custom-project-charts) is reusable: you describe the chart you want, Lightdash builds it, and anyone in the project can then apply it like a built-in chart type. -The visualization type that you pick determines how Lightdash shows the data series in your chart. To change how your data is displayed, click **Configure** when you're querying from a table. You have the option to change the chart type in the drop-down: +The visualization type that you pick determines how Lightdash shows the data series in your chart. To change how your data is displayed, click **Configure** when you're querying from a table. The **Configure chart** sidebar opens on the right. Click **Change** next to the current chart type to open the chart type gallery, then pick a card: - ![The chart type drop-down open in the Configure panel, listing bar, line, area, scatter, pie and the other chart types](/images/explore/chart-types/select-chart-type.png) + The Configure chart sidebar in the Explorer with the chart type gallery open, listing custom chart types above the built-in ones + The Configure chart sidebar in the Explorer with the chart type gallery open, listing custom chart types above the built-in ones diff --git a/explore/chart-types/custom-project-charts.mdx b/explore/chart-types/custom-project-charts.mdx index 4f837705..998dfba6 100644 --- a/explore/chart-types/custom-project-charts.mdx +++ b/explore/chart-types/custom-project-charts.mdx @@ -1,21 +1,21 @@ --- -title: "Custom project charts" +title: "Custom chart types" sidebarTitle: "Custom" description: "Reusable chart types you build once for your project, then use like any built-in chart type" doc-type: reference icon: "shape" --- -Project chart types are reusable chart types you build for your project. You describe the chart you want, Lightdash builds it, and anyone in the project can then use it like a built-in chart type. Open **Configure** in the Explorer, click **Change**, and pick it from the **Project** group of the chart type picker. +Custom chart types are reusable chart types you build for your project. You describe the chart you want, Lightdash builds it, and anyone in the project can then use it like a built-in chart type. Open **Configure** in the Explorer, click **Change**, and pick it from the **Custom** group of the chart type gallery. For a one-off chart written directly as a Vega-Lite spec, see [Custom Vega charts](/explore/chart-types/custom-vega-charts). -A project chart type is a chart type you build once and reuse. Describe the chart you want - a calendar heatmap, a hexbin map, a custom KPI layout - and Lightdash builds it, along with the inputs it needs (for example a "Category" dimension and a "Value" metric). Anyone in the project can then pick it as a chart type, map their own fields to its inputs, and save the result like any other chart. +A custom chart type is a chart type you build once and reuse. Describe the chart you want - a calendar heatmap, a hexbin map, a custom KPI layout - and Lightdash builds it, along with the inputs it needs (for example a "Category" dimension and a "Value" metric). Anyone in the project can then pick it as a chart type, map their own fields to its inputs, and save the result like any other chart. The same chart type can power many saved charts, each with its own query and field mapping. - Project chart types are an enterprise feature and require the [data apps runtime](/self-host/enterprise-features/data-apps) to be enabled. + Custom chart types are an enterprise feature and require the [data apps runtime](/self-host/enterprise-features/data-apps) to be enabled. ## Browsing chart types @@ -41,24 +41,24 @@ Each card previews the chart type with sample data. Click a card to see its desc Click **New chart type** in the gallery to open the builder, then describe the chart you want. -The builder previews the chart type with sample data as it's built. The **Configure** panel beside the preview holds the display options the chart type declares, along with a color palette to preview it against. Follow-up prompts create new versions, and **History** opens a panel where you can view an earlier version or restore it. +The builder previews the chart type with sample data as it's built. The **Generated options** panel beside the preview holds the display options the chart type declares, along with a color palette to preview it against. Follow-up prompts create new versions, and **History** opens a panel where you can view an earlier version or restore it. Name and describe the chart type in the header - that's what people see in the gallery and in the chart type picker. When it looks right, click **Preview in explorer** to try it against a real query. The chart type builder, with the sample-data preview, the Configure panel, and the prompt bar The chart type builder, with the sample-data preview, the Configure panel, and the prompt bar -You can also start one from any chart, without leaving the Explorer: open **Configure**, click **Change**, and choose **Create new chart type** in the **Project** group. The builder opens in the chart panel and previews against your query's real results. +You can also start one from any chart, without leaving the Explorer: open **Configure**, click **Change**, and pick the **New chart type** tile in the **Custom** group. The builder opens in the chart panel, the sidebar switches to its generated options, and the preview uses your query's real results. To edit a chart type you already have selected, click the pencil next to its name in the **Configure chart** sidebar. Chart types can also be developed on your machine and uploaded with the CLI. See [Chart types as code](#chart-types-as-code). @@ -123,21 +123,21 @@ Once linked, the connection stays with the chart type across versions and everyw Select the dimensions and metrics your chart needs and run the query. You have to run it before you can pick a custom chart type. - Open **Configure**, click **Change**, then pick one from the **Project** group in the chart type picker. Only chart types that finished building are listed. + Open **Configure** to open the chart sidebar, then click **Change**. The **Custom** group at the top of the gallery lists the project's chart types; click the **more** tile to see the rest, or search the gallery by name. Only chart types that finished building are listed. - Each of the chart type's inputs gets a field picker, the same as configuring axes on a bar or line chart. Required inputs can't be cleared. + Each of the chart type's inputs gets a field picker in the **General** tab, the same as configuring axes on a bar or line chart. Required inputs can't be cleared. The chart type's own display options sit in the tabs beside it. The Custom chart type picker open in the Explorer, listing the built-in Vega editor and the project's own chart types The Custom chart type picker open in the Explorer, listing the built-in Vega editor and the project's own chart types @@ -147,12 +147,12 @@ The chart re-renders as you change the mapping or the underlying query. A project chart type selected in the Explorer, with its inputs mapped to the query's fields and the chart rendering A project chart type selected in the Explorer, with its inputs mapped to the query's fields and the chart rendering @@ -160,10 +160,33 @@ The chart re-renders as you change the mapping or the underlying query. ## Saving and dashboards -Save the chart like any other chart. The saved chart remembers which chart type it uses and how its inputs are mapped. +Save the chart like any other chart. The saved chart remembers which chart type it uses, how its inputs are mapped, and which version of the chart type it uses (see [Versions and upgrades](#versions-and-upgrades)). Saved charts render in chart view and as dashboard tiles, driven by each surface's own query - dashboard filters and [date zoom](/explore/dashboards/date-zoom) apply like any other chart tile. +## Versions and upgrades + +Every follow-up prompt in the builder creates a new version of the chart type. A saved chart keeps using the version it was saved with, so changing a chart type never changes the charts that already use it. + +When you edit a chart and a newer version of its chart type exists, the **Configure chart** sidebar shows **Newer version available**. Click **Review upgrade** to see what changed: inputs and options that were added, renamed or removed, and any change to the color palette. + + + The Upgrade chart type dialog over the Explorer, listing what changed since the chart's version + The Upgrade chart type dialog over the Explorer, listing what changed since the chart's version + + +Click **Upgrade** to move the chart to the latest version. Only that chart moves, and nothing changes until you save it. If the new version added a required input, map a field to it and the chart renders again. + +The builder has its own upgrade, for the chart type itself. When a chart type was built on an older version of the data apps runtime, the builder header shows **Upgrade available**. Starting it rebuilds the chart type as a new version, and **History** shows what's new. How the chart type renders doesn't change unless you ask for it in a follow-up prompt. + ## Chart types as code Chart types round-trip through the CLI as their own resource, separate from data apps. Each one downloads to `lightdash/chart-types//` as a locally buildable project you can version in git, edit, validate with [`lightdash apps validate`](/workflow/cli/reference#lightdash-apps-validate), and upload back: diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-dark.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-dark.png index 0433980a..a73526c0 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-dark.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-dark.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-light.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-light.png index 17de8a33..3db493f9 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-light.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-builder-light.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-dark.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-dark.png index 35634d63..1c7f15c1 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-dark.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-dark.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-light.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-light.png index 0512231a..373b66e2 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-light.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-gallery-light.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-dark.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-dark.png index 2b2f618e..ad284824 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-dark.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-dark.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-light.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-light.png index c8577caf..ac79ed18 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-light.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-mapping-light.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-dark.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-dark.png index ed640f84..5a5be801 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-dark.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-dark.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-light.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-light.png index c44601ac..d4035a26 100644 Binary files a/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-light.png and b/images/explore/chart-types/custom-project-charts/custom-chart-types-picker-light.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-upgrade-dark.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-upgrade-dark.png new file mode 100644 index 00000000..d6f740be Binary files /dev/null and b/images/explore/chart-types/custom-project-charts/custom-chart-types-upgrade-dark.png differ diff --git a/images/explore/chart-types/custom-project-charts/custom-chart-types-upgrade-light.png b/images/explore/chart-types/custom-project-charts/custom-chart-types-upgrade-light.png new file mode 100644 index 00000000..39fa073c Binary files /dev/null and b/images/explore/chart-types/custom-project-charts/custom-chart-types-upgrade-light.png differ diff --git a/images/explore/chart-types/select-chart-type-dark.png b/images/explore/chart-types/select-chart-type-dark.png new file mode 100644 index 00000000..0c1e23ca Binary files /dev/null and b/images/explore/chart-types/select-chart-type-dark.png differ diff --git a/images/explore/chart-types/select-chart-type-light.png b/images/explore/chart-types/select-chart-type-light.png new file mode 100644 index 00000000..f6bcc278 Binary files /dev/null and b/images/explore/chart-types/select-chart-type-light.png differ diff --git a/images/explore/chart-types/select-chart-type.png b/images/explore/chart-types/select-chart-type.png deleted file mode 100644 index 8e5b005a..00000000 Binary files a/images/explore/chart-types/select-chart-type.png and /dev/null differ