Data & Execution Commands

This page covers data onboarding, modeling, metrics, execution, and AI-related capabilities. It aligns most closely with the hbi-data, hbi-data-modeling, hbi-pipeline, hbi-notebook, hbi-data-alert, and hbi-data-agent skills. Each command family includes a minimal runnable example and representative output so you can start with a concrete command immediately.

HQL Expressions

Commands on this page — including data-model query, metric, and measure — make extensive use of HQL (Hengshi Query Language) expressions for aggregations, calculated fields, and query conditions. HQL supports aggregation functions (SUM, AVG, COUNT), time functions (YEAR, MONTH, PERIODCOMPARE), and conditional logic. See the full HQL Function Reference.

connection

Purpose: manage data connections, browse schemas/tables, and test connectivity.

Common subcommands:

• connection lifecycle: types list show test create delete update
• internal auth rules: auth-rules auth-rule-get auth-rule-create auth-rule-update auth-rule-delete
• inheritance control: auth-inherit-get auth-inherit-update
• browsing and query: browse query

Minimal runnable example:

hbi connection list --output json

Representative output:

[
  {
    "id": 39774,
    "title": "analytics-db",
    "accessCount": 273,
    "options": {
      "type": "postgresql",
      "maxConnNum": 10,
      "metaConfig": {
        "dbMajorVersion": 13,
        "dbMinorVersion": 11,
        "dbProductName": "PostgreSQL"
      }
    },
    "createdAt": "2022-10-27 13:54:24",
    "visible": true
  }
]

Common next steps:

• Show connection details: hbi connection show 39774 --output json
• Test connectivity: hbi connection test 39774
• Browse schemas/tables: hbi connection browse 39774 --output json

Browse by schema/path:

# List schema/path levels only
hbi connection browse 39774 --schemas --output json

# List every table under the exact public schema
hbi connection browse 39774 --schema public --output json

# Repeat --schema for a multi-level path; --query filters only within the selected subtree
hbi connection browse 39774 --schema hive --schema default --query orders --output yaml

Each --schema supplies one path segment. Repeat it to preserve segment order. Do not join a multi-level path as catalog.schema, because segment names can contain dots. Combining --schema with --query uses AND semantics. Without --schema, --query keeps its existing fuzzy name filter.

dataset

Purpose: manage datasets, fields, granularities, previews, and import/export.

Common subcommands:

• lifecycle: list show update replace delete duplicate import
• preview and state: preview status schedule lineage export
• knowledge enhancement: knowledge example
• creation paths: create create-from-file upload create-custom-sql create-api create-reference
• transformation flows: create-union create-fusion create-aggregate create-pivot create-unpivot
• fields and expressions: fields expression-rewrite column-create column-update column-delete
• field supplements: column-values column-geo column-geo-role column-geo-role-reset
• granularities: granularity-list granularity-create granularity-update granularity-delete

Minimal runnable example:

hbi dataset list --app 4812 --output json

Representative output:

[
  {
    "id": 3,
    "title": "Sales Order Detail",
    "appId": 4812,
    "connectionId": 39774,
    "createdAt": "2025-01-10 09:00:00",
    "updatedAt": "2026-05-20 16:30:00",
    "status": "ready"
  }
]

Common next steps:

• Preview rows: hbi dataset preview --app 4812 --dataset 3 --limit 10 --output json
• Show fields: hbi dataset fields --app 4812 --dataset 3 --output json
• Show dataset status: hbi dataset status --app 4812 --dataset 3 --output json

data-model

Purpose: manage data models and joins.

Common subcommands:

• list show preview query
• lineage tree
• suggest-joins
• join-add join-list join-delete

Minimal runnable example:

hbi data-model query --app 4812 --dataset 3 "SUM({amount})" --output json

Representative output:

{
  "result": [
    {
      "SUM({amount})": 1234567.89
    }
  ],
  "executionTime": 234
}

Common next steps:

• Group by dimension: hbi data-model query --app 4812 --dataset 3 "SUM({amount})" --by "group({region})" --output json
• Show the model tree: hbi data-model tree --app 4812 --dataset 3 --output json
• Ask for suggested joins: hbi data-model suggest-joins --app 4812 --dataset 3 --output json

metric

Purpose: manage atomic metrics.

Common subcommands:

• create delete update
• list show
• query

Minimal runnable example:

hbi metric list --app 4812 --dataset 3 --output json

Representative output:

[
  {
    "id": 101,
    "name": "Total Sales",
    "expression": "SUM({amount})",
    "datasetId": 3,
    "createdAt": "2025-02-10 10:00:00"
  }
]

Common next steps:

• Show metric details: hbi metric show --app 4812 --dataset 3 c1 --output json
• Query metric data: hbi metric query --app 4812 --dataset 3 c1 --output json

measure

Purpose: manage business measures.

Common subcommands:

• create delete update
• list show
• query

