GuanDS User Guide

Product Overview

What Is GuanDS?

GuanDS manages data connections, datasets, and form-entry forms in Guandata BI. It reuses the GuanCLI login session and supports managing connection accounts, creating datasets from databases or files, maintaining data and fields, configuring refresh schedules, and managing form-entry forms.

When used with an AI agent, you do not need to remember individual commands. Describe the business goal, and the agent can use GuanDS to query resources, create a plan, preview operations, and execute them.

For example: “Create an extract dataset from the orders table in the analytics database. Preview it first and do not publish it to a production directory.” The agent first queries the resources and environment, then creates a plan, previews the operation, and writes changes after confirmation.

Start in a test environment or personal directory. Before operating on production data, overwriting data, deleting fields, or deleting resources, confirm the target environment, resource IDs, scope of impact, and recovery plan.

Note

The product is currently in public beta, and all features are available free of charge. Commercial authorization is required after the beta period. To continue evaluating the product, contact your Guandata sales representative or Customer Success Manager.

Use Cases

Use GuanDS for the following tasks:

• Manage data connections: View connector types, test connections, create connection accounts, rename accounts in place, and update hosts, ports, databases, usernames, passwords, and schemas in place.
• Browse source structures: View schemas, tables, and fields under an account, and preview table data or SQL query results.
• Create datasets: Create datasets from database tables, custom SQL, CSV files, Excel files, and form-entry forms.
• Maintain datasets: Search, view details and fields, view consuming cards, rename, move, save as, and delete datasets.
• Maintain dataset data: Replace file-dataset data, append data, clear data conditionally, and append with primary-key deduplication.
• Synchronize schemas: After adding, deleting, renaming, or changing source columns, use sync-schema to generate and apply a plan in place.
• Configure refresh policies: Set incremental SQL, preClean delete-then-insert behavior, deduplication keys, automatic synchronization of new columns, and schedules.
• Manage calculated fields: Create, update, delete, and bulk-create dataset-level calculated fields.
• Review permission impact: Query dataset row- and column-level permissions and associated permission templates, and view the cards that reference a dataset.
• Manage tasks: Query, wait for, and cancel refresh tasks, and view recent failed tasks for diagnosis.
• Manage form-entry forms: Create forms, export form DSL, update forms in place, rename and move forms, and manage form directories.

Scope and Limitations

GuanDS is not intended for the following tasks:

Requirement	Recommended tool	Notes
Create and publish pages, cards, and dashboards	GuanVis	Focuses on visualization artifacts.
Create, edit, save, publish, and run ETL flows	GuanETL	Focuses on ETL nodes and flow orchestration.
Perform read-only diagnostics, such as complex lineage analysis, dataset preview, page details, and ETL details	GuanCLI	Focuses on read-only analysis and issue location.
Configure or modify row- and column-level permissions	BI web UI	guands dataset permission get is read-only.
Change the schema of an uploaded-file dataset while retaining its dsId	No general CLI solution	replace-data replaces data only; it does not change field schemas.
Update nonstandard host/port form connectors in place, such as MongoDB, SAP, FTP, server files, and object storage	BI web UI	These connectors have limited account update support.
Edit the schema of a TABLE subform in place	BI web UI	Subforms can be created, but their schemas cannot yet be edited in place.

High-Risk Operations

The following operations affect production data or references. Before running them, confirm the target environment, resource IDs, preview results, and scope of impact:

• account delete、dataset delete、dir delete、form folder delete
• dataset replace-data、dataset append-data、dataset clear-data
• dataset sync-schema apply --mode reset
• dataset primary-key set/clear
• dataset calc-field delete
• Deleting an existing field with form update

Deletion, clearing, and calculated-field deletion commands require an explicit --yes. When uncertain, use --dry-run, --preview, or plan first.

Common Resource IDs

GuanDS operations use resource IDs.

ID	Meaning	Example
acId	Connection account ID	Database connection account
dsId	Dataset ID	Sales-order dataset
fdId	Field ID	Amount field
dirId	Dataset directory ID	Sales-analysis directory
fmId	Form-entry form ID	Store-inspection form

Resource names can be duplicated. Do not infer IDs from names. Before making changes, confirm the resource ID through an agent or query command.

Prerequisites

Before installing GuanDS, make sure that Node.js, npm, and GuanCLI are installed and that you have completed guancli auth login. For installation and login instructions, see GuanCLI User Guide.

Install GuanDS

Method 1: Install Globally with npm

# Initial installation
npm install -g @guandata/guands

# Verify the installation
guands version

# Enable AI agents to recognize GuanDS
guands install-skill

To upgrade, run:

npm install -g @guandata/guands@latest
guands install-skill

guands install-skill installs GuanDS tool instructions so AI agents know when to use it. This command does not replace GuanCLI login.

If installation succeeds but the terminal cannot find guands, check whether the npm global binary directory is on your system PATH:

