GBI user guide

Updated at:

GBI offers a range of editions and specifications to fit your needs. This document provides guidance for common issues, helping you troubleshoot and optimize results for your selected edition.

Introduction

GBI is a native data assistant built on the Alibaba Cloud Qianwen large language model and specifically enhanced for data analytics. Through natural language interaction, it enables multi-dimensional intelligent analysis applications based on large language models, including NL2SQL, data Q&A, analysis, and insights. It is well-suited for fast-paced, front-line business scenarios that require timely data analysis.

Procedure

To access GBI, go to the App Marketplace page, search for GBI, and click the card to open the GBI console. GBI provides a free trial quota for each customer. To continue using the service after the free quota is exceeded, purchase a product edition as needed.

After starting a trial or purchasing a product edition, you must first complete the initialization. You can follow these steps to configure the initial setup and connect your database to GBI.

  1. Associate and authorize GBI to access the specified database.
  2. Configure the schema information of the data tables that you authorize GBI to access.
  3. Configure the business knowledge that may be involved when you use GBI for Q&A.

Connect to a database

Configure a database

When using GBI for the first time, you must authorize your database in data source management to associate it with GBI. GBI supports connecting to publicly accessible MySQL or PostgreSQL protocol databases, VPC-accessible AnalyticDB for PostgreSQL databases, and virtual databases (MySQL or PostgreSQL) that can be connected only through the API.

  1. In the left-side navigation pane, click Data Table Management.

  2. Select a database and click Authorize Connection.

    ImportantEach workspace can connect to only one type of database. To change the database type, you can revoke the authorization and connect to a new database.

  3. When you connect to a MySQL or PostgreSQL database in the Access Public Database section, ensure that the IP/Domain you enter is a publicly accessible address. The IP/Domain can be the address of a cloud database purchased from Alibaba Cloud or the address of a database service in your local data center. If the connection fails, check whether the database access has IP allowlist restrictions. If it does, add GBI's IP address to the allowlist: 39.107.142.91.

    In the Database Authorization dialog box, enter the IP/Domain, Port, Database Name, Database Username, and Database Password in turn, and then click Authorize Connection to complete the connection.

  4. Before you authorize a connection to AnalyticDB for PostgreSQL in the Access VPC Database section, you must first authorize the ADB instance. If the ADB instance is not authorized, clicking the Authorize Connection button in the Authorize ADB Instance dialog box will first authorize the ADB instance. This action automatically creates a service-linked role. This permission allows Alibaba Cloud Bailian GBI to access your cloud-native data warehouse AnalyticDB for PostgreSQL resources. With this permission, GBI can query information such as databases, tables, and columns, and execute SQL queries on data.

    After authorizing the ADB instance, you must fill in the form to authorize GBI to connect to your ADB database.

    • Region: Required. Available options include Beijing, Shanghai, Hangzhou, and Shenzhen. The default is Beijing.
    • Database instance: Required. A database instance within the selected region. Only one instance can be selected.
    • Username and password: Required. The username and password used to access the selected ADB database instance.
  5. After the database is successfully connected, select the data table information that you authorize GBI to access to complete data table synchronization. If the database contains a large number of data tables, this synchronization process may take longer. After data table synchronization is successful, you can manage the tables in the list on the page.

    On the Data Table Management page, click Associate Data Tables in the upper-right corner to begin selecting the data tables to authorize and synchronize.

    In the Associate Data Tables panel, select data tables as needed (select all is supported). The selected data tables appear as tags at the bottom. After confirming that they are correct, click Confirm Association to complete the synchronization.

Configure table schema

After data table synchronization is successful, for GBI to access the tables correctly, you must maintain the schema information of each table in Data Table Management and ensure that it is consistent with the structure of the source database. Data Table Management is located under Data Source Management in the left-side navigation pane.

