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. It uses natural language to enable intelligent analysis applications, including NL2SQL, data Q&A, and insights. GBI 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 and click the GBI card to open the GBI console. Each customer receives a free trial quota of 200 questions. To continue using the service after the quota is exceeded, purchase a product edition as needed.
After starting a trial or purchasing a product edition, you must first complete the initial setup. Follow these steps to configure and connect your database to GBI.
Associate your database and authorize GBI to access it.
Configure the schema for the data tables that GBI is authorized to access.
Configure business knowledge that GBI may use for Q&A.
Connect to a database
Official preset database
GBI supports custom databases and an official preset database. If you want to test GBI's features but do not have a suitable custom database, you can use the official preset database.
View official preset database
The official preset database includes three data tables: a customer information table (customers), an order information table (orders), and a product information table (products). You can view the fields and content of each data table.
In the left-side navigation pane, click Data Table Management, and then click View Details in the View Details section to view the data tables in the official preset database.
In the Actions column of a data table, click View Details to view the table field information.
Click Preview Data Table to view the table content.
Use official preset database
You can preview the data table content in the official database and ask questions based on the content to experience GBI's capabilities and other features.
On the GBI home page, hover over the Database card, confirm that the selected database is the Official Preset Database, and then click Start Conversation.
You can click any of the preset questions to start a conversation and test GBI's features.
Configure a database
When using a custom database for the first time, you must authorize access in data management and associate your database. GBI supports connecting to publicly accessible MySQL or PostgreSQL protocol databases, VPC-accessible AnalyticDB for PostgreSQL databases, and MySQL or PostgreSQL databases accessible only through an API.
In the left-side navigation pane, click Data Table Management.
Select a database and click Authorize Connection.
ImportantEach workspace can connect to only one type of database. To change the database type, you must revoke the current authorization and connect to a new database.
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. This IP/Domain can be the endpoint for a cloud database purchased from Alibaba Cloud or a database service in your on-premises data center. If the connection fails, check whether your database enforces an IP allowlist. If it does, add GBI's IP address, 39.107.142.91, to the allowlist.
In the Database Authorization dialog box, enter the IP/Domain, Port, Database Name, Database Username, and Database Password, and then click Authorize Connection.
Before you authorize a connection to AnalyticDB for PostgreSQL in the Access VPC Database section, you must first authorize the AnalyticDB for PostgreSQL instance. If the instance is not authorized, clicking Authorize Connection in the Authorize Alibaba Cloud Model Studio to Access AnalyticDB for PostgreSQL Instances dialog box starts the authorization process. This action automatically creates a service-linked role. This permission allows GBI to access your AnalyticDB for PostgreSQL resources, query metadata such as databases, tables, and columns, and execute SQL queries.
After authorizing the instance, fill in the form to authorize GBI to connect to your AnalyticDB for PostgreSQL database.
Region: Required. Options include China (Beijing), China (Shanghai), China (Hangzhou), and China (Shenzhen). The default is China (Beijing).
Database instance: Required. Select a database instance within the specified region. You can select only one instance.
Username and password: Required. The username and password for accessing the selected AnalyticDB for PostgreSQL database instance.
After the database is successfully connected, select the data tables that you authorize GBI to access to complete table synchronization. If the database contains a large number of tables, this synchronization process may take longer. After 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 tables to authorize and sync.
In the Associate Data Tables panel, select the required data tables. You can select all tables. The selected tables appear as tags at the bottom. After confirming your selection, click Confirm Association to complete the synchronization.
Configure table schema
After table synchronization is successful, you must configure the schema information for each table in Data Table Management to ensure that GBI can access it correctly. Make sure the schema information is consistent with the source database structure.
In the Data Table Management list, locate the table you want to edit and click Edit in the Actions column to open the schema configuration page.
Basic information: Includes the table description, primary key, and foreign key information.
On the table details page, the Basic Information card at the top shows the current table description and the configured primary key and foreign key relationships.
In the Edit Basic Information dialog box, you can modify the Table Description, set the primary key, and add foreign key mappings between the columns of this table and other tables.
Table description: Describes the content and granularity of the data in the table. For example: Substation installation record table, used for xxxx.
Primary key: Ensures data integrity by making each row in the table unique. It is used to quickly find and reference specific records.
Foreign key: Creates relationships across different tables for joins. For example: table_a.column = table_b.column1. If foreign keys exist between tables, you must configure them. Otherwise, table joins may be incorrect.
Column information:
In the Table field information list, you can view properties for each column, such as Column name, Column Chinese name, Column description, Data type, and Is enum. You can adjust these properties by clicking the Edit button in the Actions column.
Column description: A concise description of the specific meaning of the column.
Column Chinese name: Optional. If the column description is missing, GBI uses the Chinese name to understand the data table information.
Enum values: Crucial for columns of an enumerated type. You need to list all the values stored in the column. If there are value-to-meaning mappings, you must set the corresponding mapped value for each enum value. You can sync enum values from the database for convenience. GBI pulls up to 99 deduplicated enum candidates from the database. Follow these best practices to ensure effectiveness and reliability:
Uniqueness: Each enum value must be unique within the predefined set. Duplicate values are not allowed.
Descriptiveness: Enum values should be as descriptive as possible so their meaning is intuitive. For example, using
'active'and'inactive'is more readable than using1and0.Reasonable count: The number of enum values should not be excessive, as this can increase code complexity and maintenance costs. In general, we recommend keeping the number of values under 10.
Click Edit in the Actions column for the desired column. In the column editing dialog box, enter the Column Chinese name and Column description. If the column is an enum type, set Is enum to Yes, and then 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.
Data files (Standard Edition · MIX only)
In GBI, you can upload Excel data files in .xlsx format. After uploading a data file, you can ask questions about it. GBI analyzes the content of the tables in the uploaded file based on your questions and generates answers and visualizations.
On the GBI home page, select Trial · Standard Edition · MIX in the lower-left corner.
Hover over the Data file card on the right side of the page and click Upload File.
On the GBI home page, click the Upload File button on the Data file card to open the upload dialog box.
Follow the requirements in the Data file upload dialog box to modify your Excel file and upload it.
After the data file is uploaded successfully, click the
icon to preview the uploaded data.The data preview panel displays the content of each data table in the uploaded file. You can switch between different data table tabs at the top to view details and start asking questions directly from the input box at the bottom.
Return to the home page, hover over the Data file card, and click Start Conversation.
Enter your question in the input box at the bottom to start a conversation.
On this page, you can also perform the following actions:
Edit Table Information: Edit the table and field descriptions to clarify their purpose.
Delete File: Click Delete File to delete the data file. The data will be permanently deleted. This operation cannot be undone.
Enterprise data management
To help GBI better understand your goals in data analysis, the Enterprise data management module provides three tools to meet your business needs.
Business terms
You can configure business-specific terms in Knowledge term explanation. For example, a natural language question might include "consultation conversion rate," but the associated data table does not have a column with this name. Its value is calculated by dividing the sum of the "customers who consulted and placed an order" column by the sum of the "customers who consulted" column. In this case, you can define the calculation logic for this metric in the term's description.
On the Knowledge term explanation page, click Add Knowledge in the upper-right corner to enter explanations and calculation definitions for business terms. You can manage them later in the list.
Synonyms
When you ask questions in natural language, a term often has multiple phrasings. These 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" in your question instead.
On the Synonym explanation page, click Add Term in the upper-right corner to enter a term and its synonyms, and bind it to a specific table column in Associate data tables.
To improve synonym recognition, we recommend associating synonyms with a specific data table column.
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
When you ask questions in natural language, company-specific business logic often needs to be configured in Business logic explanation. For example, when a question includes "this month," you can configure its logic to mean "the aggregated data from the first day of this month to today."
Business logic explanation is an advanced feature that guides the model in correcting its output based on your business rules. When the model misunderstands table schema information or generates incorrect SQL, you can often 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 configured business logic when it parses natural language.
Business logic can be global or smart. Global business logic applies to all user questions. Smart business logic is applied selectively by the model based on the user's question.
Optimization case management
If the model still fails to produce the expected result after you adjust your question phrasing and data management settings, you can add optimization cases to guide the model's learning. In the Standard Edition · MIX, GBI provides case self-management capabilities. This allows you to teach the model how to handle a category of questions through case management, without customizing the model itself.
Usage notes: Optimization Case Management provides wildcard management and case base management. Wildcards must be used together with the case base. Add wildcards first, then add the case base.After you add them, the system needs a few minutes to process the data and learn from it. Please allow a few minutes for the changes to take effect.
Wildcard management
A wildcard is a placeholder that can represent any value from a predefined list. For example, wildcard A could be [Brand] with enum values "Xiaomi", "Huawei", "vivo", and "oppo". Wildcard B could be [Job level] with enum values "Junior Engineer", "Mid-level Engineer", and "Senior Engineer". If a question's phrasing includes an enum value of a wildcard, you do not need to add a separate case for each enum value during case management. The model automatically understands the question 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 class of problems. A case consists of a sample question and the complete, correct SQL expected for it. When setting up a case, if the question's phrasing includes an enum value of a wildcard, ensure that the wildcard has already 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's phrasing and the corresponding expected SQL.
Model output intervention
If the model continues to provide incorrect answers after multiple adjustments to your question phrasing and data management settings, you can set specific replies to override the model's output.
The specified question and its corresponding SQL do not generalize to other questions.
To avoid unpredictable negative impacts from setting too many intervention conditions, set them cautiously and use this feature as sparingly as possible.
On the Model output intervention page, click Add Intervention Condition in the upper-right corner to enter the question phrasing that needs intervention and the SQL content that should be forcibly returned.
Home page queries
On the GBI home page, in the Database card, select a custom database or the official preset database. Hover over the Database card, click Start Conversation, enter your question in the input box, and then click
to submit the question.After you submit the question, GBI parses it and generates an answer in five steps.
The system sequentially displays Query Understanding, Table Selection, SQL Generation, Execution Result, and Visualization Result. Finally, the system displays the visualized query result.
You can perform the following operations on the generated answer.
On the answer results page, Callout ① is the chart type switch icon (bar/line/pie), 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 for this Q&A session.
Action
Description
Switch chart type
Click the icon at Callout ① (
) to switch the chart type (bar, line, or pie chart).Switching the chart type only changes the display format and does not regenerate the result.
Regenerate an answer
When you click Optimize Again (Callout ②), previously generated answers are retained. You can regenerate up to 5 times.
You can click
<or>(Callout ③) at the bottom of the card to switch between generated answers. The page defaults to the most recently generated answer."Regenerate (2 remaining)" indicates that you can regenerate 2 more times.
: "2/3" indicates that 3 answers have been generated, and the currently displayed answer is the second one.Export results
Click Download Result (Callout ④) to download the current question and its generated answer to your local device.
If you have generated multiple answers, only the currently displayed answer is downloaded.
The downloaded file is named after the Request ID (Callout ⑤) and is in CSV format. For example, 20839b75-xxx.csv.
Troubleshooting
Supported database types
Question type | Guidance |
What types of databases does GBI support? | GBI supports connections to publicly accessible MySQL or PostgreSQL protocol databases. For these two protocols, there are no restrictions on the database type. You can add them by selecting the corresponding type based on the database protocol. |
When will internal network databases be supported? | In mid-July 2024, GBI will support connecting to Alibaba Cloud internal network databases, including AnalyticDB for PostgreSQL, Hologres, and PolarDB. AnalyticDB for PostgreSQL will integrate via a DataAPI, requiring user access authorization. Hologres and PolarDB will integrate via reverse network access, requiring you to configure network connectivity in advance. Stay tuned. |
Database connection issues
Error type | Common mistake | Correction |
Connectivity error | Incorrect URL format | The MySQL connection format is: jdbc:mysql://host:port/db_name. The PostgreSQL connection format is: jdbc:postgresql://host:port/db_name. In these formats, |
Database connectivity error. The URL is not publicly accessible. | The URL must be publicly accessible. The host cannot be | |
Database connectivity error. The database has IP access restrictions. | In this case, you need to add GBI's public IP address, 39.107.142.91, to the IP allowlist. If the database is purchased on Alibaba Cloud, you can configure the IP allowlist in the database's security settings. If the database is deployed on an ECS instance, you must add an inbound IP allowlist rule in the ECS security group. | |
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, a single user question can only generate one SQL query. If a question includes multiple queries, only the SQL for one of them will be generated. We recommend splitting complex questions into multiple simpler ones. |
The generated SQL is still not as expected after adding data table descriptions and column schema information | Try adding the business logic that the question involves. |
Date-related queries
Question type | Guidance |
Incorrect date query | For date columns in your database, we recommend using the YYYY-MM-DD format and specifying "Date column, format is YYYY-MM-DD" in the column description. Avoid formats like YYYYMMDD or MMDDYYYY. |
Errors related to the current date | We recommend specifying an exact date in your question, such as "sales on 2024-05-30." Avoid omitting information. For example, a query for "April 20" may be difficult for the model to reason about because it omits "this year." |
Other errors
Question type | Guidance |
Column does not exist | Often, "column does not exist" errors occur because the model does not understand the column name. Consider adding the column's business meaning to the column description. We recommend using English names for columns instead of Chinese names. |
Table does not exist | "Table does not exist" errors often occur when the model does not understand which table can answer the user's question. We recommend configuring a table description that explains the table's purpose and its contents. |
Table join fails | This error is often caused by a missing foreign key. You can configure the foreign key to ensure correct table joins. |
GROUP BY error, such as "Expression of select list is not in group by clause ....." | You need to disable ONLY_FULL_GROUP_BY in your MySQL configuration. In the |
Incorrect table selection | Currently, the model may struggle to select the correct table when there are too many tables. We recommend associating no more than 20 tables and providing clear table descriptions for similar or easily confused tables. |
FAQ
What is the difference between the paid and trial editions of GBI?
A: The trial edition has the same features as the paid edition. The trial edition currently includes a limited free quota.
Each workspace can be associated with only one type of database. Does this mean only one database, or can I connect to multiple databases under MySQL/PostgreSQL?
A: Each workspace can connect to only one database. Cross-database queries are not currently supported. If your business requires queries across multiple databases, you can use different workspaces to isolate them, with each workspace using a different database.
If I can only connect to one database, what are your recommendations for querying multiple databases in a real-world business scenario?
A: Cross-database queries are not currently supported. We recommend isolating business scenarios by using different workspaces, each connected to a different database.
Does GBI support private deployment?
A: GBI supports a 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?
A: Concurrency is the number of requests the system can process 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 sent before the current one is complete will be rejected.
When generating SQL from natural language, does GBI rely on the column description or the column's Chinese name?
A: The column description takes precedence.
Can multiple workspaces reuse the same GBI instance?
A: Data is isolated between different workspaces, so they cannot be reused.
Does GBI support defining default query conditions?
A: This is not supported yet.