GuanMetric User Guide

Product Overview

What Is GuanMetric?

GuanMetric is a write-operation tool for the Guandata BI metrics platform. It creates and maintains metric topics, metric directories, atomic metrics, composite metrics, derived metrics, public dimensions, and metric trees. It reuses GuanCLI authentication.

• GuanCLI searches metrics, retrieves details, queries data, and performs attribution queries.
• GuanMetric creates and modifies metric-platform resources.

When used with an AI agent, first have the agent query resources and generate a create or edit plan, then run a dry run, validation, submission, and read-back.

For example, describe a requirement as follows:

Under the “Business Metrics” topic, create two atomic metrics, “Sales Amount” and “Order Count”, then create “Average Order Value = Sales Amount / Order Count”.
First query datasets, fields, and existing metrics, and generate a plan and dry-run result. Do not create or publish anything without confirmation.

Composite metrics, derived metrics, cards, and metric trees can reference metrics. Edit metrics in place to avoid ID changes and broken downstream references caused by deleting and recreating them.

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 GuanMetric for the following tasks:

• Standardize metric templates: Convert customer metric Excel or CSV files into templates recognized by the Guandata metrics platform.
• Organize metric requirements: Turn text, semi-structured tables, or transcribed screenshots into metric requirements and generate a standard template for user confirmation.
• Create metric topics and directories: Create metric topics and regular metric directories.
• Create and edit atomic metrics: Aggregate dataset fields by sum, count, distinct count, average, maximum, minimum, or an expression.
• Create and edit composite metrics: Use formulas between existing metrics, such as Sales Amount / Order Count or A + B - C.
• Create and edit derived metrics: Create year-over-year, period-over-period, last N, cumulative, ending-value, business-filtered, and combined-derived metrics.
• Delete metrics: Run the same impact validation as the web UI, then delete after confirmation if there are no downstream dependencies.
• Manage public dimensions: Query, view details and field mappings, create, edit, transfer ownership, and delete public dimensions.
• Create and configure metric trees: Configure dimension breakdowns, metric breakdowns, time comparisons, and contribution calculations; rename, move, and update configurations in place.
• Controlled passthrough calls: Use controlled fetch calls for composite or derived-metric APIs that do not yet have dedicated commands.

Common metric-management tasks

Business requirement	Use GuanMetric to
Import a business-metric Excel file into Metric Center	Standardize a metric template
Create a sales metric	Create an atomic metric
Create average order value	Create a composite metric
Create sales year-over-year results	Create a derived metric
Adjust a metric definition	Edit a metric
Build a business-analysis metric system	Create a metric tree
Standardize dimensions such as date and organization	Manage public dimensions

Scope and Limitations

GuanMetric is not intended for the following tasks:

Requirement	Recommended tool	Notes
Search metrics, read metric details, query metric data, or query metric attribution	guancli	Read-only metric analysis.
Read dataset details, field IDs, or preview datasets	guancli ds	Read-only dataset operations.
Create or modify datasets	guands	Data-connection and dataset management.
Create ETL flows	guanetl	Data-processing flows.
Create metric cards or dashboards	guanvis	Visualization artifacts.
Rename existing metric topics or regular metric directories	BI web UI	The CLI supports creation only. Do not simulate renaming by creating a topic or directory with the same name.
Replace editing a metric, public dimension, or metric tree with deletion and recreation	—	Changes IDs and breaks downstream references.

High-Risk Operations

The following operations affect the production metric system or downstream references. Before running them, confirm the target environment, resource IDs, scope of impact, and user authorization:

• Create and publish metrics with publish=true.
• Edit formulas, source fields, applicable dimensions, time dimensions, business filters, or publication status for existing metrics.
• Delete metrics with guanmetric delete <metricId>.
• Delete public dimensions with guanmetric public-dim delete <publicDimId>.
• Modify fields associated with a public dimension.
• Update, move, or rename metric trees.
• Call metrics-platform write APIs with fetch.

Passing a dry run, pre-save validation, impact validation, or dependency check does not mean changes were written successfully. Report an item as created, edited, or deleted only after successful submission and read-back confirmation.

Prerequisites

Before installing GuanMetric, 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 GuanMetric

Method 1: Install Globally with npm

# Initial installation
npm install -g @guandata/guanmetric

# Verify the installation
guanmetric version

# Enable AI agents to recognize GuanMetric
guanmetric install-skill

To upgrade, run:

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

guanmetric install-skill installs GuanMetric tool instructions; it does not replace GuanCLI login. If installation succeeds but the command cannot be found, check the npm global directory:

npm prefix -g

Method 2: Install with an Agent

Send the following prompt to an AI agent:

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

Sign In to a BI Environment

GuanMetric uses GuanCLI authentication. For details, see Sign In to GuanCLI.

Before a write operation, confirm the current environment and account:

guancli auth status
guancli auth list

The IDs for topics, directories, datasets, fields, metrics, public dimensions, and metric trees must come from the current environment. Names can be duplicated, so do not infer IDs.

Manage Metrics with GuanMetric