In the Data Table Management list, locate the data table to maintain, and click Edit in the corresponding Actions column to enter the schema configuration page.

  • Basic information: includes the data table description, primary key, and foreign key information of the data table.

    After you enter the data table details page, the Basic Information card at the top displays the data table description, primary key, and foreign key relationship configuration of the current table.

    In the Edit Basic Information dialog box, you can modify the Table Description, set the table primary key, and add mappings between the columns of this table and the columns of other tables one by one in the table foreign key section.

  • Table description: the data content and granularity recorded in the current table. For example: substation installation record table, used for xxxx.

  • Table primary key: used to ensure data integrity, that is, to ensure that each row in the table is unique. It is used to quickly find and reference specific records.

  • Table foreign key: creates relationships between different tables for association with other tables. For example: table_a.column_name = table_b.column_name1. If foreign keys exist between tables, you must configure them. Otherwise, joins between tables may be incorrect.

  • Column information:

    In the Table field information list, you can view properties such as Column name, Column Chinese name, Column description, Data type, and Is enum for each column, and adjust them through the Edit button in the Actions column.

  • Column description: describes the specific meaning of the column in simple and concise language.

  • Column Chinese name: optional. When the column description is missing, the data table information is understood based on the column Chinese name.

  • Enum values: crucial for columns of the enumerated type. You must list all values stored in the column. If value-to-meaning mappings exist, you must set the corresponding mapped value for each value. For convenience, you can synchronize enum values from the database, and GBI will pull up to 99 deduplicated enum values from the database. Note the following key requirements and best practices to ensure their effectiveness and reliability:

    1. Uniqueness of values: each enum value should be unique within the predefined range. Duplicate values are not allowed.
    2. Descriptiveness of values: enum values should be as descriptive as possible so that they intuitively represent their meaning. For example, using 'active' and 'inactive' is more readable than using 1 and 0.
    3. Reasonable number of values: the number of enum values should not be excessive, as too many values may increase code complexity and maintenance costs. In general, we recommend keeping the number within 10.

    Click Edit in the Actions column of a column, and in the column editing dialog box, enter the Column Chinese name and Column description. If the column is of the enum type, after you set Is enum to Yes, you can click Sync column enum candidates from database to automatically pull deduplicated candidate values from the database.

    In the enum value list, enter the corresponding Mapped value for each Enum value (for example, 1→Self-operated, 2→Franchise) to help the model understand the business meaning.

Enterprise knowledge management

To help GBI better understand how you express your goals in data analysis, the Enterprise knowledge management module provides three tools to meet your business scenario needs.

Knowledge term explanation

For business-specific terms, you can configure them in Knowledge term explanation. For example, when you ask questions in natural language, the term "consultation conversion rate" often appears, but the associated data table does not have a "consultation conversion rate" column. Its value is obtained by dividing the aggregated result of the "customers who consulted and successfully placed an order" column by the aggregated result of the "customers who consulted" column. In this case, you can define the calculation logic of the metric in the term description.

On the Enterprise knowledge term explanation page, click Add Knowledge in the upper-right corner to enter the explanations and calculation logic of business terms. You can maintain them in the list later.

Synonym explanation

When you ask questions in natural language, a term often involves multiple phrasings, which are called synonyms. In Synonym explanation, you can maintain synonym lists. For example, if a data table stores the value "Beijing", you can use the synonym "capital" instead when asking questions in natural language.

On the Synonym explanation page, click Add Term in the upper-right corner to enter a term and its synonym list, and bind it to a specific data table column in Associate data tables.

To improve synonym recognition accuracy, we recommend associating synonyms with a specific column of a data table when configuring synonyms.

In the Edit Synonym dialog box, enter the Term and its Synonym tags, select a specific data table column from the Associate data tables drop-down list, and then click Confirm to apply.

Business logic explanation

When you ask questions in natural language, company-specific business logic usually needs to be configured in Business logic explanation. For example, when a query includes "this month", you can configure the business logic explanation as "the aggregated data from the first day of this month to today".

ImportantBusiness logic explanation serves as an advanced guidance feature that applies business correction to model output. When the model inaccurately understands data table schema information or generates inaccurate SQL, you can usually tune the results by optimizing business logic explanations.

On the Business logic explanation page, click Add Business Logic in the upper-right corner to enter business rules. The model references the configured business logic when parsing natural language.

Business logic is divided into two types: global and smart. Global business logic applies to all user questions. Smart business logic is applied selectively by the model based on the content of the user's question.

Optimization case management

