Chart Builder

What is the Chart Builder?

The Chart Builder is a powerful visualization tool that transforms query results into interactive charts. It sits on top of the VisuaLeaf Charts backend, which speaks both MongoDB and SQL — so a single chart can be powered by a MongoDB aggregation pipeline or a plain SQL query against any relational database you have connected (PostgreSQL, MySQL, SQL Server, and more). Whether you're analyzing sales trends, monitoring metrics, exploring geographic data, or building business dashboards, the Chart Builder provides an intuitive interface to create professional visualizations without writing display code.

Key Features

• 20+ Chart Types - Bar, line, pie, doughnut, scatter, area, radar, boxplot, funnel, treemap, heatmap, geo/map, and more
• MongoDB or SQL Source - Power a chart with a MongoDB aggregation pipeline or a SQL query against any connected relational database
• Auto-Detection - Field types (numeric, string, date, geographic) are inferred from sample data and mapped to the right chart axes
• Live Preview - See your chart update in real-time as you adjust mappings and settings
• Custom Labels - Add titles, subtitles, and axis labels to make your charts presentation-ready
• Chart Library & Dashboards - Save charts to folders, organize your library, and pin charts to dashboards
• Source Editing - Modify the underlying MongoDB pipeline or SQL query directly from the Chart Builder

Data Sources: MongoDB or SQL

The Chart Builder is source-agnostic. Every chart is backed by one of two query types, and you can switch between them without leaving the builder:

• MongoDB aggregation - Build a pipeline in the Aggregation Builder, then click Create Chart. Every stage from $match to $group to $lookup is supported.
• SQL query - Paste (or write) a SQL statement against any registered SQL connection. Full SELECT + JOIN + GROUP BY is supported — whatever your database's dialect allows.

Under the hood the Charts backend executes the source query, streams the result set into a common tabular shape, and hands it to the field-mapping layer. From that point on the workflow (auto-detect, mapping, customization, save) is identical regardless of source.

Available Chart Types

The Chart Builder supports a comprehensive range of visualization types, organized into four categories. Each chart type is optimized for different kinds of data and analysis scenarios.

Basic Charts

Fundamental chart types for common data visualization needs:

• Bar - Compare values across categories with vertical or horizontal bars
• Line - Show trends and changes over time or continuous data
• Area - Emphasize magnitude of change over time with filled areas
• Pie - Display proportions and percentages of a whole
• Donut - Similar to pie chart with a hollow center, better for multiple series
• Scatter - Plot two numeric variables to identify correlations and patterns
• Bubble - Scatter plot with a third dimension represented by bubble size

Advanced Analytics Charts

Sophisticated visualizations for complex data analysis:

• Funnel - Visualize stages in a process and identify conversion drop-offs
• Gauge - Display a single value within a defined range, like a speedometer
• Heatmap - Show intensity or density using color gradients across two dimensions
• Treemap - Display hierarchical data as nested rectangles sized by value
• Sunburst - Circular hierarchical visualization showing relationships and proportions
• Sankey - Flow diagram showing relationships and quantities between entities
• Radar - Compare multiple variables on axes radiating from a center point

Time-Series Charts

Specialized charts for temporal data and financial analysis:

• Timeline - Display events or data points along a chronological axis
• Candlestick - Financial chart showing open, high, low, and close values (OHLC)
• Calendar - Heatmap-style visualization organized by calendar dates

Geographic Charts

Map-based visualizations for location data:

• Geo Map - Plot data on world, country, or regional maps using regions or boundaries
• Geo Scatter - Display points on a map using latitude and longitude coordinates
• Geo Heatmap - Show geographic data intensity using color gradients on maps

Creating a Chart

Charts are created from data sources - either query results or aggregation pipeline outputs. The Chart Builder provides multiple ways to access and configure your data.

Step 1: Access the Chart Builder

There are three ways to open the Chart Builder, depending on where your data lives:

• From Collection Activity - After running a MongoDB query, click the "Create Chart" button in the toolbar to visualize the results
• From Aggregation Activity - After building a pipeline, click "Create Chart" to turn the aggregated data into a visualization
• From SQL Query Activity - After running a SQL query against a registered SQL connection, click "Create Chart" to chart the result set the same way

Step 2: Choose Your Chart Type

The chart type selector in the left panel displays all available visualization types. Click the dropdown to browse chart types, organized by category. Each type shows an icon and name to help you quickly identify the right visualization for your data.

Step 3: Understanding Your Data

The Chart Builder intelligently analyzes your actual data values to accurately detect field types:

• Numeric Fields - Detected by examining actual values including MongoDB BSON types (Int32, Long, Double, Decimal128). Numbers suitable for measurements, counts, and values
• String Fields - Text values suitable for categories, labels, and dimensions
• Date Fields - Detected from Date objects and ISO date strings. Used for time-series analysis
• Geographic Fields - Detected from GeoJSON objects or coordinate arrays. Used for map visualizations
• Nested Fields - Arrays and embedded documents detected for complex data structures

