> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zgi.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Database

> Structured data foundation for business intelligence with NL2SQL

## Function overview

ZGI database is not a simple "data storage" module, but a set of **structured data capability base** for business intelligence scenarios. It supports users to quickly generate data table structures starting from business documents, tables or explanatory materials, and connect subsequent data query, statistical analysis, complex calculations, log tracking, agent question and answer and other capabilities in series.

The database function can be used as an independent data management tool or as the core data source in the agent workflow. For scenarios such as contract management, project ledgers, operating data statistics, business record analysis, rule management, etc., the database module can undertake a complete link from "structured modeling" to "natural language query".

> **Core Value**
>
> It's not just about "storing data in", but it's about allowing these data to be stably checked, accurately calculated, clearly tracked, and finally returned to business personnel through natural language.

Database capabilities are particularly suitable for the following types of business problems:

* Query single or multiple pieces of structured information
* Filter data according to conditions and output details
* Aggregate, group, sort, and perform statistical analysis on data
* Support intelligent agents to conduct natural language question and answer
* Do complex calculations with business rules, clause data, and project rule tables
* Carry out log traces and troubleshooting of database operation processes

## Overview of core competencies

| Ability Category                              | Contains capabilities                                                | illustrate                                                                             |
| --------------------------------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| **Table structure design**                    | Field definition, type setting, required mark, manual adjustment     | Supports two methods of manual table creation and intelligent generation               |
| **Intelligent generation of table structure** | Upload business documents to automatically generate table structures | Automatically identify fields from documents, forms, contracts and other materials     |
| **Data Import**                               | Structured data batch writing                                        | Supports the import of 15 pieces of data at a time, and is continuing to be optimized. |
| **Data Query**                                | Precise query, conditional filtering, fuzzy matching                 | Supports multiple query types to meet different business needs                         |
| **Statistical Analysis**                      | Aggregation, grouping, sorting, multi-table joint query              | Complex analysis and multidimensional statistics                                       |
| **Natural Language Query**                    | NL2SQL automatic conversion and execution                            | Business staff can ask questions in Chinese and get direct results.                    |
| **Operation Log**                             | SQL execution records and operation tracking                         | Full-link audit, supporting investigation and review                                   |
| **Intelligent linkage**                       | As a workflow data source node                                       | Database + agent realize end-to-end business closed loop                               |

## Supported data types

| data type   | Instructions for use              | Typical scenario                    |
| ----------- | --------------------------------- | ----------------------------------- |
| `text`      | Text type, storing string content | Name, address, description, remarks |
| `numeric`   | Exact numeric type                | Amount, rate, price                 |
| `integer`   | integer type                      | Quantity, days, serial number       |
| `timestamp` | timestamp type                    | Contract date, operation time       |
| `boolean`   | Boolean type                      | Whether to enable and complete      |

## Table structure design

### Field definition

Each field contains the following information: **storage field name**, **field description**, **data type**, **whether required**. This design takes into account both technical executability and business understandability.

### Single table and multiple table design

In a simple scenario, one table can carry complete data (employee ledger, equipment list, etc.). For complex scenarios, one database and multiple tables design is recommended:

* **Main table** — carries core structured fields (such as contract number, amount, date)

* **Term Sheet** — Contains original terms or explanatory content

* **Rule table** — carries project-level or business-level rules and calculation standards

* **Details table** — carries multiple records or change details

> For scenarios such as contracts, rules, and business analysis, a multi-table design is usually more stable and more conducive to subsequent queries and complex calculations.

## Intelligent generation of table structure

The user uploads a reference file and fills in the requirement description, and the system automatically identifies key fields based on the file content and business intent, and infers a reasonable table structure.

### Supported input sources

* Local file upload (DOC, DOCX, PDF, XLSX, XLS, PPTX, JPG)

* Custom text description

* Select reference files from the file management module

### Generate content

The system automatically generates field names, field descriptions, data type recommendations, required field recommendations, and possible business primary key/identification fields.

### Applicable scenarios

* Not familiar with modeling and don’t know how to create a table
* Already have business materials but no structured data design yet
* Hope to quickly build a demo or verification solution
* Want to convert document content into a queryable structured table

> **Usage Suggestions**
>
> Intelligent generation is suitable for "starting", but it is still recommended that the core field naming, field semantics, and field splitting methods be finalized by the business or implementation personnel.

