Spec Version:
Validate SQL Model Resource using Rudder CLI Beta
- free
- growth
- enterprise
4 minute read
This guide covers how to validate configurations and preview query results using Rudder CLI.
Prerequisites
- Rudder CLI tool installed and authenticated with your access token
- A CLI project directory with SQL model resources
- Access to the data warehouses referenced by your models
Overview
The Rudder CLI provides powerful validation and preview capabilities that help you test your SQL models before deploying them to production.
The preview feature allows you to execute your SQL queries and see the results before applying changes to your workspace — this is helpful for testing query logic and ensuring data quality.
Preview command
Run the below command to preview a specific SQL model resource:
rudder-cli retl-sources preview campaigns-cli -l path/to/project --limit 10
When you run a preview command, Rudder CLI:
- Validates connection: Confirms it can connect to the specified data warehouse.
- Executes query: Runs your SQL query against the warehouse.
- Returns results: Shows you a sample of the query results.
You can also use thepreviewcommand to validate that the primary key column is present in the result set.
Command parameters
The following table lists the parameters for the preview command:
Preview command examples
The following example demonstrates the key parameters available with the preview command:
rudder-cli retl-sources preview api-test-10 --location path/to/project --limit 5 -j --interactive=false
The above command:
- Previews the SQL model with ID
api-test-10 - Uses
path/to/projectas the location for the CLI project directory - Limits results to 5 rows using
--limit 5 - Outputs results in JSON format using
-j - Runs in non-interactive mode using
--interactive=false
Validation
Validation ensures your SQL model configurations are correct before deployment. It performs comprehensive checks without executing the full query.
Validate a specific resource
rudder-cli retl-sources validate campaigns-cli -l path/to/project
What validation checks
The validation process verifies:
SQL Syntax
- Ensures your SQL query is syntactically correct
- Validates it’s compatible with your specified warehouse type
Connectivity
- Tests connection to the specified account/warehouse
- Verifies authentication and permissions
Configuration integrity
- Validates all required fields are present and properly formatted
- Ensures account ID references exist and are accessible
Query execution (limited)
- Tests that the query can execute without errors
- May run a limited version of the query to validate structure
Best practices
This section provides best practices for using validation and preview in your development and CI/CD workflows.
Development workflow
- Write query: Create or modify your SQL in the YAML or SQL file.
- Validate first: Run validation to check syntax and configuration.
- Dry run: Use
--dry-runwithapplycommands to see what will change. - Preview results: Use preview to verify query logic and results.
- Iterate: Refine your query based on preview results.
- Final validation: Run validation once more before committing.
CI/CD pipeline
- Always validate: Include validation in your automated checks.
- Limited preview: Use preview sparingly in CI/CD due to performance implications.
Troubleshooting
This section provides troubleshooting tips for common issues you may encounter when using validation and preview.
Common validation errors
| Issue | Resolution steps |
|---|---|
| Account not found |
|
| SQL Syntax Error |
|
| Primary Key Column Missing |
|
| Connection Timeout |
|
Error handling
| Error | Resolution steps |
|---|---|
| Connection issues | Check account credentials and network connectivity |
| SQL errors | Review query syntax and warehouse-specific SQL dialect requirements |
| Primary key issues | Ensure the specified primary key column exists in your query results |
| Timeout issues | Simplify complex queries for validation, optimize for production |
