All Products
Search
Document Center

AnalyticDB:Data Agent

Last Updated:Oct 20, 2026

Data Agent is a data processing and analysis agent provided by AnalyticDB for PostgreSQL. It uses natural language as the interaction interface and provides two core capabilities: read-only query analysis and DBA read-only diagnostics. This enables users to perform data queries, result analysis, and instance health diagnostics without writing SQL.

Prerequisites

An AnalyticDB for PostgreSQL V7.0 instance with kernel minor version 7.2.1.0 or later.

Features

Data Agent is designed for DBAs and data analysts of AnalyticDB for PostgreSQL to address the following common challenges:

  • Unfamiliarity with table structures and field meanings leads to low SQL writing efficiency.

  • Execution plans are difficult to interpret, making performance issue diagnosis time-consuming.

  • Completing a single analysis or diagnostic task requires switching between multiple tools (console, monitoring, SQL clients).

Data Agent shares the same kernel as AnalyticDB for PostgreSQL and can access the Ontology semantic layer and kernel-level observability data (execution plans, segment/slice views, and control plane metrics). This allows it to accurately understand business semantics and provide professional-grade analysis conclusions and diagnostic recommendations. The product is designed for read-only queries and does not write user data. During Ontology semantic layer construction, metadata is written to the database (ontology_graph and semantic.views tables). This is an internal product management operation and does not involve user business data. Data and AI assets remain within the customer environment.

Core Capabilities

Read-Only Query Analysis

Users describe their analysis requirements in natural language. Data Agent automatically generates read-only SQL, executes the query, and returns structured results. It supports multi-turn follow-up questions (such as switching chart types or adding filter conditions) and SQL traceability (viewing the generated SQL and its execution plan).

Typical scenarios include: multi-dimensional comparison analysis (such as category month-over-month and region year-over-year comparisons), trend analysis, Top N rankings, proportion distribution, and cross-table join queries.

DBA Read-Only Diagnostics

Users send slow SQL statements or describe problems directly to Data Agent. The agent automatically reads execution plans, identifies performance bottlenecks (such as full table scans, data skew, and lock waits), and provides actionable rewrite solutions with prioritized optimization recommendations.

Supported diagnostic templates include: SQL diagnostic optimization, resource usage diagnostics, slow query analysis, lock wait analysis, data skew diagnostics, table bloat checks, long transaction diagnostics, and index usage diagnostics.

Ontology Semantic Layer

Ontology is the semantic knowledge graph of Data Agent, addressing the core NL2SQL challenge of "the model not understanding the business." It organizes database tables, columns, business concepts, metric formulas, JOIN relationships, and business rules into a structured semantic network. This enables the agent to accurately understand business terms such as "monthly active users" and "category month-over-month" when generating SQL, without requiring users to explain them each time.

Ontology uses a two-layer architecture:

  • Graph layer (based on the Apache AGE graph database extension): Stores the relationships between concepts, tables, columns, metrics, and business rules. Supports concept discovery, cross-table JOIN path finding, and authority ranking (OntoRank).

  • Semantic model layer (based on JSONB + YAML): Stores structured metadata such as column definitions, metric formulas, synonyms, and data characteristics. YAML files serve as the human-editable working format, with bidirectional synchronization to the database.

Data Agent provides complete lifecycle management for Ontology:

  • Builder: Scans database metadata and query logs, extracts business concepts and relationships through models, generates semantic model YAML, and synchronizes to the graph. Supports full builds and incremental updates.

  • Consumer: After receiving a natural language question, the agent matches relevant concepts through Ontology, finds JOIN paths, retrieves metric formulas, and generates more accurate SQL.

  • Maintainer: Incrementally refreshes changed tables and columns, and recalculates concept authority scores.

The Desktop client provides an Ontology management interface with a 5-step wizard (Initialize → Generate YAML → Sync YAML → Build Graph → Visualize) and a force-directed graph visualization showing concept-table-column relationships.

Ontology provides three-level table access control: Tables registered in the semantic model and not marked as sensitive use enhanced mode (using synonyms, metrics, and JOIN relationships from the semantic model). Unregistered tables undergo sensitivity detection (table name pattern matching + table comment markers); tables matching sensitivity markers are blocked. Remaining tables are evaluated based on RBAC permissions; tables with SELECT permission but not registered use basic mode (using only information schema metadata, with limited accuracy).

Disclaimer

  • Content generated by Data Agent is produced by AI models and is for reference only. Analysis conclusions and diagnostic recommendations are not guaranteed to be absolutely accurate. Evaluate them based on your actual business situation and verify important operations in a test environment first.

  • Data Agent is designed for read-only operations. Query analysis and diagnostic capabilities do not perform write, modify, or delete operations, eliminating the risk of data changes caused by agent operations. During Ontology semantic layer construction, metadata is written to the database (ontology_graph and semantic.views tables). This is an internal product management operation and does not involve user business data.

  • Data Agent executes queries using the identity of the currently logged-in user and does not exceed the account's own permission scope.

  • No feature transfers your data externally. All queries and diagnostics are completed within your AnalyticDB for PostgreSQL instance.

