Skip to main content
SQL files let you define reusable SQL queries that can be referenced across your project. This is useful for:
  • Organizing complex queries in dedicated files
  • Reusing the same query across multiple pages
  • Keeping your markdown cleaner by separating SQL from content

​
Creating SQL Files

Create a new SQL file from the file tree sidebar by clicking the + button on a directory and selecting “New SQL File”. SQL files use the .sql extension. Write your query directly in the editor with full SQL autocomplete support: 
SELECT
    date,
    sum(amount) as total_amount,
    count(*) as order_count
FROM orders
WHERE status = 'completed'
GROUP BY date
ORDER BY date DESC

​
Referencing SQL Files

​
From Components

Reference a SQL file in any component’s data attribute using the file path: 
{% bar_chart data="queries/orders_by_date" x="date" y="total_amount" /%}

{% table data="queries/orders_by_date" /%}

​
From Inline Queries

Reference a SQL file from an inline query using the same syntax: 
```sql orders_summary
SELECT * FROM {{queries/orders_by_date}}
WHERE total_amount > 1000
```
This allows you to build on top of SQL file queries with additional filtering or transformations.

​
Key Differences from Inline Queries

FeatureSQL FilesInline Queries
LocationStandalone .sql filesEmbedded in markdown
ReusabilityCan be used across multiple pagesScoped to the page
Variable interpolationNot supportedSupported

​
Best Practices

  • Use SQL files for shared queries: If you need the same data on multiple pages, put the query in a SQL file.
  • Use inline queries for page-specific logic: For queries that use page filters or variables, inline queries are more flexible.
  • Organize with directories: Create a queries/ directory to keep your SQL files organized.
  • Keep SQL files focused: Each file should contain a single, well-defined query.