Clickzetta Analytics Agent

ClickZetta Analytics Agent Manager

References (read when you need depth):

Wizard: Clarify Intent

On receiving an analytics agent request, classify the user's intent:

A. Build a new analytics domain (from schema tables → full domain with semantics, metrics, ABs) → Domain Setup Wizard B. Modify existing domain (add/remove tables, update semantics, add metrics or ABs) → Modification Workflow C. Test / QA a domain (run natural-language questions, verify results) → references/qa-testing.md D. Assess semantic quality (evaluate completeness, correctness, coverage of an existing domain) → references/quality-assessment.md E. Fix configuration issues (missing descriptions, alias conflicts, duplicate metricNames) → references/troubleshooting.md F. Improve semantic coverage (add descriptions, aliases, refine metrics) → references/table-semantics.md

If the user has stated clearly what they want, execute directly without asking.

Core Concepts

Object Hierarchy

Domain (domainId)
  ├── Tables (datasetId) — registered via `domain table add`
  │     └── Columns (attrId) — semantic types, descriptions, aliases
  ├── Metrics — simple or compound (both via `metric create`; classified by expression)
  ├── Answer Builders — multi-table SQL + chart config
  ├── Knowledge Base — uploaded documents bound to domain
  └── Domain Prompt — custom system prompt for QA

Dataset ID Flow

Tables added to a domain generate a dataset ID (datasetId). The analytics agent creates v_gpt_* views for each physical table. All AB SQL must reference v_gpt_* view names, not physical table names.

Physical table:  quickstart_ws.schema.dim_warehouse
Registered as:  quickstart_ws.schema.v_gpt_dim_warehouse  ← use this in AB SQL
datasetId:      1972  ← use this in semantics/metric commands

Metrics vs Answer Builders

Domain Setup Wizard

Triggered by: "build analytics domain", "create semantic layer", "set up analytics agent for X schema".

Phase 1: Register Tables

# For each table in the schema:
cz-cli analytics-agent domain table add <domain-id> \
  --profile <profile> --datasource-id <datasource-id> \
  --table "<workspace>.<schema>.<table>"

# Verify with:
cz-cli analytics-agent domain detail <domain-id> --with-tables --profile <profile>

Critical: Always pass --datasource-id (required). Tables that fail to load should be retried after data is available — the domain table add call will fail with a "table or view not found" error if the physical table doesn't exist yet.

Phase 2: Set Column Semantics

For each registered table, configure column properties. See references/table-semantics.md.

Minimum required per column:

• semanticType: CATEGORICAL (dimension), CONTINUOUS (measure), DATE_AND_TIME (date)
• description: Chinese or English business description
• dimension: true for filterable/groupable columns, false for pure measures

# Set semantic type + description + dimension flag
cz-cli analytics-agent table semantics set <dataset-id> <attr-id> \
  --profile <profile> \
  --semantic-type "CATEGORICAL" \
  --description "仓库名称" \
  --dimension true

# Add Chinese aliases (repeatable)
cz-cli analytics-agent table semantics set <dataset-id> <attr-id> \
  --profile <profile> \
  --alias "仓库" --alias "仓名" --alias "仓储地点"

Phase 3: Create Metrics

# Simple metric (single aggregate)
cz-cli analytics-agent metric create \
  --profile <profile> --domain-id <domain-id> --datasource-id <datasource-id> \
  --table-name "<workspace>.<schema>.v_gpt_<table>" \
  --name "出库总金额" \
  --expression "SUM(total_amount)" \
  --alias "出库金额" --alias "发货金额"

Phase 4: Create Answer Builders

See references/answer-builders.md for full DSL format.

Key rules (violating any causes creation failure):

1. SQL must use v_gpt_* view table names, not physical names
2. metricName is REQUIRED in every outputColumn — and must be unique within the domain
3. outputColumn aliases must not match any existing metric alias in the domain
4. Shell quote --sql with single quotes so ${dims} and ${filters} reach the CLI intact