The type detection examines your actual query results to ensure accurate field classification. If a field's type cannot be determined from the data, the system falls back to intelligent name-based heuristics (e.g., fields named "count", "total", or "amount" are assumed numeric). This two-layer approach ensures reliable auto-mapping even with diverse data schemas.

Field Mapping

Field mapping connects the columns / fields returned by your source query — MongoDB documents or SQL rows — to chart dimensions like axes, values, and categories. Different chart types require different field mappings based on their structure.

Auto-Detection

Click the "Auto Detect" button to let the Chart Builder intelligently map your fields. The auto-detection algorithm:

• Analyzes your actual data values to accurately determine field types
• Matches fields to the requirements of your selected chart type
• Falls back to name-based heuristics when data analysis is inconclusive
• Provides a starting point that you can refine manually

Data Field Mapping Panel

The data mapper panel displays each field with a color-coded type badge indicating its detected type:

• Blue (Number) - Numeric fields suitable for Y-axis values and calculations
• Green (String) - Text fields for categories and labels
• Purple (Date) - Date/time fields for X-axis in time-series charts
• Teal (Geo) - Geographic fields for map-based visualizations
• Orange (Object) - Nested documents and arrays

Common Field Mappings by Chart Type

Bar, Line, and Area Charts

Pie and Donut Charts

Scatter and Bubble Charts

Heatmap Charts

Geographic Charts

Candlestick Charts

Sankey Diagrams

Manual Field Mapping

To manually configure field mappings, use the dropdowns in the data mapper panel. Each dropdown shows the available fields from your data. As you change mappings, the chart preview updates in real-time to reflect your selections.

Chart Customization

The configuration panel on the right side provides extensive options to customize your chart's appearance and behavior.

Basic Settings

Display Labels

Customize how your chart appears by adding custom labels and titles. These labels are displayed in the rendered chart visualization.

Tip: Leave axis labels empty to automatically use the field names from your data. Add custom labels when you want more descriptive or user-friendly text in your charts.

Editing the Data Source

Charts are powered by a MongoDB query, a MongoDB aggregation pipeline, or a SQL query. You can modify the underlying data source directly from the Chart Builder without leaving the interface.

Editing a Query-Based Chart

Click the "Edit Query" button to open a Collection Activity where you can:

• Modify the filter query to change which documents are included
• Adjust sort order to reorganize results
• Update projection to include or exclude specific fields
• Change limit and skip values to control result size

When you're done editing, the Chart Builder automatically refreshes with the updated data.

Editing an Aggregation-Based Chart

Click the "Edit Aggregation" button to open an Aggregation Activity where you can:

• Add, remove, or reorder pipeline stages
• Modify stage configurations to transform data differently
• Use the preview panel to verify each stage's output
• Build complex data transformations with grouping, calculations, and joins

Changes to the aggregation pipeline immediately affect the chart's data source.

Editing a SQL-Based Chart

Click the "Edit SQL" button to open the SQL editor where you can:

• Rewrite the SELECT list, filters, joins, or grouping
• Switch to a different SQL connection (dev, staging, prod)
• Preview the result set before the chart re-renders
• Use any dialect features your database supports (window functions, CTEs, etc.)

Walkthrough: Build a Bar Chart from a PostgreSQL orders Table

This end-to-end example shows how to chart data that lives in a SQL database rather than MongoDB. Suppose you have a PostgreSQL orders table and you want a bar chart of total revenue by country for the last 30 days.

1. Register the SQL connection. Open the Connection Manager and add your PostgreSQL database (host, port, database, user, password). Test the connection.
2. Open a SQL Query Activity against that connection.
3. Write the query. Paste a statement that produces one row per country:

   SELECT
       country,
       SUM(total)::numeric(12,2) AS revenue,
       COUNT(*)                  AS order_count
   FROM orders
   WHERE created_at >= NOW() - INTERVAL '30 days'
     AND status = 'completed'
   GROUP BY country
   ORDER BY revenue DESC
   LIMIT 20;

4. Run the query. Verify you get a result set with columns country, revenue, and order_count.
5. Click "Create Chart". The Chart Builder opens with the SQL result set already loaded.
6. Pick "Bar" from the chart type dropdown.
7. Click "Auto Detect". Auto-detection sees country as a string and revenue as numeric, and maps them to X-axis and Y-axis respectively.
8. Fine-tune labels. Set the chart title to "Revenue by Country (Last 30 Days)", the X-axis label to "Country", and the Y-axis label to "Revenue (USD)".
9. (Optional) Add a series. To split each bar by order_count, choose a different chart type such as a stacked bar or switch to a combo chart.
10. Save the chart to a folder like reports/sales. Then open the Dashboard Builder and pin the chart to your sales dashboard for daily viewing.

The exact same workflow applies to MySQL, SQL Server, and other supported SQL databases — only the SQL syntax changes, and only in the ways your database dialect requires.

Saving and Managing Charts

Once you've created and configured your chart, save it to your workspace for future access and reuse. Saved charts land in the Chart Library where they can be organized into folders, edited, and pinned to dashboards for at-a-glance monitoring.

Saving a Chart

1. Ensure you've provided a meaningful chart title in the configuration panel
2. Optionally set a folder path to organize the chart (e.g., "sales/monthly" or "analytics")
3. Click the "Save Chart" button in the bottom-right corner
4. The chart is now saved and accessible from the Charts workspace

