Keboola

View saved version →

---
name: build-flow
description: Create or change a Keboola flow that runs extractors, transformations and writers in order, optionally on a schedule. Use when the user wants to orchestrate, chain or schedule existing Keboola configurations.
---

# Build a flow

Create a flow from existing configurations, or change an existing flow, in the one project the user confirms.

## Input

Which configurations to run, in what order, and whether the flow needs a schedule. For an existing flow, its name
or ID.

## Steps

1. **Pick the project.** Call `get_accessible_projects` (with `with_llm_instruction=true` on the first call in the
   conversation) and ask the user which project the flow belongs in. Never pick a project on your own: confirm it.
   Do this even when the session looks scoped already or a data tool would work without it: this plugin
   always narrows the session to the projects the user confirms. If `get_accessible_projects` fails because
   no programmatic token is present, the login is bound to one project: confirm it with the user and skip
   step 2.
2. **Scope the session to that project.** Call `set_project_scope` with `project_ids=[<the confirmed id>]`. This
   must happen before any write. If the result carries a non-null `scope_token`, pass it on every later tool call.
   Every write below also passes the confirmed id as `project_id`: other conversations on the same login share the
   scope, and a scope they moved makes the write fail instead of landing in another project.
3. **Get context.** Call `get_project_info` with `project_id=<the confirmed id>`. It says whether conditional
   flows are enabled in the project, and its `toolset_restrictions` say whether the user's role may set schedules.
   If they say only read-only tools are available, tell the user they cannot create flows in this project and stop.
4. **Collect the tasks.** Find every configuration the flow should run with `search`
   (`item_types=["configuration", "transformation"]`) and confirm the list with the user. Each task needs a
   component ID and a configuration ID; use `get_configs` with `configs=[...]` when a search hit does not show
   them. Do not create the configurations here; a missing SQL transformation is built with the
   `build-sql-transformation` skill first. A data app is the exception: find it with `get_data_apps` and add it
   as a `keboola.data-app-control` task with `configData: {"parameters": {"appId": "<data_app_id>"}}` and no
   configuration ID.
5. **Load the schema.** Call `get_flow_schema` with `flow_type="keboola.flow"` when conditional flows are enabled,
   otherwise `flow_type="keboola.orchestrator"`. Call `get_flow_examples` with the same type if you have not seen
   one in this conversation.
6. **Show the plan.** List the phases, the tasks in each phase and their order. Tasks in one phase run in
   parallel; phases run in order. Wait for the user to agree.
7. **Create or update.**
   - New flow: call `create_conditional_flow` with `project_id=<the confirmed id>` for `keboola.flow`, or
     `create_flow` with `project_id=<the confirmed id>` for `keboola.orchestrator`. Give every phase and task an
     `id` and a `name`.
   - Existing flow: find it with `search` and `item_types=["flow"]`, read it with `get_flows` and
     `flow_ids=[...]`, then call `modify_flow` with `project_id=<the confirmed id>`, its
     `configuration_id=...`, the `flow_type=...` it already has, a `change_description=...` and only the fields
     that change.
8. **Schedule, if asked.** Call `modify_flow` with `project_id=<the confirmed id>` and `schedules=[...]` for the
   schedule the user asked for. Confirm the cron expression and time zone with the user first. If
   `toolset_restrictions` from step 3 say the role cannot set schedules, tell the user and skip this step.
9. **Run, if asked.** Ask before running. Call `run_job` with `project_id=<the confirmed id>`, the flow's
   `component_id=...` and `configuration_id=...`, then follow it with `get_jobs`. On failure, continue with the
   `debug-failed-job` skill.
10. **Report.** Give the flow name, its phases, the schedule and the links the tools returned.

## Rules

- No write before step 2. If the user switches projects mid-conversation, go back to step 1.
- Add retries, conditions or `continueOnFailure` only when the user asks for them; a failed task already stops
  the flow.
- Do not change the type of an existing flow.

View saved version →

---
name: build-sql-transformation
description: Create or change a Snowflake or BigQuery SQL transformation in Keboola. Use when the user wants to turn a query into a saved transformation, build a new table from existing Keboola tables, or edit the SQL of an existing transformation.
---

# Build a SQL transformation

Create a new SQL transformation, or update an existing one, in the one project the user confirms.

## Input

What the transformation should produce, from which tables, and whether to run it once it is saved. For an
existing transformation, its name or ID.

## Steps

1. **Pick the project.** Call `get_accessible_projects` (with `with_llm_instruction=true` on the first call in the
   conversation). Show the projects and ask the user which one the transformation belongs in. Never pick a project
   on your own, even when only one is listed: confirm it.
   Do this even when the session looks scoped already or a data tool would work without it: this plugin
   always narrows the session to the projects the user confirms. If `get_accessible_projects` fails because
   no programmatic token is present, the login is bound to one project: confirm it with the user and skip
   step 2.
