Skip to content

Best Practices

Dashboard design and development best practices for Dataface.

Naming Conventions

Dashboard Names

  • Use lowercase with underscores: sales_overview, not Sales Overview
  • Be descriptive: monthly_sales_dashboard is better than dashboard1
  • Avoid spaces and special characters

Query Names

  • Use descriptive names that indicate what data the query fetches: sales, products, customers
  • Keep names concise but clear
  • Use explicit namespacing (queries.sales) when needed to avoid collisions

Chart IDs

  • Use descriptive names: revenue_by_month, not chart1
  • Indicate chart purpose: sales_trend, kpi_revenue
  • Be consistent with naming patterns

Variable Names

  • Use clear, descriptive names: region, date_range, min_revenue
  • Avoid abbreviations unless widely understood
  • Use snake_case consistently

Organization Strategies

Keep queries for the same domain together:

queries:
  # Sales queries
  sales: ...
  sales_by_region: ...

  # Product queries
  products: ...
  product_categories: ...

Use Sections for Logical Grouping

Break dashboards into logical sections:

sections:
  - title: "Overview"
    # High-level KPIs
  - title: "Trends"
    # Time series charts
  - title: "Details"
    # Detailed tables

Add Descriptions

Help others understand your dashboard:

title: "Sales Dashboard"
description: "Monthly sales metrics and trends by region"

Performance Optimization

Limit Query Results

Use limit when you don't need all rows:

queries:
  sales:
    metrics: [total_revenue]
    dimensions: [month]
    limit: 100  # Only fetch 100 rows

Reuse Queries

Multiple charts can reference the same query (more efficient):

queries:
  sales:
    metrics: [total_revenue]
    dimensions: [month, region]

sections:
  - charts:
      chart1:
        query: sales  # Same query
      chart2:
        query: sales  # Same query

Use Time Grain

Let the system handle time grouping when possible:

queries:
  monthly:
    metrics: [total_revenue]
    dimensions: [order_date]
    time_grain: month  # Automatic grouping

Filter Early

Use query filters to limit data:

queries:
  filtered:
    metrics: [total_revenue]
    filters:
      region: region  # Filter at query level
      order_date: "{{ date_range }}"

User Experience

Provide Defaults

Set sensible default values for variables:

variables:
  region:
    default: "North"  # Show useful data by default

  date_range:
    default: "2024-01-01"  # Recent time period

Use Appropriate Input Types

Match input types to use cases:

  • Select: Single choice from predefined list
  • Slider: Numeric ranges
  • Date range: Time period selection
  • Checkbox: Simple on/off flags

Add Descriptions

Help text makes dashboards more usable:

charts:
  revenue_chart:
    title: "Revenue by Month"
    description: "Monthly revenue trends over the past 12 months"
    query: sales
    type: bar

Test Interactions

Verify click actions and filters work as expected:

  • Test all variable combinations
  • Verify chart interactions
  • Check filter behavior
  • Test on different screen sizes

Common Patterns

Summary + Detail

Show high-level summary with drill-down detail:

sections:
  - title: "Summary"
    charts:
      summary_kpi: ...
  - title: "Details"
    charts:
      detail_table: ...

Time Series with Filters

Combine time series with filters:

variables:
  region: ...

queries:
  trends:
    metrics: [total_revenue]
    dimensions: [month]
    filters:
      region: region

charts:
  trend_chart:
    query: trends
    type: line
    x: month
    y: total_revenue

Comparison Views

Compare metrics side by side:

charts:
  comparison:
    query: sales
    type: bar
    x: month
    y: total_revenue
    color: region  # Compare regions

Anti-Patterns to Avoid

❌ Missing Query References

charts:
  chart1:
    query: nonexistent  # Error: query doesn't exist

❌ Invalid Metric Names

queries:
  sales:
    metrics: [invalid_metric]  # Error: metric doesn't exist in Semantic Layer

❌ Circular Dependencies

variables:
  var1:
    default: "{{ var2 }}"  # var2 depends on var1 - circular!
  var2:
    default: "{{ var1 }}"

❌ Missing Required Fields

charts:
  chart1:
    # Missing: query, type
    x: month

❌ YAML Syntax Errors

Common mistakes: - Wrong indentation (use spaces, not tabs) - Missing colons - Unquoted special characters

Version Control Best Practices

Commit Dashboard Files

Dashboard YAML files are version-controlled: - Commit dashboard changes with model changes - Use descriptive commit messages - Review dashboard changes in PRs

Organize by Feature

Group related dashboards: 

dashboards/
  sales/
    overview.yml
    trends.yml
  marketing/
    campaigns.yml
    leads.yml

Document Changes

Add comments for complex logic:

queries:
  complex:
    metrics: [total_revenue]
    filters:
      # Filter to active customers only
      status: "active"
      # Exclude test data
      is_test: false

Development Workflow

Validate Before Committing

Always validate your dashboards before committing:

face validate dashboards/

See the CLI Reference for validation options.

Use Compile for Debugging

When troubleshooting, compile your dashboard to see the normalized structure:

face compile dashboards/sales.yml --format yaml

See the CLI Reference for compilation options.

Preview While Developing

Use the serve command with auto-reload for fast iteration:

face serve dashboards/sales.yml --reload

See the CLI Reference for server options.