Create a Lark Bitable data source-Quick BI(Quick BI)-阿里云帮助中心

Using a Lark Bitable as a data source lets you import its data into Quick BI for visual analysis and business intelligence. This approach combines the data management strengths of Lark Bitable with the powerful analytics of Quick BI, enabling efficient collaboration and real-time insights. This article describes how to create a Lark Bitable data source.

Prerequisites

You have created a custom application in Lark and obtained the required authorization credentials. For more information, see Obtain application authorization information.
You have obtained the sharing link for the Lark Bitable that you want to connect to Quick BI. For more information, see Obtain the Bitable link.

Limitations

Only the Quick BI Professional Edition supports creating Lark Bitable data sources.
Lark Bitable supports various field types. For information about how Lark Bitable field types are mapped to Quick BI field types, see Lark Bitable parsing rules.
Lark Bitable data sources have the following functional limitations:
- For a dataset created from a Lark Bitable data source:
  - Custom SQL, extract acceleration, association modeling, and placeholders are not supported.
  - You cannot create trend analysis tables or multi-dimensional analysis tables based on the dataset.
- The monitoring and alerts and self-service data retrieval features are not supported.
Due to limitations on the Lark side, starting October 31, 2024, the free basic version of Lark will have a cumulative API call limit of 10,000 calls per month. If this limit is insufficient for your needs, you can upgrade to another Lark edition to increase the call limit. For more information, see the Lark documentation about adjustments to custom application API call limits.

Procedure

Connecting a Lark Bitable to Quick BI involves three main steps: obtaining authorization information for your Lark application, getting the sharing link for your Lark Bitable, and creating the Lark Bitable data source in Quick BI.

If your organization has already configured Lark API authorization in Organization Management > Office Software Integration, Quick BI automatically retrieves the application information when you create the data source. Ensure that the app installed in your Lark organization is the latest version. You can skip to Step 2: Obtain the Bitable link.
If your organization has not configured Lark API authorization in Organization Management > Office Software Integration, you can either contact your organization administrator to set it up or add a custom application to connect your Lark Bitable data. Start with Step 1: Obtain application authorization information.

Step 1: Obtain application authorization information

Create a custom application in the Lark Open Platform to obtain its authorization credentials. Quick BI uses these credentials to authenticate the data source connection.

Log on to the Lark Open Platform, click Create Custom App, fill in the application details in the dialog box, and then click Create.
Quick BI reads Lark Bitable data through APIs. Therefore, you must apply for API permissions for your application. In the developer console for your application, go to Permission Management in the left-side navigation pane. On the API Permissions tab, configure the required permissions for your application.
Select the following API permissions and click Enable.
- View, comment on, edit, and manage all files in Docs
- View, comment on, edit, and manage Bitable
- View, comment on, and export Bitable
- Get app information
In the confirmation dialog box, click Confirm and create app version.
On the Version Management and Release page, click Create a Version.
Enter the version details, and then click Save > Request Online Release to publish the application.
In the application's Developer Console, go to the Credentials and Basic Information page. Copy and save the App ID and App Secret for your application.

Step 2: Obtain the Bitable link

Log on to Lark Docs, find the Bitable that you want to connect to Quick BI, and then copy its sharing link.

In your list of documents in Lark Docs, find the target Lark Bitable that you want to connect to Quick BI. In the actions column for the Bitable, click Share.
Note
Before connecting a Lark Bitable to Quick BI, ensure that it meets the following requirements:
- A single sheet cannot exceed 100 columns or 10,000 rows.
- Sheets containing Attachment, Association, or Lookup field types cannot be imported. For a list of supported field types, see the Field mapping details table in Lark Bitable parsing rules.
- Calculated formulas from the sheet are not inherited. Only the resulting values are imported.
In the Share doc dialog box, configure the sharing scope for the link.
Note
If you set the sharing scope to Only collaborators can access with this link, you must add your custom application to the App list for the Bitable.
Click Copy link and save the sharing link for the Bitable.

Step 3: Create the data source

After obtaining the Lark authorization credentials and the Bitable sharing link, enter them on the New Data Source page in Quick BI to connect your Lark Bitable.

Log on to the Quick BI Workbench. Go to Data Sources and click New Data Source in the upper-right corner.
On the New Data Source page, click Application Service > Lark Bitable.

On the configuration page, enter the authorization credentials and the Bitable link that you obtained in Step 1 and Step 2.