How It Works

The overall architecture of Data Agent consists of four layers:

  • Agent Runtime layer: The layer where Data Agent resides, responsible for natural language understanding, SQL generation, tool orchestration, and result presentation.

  • Agent Context layer: Provides context support including the Ontology semantic layer, knowledge base, memory, and Skills.

  • Disk+OSS Storage layer: Structured table storage of the AnalyticDB for PostgreSQL instance.

  • MaaS layer: Model invocation, including NL2SQL, diagnostic attribution, and result analysis. An API Key from the ADB-PG AI Gateway is required before use.

Data Agent interacts with AnalyticDB for PostgreSQL instances through an MCP (Model Context Protocol) Server. All SQL undergoes two layers of validation before execution:

Security Validation (SQLGuard)

Dual-layer parallel validation. The regex layer handles statement type whitelisting (only SELECT/WITH read-only statements are allowed), multi-statement injection protection, dangerous function interception (pg_sleep, pg_terminate_backend, dblink, file read/write functions, etc.), dangerous pattern interception (COPY PROGRAM, INTO OUTFILE, etc.), sensitive table access blocking (system tables such as pg_user and pg_shadow), and destructive DML/DDL interception. The AST layer (pglast) provides PostgreSQL native parser-level syntax validation, automatically degrading to the regex layer when Greenplum dialect is encountered or parsing fails.

Quality Check (Query Quality Guard)

SQL static analysis based on sqlglot that intercepts common anti-patterns affecting execution plans. Blocking-level rules include implicit Cartesian product detection, large tables without WHERE filtering, and large table full-table aggregation without GROUP BY. Warning-level rules include SELECT *, deeply nested subqueries, excessive SELECT column count, partition tables not referencing partition keys (preventing partition pruning), and cascading CTEs. When blocked, specific issues and modification suggestions are returned for the agent to rewrite and resubmit.

Query results automatically inject LIMIT to prevent returning excessively large data volumes.

Skill Packages

Data Agent capabilities are organized into four built-in Skill packages. The agent automatically loads the corresponding Skill and its reference documents based on user intent:

Skill Package

Purpose

Covered Scenarios

adbpg-query

Data query. Executes read-only queries through MCP tools, supports semantic model-driven SQL generation, and supports CSV export of results

Daily data retrieval, statistical analysis, result export

adbpg-diagnostics

Database diagnostics. Matches 8 diagnostic templates by scenario, each with a corresponding diagnostic process reference document

SQL diagnostic optimization, resource usage diagnostics, slow query analysis, lock wait analysis, data skew diagnostics, table bloat checks, long transaction diagnostics, index usage diagnostics

adbpg-optimizer

SQL Pattern Recognition and Optimization. Identifies high-risk SQL patterns in MPP environments (Lateral joins, subquery projection columns, missing partition pruning, etc.) and provides rewrite recommendations.

Slow SQL rewriting, batch SQL risk triage, optimizer fallback investigation.

adbpg-ontology

Ontology semantic layer management. Supports Builder (graph construction), Maintainer (incremental maintenance + OntoRank authority recalculation), and Consumer (semantic discovery-assisted SQL generation) modes

Semantic model construction, concept discovery, JOIN path finding, metric formula retrieval

Skill packages are built into the Desktop client and automatically loaded on demand during agent runtime, requiring no manual configuration from users.

Usage

Using the Desktop Client

Data Agent is provided as a Desktop client. Install it to get started. Currently supported platforms:

Platform

Architecture

Download

macOS

Apple Silicon (arm64)

ADB-PG-Data-Agent-arm64.dmg

macOS

Intel (x64)

ADB-PG-Data-Agent-x64.dmg

Windows

Intel (x64)

ADB-PG-Data-Agent-x64.exe

  1. Install the Data Agent Desktop client.

  2. Obtain an API Key for the ADB-PG AI Gateway. On the AgenticDB > Model Operator Management page of the AnalyticDB for PostgreSQL console, click Create API Key, enter a description in the dialog box, and confirm. After creation, copy the API Key and endpoint address. After creation, you must submit a ticket for the Alibaba Cloud technical team to complete the backend configuration. After configuration, enter the API Key and endpoint address on the Desktop client's guidance page.

  3. Configure the AnalyticDB for PostgreSQL instance connection information (Host, Port, username, password, database name). We recommend using a read-only account with SELECT permission on target tables to minimize the permission scope.

  4. To use control plane diagnostic capabilities (instance metrics, slow SQL records, etc.), configure an Alibaba Cloud RAM AK/SK. For more information, see Create an AccessKey pair. We recommend attaching the AliyunGPDBReadOnlyAccess system policy to the RAM user associated with the AK/SK.

  5. To use the Ontology semantic layer, complete permission configuration and build first. For more information, see Ontology Usage Guide.

  6. Enter a natural language question in the dialog box or send SQL to be analyzed.

