Skip to main content

GuanETL User Guide

What Is GuanETL

GuanETL is an assistant tool for Guandata BI ETL development and execution. With an AI Agent, users can describe data processing needs in natural language, such as "Modify the sales order cleaning flow to filter out records with empty amounts." AI can read ETL structure, modify processing logic, check configuration, preview results, and save to the Guandata environment after confirmation.

GuanETL is suitable for quickly building data cleaning flows, modifying existing ETL, troubleshooting ETL failures, and configuring schedules. It is also useful for presales, implementation, customer trials, and internal validation.

Use GuanETL in a test environment, demo environment, or personal test folder first. For production ETL or important customer environments, confirm field definitions, output locations, downstream dependencies, and impact scope before saving.

Note

The product is currently in public beta. All features are free during beta. After beta, commercial authorization is required. To continue using it, contact Guandata sales or your customer success manager.

Prerequisites

Before installing GuanETL, make sure Node.js, npm, and GuanCLI are installed, and guancli auth login has been completed. See GuanCLI User Guide.

Install GuanETL

Option 1: Install Globally with npm

# First installation
npm install -g @guandata/guanetl
guanetl install-skill

# Update if already installed
npm update -g @guandata/guanetl
guanetl install-skill
Note

guanetl install-skill installs GuanETL tool instructions for AI Agents, so AI knows when to call GuanETL to develop, check, or run ETL. It does not replace GuanCLI login. ETL operations still reuse GuanCLI authentication.

After installation, ask in Codex, Cursor, Claude Code, and similar tools:

Inspect the Sales Order Cleaning ETL, explain what data it uses and its main processing logic, and do not modify anything yet.

Verify installation:

guanetl version

If the command is not found, check the npm global command directory:

npm prefix -g

Option 2: Ask an Agent to Install

Check whether Node.js, GuanCLI, and GuanETL are installed on this computer.
If GuanETL is not installed, install it with npm install -g @guandata/guanetl, confirm guanetl version works, and run guanetl install-skill.

Log In to BI

GuanETL uses GuanCLI authentication. After guancli auth login succeeds, GuanETL automatically reuses the current authentication when querying ETL, modifying flows, saving, and running tasks. See Log In to GuanCLI.

Develop ETL with GuanETL

Users usually do not need to run every GuanETL command manually. The recommended workflow is to describe the business requirement in an AI Agent, let AI understand the related data and flow first, then modify, check, and report results.

For first use, validate in stages: check tools and login, choose low-risk ETL, then modify, save, run, or schedule.

Stage 1: Check Installation and Login

Check whether GuanCLI and GuanETL are installed and whether I am logged in to a Guandata environment. Only check; do not modify any ETL.

AI should confirm whether guanetl and guancli are available, which environment is logged in, and who the current account is.

Stage 2: Choose a Low-risk ETL

Find an ETL whose name contains "test" or "sample", and list its name, ID, folder, input data, and output result. Do not open a draft or modify anything yet.

If you already know the ETL:

View the basic information of this ETL and explain its input data and final output. The ETL name is "XXX".

Stage 3: Open an ETL Draft Without Modifying

Use GuanETL to open this ETL and create a local draft. Tell me where the draft is, what files it contains, and which files can be edited. Do not modify anything yet.

Stage 4: Make a Small Change and Check First

Choose a small, easy-to-verify change, such as renaming a node, adding a simple filter, or modifying a clear SQL segment.

In this ETL draft, make a small change: rows with empty order amount should not enter the final result. After changing, check configuration and results, but do not save online yet. Tell me what changed, whether checks passed, and whether the result is as expected.

Stage 5: Save After Confirmation

I have confirmed the check result. Save it to the Guandata environment. Before saving, confirm the current environment and target ETL again. After saving, tell me whether it succeeded.

Stage 6: Run and Wait for Result When Needed

Run the ETL that was just saved and wait until the task finishes. If it fails, tell me the real error message and next troubleshooting steps.
Note

"Started" only means Guandata accepted the run request. The flow may still be running or fail later. Ask the Agent to wait for the final task state.

Stage 7: Schedule or Check Before Deletion

Schedule example:

Schedule this ETL to run every day at 3:00 AM. Before setting it, confirm the environment and target ETL. After setting it, explain the rule briefly.

Deletion pre-check:

Check whether this ETL can be deleted. Only perform pre-deletion checks and tell me which output datasets, pages, or other flows may be affected. Do not delete it directly.

Suggestions

  • For first trials, choose ETL in a test environment, personal folder, or test folder.
  • State the business goal and data definition clearly; do not only say "modify this ETL".
  • Prefer ETL with clear inputs, outputs, and field meanings.
  • Before saving, running, scheduling, or deleting, confirm environment, field definitions, output results, and impact scope.
  • Ask AI to explain planned save/run/schedule operations and impact before you confirm.
  • In production, ask the Agent to list commands before execution.
  • Avoid using a core production flow, a collaboratively maintained key ETL, or a complex downstream dependency chain for first trials.

Troubleshooting

GuanETL Command Not Found

npm list -g @guandata/guanetl
npm prefix -g

Add the npm global command directory to PATH and reopen the terminal.

AI Does Not Use GuanETL Automatically

Say explicitly:

Use GuanETL to modify this ETL.

or:

Follow the GuanETL workflow: read ETL structure first, then modify, check, and save.

If needed, run:

guanetl install-skill

Not Logged In or Authentication Failed

guancli auth status
guancli auth login
guancli auth list
guancli auth use <profile>

Save Failed

Do not repeatedly save directly. Ask the Agent to:

  1. Read the exact failure reason.
  2. Re-run configuration checks.
  3. Check whether an old working directory was reused.
  4. If the online version may have changed, reopen the latest online version and make the smallest change again.
  5. Validate after the smallest change.

Prompt:

Save failed. Do not retry saving directly. Analyze the failure reason first. If the online version may have changed, reopen the latest version, make the smallest change, and check again.

Check Result Shows 0 Rows

This is not necessarily a failure. The filter may be too strict, or the input data may have no matching records.

The check result has 0 rows. Check whether the source data has records, then check filters, join conditions, and field types.

"Started" Does Not Mean Success

Use:

guanetl run <etl_id> --wait --timeout 600

or:

guanetl task wait <taskId>

What Files Can AI Modify

Normally, AI should only modify files in the current ETL draft, such as:

  • etl/etl.go
  • etl/*.sql
  • etl/meta.json when necessary

Do not manually modify tool-generated state or export files:

  • _guanetl_state.json
  • _input.json
  • _base_etl.json
  • _exported.json

Can ETL Be Deleted

Yes, but carefully. GuanETL performs a pre-deletion check by default:

guanetl delete <etl_id>

Execute only after confirmation:

guanetl delete <etl_id> --yes

To also delete output datasets, only do so when safety checks pass:

guanetl delete <etl_id> --cascade --yes

Permissions and Security

GuanETL permissions follow Guandata BI permissions. Suggestions:

  • Use a test environment or test folder for trials.
  • Confirm the current environment before saving, running, scheduling, or deleting.
  • Do not paste accounts, passwords, Tokens, customer private data, or sensitive business data into prompts.
  • Before modifying critical ETL, confirm inputs, outputs, downstream dependencies, and business definitions.
  • In production, ask the Agent to list commands before execution.