If your organization has already configured Lark API authorization in Organization Management > Office Software Integration, Quick BI automatically retrieves the authorized application information. Ensure the application has permission to call the relevant Bitable APIs in Lark.

If your organization has not configured Lark API authorization in Organization Management> Office Software Integration, you must enter the authorization credentials for the custom application that you created in Step 1.

Parameter	Description
AppKey	Enter the unique identifier for your Lark custom application. This corresponds to the App ID on the Credentials and Basic Information page in the Lark Developer Console.
AppSecret	Enter the secret key for your Lark custom application. The Lark platform automatically generates the key when you create the application. This corresponds to the App Secret on the Credentials and Basic Information page in the Lark Developer Console.
Lark Base Link	Enter the sharing link for your Lark Bitable. This is the link you copied from the Lark document sharing page.

Click Test Connection. After the connection is successful, information about the authorized application appears on the page.

Click Confirm and Connect to go to the Data Preview page. Here, you can view the following information and perform related operations.

Area	Action	Description
Area ① Display name of the Bitable in Quick BI	Rename the display name	When you connect the Bitable, Quick BI automatically detects its name and uses it as the display name. You can modify this name as needed. Note The display name cannot contain special characters or leading/trailing spaces.
Area ② Sharing link of the Bitable	View the source document	Click the icon next to the link to open and view the source document in a new tab.
Area ③ Number and titles of sheets in the Bitable	Switch sheets	Click a sheet tab to preview its data. The data content in Area ④ updates accordingly.
Area ③ Number and titles of sheets in the Bitable	Rename a sheet	Double-click a sheet name to rename it based on your business needs. By default, Quick BI reads the name from the sheet in Lark. Note The sheet name cannot contain special characters or leading/trailing spaces.
Area ④ Data content of the Bitable	Data Preview	On the Data Preview tab, preview the data and perform the following operations. Modify field name: Click the field name input box to modify the name. Modify field type: Click the field type icon and select a new type from the dropdown list. Supported types include Text, Numeric, and Datetime. Note Unsupported field types such as Attachment, Association, or Lookup are removed during import. Calculated formulas from the source document in Lark are not inherited. Only the resulting values are imported. When you import a Lark Bitable, Quick BI automatically converts the field types from the source document to corresponding data types. For more information about the mapping, see the Field mapping details table in the Limitations section.
	Field Details	After you connect the Bitable, its data is stored in a database table format. The database field name and field type correspond to the field names and types in the generated database table, while the field name corresponds to the field names in the original Lark Bitable. You can rename fields and change field types as needed. To remove a field, click the icon. Note Unsupported field types such as Attachment, Association, or Lookup are removed during import. Calculated formulas from the source document in Lark are not inherited. Only the resulting values are imported. When you import a Lark Bitable, Quick BI automatically converts the field types from the source document to corresponding data types. For more information about the mapping, see the Field mapping details table in the Limitations section.
	Auto Parse	In Lark Bitable, a single cell can contain more than just simple text or numbers. It may include rich content like cards or tag lists to display multi-dimensional information. When Quick BI extracts data via an API, Lark often transmits fields with complex information in JSON format. To preserve the data hierarchy and semantic information, Quick BI must parse this JSON data into standard fields for analysis. At this point, you can enable the automatic parsing feature to use the Lark Bitable parsing rules provided by Quick BI and automatically parse JSON data into corresponding field types. You can also customize parsing rules as needed by creating a calculated field. By default, Auto Parse is enabled for the data source. You can toggle it by clicking the switch icon (). Note When you create a calculated field in a dataset from a Lark Bitable data source, only built-in functions are supported.
	Set scheduled synchronization	To automatically update your data source with the latest business data every day, enable the Scheduled Synchronization option. In the Data Scheduled Synchronization dialog box, set the time of day for the data synchronization. Note Each synchronization performs a full overwrite of the existing data. The limit for a single sheet is 10,000 rows and 100 columns. This setting applies only to the current sheet. If you need to schedule synchronization for multiple sheets, you must configure each sheet individually.