## Data import and maintenance

After the table structure is built, the business data is written into the table through the import capability of the database module itself. Currently, it supports importing **15** pieces of data at a time, and this capability is being continuously optimized.

### Applicable scenarios

Initial ledger establishment, contract sample import, project rule data entry, tabular data rapid storage, and demo data preparation.

> **Recommendation process**
>
> Design the table first → import in batches → verify the query to avoid finding unreasonable field design after one-time import.

## Data query capabilities

| Query type                 | illustrate                                            | Example                                                           |
| -------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
| Precise query              | Locate a single record by primary key or unique field | "Contract information of Sunshine Company"                        |
| Conditional filtering      | Filter multiple records by conditions                 | "All contracts expiring this month"                               |
| fuzzy matching             | Keyword fuzzy search                                  | "Items containing 'property'"                                     |
| aggregate statistics       | Summarize, count, group, sort                         | "Total annual rent for each building"                             |
| Multiple table joint query | Cross-table related query                             | "Contract Master Table + Term Sheet Joint Query"                  |
| Complex calculations       | Multi-field operations and rule judgment              | "Liquidated damages = daily rent × number of overdue days × rate" |

## Natural language query (NL2SQL)

Business personnel can directly ask questions in Chinese, and the system automatically converts natural language into SQL and executes it.

### Query example

```text theme={null}
User question: What is the property fee payment method for Sunshine Company?

→ System-generated SQL:
  SELECT payment_method FROM contracts WHERE company_name = 'Sunshine Company';
→ Natural language response:
  The property fee payment method for Sunshine Company is "quarterly prepayment."
```

### conversion process

### Understanding the problem

The system identifies query objects, query indicators and query types

### Generate SQL

Automatically generate corresponding SQL statements based on the table structure

### Execute query

Execute SQL in database and get raw results

### Natural language reply

Convert query results into natural language answers that business people can understand

## Complex business calculations

The database is not only suitable for "looking up data", but can also provide structured support for complex business calculations. Together with the rules table and terms table, you can achieve:

* **Liquidated Penalty Calculation** — Automatically calculated based on overdue days, daily rent and rate

* **Property fee calculation** — Calculated based on multiple dimensions such as area, unit price, cycle, etc.

* **Deposit Return Judgment** — Comprehensive judgment based on contract terms and actual performance.

* **Payment Cycle Alert** — Automatically identify payment nodes that are about to expire

## Operation logs and tracking

| Dimensions       | illustrate                                                 |
| ---------------- | ---------------------------------------------------------- |
| Operating time   | Operation timestamp accurate to seconds                    |
| Operation type   | Create tables, queries, update, delete, etc.               |
| Execution status | Success/failure and error reasons                          |
| Operation sheet  | Involved data table name                                   |
| operating user   | The account that performs the operation                    |
| Execute SQL      | The actual executed SQL statement for easy troubleshooting |

The log supports filtering by operation type, status, and time range, and is suitable for scenarios such as query error troubleshooting, prompt word optimization review, business data modification tracking, and abnormal location of agent results.

## Linked to intelligent agent workflow

* **As a data source**: Provide query objects, core fields, and statistical data, allowing agents to directly consume structured data
* **Statistical Analysis Link**: In scenarios such as business analysis and contract statistics, it directly assumes the role of statistics and return results.
* **Complex calculation support**: Provides core numerical fields and rule fields to provide a data basis for rule-driven business calculations
* **Natural language reply**: The query results directly generate natural language answers, not just returning forms, but service business questions and answers

## Typical business scenarios

| scene                    | The role of the database                                                       | core competencies                            |
| ------------------------ | ------------------------------------------------------------------------------ | -------------------------------------------- |
| **Contract Management**  | Stores the main contract table + terms table, supporting natural language Q\&A | Multi-table query + NL2SQL                   |
| **Project Ledger**       | Structured management of project schedule, budget, person in charge, etc.      | Conditional filtering + aggregate statistics |
| **Operational Analysis** | Multi-dimensional data statistics and visualization                            | Group statistics + complex calculations      |
| **Property Management**  | Ledger management of rent, property fees, deposits, etc.                       | Rule calculation + early warning             |
| **HR Management**        | Structured storage of employee information, attendance, and performance        | Precise query + filter                       |
| **Equipment Asset**      | Equipment list, inspection records, maintenance information                    | Conditional query + log tracking             |