The Desktop client also provides the following auxiliary capabilities:

  • DBA Diagnostic Panel: Fill in parameter forms by scenario template (SQL diagnostics, resource usage, slow queries, lock waits, data skew, table bloat, long transactions, index usage) to trigger structured diagnostics with one click, without writing diagnostic SQL.

  • Instance Monitoring: Pulls instance performance metrics (CPU, memory, IO, QPS, TPS) through control plane OpenAPI and displays trends as charts. Supports time range selection and node dimension switching.

  • Ontology Visualization: Force-directed graph showing concept-table-column relationships, with node filtering and detail drill-down support.

  • Result Visualization: Query results support automatic ECharts chart generation (bar charts, line charts, pie charts, scatter plots) with chart type switching in multi-turn conversations.

CLI/Skill Integration

Note

This capability is not yet available. Future versions will support integration with other AI programming tools through MCP Server and Skill forms.

Security and Permissions

Data Agent builds a security protection system on both the product side and the user side.

Product-Side Protections

  • Read-only guarantee: The agent registers only read-only tools. SQLGuard performs dual-layer validation at both the regex and AST layers, and the database side wraps operations in READ ONLY transactions.

  • Data sovereignty: All queries and diagnostics are completed within the customer's AnalyticDB for PostgreSQL instance. Data and AI assets do not leave the customer environment.

Database Account

For the database account used for read-only queries and in-database diagnostics, we recommend using a read-only account that has only SELECT permission on target tables. Diagnostic capabilities such as lock wait, data skew, and table bloat require reading system views such as pg_stat_activity and gp_toolkit, which are accessible to ordinary read-only accounts. To view session information of other users (such as blocked sessions in lock wait diagnostics), grant the additional pg_read_all_stats permission.

We recommend that the DBA create a dedicated read-only account and authorize only the specific tables required for business operations. Full-database authorization is strictly prohibited:

CREATE ROLE readonly_agent LOGIN PASSWORD '<strong_password>';
GRANT CONNECT ON DATABASE mydb TO readonly_agent;
GRANT USAGE ON SCHEMA public TO readonly_agent;
GRANT SELECT ON public.orders, public.customers TO readonly_agent;  -- Authorize only required tables

Configure a dedicated resource group for the read-only account to prevent agent queries from competing with business workloads:

CREATE RESOURCE GROUP agent_rg WITH (concurrency=5, cpu_max_percent=10, memory_limit=10);
ALTER ROLE readonly_agent RESOURCE GROUP agent_rg;

RAM AK/SK

To use control plane diagnostic capabilities such as instance metrics and slow SQL records, configure an Alibaba Cloud RAM AK/SK. The OpenAPI calls made by Data Agent to the control plane are all read-only interfaces. We recommend attaching the AliyunGPDBReadOnlyAccess system policy to the RAM user associated with the AK/SK. This policy covers all read-only interfaces required by Data Agent.

Network Access Control

Ensure that the egress IP of the Data Agent runtime environment is added to the whitelist of the AnalyticDB for PostgreSQL instance. Add it in the console under Data Security > Whitelist Settings.

Application Scenarios

User Role

Typical Scenarios

Data Analyst / BI Engineer

Natural language data retrieval, multi-dimensional comparison analysis, trend interpretation, joint analysis of local CSV and in-database data, chart switching

DBA / Operations Engineer

Slow SQL diagnostics and rewrite suggestions, instance health inspection, lock wait analysis, data skew diagnostics, table bloat checks, long transaction investigation, index usage analysis

Data Engineer / Business Developer

Ontology semantic model construction, business concept-to-table-column mapping maintenance, JOIN relationship organization, metric caliber solidification

Billing

Data Agent itself is not billed separately. The costs incurred during use include:

  • MaaS Token consumption: Token costs generated by agent orchestration, NL2SQL, and diagnostic analysis model calls, charged according to AI Gateway billing standards.

  • Instance fees: Computing and storage resources of the AnalyticDB for PostgreSQL instance consumed by queries, charged according to the instance's existing billing method.

FAQ

Can Data Agent access business data?

Yes, but only for read-only queries. For analysis requirements raised by users in conversations, Data Agent generates SELECT statements and executes them on the instance, returning query results. Diagnostic capabilities mainly read execution plans, system views, and monitoring metadata. All operations are bounded by the permissions of the currently logged-in user.

Why are responses sometimes inaccurate?

The accuracy of Data Agent depends on the understandability of business semantics. When table structures are complex, field meanings are unclear, or business calibers are undefined, the model may generate SQL that does not meet expectations. We recommend improving table and column business descriptions and metric calibers through the Ontology semantic layer, or providing more specific context when using the service (such as table names, field names, and problem descriptions).

Does using Data Agent affect instance performance?

Diagnostic capabilities only read system views and monitoring data, with negligible impact on instance performance. Query analysis capabilities actually execute SELECT queries on the instance. Large-data-volume queries consume instance computing resources. We recommend executing during business off-peak hours or using LIMIT to restrict the number of returned rows.