After you finish the configuration, click Confirm and Connect to create the Lark Bitable data source.
Return to the Data Sources page. In the list of data sources, find the Lark Bitable data source you just created, and click the icon in the actions column for each sheet to sync data.
(Optional) On the Data Sources page, you can view and manage your created Lark Bitable data sources and their sheets. The following operations are supported.
- Preview Data Table: In the Name column, click the name of a data table to view its content on the Data Preview page.
- Set scheduled synchronization: Click the Scheduled Synchronization switch to enable or disable the feature. If it is enabled, you can click the icon to modify the synchronization time.
- Create Dataset: Click the icon to go to the dataset creation page and create a dataset based on the current sheet. For more information, see Create a dataset.
  Note
  You can create a dataset from a sheet only after the sheet is successfully synchronized.
- Sync Data: Click the icon to manually trigger a synchronization task.
- View Sync Records: Click the icon. In the View Logs dialog box, you can view the update history for the current sheet. The logs include the update time, status, duration, and log information. You can also query logs for a specific time range.

Step 4: Edit the data source

After you connect a Lark Bitable to the Quick BI platform, you can edit its authorization credentials, sharing link, and display name.

In the Lark Bitable list, find the target data source and click Edit.

On the Select Data page for the Lark Bitable, modify the authorization credentials for the custom application.

Parameter	Description
Authorized App	Click the icon in the Authorized App dropdown list. The input fields for AppKey and AppSecret appear. Enter the AppKey and AppSecret for the new application.
Lark Base Link	Enter the sharing link for the new Bitable.

Click Test Connection. After the connection is verified, click Confirm and Connect to go to the Data Preview page. Here you can edit the Bitable's display name, scheduled synchronization settings, field names, and data types as needed. The procedure is the same as in step 5 of Create the data source.
After you finish editing, click Confirm and Connect.

Lark Bitable parsing rules

To display multi-dimensional information, a Lark Bitable may contain data with rich formatting, such as cards and tag lists. When Quick BI retrieves data from the Bitable via API, fields with styled information are transmitted in JSON format. In auto-parse mode, Quick BI uses a unified set of parsing rules to automatically convert this JSON data into standard fields that can be used for data modeling, reporting, and other analysis tasks.

The following table lists the Lark Bitable field types that Quick BI can parse and the parsing strategies used.

Note

Quick BI does not support importing the following field types: One-way Association, Two-way Association, Lookup, and Attachment.

Lark Bitable field	Lark Bitable field type	Quick BI field type	Parsing strategy
Number, Progress, Currency, or Rating	string	Numeric	/
Single select	string	Text	/
Multiple select	array<string>	Text	Converted to string
Date	number	Datetime	Converted to date
Checkbox	boolean	Text	/
User	list of object	Text	Parsed to name
Phone number	string	Text	/
Hyperlink	object	Text	Parsed to link
Formula	object	Text	/
Location	object	Text	Parsed to full_address
Group chat	list of object	Text	Parsed to name
Created time	number	Datetime	Converted to date
Last modified time	number	Datetime	Converted to date
Created by	object	Text	Parsed to name
Last modified by	object	Text	Parsed to name
Auto-number	string	Numeric	/
Text	list of object	Text	Parsed to text
Barcode	list of object	Text	Parsed to text
Email	list of object	Text	Parsed to text

Next steps

After creating the data source, you can create a dataset and analyze your data.

To create a dataset from your Lark Bitable data source, see Create a dataset.
To add charts and analyze data, see Create a dashboard and Chart types overview.
To drill down and perform in-depth data analysis, see Step 3: Configure and display drill-down data.

FAQ

1. Common connection failures

If you encounter a connection failure when connecting to a Lark Bitable, check for the following issues:

Cause	Solution
The AppKey or AppSecret is incorrect.	Log on to the Lark Developer Console to get the correct AppKey and AppSecret for the application.
The required API permissions are not enabled for the custom application on the Permission Management page in the Lark Developer Console.	You must enable the following API permissions: View, comment on, edit, and manage all files in Docs View, comment on, edit, and manage Bitable View, comment on, and export Bitable Manage the app's own resources Get app information
If you set the sharing scope of the Lark Bitable link to Only collaborators can access with this link and did not add the corresponding custom application as a document application.	Add the corresponding custom application as a document application on the editing page of the Lark Bitable, as shown in the following figure.
When the sharing scope of the Lark Bitable link is set to Only collaborators can access with this link, you are unable to select the corresponding custom application as a document application on the document editing page.	To add a custom application to a document, you must include the current account in the Availability settings when creating the application version.
If you use the application selected by default, it may not be the latest version.	Go to the Lark Admin Console to update the application to the latest version.