2. **Scope the session to that project.** Call `set_project_scope` with `project_ids=[<the confirmed id>]`. This
   must happen before any write. If the result carries a non-null `scope_token`, pass it on every later tool call.
   Every write below also passes the confirmed id as `project_id`: other conversations on the same login share the
   scope, and a scope they moved makes the write fail instead of landing in another project.
3. **Get context.** Call `get_project_info` with `project_id=<the confirmed id>`. Note the SQL dialect (Snowflake
   or BigQuery). Python, R and DuckDB transformations are out of scope for this skill; say so and stop. If its
   `toolset_restrictions` say only read-only tools are available, tell the user they cannot save transformations
   in this project and stop.
4. **Find the inputs.** Use `search` with `item_types=["table"]` for the source tables, then `get_tables` with
   `table_ids=[...]` for their `fullyQualifiedName` and column `quotedName` values.
5. **Prototype the SQL.** Run the `SELECT` part through `query_data` with a small `LIMIT` and show the user sample
   rows. Fix errors here, before anything is saved.
6. **Save it.**
   - New transformation: call `create_sql_transformation` with `project_id=<the confirmed id>`. Reference input
     tables by fully qualified name; create output tables with the dialect's delimited plain name
     (`"daily_orders"` on Snowflake, a backticked name on BigQuery), never a fully qualified one, and list the
     names without delimiters in `created_table_names=[...]`. Give it a name and description that state its
     purpose.
   - Existing transformation: find it with `search` and `item_types=["transformation"]`, read it with
     `get_configs` and `configs=[...]` to get the `block_id` and `code_id` values, then call
     `update_sql_transformation` with `project_id=<the confirmed id>`, `configuration_id=...`,
     `parameter_updates=[...]` (operations such as `set_code` or `str_replace`) and `change_description=...`. A
     `storage=...` value replaces all mappings: include every mapping you want to keep.
7. **Run it, if the user asked.** Ask before running. Call `run_job` with `project_id=<the confirmed id>` and
   the transformation's `component_id=...` and `configuration_id=...`, then poll `get_jobs` with `job_ids=[...]`
   until the job ends. On failure, continue with the `debug-failed-job` skill.
8. **Report.** Give the transformation name, the output tables, the job result and the links the tools returned.

## Rules

- No write before step 2. If the user switches projects mid-conversation, go back to step 1.
- Confirm with the user before overwriting SQL in an existing transformation and before every `run_job`.
- Use the dialect's delimited identifiers everywhere and never mix quoting styles in one statement.
- A destructive schema change (dropping, renaming or retyping a column) needs the output table removed before the
  next run. Tell the user; `query_data` runs in a read-only workspace and cannot drop or change Storage tables.

View saved version →

---
name: debug-failed-job
description: Find out why a Keboola job failed and propose a fix. Use when the user says a Keboola job, extractor, transformation, writer or flow failed or errored, or asks why their pipeline is red.
---

# Debug a failed job

Find the failed job, read its error and logs, explain the cause, and fix it only after the user agrees.

## Input

A job ID, a configuration or flow name, or just "my last job failed". Ask for nothing more until step 4 shows
whether it is needed.

## Steps

1. **Pick the project.** Call `get_accessible_projects` (with `with_llm_instruction=true` on the first call in the
   conversation) and ask the user which project the job ran in. Do not guess.
   Do this even when the session looks scoped already or a data tool would work without it: this plugin
   always narrows the session to the projects the user confirms. If `get_accessible_projects` fails because
   no programmatic token is present, the login is bound to one project: confirm it with the user and skip
   step 2.
2. **Scope the session to that project.** Call `set_project_scope` with `project_ids=[<the confirmed id>]`. This
   must happen before any write in step 7. If the result carries a non-null `scope_token`, pass it on every later
   tool call. Every write in step 7 also passes the confirmed id as `project_id`: other conversations on the same
   login share the scope, and a scope they moved makes the write fail instead of landing in another project.
3. **Find the job.**
   - Known job ID: go to step 4.
   - Known configuration or flow name: find its ID with `search` (`item_types=["configuration", "transformation",
     "flow"]`), then call `get_jobs` with `job_ids=[]`, `status="error"`, `component_id=...` and `config_id=...`.
   - Nothing known: call `get_jobs` with `job_ids=[]`, `status="error"` and `limit=10`, and ask the user which job
     they mean if more than one is recent.
4. **Read the failure.** Call `get_jobs` with `job_ids=["<id>"]`, `include_logs=true` and
   `log_event_types=["error", "warn"]`. If the error event is not enough, call again with a larger
   `log_tail_lines=...` and no event type filter.
5. **Read what ran.** Call `get_configs` with `configs=[...]` for the job's configuration. For a flow job, call
   `get_flows` with `flow_ids=[...]` and find the failed task, then repeat steps 3 and 4 for that task's job.
