Skip to main content

​
Overview

Quail provides powerful charting capabilities that transform your data into clear, actionable visualizations. Whether you’re creating a simple bar chart or a complex multi-series visualization, Quail makes it easy to build, customize, and share charts.

​
Creating Charts

You can create charts in Quail through multiple methods, depending on your workflow:
1

Navigate to Charts

Click on Charts in the main navigation menu.
2

Create New Chart

Click the Create New Chart button in the top right.
3

Select Data Source

Choose your database connection and either:
  • Select an existing table or view
  • Write a custom SQL query
4

Choose Chart Type

Select the type of chart that best represents your data (bar, line, pie, etc.).
5

Configure Settings

Map your data columns to chart elements:
  • X-axis and Y-axis
  • Series grouping
  • Filters and aggregations
6

Save Your Chart

Give your chart a name and description, then click Save.

​
Chart Types and When to Use Them

Choosing the right chart type is crucial for effectively communicating your data insights.

​
Bar Charts

Best for:
  • Comparing values across categories
  • Showing rankings
  • Displaying discrete data
Use cases:
  • Sales by product category
  • Customer count by region
  • Top 10 products by revenue
Variants:
  • Vertical bars: Standard comparison
  • Horizontal bars: Better for long category names
  • Stacked bars: Show composition within categories
  • Grouped bars: Compare multiple series side-by-side
Bar charts work best with 2-15 categories. If you have more, consider filtering to top N or using a different chart type.

​
Line Charts

Best for:
  • Showing trends over time
  • Continuous data
  • Multiple series comparison
Use cases:
  • Daily revenue trends
  • Website traffic over time
  • Year-over-year comparison
Variants:
  • Single line: One metric over time
  • Multi-line: Compare multiple metrics
  • Area chart: Emphasize magnitude of change
  • Stacked area: Show composition over time
Line charts are most effective when your x-axis represents time or another continuous variable.

​
Pie and Donut Charts

Best for:
  • Showing proportions and percentages
  • Part-to-whole relationships
  • Composition of a total
Use cases:
  • Market share distribution
  • Revenue breakdown by category
  • Customer segmentation
Best practices:
  • Limit to 5-7 slices maximum
  • Start largest slice at 12 o’clock
  • Use a legend for small slices
  • Consider a bar chart if values are similar
Pie charts can be difficult to read when slices are similar in size. Consider using a bar chart instead for easier comparison.

​
Scatter Plots

Best for:
  • Showing relationships between two variables
  • Identifying correlations
  • Detecting outliers
Use cases:
  • Price vs. units sold
  • Customer lifetime value vs. acquisition cost
  • Age vs. purchase frequency
Features:
  • Bubble size for third dimension
  • Color for categories
  • Trend lines

​
Radar Charts

Best for:
  • Comparing multiple variables across categories
  • Showing strengths and weaknesses
  • Multi-dimensional data
Use cases:
  • Product feature comparison
  • Performance metrics across teams
  • Customer satisfaction scores

​
Polar Area Charts

Best for:
  • Cyclical data
  • Comparing categories with circular layout
  • Emphasizing magnitude differences
Use cases:
  • Sales by hour of day
  • Activity by day of week
  • Seasonal patterns

​
Customizing Your Charts

Quail provides two ways to customize your charts:

​
Using the AI Agent

The easiest way to customize charts is by asking the AI agent:
1

Select Your Chart

Open the chart you want to customize.
2

Click Edit or Chat

If the chart was created in Chat, continue the conversation. Otherwise, click Edit with AI.
3

Request Changes

Tell the agent what you want to change:
  • “Change the colors to blue and green”
  • “Make the title bigger”
  • “Add a subtitle explaining this data”
  • “Show values on the bars”
  • “Format the y-axis as currency”
4

Review and Apply

The agent updates the chart. If you like it, click Save. If not, ask for more changes.

​
Manual Editing (Advanced)

For precise control, you can manually edit the chart configuration:
1

Save the Chart

Charts must be saved before manual editing is available.
2

Open Chart File

Saved charts are stored as MDX files with React components. You can edit these files directly.
3

Edit JSX Components

Modify the chart components using standard React and charting library syntax.
4

Preview Changes

Your changes are reflected immediately in the chart preview.
Manual editing requires familiarity with React and Quail’s charting components. Most users will find the AI agent sufficient for their customization needs.

​
Chart Customization Options

Whether using the AI agent or manual editing, you can customize:

​
Style and Appearance

Colors

  • Single color or color scheme
  • Custom colors for each series
  • Gradient fills
  • Conditional colors based on values