Updating an Existing Chart

When you open a saved chart and make changes:

• The chart automatically enters edit mode
• Modify any settings, mappings, or the data source
• Click "Save Chart" to update the existing chart with your changes
• All references to this chart (in dashboards or links) will reflect the updates

Chart Organization

Use folder paths to organize charts hierarchically:

• Use forward slashes to create nested folders: reports/sales/monthly
• Leave the folder field empty to save charts at the root level
• Use consistent naming conventions across your team for easy discovery
• Consider organizing by: department, project, data source, or chart type

Actions and Workflow

• Auto Detect Fields - Automatically map fields to chart dimensions based on data types and chart requirements. Click the "Auto Detect" button in the data mapper panel to let the system intelligently suggest field mappings. This is the fastest way to get started with a new chart.
• Edit Query/Aggregation - Modify the underlying data source without leaving the Chart Builder. Click "Edit Query" or "Edit Aggregation" in the preview panel to open the appropriate editor, make your changes, and see the chart update automatically.
• Toggle Panels - Collapse the left or right panels to maximize chart preview space. Use the blue toggle button on the left panel and the purple toggle button on the right panel. This is helpful when working with complex charts that need more screen space.
• Switch Chart Types - Experiment with different visualizations by changing the chart type. Click the chart type dropdown in the left panel and select a new type. Click outside the dropdown to close it without making a selection. Your field mappings will be preserved where applicable, making it easy to find the best visualization for your data.
• Save Chart - Save your configured chart to the workspace for future access. Ensure you've set a meaningful title and optional folder path, then click "Save Chart" in the bottom-right corner. The chart will be available in the Charts workspace for viewing and editing.
• Cancel - Close the Chart Builder without saving changes. Click "Cancel" in the bottom-right corner to exit. Any unsaved modifications will be lost, so ensure you've saved your work before canceling if you want to keep your changes.

Advanced Features

Geographic Map Regions

When using geographic charts (Geo Map, Geo Scatter, Geo Heatmap), you can select different map regions to focus your visualization:

• World - Global map with all countries
• USA - United States with state boundaries
• China - China with province boundaries
• Japan - Japan with prefecture boundaries
• Canada - Canada with province/territory boundaries
• UK - United Kingdom with regional boundaries
• Germany - Germany with state boundaries
• France - France with regional boundaries
• India - India with state boundaries
• Australia - Australia with state/territory boundaries
• Europe - European continent view
• Asia - Asian continent view

Real-Time Preview

The Chart Builder provides instant visual feedback:

• Charts update automatically as you change field mappings
• Label changes are reflected immediately in the preview
• Switching chart types preserves your data and shows the new visualization instantly
• Data limit changes trigger automatic re-query after a short delay

Data Limit Management

The data limit setting controls how many documents are fetched for visualization:

• Default limit is 1000 documents for balanced performance and data completeness
• Reduce the limit for faster queries with large datasets
• Increase the limit (up to 10,000) when you need comprehensive data coverage
• Changes to the limit automatically re-execute the query after a brief debounce period

Pro Tips

• Start with Auto Detect - Use the "Auto Detect" button first to get intelligent field mappings, then manually refine them. This saves time and helps you understand which fields work best for each chart type.
• Prepare Data with Aggregation - For complex charts, use aggregation pipelines to pre-process data before charting. Group, calculate, and transform your data first, then create simple charts from the aggregated results.
• Use Folders for Organization - Establish a folder structure early (e.g., "dashboards/executive", "reports/monthly", "analytics/user"). This makes charts easier to find and maintain as your library grows.
• Experiment with Chart Types - Don't settle on the first chart type. Try switching between Bar, Line, Area, and other types to find the clearest way to communicate your data story. Different types reveal different insights.
• Add Descriptive Labels - While field names work as defaults, adding custom titles, subtitles, and axis labels makes charts more professional and easier to understand for stakeholders who may not know your data schema.
• Optimize Data Limits - For time-series or trending data, consider reducing the data limit and using sort orders to show "Top N" or "Most Recent" data. This improves performance while keeping charts focused and readable.
• Leverage Geographic Charts - If your data includes location information (coordinates, country/state names, regions), geographic visualizations can reveal spatial patterns that are invisible in traditional charts.
• Use Heatmaps for Patterns - Heatmaps are excellent for finding patterns in two-dimensional categorical data, like "hour of day vs. day of week" or "product vs. region". The color intensity makes patterns jump out visually.

Related Features

• Collection Activity - Query collections and create charts from filtered result sets. Use the Query Builder to construct complex filters, then visualize the results with one click.
• Aggregation Pipeline Builder - Build powerful data transformations with MongoDB's aggregation framework. Create charts from grouped, calculated, and transformed data for advanced analytics.
• Chart Library - Access, organize, and manage all your saved charts. View charts in list or folder view, search by name or description, and open charts for editing or viewing.
• Export Data - Export chart data in various formats (JSON, CSV, Excel) for use in external tools or reports. Combine charting with data export for comprehensive analysis workflows.