Scripts
Save the code behind an answer, rerun it on new data with one click, fork per client, schedule.
A Script is a saved, named, parameterized piece of code. It’s the side of an Agent answer you don’t usually see — the SQL, the Python, the munging — turned into something you can run again tomorrow.
Use a Script when the question stays the same but the data changes. A consultant doing cohort retention for twelve clients. A founder running the same health check every Monday. A dev comparing this sprint’s errors to last sprint’s.
Creating a Script
From the Keep bar under any Agent answer, click ＋ Save as Script. The Agent packages the tool calls that produced the answer into a named function with:
- A title you can rename.
- Parameters extracted from the query — any literal (a date, a client name, a threshold) the Agent used becomes an editable input.
- The full code (SQL + Python) ready to re-execute.
Scripts live in the Sidebar → Scripts. You can also browse them by category (analysis / transform / report / alert) and search by name.
Anatomy of a Script
A Script has three parts:
- Inputs — named parameters with types and defaults.
start_date: date = last_monday(),client_name: text,threshold: number = 0.03. - Steps — ordered tool calls (SQL, Python, fetches). Each step can reference outputs from earlier steps.
- Output — what to return. A table, a KPI, a Markdown block, a chart, or a combination.
Editing a Script looks like editing a notebook — each step is a cell. You can run one step at a time while debugging.
Running a Script
Three ways:
- Manual — click Run. Fill in the parameters. See the output.
- Schedule — see Automation below.
- Ask the Agent — “run the weekly-churn script with start_date = last Monday.”
Output shows up in the right panel. You can save the output as a Report, pipe it to a Watch, or chain it into another Script.
Schema auto-mapping
The best-in-class reason to use a Script: the Agent can adapt it to new data without you rewriting the query.
Example: you wrote a Script against a table with columns (user_id, signup_date, plan). You run it against a new client whose table has (customer_id, registered_at, tier). The Agent:
- Introspects the new schema.
- Proposes the mapping:
user_id → customer_id,signup_date → registered_at,plan → tier. - Shows you the mapping and asks to confirm.
- Rewrites the SQL on the fly.
Result: first client took 30 minutes. Next one takes 5.
You can also lock a mapping — “always use this mapping for clients with a Mercato schema” — and the Agent applies it automatically for matching future runs.
Forking
When a Script is mostly right for a new context but needs a tweak (different threshold, different segment), fork it:
- Sidebar → the Script → Fork.
- Gets a copy named
your_script (fork)that you can edit freely. - Original stays untouched.
Forking is how consultants maintain one script per client — a common template, small per-client deviations.
Version history
Every save creates a version. From a Script’s page:
- Versions drawer shows each save with a short auto-generated description.
- Diff between any two versions.
- Revert to any previous version.
- Named tags — promote a version as “v1.0” or “stable” for shareable references.
Useful when a scheduled run breaks — revert, investigate, re-promote.
Scheduling
Open the Script → Schedule. Pick a cadence (daily / weekly / custom cron). Fill in parameter defaults for scheduled runs (e.g., start_date = last_monday()).
Each scheduled run:
- Saves output as a new Run.
- Can feed into a Report (with “attach to report” toggle).
- Can trigger a Watch (output compared to a threshold).
- Shows up in the Jobs page with run status and duration.
Runs are kept for 90 days by default; you can pin runs to keep them longer.
Parameters
Scripts support these parameter types:
| Type | Example default | Notes |
|---|---|---|
text | "last 7 days" | Free-form string. |
number | 0.03 | Ints and floats. |
date | last_monday() | Expressions like today(), last_monday(), first_of_month() are evaluated at run time. |
timestamp | now() - interval '1 hour' | Full PG interval syntax. |
table | data.users | Parameter picks a table at run time. |
enum | ["daily","weekly"] | Dropdown of allowed values. |
secret | @OPENAI_KEY | References a workspace secret. |
The Agent detects parameters automatically when you Save as Script; you rarely define them by hand.
Inputs from external triggers
Scripts can be triggered by things other than a schedule:
- Webhook POST — expose a script at
https://api.tablize.com/scripts/<id>/run. Payload becomes parameter inputs. - Agent chain — one script’s output becomes another’s input.
- IoT event — a Watch firing on a sensor can trigger a Script (e.g., “generate incident report when freezer crosses threshold”).
These are what turn Scripts into a light-weight workflow engine without you having to learn one.
Sharing
Scripts can be:
- Private — workspace only.
- Team-shared — within your workspace, a teammate can run and fork.
- Public templates — published to the template gallery (Templates). Others can fork into their workspace.
Public templates are how good patterns spread. Good candidates: cohort analysis, churn model, margin report, weekly signup recap.
Common gotchas
- Script fails after a schema change. The data type of a column shifted upstream. Run once manually — the Agent proposes a fix you can accept in the UI.
- Scheduled run not appearing. Check the Jobs page for the script’s status. Most common cause: a parameter default that evaluates to NULL (e.g., a time expression in a cleared timezone).
- Slow scheduled runs. Scripts that scan full tables get slow as data grows. Add a date filter. The Agent suggests rewrites when a run exceeds 2x its average duration.
- Fork confusion. Forks don’t auto-sync with the original. If the original has a bug fix, you have to apply it to the fork (the UI shows a diff).