If the model still fails to output the expected result after you adjust question phrasing and data management, you can add optimization cases to guide the model's learning. In the Standard Edition · MIX, GBI provides case self-management capabilities, allowing you to guide the model to self-learn a category of questions through case management without customizing the model itself.

NoteUsage notes: Optimization case management provides two capabilities: wildcard management and case base management. Wildcards must be used together with the case base. Add wildcards first, and then add the case base. After you add them, the system needs to parse the data for the model to self-learn. Please wait a few minutes before using it.

Wildcard management

A wildcard is an advanced term that can be fuzzily substituted by one or more characters. For example, wildcard A is [Brand], with enum values "Xiaomi", "Huawei", "vivo", and "oppo"; wildcard B is [Job level], with enum values "Junior Engineer", "Mid-level Engineer", and "Senior Engineer". A question phrasing may include an enum value of a wildcard. When you manage cases for such question phrasings, you do not need to add a case for each enum value one by one. The model will intelligently understand them based on the wildcard configuration.

On the Optimization case management page, on the Wildcard management tab, click Add Wildcard in the upper-right corner to enter a wildcard name and its corresponding list of enum values.

Case base management

Adding cases can effectively improve the model's accuracy in solving a category of problems. A case consists of the question phrasing description and the complete SQL content expected to be correctly executed. When setting up a case, if the question phrasing description includes an enum value of a wildcard, ensure that the wildcard has been configured in wildcard management.

Switch to the Case base management tab and click Add Case in the upper-right corner to enter the question phrasing description and the corresponding expected SQL content.

Model output intervention

If the model still returns incorrect answers after you adjust question phrasing and data management multiple times, you can set specific replies to intervene in the model's output.

NoteThe question phrasing description for intervention and the complete SQL expected to be correctly executed do not generalize.

ImportantTo avoid unpredictable negative impacts caused by setting too many intervention conditions, set intervention conditions with caution and minimize the use frequency of this feature.

On the Model output intervention page, click Add Intervention Condition in the upper-right corner to enter the question phrasing description that requires intervention and the SQL content to be forcibly returned.

Home page queries

  1. On the GBI home page, in the Database card, confirm that a database has been associated, click Start Conversation, and then enter the question you want to query in the input box and submit it.

    After the question is submitted, GBI parses your question and generates the corresponding answer in five steps.

    The system sequentially displays the five steps of Query Understanding, Table Selection, SQL Generation, Execution Result, and Visualization Result, and outputs the visualized query result in the final step.

  2. You can perform the following operations on the generated answer.

    On the answer results page, Callout ① is the chart type switch icon (bar chart/line chart/pie chart), Callout ② is the Regenerate button, Callout ③ is the control for switching among generated answers, Callout ④ is the Download Result button, and Callout ⑤ is the Request ID of this Q&A.

    ActionDescription

    Switch chart type

    Click the chart type switch icon (Callout ①) to switch the chart type (bar chart, line chart, pie chart).

    Switching the chart type only changes the display form of the chart and does not regenerate the result.

    Regenerate an answer

    When you click Regenerate (Callout ②), the already generated answers are retained. You can regenerate up to 5 times.

    You can click < or > (Callout ③) at the bottom of the card to switch among generated answers. The page stays on the most recently generated answer by default.

    "Regenerate (2 remaining)" indicates that you can regenerate 2 more times.

    "2/3" indicates that 3 answers have been generated, and the page currently stays on the second generated answer.

    Export results

    Click Download Result (Callout ④) to download the current question and the generated answer to your local device.

    If you have generated multiple answers, only the answer displayed on the current page is downloaded.

    The downloaded file is named after the Request ID (Callout ⑤), in CSV format. For example, 20839b75-xxx.csv.

Troubleshooting

Supported database types

Question type

Guidance

What types of databases does GBI currently support?

GBI supports connecting to publicly accessible MySQL or PostgreSQL protocol databases. There is no restriction on the database types of these two protocols. You can select the corresponding type to add a database based on the database protocol.

Are internal network databases supported?

GBI now supports associating databases on the Alibaba Cloud VPC internal network. Currently, AnalyticDB for PostgreSQL is supported through OpenAPI. You can authorize the connection in the Access VPC Database section on the data source management page.

