Back to tutorials

dbt run-operation Command: Usage & Examples


What is dbt?

dbt is a transformative software in analytics and engineering. It bridges the gap between raw data in your warehouse and actionable insights by allowing for sophisticated transformations and modeling.

The Power of run-operation

Among dbt's arsenal of commands, run-operation stands out. It's not just about invoking macros; it's about automating repetitive tasks, ensuring data integrity, and customizing operations to suit specific business needs.

run-operation Meaning and Usage

At its core, the command is a bridge to your macros, enabling you to execute them with specific arguments.

$ dbt run-operation {macro} --args '{args}'

Deep Dive:

  • {macro}: This is your macro's name, which should be descriptive of its function.
  • -args: These are the specific details or parameters for your action. A YAML formatted string. YAML, or "YAML Ain't Markup Language", is a human-readable data serialization format. It's crucial to get the formatting right to avoid errors.

Practical Examples

The examples below assume that you’ve already created the mentioned macros, and you’re using run-operation to execute them either manually from a command line, or through a scheduled action.

Example 1: Granting Select Permissions

Business Scenario: Imagine a growing company with new hires in the data department. Instead of manually granting permissions, automate the process using this macro.


$ dbt run-operation grant_select --args '{role: reporter}'

Example 2: Cleaning Stale Models

Business Scenario: As data accumulates, old models can clutter your warehouse. Regularly cleaning them optimizes performance and storage costs.


$ dbt run-operation clean_stale_models --args '{days: 7, dry_run: True}'

Example 3: Updating Sales Metrics

Business Scenario: Monthly sales reviews are common in businesses. Automate the data gathering process to ensure timely and accurate reports.


$ dbt run-operation update_sales_metrics --args '{month: "July", year: 2023}'

Example 4: Archiving Old Customer Data

Business Scenario: Compliance, like GDPR, mandates certain data handling practices. Use this operation to ensure you're not retaining customer data longer than necessary.


$ dbt run-operation archive_old_customers --args '{inactive_days: 365}'

Example 5: Generating Monthly Financial Reports

Business Scenario: Financial reviews are pivotal for business strategy. Generate tailored financial reports for specific departments to aid in decision-making.


$ dbt run-operation generate_financial_report --args '{month: "August", year: 2023, department: "Sales"}'

Tips and Best Practices

  • Validation: Always validate your macros and arguments before executing to ensure data integrity.
  • Documentation: A well-documented macro is easier to use and reduces the risk of errors.
  • Regular Updates: As your business evolves, so will your data needs. Regularly review and update your macros to stay relevant.

Troubleshooting Common Issues

  • YAML Formatting: Common errors include missing spaces or incorrect indentation. Use online YAML validators for assistance.
  • Macro Errors: Ensure your macro is correctly defined in your dbt project.
  • Argument Issues: Missing or incorrectly formatted arguments can cause failures. Always refer to your macro's documentation.


The dbt run-operation command, when mastered, can be a game-changer. It streamlines processes, ensures data accuracy, and allows for a high degree of customization. As with any tool, the key lies in understanding its potential and applying it effectively.

Additional Resources

database icon
The first SQL editor with built-in dbt Core ™
Simplified dbt development - Create and manage your dbt models and macros all in one place with PopSQL