6. **Explain.** Name the cause in one or two sentences and quote the error line. Typical causes: an SQL error in
   a transformation (check columns with `get_tables` and reproduce the failing `SELECT` with `query_data`), a
   missing input table, expired credentials of an extractor or writer, or a schema change in the output table.
   Use `docs_query` for component-specific errors. Propose a fix.
7. **Fix, only on request.** Ask before changing anything.
   - SQL transformation: `update_sql_transformation` with `project_id=<the confirmed id>`, its
     `configuration_id=...`, the `parameter_updates=[...]` and a `change_description=...`.
   - Flow: `modify_flow` with `project_id=<the confirmed id>`, its `configuration_id=...`, the `flow_type=...` it
     already has and a `change_description=...`.
   - Another component: `get_components` for its schema. When the fix belongs in a configuration row, call
     `update_config_row` with `project_id=<the confirmed id>`, `component_id=...`, `configuration_id=...`,
     `configuration_row_id=...` and a `change_description=...`. Otherwise call `update_config` with
     `project_id=<the confirmed id>`, `component_id=...`, `configuration_id=...` and a `change_description=...`.
   - Expired OAuth credentials need the user: create a link with `create_oauth_url`,
     `project_id=<the confirmed id>`, `component_id=...` and `config_id=...`, and ask them to reauthorize.

   Then, with the user's consent, call `run_job` with `project_id=<the confirmed id>`, `component_id=...` and
   `configuration_id=...`, and check the new job with `get_jobs`. If the server refuses a write because the user's
   role is read-only, give the user the proposed fix to pass to a project admin.

## Rules

- No write before step 2, and no write at all without the user's go-ahead.
- Never rerun a job just to see whether it fails again; read the logs first.
- Report what the logs say. If they do not show a cause, say so and list what you checked.

View saved version →

---
name: explore-project-data
description: Explore a Keboola project's data. Use when the user asks what data they have in Keboola, which buckets or tables exist, what a table contains, or wants a read-only SQL answer from their Keboola tables.
---

# Explore project data

Answer questions about the data in the user's Keboola project without changing anything.

## Input

A question about the data: which tables exist, what a table holds, or a question answerable with a `SELECT`.
If the user names no project, find it in step 1.

## Steps

1. **Pick the project.** Call `get_accessible_projects` with `with_llm_instruction=true` on the first call in the
   conversation. Show the projects with their organization and SQL dialect. If there is exactly one, say which one
   you will use; otherwise ask the user which project or projects to explore. Do not guess.
   Do this even when the session looks scoped already or a data tool would work without it: this plugin
   always narrows the session to the projects the user confirms. If `get_accessible_projects` fails because
   no programmatic token is present, the login is bound to one project: confirm it with the user and skip
   step 2.
2. **Scope the session.** Call `set_project_scope` with `project_ids=[...]` set to the user's choice and
   `read_only=true`. If the result carries a non-null `scope_token`, pass it on every later tool call. If the user
   later asks for a change, call `set_project_scope` again without `read_only` before any write.
3. **Get context.** Call `get_project_info` once for the project (pass `project_id=...` when 2+ projects are
   scoped). Note the SQL dialect: it decides identifier quoting in step 6.
4. **Find the data.** Use `search` with `item_types=["table"]` or `item_types=["bucket"]` and the names the user
   mentioned. Use `get_buckets` with `bucket_ids=[]` only when the user wants the full inventory. Never list every
   table just to find one by name.
5. **Describe tables.** Call `get_tables` with `table_ids=[...]` for the tables that matter, and with
   `project_ids=[<the table's project>]` when 2+ projects are scoped: without it the call runs in every scoped
   project. Report columns, types, description and row count. Check `fullyQualifiedName`: a table without one (for
   example a linked table from another project) cannot be queried. Say so and stop for that table.
6. **Query.** Call `query_data` with one `SELECT` (or `WITH ... SELECT`) statement, and with
   `project_ids=[<the table's project>]` when 2+ projects are scoped: a query runs in every scoped project
   otherwise. Copy table names from `fullyQualifiedName` and column names from `quotedName` exactly. Always add a
   `LIMIT`; compute counts and aggregates in SQL rather than pulling raw rows. Inspect distinct values before
   filtering on a categorical column.
7. **Answer.** Give the answer with the query you ran and the links the tools returned.

## Rules

- This skill never writes. Do not call create, update, modify, run or deploy tools here; hand over to the
  `build-sql-transformation` skill if the user wants to persist a result.
- `query_data` is for reading: send one `SELECT` per call, never `INSERT`, `UPDATE`, `DELETE`, `CREATE` or `DROP`.
- If the question is about Keboola itself rather than the user's data, use `docs_query`.
- If a tool fails because the login cannot reach a project, tell the user to reconnect the Keboola plugin or ask
  the project admin for access. Do not try another project on your own.