Use the following sequence: query → plan → preview and validate → confirm → write → read back. For a first trial, use a test topic or directory.

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 GuanMetric directly.

Step 1: Query Topics, Metrics, and Datasets

Prompt for the agent:

Confirm the current environment, then search for metrics, metric topics, and datasets related to “Sales Amount”.
List the name, ID, dataset, and field for each candidate resource. Query only; do not create or modify anything.

Common query commands:

guancli auth status
guancli metric project 经营 -f json
guancli metric tree -f json
guancli metric search 销售额 -f json
guancli metric get <metricId> --brief
guancli ds get <dsId> --brief

Step 2: Confirm Metric Types and the Creation Plan

Prompt for the agent:

I have confirmed the environment. Based on the following requirements, determine whether each metric should be atomic, composite, or derived, and output a creation plan:
1. Sales Amount: sum the `amount` field in the orders table.
2. Order Count: distinct-count `order_id` in the orders table.
3. Average Order Value: Sales Amount / Order Count.
The plan must include the topic, directory, metric name and type, dataset and fields, aggregation method or formula, applicable dimensions, time dimension, owner, save mode (draft or published), and creation order. Do not generate final submission files until the plan is confirmed.

First determine the appropriate metric model:

Requirement	Recommended type
Sum, count, distinct count, average, maximum, or minimum on one field	Atomic metric
Arithmetic between existing metrics	Composite metric
Year-over-year, period-over-period, last N, cumulative, ending value, or business filter	Derived metric
Combine multiple derived metrics	Combined derived metric

The plan must include the target environment; topic and directory; metric name and type; core definition; dataset and fields; applicable and time dimensions; owner; draft or publication status; and dependency order. Do not submit real write operations until the plan is confirmed.

Business example table:

Business metric	Type	Description
Sales Amount	Atomic metric	SUM of order amount
Order Count	Atomic metric	Distinct count of order ID
Average Order Value	Composite metric	Sales Amount / Order Count
Sales Year-over-Year Growth Rate	Derived metric	Year-over-year calculation based on Sales Amount
Sales Amount in the Last 30 Days	Derived metric	Time-window calculation

Step 3: Create or Edit an Atomic Metric

Prompt for the agent:

The plan has been confirmed. Create an atomic metric named “Sales Amount” in the “Business Metrics/Core Metrics” directory.
Use field `<fdId>` in dataset `<dsId>` with the `SUM` aggregation.
Run a dry run and show the request body before creating it. After creation, read back the metric details for verification.
If editing is required, use `guanmetric edit <metricId>` to modify the metric in place; do not delete and recreate it.

An atomic metric is defined from a single dataset field or field expression. Common aggregation methods include SUM, CNT, CNT_DISTINCT, AVG, MAX, and MIN.

Common commands:

# Preview the create request
guanmetric create --file atomic_metric.json --dry-run

# Create after confirmation
guanmetric create --file atomic_metric.json -f json

# Read back for verification
guancli metric get <metricId> --brief

# Edit an existing metric in place
guanmetric edit <metricId> --set name=销售额 --set desc=核心口径 --dry-run
guanmetric edit <metricId> --file atomic_metric_update.json -f json

When publishing a metric, the command performs pre-save validation. Editing an existing metric also runs impact validation based on changes. If it finds a definition conflict or downstream impact, show the result and obtain confirmation first.

Step 4: Create Composite and Derived Metrics

Prompt for the agent:

The atomic metrics have been created. Create the composite metric “Average Order Value = Sales Amount / Order Count” using the following information:
- Sales Amount metricId: `<metric_sales_amount>`
- Order Count metricId: `<metric_order_count>`
The formula must use `[metricId]` values rather than Chinese names. First show the human-readable formula and ID formula for confirmation, then run a dry run and validation, create the metric, and read it back.

Composite metrics use existing metrics, for example “Average Order Value = Sales Amount / Order Count”. Submitted formulas must use metric IDs rather than Chinese names:

Human-readable formula: Sales Amount / Order Count
Submitted formula: [metric_sales_amount] / [metric_order_count]

Common commands:

# Create a composite metric
guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file composite_metric.json

# Create a derived metric
guanmetric fetch POST /api/metric-platform/metrics/derived-metrics --file derived_metric.json

# Read back after creation
guancli metric get <newMetricId> --brief

Year-over-year, period-over-period, and ending values require the base metric to have a time dimension. Last N can be derived only from an atomic metric. Business filters require filter. The applicable dimensions of a composite metric can be selected only from dimensions shared by the referenced metrics.

Step 5: Standardize Metric Templates in Bulk

Prompt for the agent:

I uploaded a customer metric list named `customer_metrics.xlsx`. First use `guanmetric template normalize` to convert it to the standard template.
After generating the standard Excel file and report, show the count of rows in each status in the Summary sheet: Ready to Create, Pending Confirmation, and Error.
For Pending Confirmation and Error rows, list the issue and information I need to provide. Do not proceed to the creation plan until every row is Ready to Create and I have confirmed the template.
Do not create any metrics directly.

