Getting started with DataLens

This section outlines how to deploy DataLens locally, connect to a data source, create your first dataset, build multiple charts for data visualization, and place them on a dashboard.

Deploy DataLensDeploy DataLens

To deploy DataLens locally, just run multiple containers using Docker Compose:

1. If you do not have Docker, install it by following the guide for your platform:

   • macOS
   • Linux
   • Windows

2. Run the following commands:

   1. Clone the repository:

      git clone https://github.com/datalens-tech/datalens
      

   2. Go to the repository directory and run all the containers required to start DataLens:

      cd <path_to_datalens_folder> && \
      HC=1 docker compose up
      

      You can run the last command with a parameter for connecting an external database:

      METADATA_POSTGRES_DSN_LIST="postgres://{user}:{password}@{host}:{port}/{database}" HC=1 docker compose up
      

      Note

      Highcharts is a patented commercial product. If you enable Highcharts in your DataLens instance (with the HC=1 variable), make sure to comply with the license. When Highcharts is disabled, not all visualization types are available.

3. Open the DataLens UI at http://localhost:8080.

Once you run DataLens, you can:

• Review demo examples
• Attach data sources
• Build custom dashboards

The first release of the open-source version includes everything you need to try DataLens features in your infrastructure. The repository currently hosts the service core, a set of key connectors (PostgreSQL, ClickHouse®, and YTsaurus), and the main interface components.

Create a workbookCreate a workbook

In DataLens, all objects are stored in special containers, i.e., workbooks and collections:

• A workbook stores connections, datasets, charts, and dashboards.
• A collection is a container used for grouping workbooks and other collections.

To create a workbook:

1. Go to the DataLens page.
2. In the top-right corner, click Create → Create workbook.
3. Enter a name for the workbook: Quick start.
4. Click Create.

Create a connectionCreate a connection

Connections contain information about data source access parameters, such as the DB host IP address and port. You can create datasets based on connections.

To create a connection:

1. In the top-right corner of the workbook, click Create → Connection.

2. Select a ClickHouse® connection.

   1. In the window that opens, specify the connection parameters:

      • Host name: rc1a-ckg8nrosr2lim5iz.mdb.yandexcloud.net
      • HTTP interface port: 8443 (default)
      • Username: samples_ro
      • Password: MsgfcjEhJk

   2. Enable Allow subqueries in datasets and queries from charts.

   3. Click Check connection and make sure you get a green check mark.

   4. Click Create connection.

      

   5. Enter the connection name:Sample ClickHouse.

   6. Click Create.

Wait for the connection to be saved.

Create a datasetCreate a dataset

A dataset describes a set of data and its structure. It is created by connecting to a data source. A dataset is used when creating the following widgets:

• Charts: To visualize data.
• Selectors: To filter data.

To create a dataset based on the Sample ClickHouse connection:

1. In the top-right corner of the connection page, click Create dataset.

2. Drag the MS_SalesMiniTable table to the workspace.

   

3. Go to the Fields tab.

4. Create a measure for the order amount. To do this, select Sum for the Sales field in the Aggregation column.

   

5. Create a measure for the number of orders:

   1. Rename the OrderID field as OrderCount: click the field name, delete the current name, and enter the new one.
   2. Select Number of unique for the OrderCount field in the Aggregation column.

6. Change the data type for the ShopAddressCoord field: select Geopoint in the Type column.

   

7. Save the dataset:

   1. In the top-right corner, click Save.

   2. Enter Sales Dataset for the dataset name and click Create.

      

Create a column chartCreate a column chart

Charts visualize the data from a dataset as tables, diagrams, or maps.

To create a chart based on Sales Dataset:

1. Click Create chart in the top-right corner of the dataset page.

2. Add the product subcategory to the chart. To do this, drag the ProductSubcategory field from Dimensions to the X section.

3. Add a sales measure to the chart. To do this, drag the Sales field from Measures to the Y section.

4. Sort the chart by sales in descending order by dragging the Sales field from Measures to the Sorting section.