Database connection issues

Error type

Common mistake

Correction

Connectivity error

Incorrect URL format

In the database authorization form, correctly enter the IP/Domain and Port. The IP/Domain is the domain name or IP address of the database, and the Port is the port number of the database service.

The default port of MySQL is 3306, and the default port of PostgreSQL is 5432.

Database connectivity error. The URL is not a publicly accessible address.

The URL you enter must be a publicly accessible address. The host part cannot be localhost. If the database is purchased on Alibaba Cloud, you can find the public host in the Database Connections menu of the database instance.

Database connectivity error. The database has IP access restrictions.

In this case, you must add GBI's public IP address 39.107.142.91 to the allowlist.

If the database is purchased on Alibaba Cloud, you can configure the access IP allowlist in the Security menu of the database.

If the database is deployed on an ECS instance, you must add an inbound IP allowlist rule in the security group of the ECS.

Incorrect account or password

Incorrect username

Enter the username for accessing the database, not the database name.

Unexpected results

Question type

Guidance

A user question includes multiple queries

Currently, one user question can generate only one query SQL. If a user question includes multiple queries, only the query SQL of one question is output. We recommend splitting complex questions into multiple simple questions.

The generated SQL is still not as expected after supplementing data table descriptions and column schema information

You can try adding the business logic involved in the question.

Question type

Guidance

Date query errors

For date columns in the database, we recommend using the YYYY-MM-DD format and filling in the column description with "Date column, format is YYYY-MM-DD". Avoid formats such as YYYYMMDD or MMDDYYYY.

Errors related to the current date

We recommend specifying an exact date in the question, such as the sales on 2024-05-30. Do not omit information by default. For example, the phrasing "April 20" omits "this year" by default, which makes it difficult for the model to reason.

Other errors

Question type

Guidance

Column does not exist

In many cases, the "column does not exist" error occurs because the model does not understand the column name. Consider adding the Chinese meaning of the column to the column description;

Avoid using Chinese names for columns. English names are recommended;

Table does not exist

The "table does not exist" error often occurs when the model does not understand which table can solve the user's question. We recommend configuring a table description to explain the purpose and stored content of the table in Chinese.

Table join fails

This error is often caused by missing foreign keys between tables. You can configure foreign keys to improve the join effect.

GROUP BY error. The error message is similar to Expression *** of select list is not in group by clause .....

You must disable ONLY_FULL_GROUP_BY in the MySQL configuration. In the [mysqld] section, add or find the sql_mode setting and remove ONLY_FULL_GROUP_BY from it.

Incorrect table selection

Currently, when there are too many tables, the model has some difficulty in selecting tables accurately. We recommend associating no more than 20 tables and clearly defining table description information for similar tables that are easy to confuse.

FAQ

  • What is the difference between the official and trial editions of GBI?

    A: The trial edition has the same features as the official edition. The trial edition currently offers a limited free quota.

  • Each workspace can be associated with only one type of database. Does this mean only one database can be associated? Or can multiple databases be connected under MySQL/PostgreSQL?

    A: Only one database can be connected under one workspace. Cross-database queries are not currently supported. If your business requires queries across multiple databases, you can isolate them by using workspaces, with each workspace using a different database.

  • If only one database can be connected, what are the recommendations for querying multiple databases in real business scenarios?

    A: Cross-database queries are not currently supported. We recommend isolating business scenarios by using workspaces, with each workspace using a different database.

  • Does GBI support private deployment?

    A: GBI supports hybrid deployment where the database is on-premises and the service is on the public cloud. Private deployment is not currently supported.

  • What does concurrency mean for the GBI product? If two users access it at the same time, does the second user have to wait in a queue?

    A: Concurrency refers to the number of requests that the system processes at the same time. If you purchase only 1 unit of concurrency, the system can process only one request at a time. A second request will be rejected before the current request is completed.

  • Is SQL generated from natural language based on the column description or the column Chinese name?

    A: The column description takes priority.

  • Can multiple workspaces reuse the same GBI?

    A: Data is isolated between different workspaces and cannot be reused.

  • Does GBI support defining default query conditions?

    A: This is not currently supported.