When a user provides Excel, CSV, a table, or written requirements and wants to create metrics in bulk, standardize the template before creating anything:

guanmetric template normalize 客户指标.xlsx \
  --out standard_metrics.xlsx \
  --report standard_metrics_report.json

The standard file separates sheets by atomic, composite, and derived-metric type, and marks row status in Summary:

Row status	Next step
Ready to Create	Proceed to the creation plan after user confirmation.
Pending Confirmation	Provide or confirm the candidate information.
Error	Correct required fields, IDs, or formula mappings, then normalize again.

Create metrics only after every actual metric row is Ready to Create and the user confirms the template. The agent must map Chinese field and metric names to IDs before generating the final payload.

Step 6: Manage Public Dimensions and Metric Trees

Metric trees vs. metric directories

• A metric directory manages where metrics are stored.
• A metric tree describes analytical relationships between metrics.

For example:

Sales Amount

├── Regional breakdown

├── Category breakdown

└── Channel breakdown

Prompt for the agent:

Create or edit the following resources. Run a dry run before every write operation:
1. A public dimension named “Date”, based on date field `<fdId>` in dataset `<dsId>`.
2. A metric tree named “Sales Amount Metric Tree”, with root metric `<metricId>` under metric-tree directory `<metricTreeDirId>`.
Confirm that the root metric has a time dimension and that the metric-tree directory ID comes from `guancli metric_attribution tree`, not a regular metric directory.

Common commands:

# Public dimensions
guanmetric public-dim list 日期
guanmetric public-dim fd-map <dsId>
guanmetric public-dim create --file public_dim.json --dry-run
guanmetric public-dim edit <publicDimId> --file public_dim_patch.json --dry-run

# Metric trees
guancli metric_attribution tree -f json
guanmetric metric-tree create 销售额指标树 --metric-id <metricId> --parent-dir-id <metricTreeDirId> --dry-run
guanmetric metric-tree update-config <metricTreeId> --file metric_tree_config.json --dry-run
guanmetric metric-tree get <metricTreeId>

Before deleting a public dimension, check its dependencies. A metric tree must use the metric-tree directory ID returned by guancli metric_attribution tree, not a regular metric directory ID. The root metric must have a time dimension.

Step 7: Check and Read Back before Deletion

Prompt for the agent:

Check whether metric `<metricId>` can be deleted. After impact validation, show downstream references.
If downstream metrics or cards exist, list them and let me decide how to handle them. Add `--confirm` to delete only when `deletable=true` and I explicitly confirm.
After deletion, read back the result using search or `get`.

By default, metric deletion first checks impact:

guanmetric delete <metricId>

Run the following only when the result shows that the metric can be deleted, downstream references have been handled, and the user explicitly confirms:

guanmetric delete <metricId> --confirm

Read back every completed write operation. In addition to metric details, verify public dimensions with guanmetric public-dim get <publicDimId> and metric trees with guanmetric metric-tree get <metricTreeId>.

Recommendations

• Query before writing; topics, directories, datasets, fields, and metrics can all have duplicate names.
• Generate a plan and run --dry-run, pre-save validation, or impact validation before every create or edit operation.
• Atomic metrics use dataset field references, [fdId]; composite and combined-derived metrics use metric references, [metricId].
• Do not simulate editing by deleting and recreating resources. Metric ID changes break references from cards, metric trees, and downstream metrics.
• Deleting public dimensions or metrics, updating metric-tree configuration, and using fetch for unwrapped write APIs are high-risk operations. Confirm the scope of impact first.
• Prefer dedicated commands for standard atomic metrics, topics, directories, public dimensions, and metric trees. Use fetch only for unwrapped composite, derived, or validation APIs.

Troubleshooting

Issue 1: Cannot Find a Topic, Directory, Metric, or Dataset

After confirming the environment, search by resource type:

guancli auth status
guancli metric project <关键词> -f json
guancli metric tree -f json
guancli metric search <关键词> -f json
guancli ds search <关键词>

When multiple candidates exist, specify the ID.

Issue 2: A Standard Template Shows Pending Confirmation or Error

Do not create metrics directly. Review issues in Summary, supply topics, directories, datasets, fields, base metrics, or formula mappings, and then run template normalize again.

Issue 3: A Composite Formula Cannot Be Parsed

Confirm that every token in the formula maps to an existing metric, dataset field, or base metric defined in the current batch. Do not guess the resource represented by a Chinese name or bare token.

Issue 4: Editing or Deletion Is Blocked by Downstream Impact

First show affected metrics or cards and handle their references. Do not add --confirm without confirmation, and do not force deletion when downstream references exist.

Issue 5: AI Does Not Automatically Use GuanMetric

State the requirement explicitly:

Use GuanMetric to manage these metrics. First query resources and generate a plan, then run a dry run and impact validation. Do not create, publish, edit, or delete anything without my confirmation.

Also confirm that you have run:

guanmetric install-skill

Issue 6: I Do Not Know Which Metric Type to Use

You can have an agent determine whether a metric should be atomic, composite, or derived based on business requirements, but you must confirm the business definition.