5. Save the chart:

   1. In the top-right corner, click Save.

   2. In the window that opens, enter the Sales by subcategory name for the chart and click Save.

      

Create an area chartCreate an area chart

1. Copy the chart you created in the previous step:

   1. In the top-right corner, click → Save as copy.

      

   2. In the window that opens, enter the Sales by week name for the new chart and click Save.

2. Select Area chart as the visualization type.

   

3. Replace the product subcategories with the order date on the X-axis. To do this, drag the OrderDate field from Dimensions to the X section and hold it over the ProductSubcategory field until the latter turns red.

4. Add the product category to the chart. To do this, drag the ProductCategory field from Dimensions to the Colors section.

5. Display a week by week chart:

   1. Click the calendar icon next to the OrderDate field in the X section.

   2. In the Grouping field, select Rounding → Week.

      

   3. Click Apply.

6. Remove sorting by sales: click (the icon appears when you hover over the field) next to the Sales field in the Sorting section.

7. In the top-right corner, click Save.

   

Create a pie chartCreate a pie chart

1. Copy the chart you created in the previous step:

   1. In the top-right corner, click → Save as copy.
   2. In the window that opens, enter the Sales by category name for the new chart and click Save.

2. For the visualization type, select Pie chart.

3. Add the product category to the chart. To do this, drag the ProductCategory field from Dimensions to the Color section.

4. Check that the chart includes the sales measure: the Sales field should be located in the Measures section. If it is not there, drag it from under Measures.

5. Add a measure label:

   1. Drag the Sales field from Measures to the Labels section.

   2. Click the icon to the left of the measure name.

   3. In the window that opens, for Label value, select Percentage and click Apply.

      

6. In the top-right corner, click Save.

   

Create a dashboard and add charts to itCreate a dashboard and add charts to it

A dashboard is a page or multiple pages that contain widgets. It allows you to group your charts in the same place and add captions and titles to them.

To create a dashboard:

1. Go to the Quick start workbook by clicking its name in the chart path.

   

2. In the top-right corner, click Create → Dashboard.

3. In the panel at the bottom of the page, select Chart.

4. In the window that opens, click Select.

5. Select the Sales by subcategory chart.

   

6. Click Add.

7. Repeat steps 3 through 6 to add the Sales by week and Sales by subcategory charts.

8. Adjust the size of the charts with your mouse and place them on the dashboard as you prefer.

   

Set up chart filteringSet up chart filtering

Add filtering by the Sales by subcategory chart to the dashboard to filter other charts:

1. Click in the top-right corner of the Sales by subcategory chart.

   

2. Enable the Filtering option.

   

3. Click Save.

By default, the chart used for filtering filters data in all charts on the current dashboard tab that share the same dataset.

Add a selector to the dashboardAdd a selector to the dashboard

Selectors are filters that affect the results of queries in the linked widgets.

To add a selector to a dashboard:

1. In the panel at the bottom of the page, choose Selector.

2. Add the calendar selector for the order date:

   1. Select Sales Dataset.

   2. Select the OrderDate field.

   3. In the Header field, enter Order date.

   4. Enable Range.

      

   5. Click Save.

3. Position the selector on the dashboard wherever you like.

4. Save the dashboard:

   1. In the top-right corner of the dashboard, click Save.

   2. Enter Sales for the dashboard name and click Create.

      

Learn how a dashboard worksLearn how a dashboard works

1. Apply cross-chart filtering on the dashboard:

   1. In the Sales by subcategory chart, click the column with the Kitchen appliances value. This will filter the linked charts by the selected dimension.

      {

   2. Clear chart filtering by clicking the selected item once more or in the top-right corner of the chart.

2. Use the Order date selector:

   1. In the Order date selector, enter the period start and end dates: 01.01.2019 - 31.01.2019.

   2. This will filter data by the OrderDate field in all charts on the current tab that share the same dataset.

      

   3. Clear selector filtering by clicking in the right corner of the selector.

What's nextWhat's next

• Read about service concepts.
• View an example of a ready-to-use dashboard.

ClickHouse® is a registered trademark of ClickHouse, Inc.