Typography

  • Title and subtitle
  • Font sizes and families
  • Axis labels
  • Legend formatting

Layout

  • Chart dimensions
  • Padding and margins
  • Legend position
  • Grid lines and background

Data Labels

  • Show/hide values on chart
  • Number formatting
  • Label position
  • Units and prefixes

​
Data Configuration

Axes

  • Scale type (linear, logarithmic)
  • Min and max values
  • Axis labels and units
  • Tick intervals

Series

  • Multiple data series
  • Series names and colors
  • Series types (line, bar, area)
  • Show/hide series

Filters

  • Date range filters
  • Category filters
  • Top N filters
  • Custom SQL filters

Aggregations

  • SUM, AVG, COUNT, MIN, MAX
  • Group by dimensions
  • Calculated fields
  • Running totals

​
Saving and Organizing Charts

​
Saving Charts

1

Complete Your Chart

Ensure your chart displays the data and styling you want.
2

Click Save

Click the Save button in the chart editor.
3

Add Metadata

Provide:
  • Name: Clear, descriptive name
  • Description: What the chart shows and why it’s useful
  • Tags: Keywords for organization (e.g., “sales”, “monthly”, “executive”)
4

Confirm

Click Save Chart to store it in your charts library.

​
Organizing Your Charts

Keep your charts organized as your library grows:
  • Use descriptive names: “Q1 2026 Revenue by Region” is better than “Chart 1”
  • Add tags: Tag charts by topic, department, or time period
  • Create folders: Group related charts together
  • Star favorites: Mark frequently used charts
  • Archive old charts: Remove outdated visualizations

​
Adding Charts to Dashboards

Charts become even more powerful when combined into dashboards:
1

Open Your Chart

Navigate to the chart you want to add to a dashboard.
2

Click Add to Dashboard

Click the Add to Dashboard button.
3

Select Dashboard

Choose an existing dashboard or create a new one.
4

Confirm

Click Add to place your chart on the dashboard.
5

Arrange on Dashboard

Navigate to the dashboard to arrange and resize your chart as needed.
Charts added to dashboards remain linked to the original. Updates to the chart are reflected across all dashboards using it.

​
Sharing Charts

​
Share Individual Charts

1

Open the Chart

Navigate to the chart you want to share.
2

Click Share

Click the Share button in the top right.
3

Configure Access

Choose sharing options:
  • Private: Only you can access
  • Link: Anyone with the link can view
  • Specific people: Invite by email
4

Set Permissions

Choose permission level:
  • View: Can see the chart and refresh data
  • Edit: Can modify chart settings
5

Copy Link

Copy the share link and send it to your recipients.

​
Export Options

PNG Image

Download chart as a high-resolution PNG for presentations and reports.

SVG Vector

Export as SVG for editing in design tools or printing.

CSV Data

Export the underlying data as CSV for use in spreadsheets.

Embed Code

Get embed code to display the chart on external websites.

​
Best Practices

​
Design Principles

  1. Simplicity: Remove unnecessary elements that don’t add to understanding
  2. Clarity: Use clear titles, labels, and legends
  3. Consistency: Use the same colors and styles across related charts
  4. Accessibility: Ensure colors are distinguishable and text is readable

​
Data Accuracy

  1. Verify queries: Always check that your query returns the correct data
  2. Update frequency: Note when data was last refreshed
  3. Handle nulls: Decide how to display missing or null values
  4. Check aggregations: Ensure SUM, AVG, etc. are calculated correctly

​
Performance

  1. Limit data points: Charts with thousands of points may render slowly
  2. Use aggregation: Aggregate data at the database level when possible
  3. Add filters: Allow users to filter data for faster rendering
  4. Cache results: Enable caching for frequently viewed charts

​
Naming and Documentation

  1. Descriptive titles: Clearly state what the chart shows
  2. Add context: Include time periods, filters, or other relevant details
  3. Document calculations: Explain any custom calculations or metrics
  4. Include sources: Note which tables and databases are used

​
Troubleshooting

​
Chart Not Displaying Data

  • Verify your query returns results in the SQL Editor
  • Check that columns are mapped correctly to chart axes
  • Ensure date formats are recognized properly
  • Look for null values that might be filtered out

​
Chart Looks Wrong

  • Try a different chart type that better fits your data
  • Check axis scales (linear vs. logarithmic)
  • Verify data aggregation is correct
  • Review filter settings

​
Performance Issues

  • Reduce the number of data points
  • Add filters to limit results
  • Use server-side aggregation
  • Consider caching for frequently accessed charts

Build docs developers (and LLMs) love

Get started for freeTalk to us