cz-cli analytics-agent answer-builder create \
  --profile <profile> --domain-id <domain-id> --datasource-id <datasource-id> \
  --analysis-name "各仓库出库金额排名" \
  --analysis-desc "按仓库统计出库总金额排名" \
  --content '{"chartParams":[...],"outputColumns":[...],"relatedTables":[...]}' \
  --sql 'SELECT ${dims}, SUM(total_amount) AS out_amt FROM ... WHERE ${filters} GROUP BY ${dims}'

Phase 5: Knowledge Base & Domain Prompt

# Create KB space
cz-cli analytics-agent knowledge space create \
  --profile <profile> --name "行业知识库"

# Upload KB file and bind to domain in one step
cz-cli analytics-agent knowledge file upload <space-id> <local-file> \
  --profile <profile> --domain-id <domain-id> \
  --target-path "docs/" --name "数据说明.md"

# Set domain prompt
cz-cli analytics-agent domain prompt set <domain-id> \
  --profile <profile> --prompt "You are a domain expert..."

Key Syntax & Constraints

DATE Literals in SQL

Implicit string-to-DATE cast is NOT supported. Always use DATE 'YYYY-MM-DD'.

AB DSL Format

{
  "chartParams": [
    {"name":"dims","type":"dimension","allowMulti":false,
     "fromTableRefs":[{"tableName":"cat.schema.v_gpt_table","columns":["col1"]}]},
    {"name":"filters","type":"filter","allowMulti":true,
     "fromTableRefs":[{"tableName":"cat.schema.v_gpt_table","columns":["date_col"]}]}
  ],
  "outputColumns": [
    {"name":"out_col","type":"double","alias":["显示别名"],"metricName":"域内唯一指标名"}
  ],
  "relatedTables": ["cat.schema.v_gpt_table1","cat.schema.v_gpt_table2"]
}

Uniqueness Rules

Modification Workflow

Adding a new table to existing domain

cz-cli analytics-agent domain table add <domain-id> \
  --profile <profile> --datasource-id <datasource-id> \
  --table "<workspace>.<schema>.<table>"
# Then set semantics, aliases, create new metrics as needed

Fixing missing column descriptions

# List columns for a dataset, find missing descriptions
cz-cli analytics-agent table semantics list <dataset-id> --profile <profile> --format json

# Set description only (faster than full type+dimension reset)
cz-cli analytics-agent table semantics set <dataset-id> <attr-id> \
  --profile <profile> --description "业务含义"

Updating an Answer Builder

cz-cli analytics-agent answer-builder update <analysis-id> \
  --profile <profile> --analysis-name "<name>" --analysis-desc "<desc>" \
  --datasource-id <datasource-id> --domain-id <domain-id> \
  --content '<json>' --sql '<sql>'

QA Testing Quick Start

# Create named session
cz-cli analytics-agent session create \
  --profile <profile> --domain-id <domain-id> \
  --title "测试会话"

# Run a question (always pass --domain-id even with --session-id)
cz-cli analytics-agent session run \
  --profile <profile> --domain-id <domain-id> --session-id <session-id> \
  --msg "总行驶里程是多少？" \
  --model-name "Qwen3.7 Max" --summary --timeout-ms 180000

QA must be serial — do not submit the next question before the previous one answers.

Model name is case-sensitive: "Qwen3.7 Max" works; "qwen3.7 max" may silently fail.

Common Pitfalls

Related Skills

⚠️ Always Read --help First

Every cz-cli command in this skill has been verified against the current version, but the --help output is the single source of truth. Parameter names, required flags, and DSL formats can change between versions. Before executing any command for the first time in a session, run:

cz-cli analytics-agent <subcommand> --help

This prevents the most common class of errors: assuming a parameter format from memory that has changed in a newer version. For example, answer-builder create in v1.17.20 moved SQL from inline JSON (content.sql) to a separate --sql parameter — a breaking change immediately visible in --help.