npm prefix -g

Method 2: Install with an Agent

Send the following prompt to an AI agent:

Check whether Node.js, GuanCLI, and GuanDS are installed on this computer.
If GuanDS is not installed, run npm install -g @guandata/guands and confirm that guands version runs successfully.
Then run guands install-skill. Do not modify any BI resources.

Sign In to a BI Environment

GuanDS uses GuanCLI authentication. Once guancli auth login succeeds, GuanDS automatically reuses the current environment and account. For details, see Sign In to GuanCLI.

Before performing a write operation, check the environment:

guancli auth status
guancli auth list

When using multiple environments, confirm that the current profile is correct. Do not use acId, dsId, dirId, or fmId values from a different environment.

Manage Data Assets with GuanDS

You usually do not need to run every command manually. Have an agent query resources and impact first, then preview write operations. Create, update, or delete only after confirming the results.

Each step below provides two ways to work:

• AI agent prompt example: for users who prefer natural-language operations.
• CLI command reference: for technical users who call GuanDS directly.

Step 1: Check the Environment and Resources

Check the BI environment currently signed in through GuanCLI, and search for datasets whose names contain “sales”.
List the name, ID, directory, data source, and most recent refresh status. Query only; do not make changes.

To manage connection accounts, use a prompt such as:

List the connectors and database connection accounts available in the current environment. Do not display passwords or modify configuration.

Step 2: Create a Dataset from a Database or File

Before creating a dataset from a database, have the agent test the connection and inspect tables and fields, then select extract or direct mode:

Use GuanDS to inspect the `orders` table in the analytics database, then create an extract dataset named “Order Detail Test” in a test directory.
First show the commands to run and the target directory. Create the dataset only after confirming the fields, directory, and environment, then wait for the initial extraction task to finish.

Before creating a dataset from CSV or Excel, preview the file:

Preview the sheets and fields in `./sales.xlsx`. After confirming the headers and field types in the “Sales Detail” sheet, import it as a test dataset. Do not overwrite any existing dataset.

Commands:

# Browse the database structure
guands connector list
guands account list
guands account tables <acId> --schema public
guands account columns <acId> --table orders --schema public

# Create a dataset from a database table or SQL
guands dataset create-db --ac-id <acId> --tables "orders" --ds-names "订单表"
guands dataset create-query --ac-id <acId> --name "用户订单汇总" --sql "SELECT customer_id, SUM(amount) AS total_amount FROM orders GROUP BY customer_id"

# Preview and import files
guands dataset import ./sales.csv --preview
guands dataset import ./sales.xlsx --sheet "销售明细"

For an Excel file with multiple sheets, you must specify --sheet. The first CSV row must be the header. Use --preview first when you need to specify encoding, delimiters, or field types.

Step 3: Update an Existing Dataset

When updating an existing dataset, modify it in place to retain its dsId and related cards, ETL flows, permissions, and schedules. You can describe the requirement directly to an agent:

Use GuanDS to replace the data in dataset `<dsId>` with `./fixed.csv`. First inspect the cards that reference the dataset and its permission settings.
Then run `--dry-run` to preview row-count changes. Perform the replacement only after confirming the target environment and scope of impact.

Use GuanDS to append `./daily.csv` to dataset `<dsId>`, and preview with `--dry-run` first.
If duplicate primary keys exist, use `--distinct-by` to deduplicate while retaining new data.

Use GuanDS to clear rows where “date < 2024-01-01” from dataset `<dsId>`.
This is a high-risk operation. Use `--dry-run` to preview the number of rows to delete, then execute only after confirmation.

Commands:

# Replace or append file data
guands dataset replace-data <dsId> ./fixed.csv --dry-run
guands dataset append-data <dsId> ./daily.csv --dry-run

# Clear data conditionally; actual execution requires --yes
guands dataset clear-data <dsId> --where "日期 < 2024-01-01"
guands dataset clear-data <dsId> --where "日期 < 2024-01-01" --yes

# View references and permissions
guands dataset cards <dsId>
guands dataset permission get <dsId>

Note

Do not replace editing with “delete the old dataset and create a new dataset with the same name.” This changes the ID and breaks downstream references.

Step 4: Synchronize Schemas, Fields, and Calculated Fields

After a database source table adds, deletes, renames, or changes the type of columns, have the agent generate a schema synchronization plan. When fields are renamed, map the new field names in the plan to retain the original field fdId:

The database source-table schema has changed. Use GuanDS to generate a schema synchronization plan for dataset `<dsId>`.
Show `addedNew`, `unmappedOrig`, and mappable fields. Verify with `--dry-run` before applying the plan.
For renamed fields, map the new field names to retain the original `fdId`.

Add a calculated field named “Profit Margin” to dataset `<dsId>`, using the formula `[利润]/[销售额]`.
First show the command to run and field type, then create it after confirmation.

Commands:

guands dataset sync-schema plan <dsId>
guands dataset sync-schema apply <dsId> --plan sync-schema-plan-<dsId>.json --mode schema-only --dry-run
guands dataset sync-schema apply <dsId> --plan sync-schema-plan-<dsId>.json --mode schema-only

# Change a field display name or calculated field
guands dataset alias <dsId> --fd-id <fdId> --alias "展示名"
guands dataset calc-field add <dsId> --name "利润率" --formula "[利润]/[销售额]"
guands dataset calc-field update <dsId> --fd-id <fdId> --formula "[利润]/[销售额]*100"

Note

--mode schema-only updates the schema only. --mode reset resets and fully overwrites data. Direct datasets can use only reset; confirm the scope of impact before running it.

Step 5: Configure Refreshes and Schedules

After creating a dataset, have the agent configure incremental refreshes, deduplication primary keys, and scheduled tasks:

Configure a time-window incremental refresh for dataset `<dsId>`. The incremental SQL should retrieve data from the last seven days,
and preClean should clear old data in the same window. Show the SQL and rules before applying them.

Configure a daily refresh at 2:00 AM for dataset `<dsId>`, then run `refresh --wait` once to verify that the task finishes successfully.

Commands:

guands dataset update-setting <dsId> \
  --incremental \
  --incremental-sql "SELECT * FROM orders WHERE data_date >= '{{{today - 7 days}}}'" \
  --preclean \
  --preclean-rule "data_date >= '{{{today - 7 days}}}'"

guands dataset primary-key set <dsId> --columns "id" --dry-run
guands dataset schedule <dsId> --cron-type daily --hour 2 --minute 0
guands dataset refresh <dsId> --wait --timeout 600

Note

Use BI time macros in incremental SQL and cleanup rules, such as {{{yesterday}}} or {{{first day of this month}}}. Do not rely on database time functions such as NOW() or CURDATE(). Before setting a primary key, confirm that the field is non-null and unique.

Step 6: Manage Form-Entry Forms and Tasks

Before updating a form, export its current DSL and edit the exported file, preserving existing field anchors:

Export the form-entry form with ID `<fmId>` to `form.js`. I will modify it and then update it in place with GuanDS.
Before updating, use `--dry-run` to verify field changes and ensure that no existing fields are deleted.

The most recent refresh for dataset `<dsId>` may have failed. Use GuanDS to review failed task history from the last 24 hours,
and show the task ID, error message, and current dataset status.

Commands:

guands form export <fmId> --out form.js
guands form validate form.js
guands form update <fmId> form.js --dry-run
guands form update <fmId> form.js

guands task status <taskId>
guands task wait <taskId> --timeout 600
guands task history --status FAILED --hours 24

Forms and datasets are separate resource types. To use form-entry data in downstream ETL, first create the associated form dataset. Deleting a form field deletes historical column data, so confirm the impact first.

Recommendations

• Search when an ID is missing; do not infer it from a name. Resource names can be duplicated.
• Use --dry-run, --preview, or plan before write operations, and read back results after execution.
• Deleting, clearing, overwriting, deleting fields, and sync-schema --mode reset are high-risk operations. Confirm the target, impact, and authorization first.
• dataset refresh does not submit another task when one is already running. Use --wait to wait for the existing task to finish.
• rowCount is a backend metadata snapshot, not a real-time row count. Validate data volume with business SQL, samples, or downstream queries.
• A time-window incremental refresh does not automatically remove records deleted at the source. To apply deletion semantics, configure an appropriate preClean window or run periodic full refreshes.

Troubleshooting

Issue 1: Cannot Find a Dataset, Directory, or Connection Account

First confirm the current environment:

guancli auth status
guands account list
guands dataset list 销售
guands dir tree

If names are duplicated, specify the resource ID from the search results.

Issue 2: Fields Are Incorrect after File Import

Preview the file first:

guands dataset import ./data.csv --preview

Confirm the CSV header, encoding, and delimiter, or the Excel sheet and header row. For an Excel file with multiple sheets, explicitly specify --sheet.

Issue 3: Data Volume Does Not Change after Refresh

First wait for the task to finish and check its status:

guands dataset refresh <dsId> --wait --timeout 600
guands task history --status FAILED --hours 24

rowCount may not yet be refreshed. Verify actual data with a business query or sample, and check the incremental SQL and cleanup rules.

Issue 4: AI Does Not Automatically Use GuanDS

State the requirement explicitly:

Use GuanDS to manage this dataset. Query resources and impact first, then preview write operations. Do not overwrite, delete, or clear anything without my confirmation.

Also confirm that you have run:

guands install-skill

Issue 5: Permissions Allow Viewing but Not Modification

GuanDS follows Guandata BI resource permissions. First review the current account and dataset permissions. To change row- or column-level permissions, use the BI web UI.

guancli auth status
guands dataset permission get <dsId>