home / skills / windmill-labs / windmill / write-script-bigquery

write-script-bigquery skill

safe

/system_prompts/auto-generated/skills/write-script-bigquery

This skill assists you write clean BigQuery queries by guiding parameter naming, syntax, and best practices for scalable analytics workflows.

npx playbooks add skill windmill-labs/windmill --skill write-script-bigquery

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

565 B

---
name: write-script-bigquery
description: MUST use when writing BigQuery queries.
---

## CLI Commands

Place scripts in a folder. After writing, run:
- `wmill script generate-metadata` - Generate .script.yaml and .lock files
- `wmill sync push` - Deploy to Windmill

Use `wmill resource-type list --schema` to discover available resource types.

# BigQuery

Arguments use `@name` syntax.

Name the parameters by adding comments before the statement:

```sql
-- @name1 (string)
-- @name2 (int64) = 0
SELECT * FROM users WHERE name = @name1 AND age > @name2;
```

Overview

This skill helps you write BigQuery queries that integrate with the platform’s script workflow. It enforces parameter syntax and metadata conventions so queries become reusable, parameterized scripts ready for deployment. Use it whenever you craft SQL that will run inside the platform’s script engine or be exposed as a webhook/workflow step.

How this skill works

The skill inspects SQL and ensures parameters use the @name syntax and that each parameter is declared in a preceding comment with type and optional default. It also guides placement of script files in the expected folder layout and reminds you to run the platform CLI commands to generate metadata and deploy. The output is a script file compatible with the platform’s metadata and lockfile generation process.

When to use it

When writing parameterized BigQuery SQL for use as a script or webhook
When preparing queries that will be incorporated into workflows or UIs
When you need query parameters to be well-typed and have defaults
When you plan to deploy scripts using the platform CLI
When converting ad-hoc SQL into production-ready, versioned scripts

Best practices

Declare each parameter in a comment immediately above the query using the -- @name (type) [= default] pattern
Prefer precise BigQuery types (STRING, INT64, BOOL, FLOAT64, TIMESTAMP) for parameter declarations
Include sensible defaults when applicable to make scripts safe to run locally and in CI
Keep queries focused and idempotent so they behave predictably as workflow steps
Run metadata generation and push commands after edits to ensure deployment metadata and lockfiles are current

Example use cases

Add a parameterized user report query to a workflow that runs nightly with a date parameter
Create a webhook that accepts an organization_id and returns aggregated metrics from BigQuery
Convert exploratory analysis into a versioned script with typed inputs and default values for reproducible runs
Embed a reusable query in a UI component that lets users supply filters and page size

FAQ

How do I declare parameters for a BigQuery script?

Add comment lines immediately above the statement using the pattern: -- @paramName (TYPE) = default. Then reference the parameter in SQL with @paramName.

What CLI steps are required to deploy the script?

Place your script file in the scripts folder, then run the metadata generation command followed by the sync push command to deploy. Also use the resource-type list command to discover available resource types.