Minimal runnable example:

hbi measure list --app 4812 --dataset 3 --output json

The final argument to measure show can be a measure field name such as m1 or a display label such as Monthly Paid Sales. For a label, the CLI requires an exact match within the selected dataset. If the label matches more than one measure, the command lists the candidate field names so you can retry with one of them. measure update and measure delete continue to accept field names only.

hbi measure show --app 4812 --dataset 3 "Monthly Paid Sales" --output json

When creating or updating a business measure, you can also define its filters and time axis:

• -w, --where <HQL>: an HQL filter expression; repeat the option to combine multiple expressions with AND.
• --time-dimension <FIELD>: the field used as the time axis.
• --time-granularity <GRANULARITY>: the time granularity. Supported values are year, qoy, quarter, moy, month, week, dom, dow, and day.

--time-dimension and --time-granularity must be provided together. When measure update explicitly sets filters or a time axis, the measure uses that custom analysis context instead of its existing dataset granularity configuration.

hbi measure create --app 4812 --dataset 3 \
  --label "Monthly Paid Sales" \
  --expression "SUM({amount})" \
  --where "{status} = 'paid'" \
  --time-dimension order_date \
  --time-granularity month

hbi measure update --app 4812 --dataset 3 m1 \
  --where "{amount} > 0" \
  --time-dimension order_date \
  --time-granularity day

Representative output:

[
  {
    "id": 201,
    "name": "Monthly Sales Growth Rate",
    "expression": "PERCENTCHANGE(SUM({amount}), month({date}))",
    "datasetId": 3,
    "createdAt": "2025-03-15 11:00:00"
  }
]

Common next steps:

• Show measure details: hbi measure show --app 4812 --dataset 3 m1 --output json
• Search measures: hbi measure query --app 4812 --query "sales" --output json

pipeline

Purpose: manage pipeline flows and nodes.

Common subcommands:

• pipeline lifecycle: list show create update delete duplicate
• runtime state: status errors schedule
• node read/write entrypoints: node edit

Minimal runnable example:

hbi pipeline list --output json

Representative output:

[
  {
    "id": 450,
    "title": "Daily Aggregation",
    "createdAt": "2025-04-01 08:00:00",
    "updatedAt": "2026-05-25 10:00:00",
    "status": "success"
  }
]

Common next steps:

• Show pipeline details: hbi pipeline show 450 --output json
• Show runtime status: hbi pipeline status 450 --output json
• Edit nodes: hbi pipeline edit add 450 --help

edit is the most common deeper entrypoint, with:

• add
• remove
• connect

notebook

Purpose: manage notebooks, paragraphs, and execution-related resources.

Common subcommands:

• notebook lifecycle: list show create update delete
• paragraphs: paragraphs add-paragraph update-paragraph execute delete-paragraph
• connections: connections add-connection authorize-connection revoke-connection remove-connection
• other: schedule languages

Minimal runnable example:

hbi notebook list --output json

Representative output:

[
  {
    "id": 350,
    "title": "Data Analysis Notes",
    "createdAt": "2025-05-10 14:00:00",
    "updatedAt": "2026-06-01 09:30:00"
  }
]

Common next steps:

• Show notebook details: hbi notebook show 350 --output json
• List paragraphs: hbi notebook paragraphs 350 --output json
• Execute one paragraph: hbi notebook execute 350 para_123

data-alert

Purpose: manage data alerts.

Common subcommands:

• list show
• create update delete
• enable disable
• validate

Minimal runnable example:

hbi data-alert list 4812 --output json

Representative output:

[
  {
    "id": 520,
    "title": "Daily Sales Alert",
    "enabled": true,
    "createdAt": "2025-06-01 10:00:00"
  }
]

Common next steps:

• Show alert details: hbi data-alert show 4812 520 --output json
• Enable the alert: hbi data-alert enable 4812 520
• Disable the alert: hbi data-alert disable 4812 520 --dry-run

data-agent

Purpose: manage Data Agent / ChatBI backend configuration.

Common subcommands:

• config
• prompt
• vector

Minimal runnable example:

hbi data-agent config get --output json

Representative output:

{
  "enabled": true,
  "model": "gpt-4",
  "basePrompt": "You are a data analysis assistant",
  "updatedAt": "2026-05-30 16:00:00"
}

Common next steps:

• List prompts: hbi data-agent prompt list --output json
• Show vector status: hbi data-agent vector status --output json

Where to drill down next

Scenario	Start with
data connections, schema browsing, and connectivity checks	connection
dataset lifecycle, preview, fields, and granularities	dataset
joins and model queries	data-model
pipeline resources	pipeline
node add/remove/connect operations	pipeline edit
notebooks, paragraphs, and connections	notebook
alert definitions and enable/disable actions	data-alert
Data Agent config, prompts, and vector state	data-agent

When you need exact flags and examples, use that command tree's --help in the terminal.