@nocobase/plugin-ai 2.2.0-alpha.1 → 2.2.0-alpha.10

package/dist/ai/docs/nocobase/data-sources/data-source-rest-api/index.md

@@ -1,35 +1,34 @@
 ---
-pkg: "@nocobase/plugin-data-source-rest-api"
+title: "REST API data source"
+description: "Connect REST API data and map RESTful resources to collections. Configure List, Get, Create, Update, and Destroy API mappings to support CRUD operations."
+keywords: "REST API data source,external API,API mapping,collection mapping,NocoBase"
 ---
 
-# REST API Data Source
+# REST API data source
+
+<PluginInfo commercial="true" name="data-source-rest-api"></PluginInfo>
 
 ## Introduction
 
-This plugin allows you to integrate data from REST API sources seamlessly.
+Use this data source to connect data provided by REST APIs.
 
 ## Installation
 
-This is a commercial plugin. For detailed activation instructions, please refer to: [Commercial Plugin Activation Guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide)
-
-
-## Adding a REST API Source
+This is a commercial plugin. For activation instructions, see the [Commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide).
 
-After activating the plugin, you can add a REST API source by selecting it from the Add new dropdown menu in the data source management section.
+## Add a REST API source
 
+After activating the plugin, choose **REST API** from the **Add new** menu in Data source management.
 
-![20240721171420](https://static-docs.nocobase.com/20240721171420.png)
-
+![Choose the REST API data source](https://static-docs.nocobase.com/20240721171420.png)
 
 Configure the REST API source.
 
+![Configure the REST API source](https://static-docs.nocobase.com/20240721171507.png)
 
-![20240721171507](https://static-docs.nocobase.com/20240721171507.png)
-
-
-## Adding a Collection
+## Add a collection
 
-In NocoBase, a RESTful resource is mapped to a Collection, such as a Users resource.
+A RESTful resource maps to a NocoBase collection. For example, consider a Users resource:
 
 ```bash
 GET /users
@@ -39,7 +38,7 @@ PUT /users/1
 DELETE /users/1
 ```
 
-These API endpoints are mapped in NocoBase as follows:
+It maps to the following NocoBase API configuration:
 
 ```bash
 GET /users:list
@@ -49,235 +48,198 @@ POST /users:update?filterByTk=1
 POST /users:destroy?filterByTk=1
 ```
 
-For a comprehensive guide on NocoBase API design specifications, refer to the API documentation.
+For the complete NocoBase API design specification, see the API documentation.
 
+![API documentation entry](https://static-docs.nocobase.com/20240716213344.png)
 
-![20240716213344](https://static-docs.nocobase.com/20240716213344.png)
+See the **NocoBase API - Core** section.
 
+![NocoBase API - Core](https://static-docs.nocobase.com/20240716213258.png)
 
-Check the "NocoBase API - Core" chapter for detailed information.
-
-
-![20240716213258](https://static-docs.nocobase.com/20240716213258.png)
-
-
-The Collection configuration for a REST API data source includes the following:
+The REST API data-source collection is configured as follows.
 
 ### List
 
-Map the interface for viewing a list of resources.
-
-
-![20251201162457](https://static-docs.nocobase.com/20251201162457.png)
+Configure the API mapping for retrieving a resource list.
 
+![Configure the List API](https://static-docs.nocobase.com/20251201162457.png)
 
 ### Get
 
-Map the interface for viewing resource details.
-
-
-![20251201162744](https://static-docs.nocobase.com/20251201162744.png)
+Configure the API mapping for retrieving resource details.
 
+![Configure the Get API](https://static-docs.nocobase.com/20251201162744.png)
 
 ### Create
 
-Map the interface for creating a resource.
-
-
-![20251201163000](https://static-docs.nocobase.com/20251201163000.png)
+Configure the API mapping for creating a resource.
 
+![Configure the Create API](https://static-docs.nocobase.com/20251201163000.png)
 
 ### Update
 
-Map the interface for updating a resource.
-
-
-![20251201163058](https://static-docs.nocobase.com/20251201163058.png)
+Configure the API mapping for updating a resource.
 
+![Configure the Update API](https://static-docs.nocobase.com/20251201163058.png)
 
 ### Destroy
 
-Map the interface for deleting a resource.
-
-
-![20251201163204](https://static-docs.nocobase.com/20251201163204.png)
+Configure the API mapping for deleting a resource.
 
+![Configure the Destroy API](https://static-docs.nocobase.com/20251201163204.png)
 
-Both the List and Get interfaces are required to be configured.
+List and Get are required API mappings.
 
-## Debugging the API
+## Debug APIs
 
 ### Request parameter integration
 
-Example: Configure pagination parameters for the List API. If the third-party API does not support pagination natively, NocoBase will paginate based on the retrieved list data.
-
-
-![20251201163500](https://static-docs.nocobase.com/20251201163500.png)
+For example, configure pagination parameters for the List API. If the third-party API itself does not support pagination, NocoBase paginates the returned list data.
 
+![Configure List pagination parameters](https://static-docs.nocobase.com/20251201163500.png)
 
-Please note that only variables added in the interface will take effect.
+Only variables added to the API take effect.
 
-| Third-party API params name | NocoBase params             |
-| --------------------------- | --------------------------- |
-| page                        | {{request.params.page}}     |
-| limit                       | {{request.params.pageSize}} |
+| Third-party API parameter | NocoBase parameter |
+| --- | --- |
+| page | {{request.params.page}} |
+| limit | {{request.params.pageSize}} |
 
-You can click Try it out to debug and view the response.
+Click **Try it out** to debug the API and inspect the response.
 
-
-![20251201163635](https://static-docs.nocobase.com/20251201163635.png)
+![Debug an API request](https://static-docs.nocobase.com/20251201163635.png)
 
 <video width="100%" height="440" controls>
       <source src="https://static-docs.nocobase.com/20241121211034.mp4" type="video/mp4">
 </video>
 
-### Response format transformation
-
-The response format of the third-party API may not be in NocoBase standard, and it needs to be transformed before it can be correctly displayed on the front end.
-
+### Response format conversion
 
-![20251201164529](https://static-docs.nocobase.com/20251201164529.png)
+The response format of a third-party API might not match the NocoBase standard. Convert it before it can be displayed correctly in the client.
 
-Adjust the conversion rules based on the response format of the third-party API to ensure the output conforms to the NocoBase standard.
+![Configure response conversion](https://static-docs.nocobase.com/20251201164529.png)
 
+Adjust the conversion rules according to the third-party API response so that it matches the NocoBase output standard.
 
-![20251201164629](https://static-docs.nocobase.com/20251201164629.png)
+![Response conversion rules](https://static-docs.nocobase.com/20251201164629.png)
 
+Debugging flow.
 
-Debugging process description
+![Response conversion debugging flow](https://static-docs.nocobase.com/20240717110051.png)
 
+### Error information conversion
 
-![20250418085020](https://static-docs.nocobase.com/20250418085020.png)
+When a third-party API returns an error, its error response might not match the NocoBase standard. Convert it before the client can display it correctly.
 
-### Extract error message
+![Configure error conversion](https://static-docs.nocobase.com/20251201170545.png)
 
-When a third-party API throws an exception, its response format may not follow NocoBase’s standard. In such cases, the error message needs to be transformed before it can be correctly displayed on the frontend.
+When error conversion is not configured, the error is converted by default to an error message that includes the HTTP status code.
 
-![20251201170545](https://static-docs.nocobase.com/20251201170545.png)
+![Default error conversion](https://static-docs.nocobase.com/20251201170732.png)
 
-If no error message transformer is configured, NocoBase will apply the default transformation, converting the error into a message that contains the HTTP status code.
+After configuring error conversion to match the NocoBase output standard, the client can display third-party API error information correctly.
 
-![20251201170732](https://static-docs.nocobase.com/20251201170732.png)
-
-After configuring an error message transformer to match NocoBase’s output standard, the frontend will be able to properly display the exception messages returned by the third-party API.
-
-![20251201170946](https://static-docs.nocobase.com/20251201170946.png)
-![20251201171113](https://static-docs.nocobase.com/20251201171113.png)
+![Error conversion rules](https://static-docs.nocobase.com/20251201170946.png)
+![Converted third-party API error](https://static-docs.nocobase.com/20251201171113.png)
 
 ## Variables
 
-The REST API data source supports three types of variables for API integration:
-
-- Custom data source variables
-- NocoBase request variables
-- Third-party response variables
-
-### Custom Data Source Variables
-
-
-![20240716221937](https://static-docs.nocobase.com/20240716221937.png)
-
-
+The REST API data source provides three variable categories for API integration:
 
-![20240716221858](https://static-docs.nocobase.com/20240716221858.png)
+- Data-source custom variables
+- NocoBase requests
+- Third-party responses
 
+### Data-source custom variables
 
-### NocoBase Request
+![Data-source custom variables](https://static-docs.nocobase.com/20240716221937.png)
 
-- Params: URL query parameters (Search Params), which vary depending on the interface.
-- Headers: Custom request headers, primarily providing specific X- information from NocoBase.
-- Body: The request body.
-- Token: The API token for the current NocoBase request.
+![Configure a data-source custom variable](https://static-docs.nocobase.com/20240716221858.png)
 
+### NocoBase requests
 
-![20251201164833](https://static-docs.nocobase.com/20251201164833.png)
+- Params: URL query parameters (Search Params). The available Params differ between APIs
+- Headers: request headers, primarily providing NocoBase custom `X-` information
+- Body: the request body
+- Token: the API token of the current NocoBase request
 
-### Third-Party Responses
+![NocoBase request variables](https://static-docs.nocobase.com/20251201164833.png)
 
-Currently, only the response body is available.
+### Third-party responses
 
+Currently, only the response Body is available.
 
-![20251201164915](https://static-docs.nocobase.com/20251201164915.png)
+![Third-party response variables](https://static-docs.nocobase.com/20251201164915.png)
 
-
-Below are the variables available for each interface:
+The available variables for each API integration are as follows.
 
 ### List
 
-| Parameter               | Description                                                |
-| ----------------------- | ---------------------------------------------------------- |
-| request.params.page     | Current page                                               |
-| request.params.pageSize | Number of items per page                                   |
-| request.params.filter   | Filter criteria (must meet NocoBase Filter format)         |
-| request.params.sort     | Sorting criteria (must meet NocoBase Sort format)          |
-| request.params.appends  | Fields to load on demand, typically for association fields |
-| request.params.fields   | Fields to include (whitelist)                              |
-| request.params.except   | Fields to exclude (blacklist)                              |
+| Parameter | Description |
+| --- | --- |
+| request.params.page | Current page number |
+| request.params.pageSize | Number of records per page |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
+| request.params.sort | Sorting rules. They must use the NocoBase Sort format. |
+| request.params.appends | Fields loaded on demand, typically for loading relationship fields on demand |
+| request.params.fields | Fields that the API returns, as an allowlist |
+| request.params.except | Fields to exclude, as a denylist |
 
 ### Get
 
-| Parameter                 | Description                                                |
-| ------------------------- | ---------------------------------------------------------- |
-| request.params.filterByTk | Required, typically the current record ID                  |
-| request.params.filter     | Filter criteria (must meet NocoBase Filter format)         |
-| request.params.appends    | Fields to load on demand, typically for association fields |
-| request.params.fields     | Fields to include (whitelist)                              |
-| request.params.except     | Fields to exclude (blacklist)                              |
+| Parameter | Description |
+| --- | --- |
+| request.params.filterByTk | Required. Usually the ID of the current record |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
+| request.params.appends | Fields loaded on demand, typically for loading relationship fields on demand |
+| request.params.fields | Fields that the API returns, as an allowlist |
+| request.params.except | Fields to exclude, as a denylist |
 
 ### Create
 
-| Parameter                | Description               |
-| ------------------------ | ------------------------- |
-| request.params.whiteList | Whitelist                 |
-| request.params.blacklist | Blacklist                 |
-| request.body             | Initial data for creation |
+| Parameter | Description |
+| --- | --- |
+| request.params.whiteList | Allowlist |
+| request.params.blacklist | Denylist |
+| request.body | Initial data for creating the record |
 
 ### Update
 
-| Parameter                 | Description                                        |
-| ------------------------- | -------------------------------------------------- |
-| request.params.filterByTk | Required, typically the current record ID          |
-| request.params.filter     | Filter criteria (must meet NocoBase Filter format) |
-| request.params.whiteList  | Whitelist                                          |
-| request.params.blacklist  | Blacklist                                          |
-| request.body              | Data for update                                    |
+| Parameter | Description |
+| --- | --- |
+| request.params.filterByTk | Required. Usually the ID of the current record |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
+| request.params.whiteList | Allowlist |
+| request.params.blacklist | Denylist |
+| request.body | Data to update |
 
 ### Destroy
 
-| Parameter                 | Description                                        |
-| ------------------------- | -------------------------------------------------- |
-| request.params.filterByTk | Required, typically the current record ID          |
-| request.params.filter     | Filter criteria (must meet NocoBase Filter format) |
-
-## Field Configuration
-
-Field metadata (Fields) is extracted from the CRUD interface data of the adapted resource to serve as the fields of the collection.
+| Parameter | Description |
+| --- | --- |
+| request.params.filterByTk | Required. Usually the ID of the current record |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
 
+## Configure fields
 
-![20250418085048](https://static-docs.nocobase.com/20250418085048.png)
+Extract field metadata (Fields) from data returned by the adapted resource CRUD APIs and use it as the fields of the collection.
 
+![Extract collection fields](https://static-docs.nocobase.com/20240716223636.png)
 
 Extract field metadata.
 
-
-![20251201165133](https://static-docs.nocobase.com/20251201165133.png)
-
+![Extract field metadata](https://static-docs.nocobase.com/20251201165133.png)
 
 Fields and preview.
 
+![Fields and preview](https://static-docs.nocobase.com/20240716224403.png)
 
-![20240716224403](https://static-docs.nocobase.com/20240716224403.png)
-
-
-Edit fields (similar to other data sources).
-
-
-![20240716224704](https://static-docs.nocobase.com/20240716224704.png)
-
+Edit fields in the same way as for other data sources.
 
-## Adding REST API Data Source Blocks
+![Edit REST API fields](https://static-docs.nocobase.com/20240716224704.png)
 
-Once the collection is configured, you can add blocks to the interface.
+## Add REST API data-source blocks
 
+After configuring the collection, you can add blocks to pages.
 
-![20240716225120](https://static-docs.nocobase.com/20240716225120.png)
+![Add a REST API data-source block](https://static-docs.nocobase.com/20240716225120.png)

package/dist/ai/docs/nocobase/data-sources/external/clickhouse.md

@@ -0,0 +1,124 @@
+---
+pkg: "@nocobase/plugin-data-source-external-clickhouse"
+title: "External data source - ClickHouse"
+description: "Learn how to connect ClickHouse as an external database in NocoBase, including the MySQL-compatible port, SSL, collection scope, read-only analytics use cases, and field mapping."
+keywords: "external data source,ClickHouse,external database,MySQL-compatible port,reporting,field mapping,NocoBase"
+---
+
+# ClickHouse
+
+## Introduction
+
+ClickHouse can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from ClickHouse and makes them available as collections in the external data source.
+
+ClickHouse is better suited to analytical queries, log analysis, metric aggregation, and reporting. Unlike transactional databases, it is not suitable as a data source for frequently creating, editing, and deleting business records in NocoBase.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | ClickHouse >= 20.2. |
+| Commercial editions | Available in the Enterprise edition. |
+| Plugin | `@nocobase/plugin-data-source-external-clickhouse`. |
+| Connection method | Connect through the ClickHouse MySQL-compatible port. |
+| Recommended use | Primarily for viewing, filtering, aggregation, and reporting. |
+
+External ClickHouse is suitable when you need to:
+
+- Connect analytical data such as logs, event tracking data, metrics, or risk-control data
+- Build operational dashboards, reports, or query pages in NocoBase
+- Provide business users with a read-only query entry point instead of direct database-client access
+- Apply permissions and visual presentation to existing ClickHouse data
+
+:::warning Note
+
+Use ClickHouse in NocoBase as a read-only analytical data source. Do not use it as the write data source for regular business collections, and do not configure create, edit, or delete actions in pages.
+
+:::
+
+## Plugin installation
+
+This is a commercial plugin. For activation instructions, see the [Commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide).
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select ClickHouse, and then enter the connection details.
+
+![Add an external ClickHouse data source](https://static-docs.nocobase.com/20260709211117.png)
+
+Common connection settings are as follows:
+
+| Setting | Description |
+| --- | --- |
+| Data source name | The internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after the data source is created. |
+| Data source display name | The name displayed in the interface. Use a name that business users can recognize, such as `ClickHouse log database` or `Metrics database`. |
+| Host / Port | The ClickHouse host address and MySQL-compatible port. Do not enter the HTTP port or native TCP port. |
+| Database | The name of the ClickHouse database to connect to. |
+| Username / Password | The account credentials used to connect to ClickHouse. NocoBase can read only objects that this account is allowed to access; it does not grant access to, or read, objects private to other accounts. |
+| Table prefix | A table-name prefix. When configured, NocoBase reads only tables that match the prefix, and removes the prefix from the generated NocoBase collection names. |
+| Use SSL | Whether to enable SSL. This is usually required when connecting to ClickHouse Cloud or a secure connection environment. |
+| Enabled the data source | Whether to enable the data source. When disabled, its configuration is retained, but blocks, permissions, workflows, and APIs can no longer read its data. |
+
+:::tip Tip
+
+The ClickHouse plugin connects through the MySQL-compatible protocol. Before configuring the source, make sure the ClickHouse service has enabled its MySQL-compatible port and that the network, firewall, and account permissions allow NocoBase to connect.
+
+:::
+
+## Connection scope
+
+ClickHouse pages do not provide a **Collections** selection list. The connection scope is primarily controlled by `Database`, connection-account permissions, and `Table prefix`.
+
+When ClickHouse contains many tables, prepare a dedicated database, account, or table-name prefix for NocoBase. Expose only the tables that the current application needs to view and aggregate.
+
+:::warning Note
+
+An external data source can connect up to 500 tables or views at a time. When ClickHouse contains many objects, narrow the scope through the database, account permissions, or `Table prefix` first.
+
+:::
+
+## Synchronize and configure fields
+
+The external ClickHouse schema is maintained in the database. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the ClickHouse schema changes, run **Sync from database** from the data source to read collection and field metadata again. Synchronization updates the collections, fields, primary keys, unique keys, and field-type mapping metadata stored in NocoBase. It does not delete actual ClickHouse tables or data.
+
+After fields are synchronized, you can configure their titles, Field type, and Field interface in NocoBase. NocoBase relationship fields are also stored as relationship metadata in NocoBase and do not automatically add actual foreign-key columns to ClickHouse tables.
+
+## Field type mapping
+
+NocoBase converts ClickHouse types into a MySQL-compatible representation before mapping them to appropriate Field types and Field interfaces. You can adjust the display interface in field settings.
+
+| ClickHouse type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `Int8`, `Int16`, `Int32`, `UInt8`, `UInt16`, `UInt32` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `Int64`, `UInt64` | `bigInt`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `Float32`, `Float64` | `float` | Number, Percent. |
+| `Decimal` | `decimal`, `double` | Number, Percent, Currency. |
+| `String`, `FixedString` | `text`, `string` | Input, Textarea, Markdown, URL. |
+| `Date`, `Date32` | `dateOnly` | Date. |
+| `DateTime`, `DateTime64` | `datetimeNoTz`, `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `UUID` | `string`, `uuid` | Input, UUID. |
+| `Bool`, `Boolean` | `integer`, `boolean`, `sort` | Checkbox, Switch, Integer. |
+| `Array` | `json`, `array` | JSON. |
+| `Nullable(...)` | Mapped according to the inner field type | Depends on the inner field type. |
+| `LowCardinality(...)` | Mapped according to the inner field type | Depends on the inner field type. |
+
+:::warning Note
+
+Some analytical or nested ClickHouse types cannot be mapped directly to regular business fields. For unsupported types, create a view or query table suitable for display in ClickHouse first, and then connect it to NocoBase.
+
+:::
+
+## Primary key and Record unique key
+
+ClickHouse sorting keys and partition keys are not necessarily business-unique identifiers. Collections used for block display should still have a field that can uniquely identify each record.
+
+For tables or views without a unique field, configure **Record unique key** manually in the collection settings. Without a usable unique identifier, blocks might not display record details correctly and are not suitable for edit or delete actions.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709211300.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709211239.png)
+
+## Related links
+
+- [External databases](./index.md) - General external-database configuration and management.
+- [Data source management](../data-source-manager/index.md) - Data-source entry points and management.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field types and field mapping.

package/dist/ai/docs/nocobase/data-sources/external/doris.md

@@ -0,0 +1,130 @@
+---
+pkg: "@nocobase/plugin-data-source-external-doris"
+title: "External data source - Doris"
+description: "Learn how to connect Doris as an external database in NocoBase, including the MySQL-compatible port, FE query_port, collection scope, read-only analytics use cases, and field mapping."
+keywords: "external data source,Doris,external database,MySQL-compatible port,FE query_port,reporting,field mapping,NocoBase"
+---
+
+# Doris
+
+## Introduction
+
+Doris can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from Doris and makes them available as collections in the external data source.
+
+Doris is better suited to analytical queries, wide-table details, metric aggregation, and reporting. Unlike transactional databases, it is not suitable as a data source for frequently creating, editing, and deleting business records in NocoBase.
+
+| Setting | Description |
+| --- | --- |
+| Supported version | Doris >= 2.1.0. |
+| Commercial editions | Available in the Enterprise edition. |
+| Plugin | `@nocobase/plugin-data-source-external-doris`. |
+| Connection method | Connect through the Doris MySQL-compatible port, the FE `query_port`. |
+| Recommended use | Primarily for viewing, filtering, aggregation, and reporting. |
+
+External Doris is suitable when you need to:
+
+- Connect data-warehouse detail tables, aggregate tables, wide tables, or metric tables
+- Build operational dashboards, reports, or query pages in NocoBase
+- Provide business users with a read-only query entry point instead of direct database-client access
+- Apply permissions and visual presentation to existing Doris data
+
+:::warning Note
+
+Use Doris in NocoBase as a read-only analytical data source. Do not use it as the write data source for regular business collections, and do not configure create, edit, or delete actions in pages.
+
+:::
+
+## Plugin installation
+
+This is a commercial plugin. For activation instructions, see the [Commercial plugin activation guide](https://www.nocobase.com/en/blog/nocobase-commercial-license-activation-guide).
+
+## Add a data source
+
+In **Data source management**, click **Add new**, select Doris, and then enter the connection details.
+
+![Add an external Doris data source](https://static-docs.nocobase.com/20260709211333.png)
+
+Common connection settings are as follows:
+
+| Setting | Description |
+| --- | --- |
+| Data source name | The internal identifier used by blocks, permissions, workflows, and APIs. It cannot be changed after the data source is created. |
+| Data source display name | The name displayed in the interface. Use a name that business users can recognize, such as `Doris data warehouse` or `Metrics database`. |
+| Host / Port | The Doris FE address and MySQL-compatible port, which is `query_port`. Do not enter the HTTP port. |
+| Database | The name of the Doris database to connect to. |
+| Username / Password | The account credentials used to connect to Doris. NocoBase can read only objects that this account is allowed to access; it does not grant access to, or read, objects private to other accounts. |
+| Table prefix | A table-name prefix. When configured, NocoBase reads only tables that match the prefix, and removes the prefix from the generated NocoBase collection names. |
+| Enabled the data source | Whether to enable the data source. When disabled, its configuration is retained, but blocks, permissions, workflows, and APIs can no longer read its data. |
+
+:::tip Tip
+
+The Doris plugin connects through the MySQL-compatible protocol. Before configuring the source, make sure the Doris FE `query_port` is reachable from NocoBase and that the account can read metadata for the target database, tables, and columns.
+
+:::
+
+## Connection scope
+
+Doris pages do not provide a **Collections** selection list. The connection scope is primarily controlled by `Database`, connection-account permissions, and `Table prefix`.
+
+When Doris contains many tables, prepare a dedicated database, account, or table-name prefix for NocoBase. Expose only the tables that the current application needs to view and aggregate.
+
+:::warning Note
+
+An external data source can connect up to 500 tables or views at a time. When Doris contains many objects, narrow the scope through the database, account permissions, or `Table prefix` first.
+
+:::
+
+## Synchronize and configure fields
+
+The external Doris schema is maintained in the database. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the Doris schema changes, run **Sync from database** from the data source to read collection and field metadata again. Synchronization updates the collections, fields, primary keys, unique keys, and field-type mapping metadata stored in NocoBase. It does not delete actual Doris tables or data.
+
+After fields are synchronized, you can configure their titles, Field type, and Field interface in NocoBase. NocoBase relationship fields are also stored as relationship metadata in NocoBase and do not automatically add actual foreign-key columns to Doris tables.
+
+## Field type mapping
+
+NocoBase maps Doris types to appropriate Field types and Field interfaces according to MySQL compatibility rules and Doris-specific types. You can adjust the display interface in field settings.
+
+| Doris type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `TINYINT`, `SMALLINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT`, `INTEGER` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `LARGEINT` | `bigInt` | Integer. |
+| `FLOAT` | `float`, `sort` | Number, Percent, Sort. |
+| `DOUBLE` | `double`, `sort` | Number, Percent, Sort. |
+| `DECIMAL`, `DECIMALV3` | `decimal` | Number, Percent, Currency. |
+| `BOOLEAN` | `boolean` | Checkbox, Switch. |
+| `CHAR` | `string` | Input, Email, Phone. |
+| `VARCHAR` | `string`, `uuid`, `nanoid`, `encryption` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT`, `STRING` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE`, `DATEV2` | `date` | Date. |
+| `DATETIME`, `DATETIMEV2` | `datetime` | Date, Time, Created at, Updated at. |
+| `JSON`, `JSONB` | `json` | JSON. |
+| `HLL`, `BITMAP`, `QUANTILE_STATE`, `AGG_STATE` | `json` | JSON. |
+| `VARIANT`, `ARRAY`, `MAP`, `STRUCT` | `json` | JSON. |
+| `IPV4`, `IPV6` | `string` | Input. |
+
+`VARIANT` is a dynamic type available in Apache Doris 2.1.0 and later. When using a Doris version earlier than 2.1.0, you cannot connect fields of this type.
+
+:::warning Note
+
+Aggregate-state, semi-structured, and complex types in Doris are better suited to display or debugging and might not be appropriate for form input. For complex types, prepare a view or detail table better suited to business viewing in Doris before connecting it to NocoBase.
+
+:::
+
+## Primary key and Record unique key
+
+Doris data and key models are not necessarily business-unique identifiers. Collections used for block display should still have a field that can uniquely identify each record.
+
+For tables or views without a unique field, configure **Record unique key** manually in the collection settings. Without a usable unique identifier, blocks might not display record details correctly and are not suitable for edit or delete actions.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709211439.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709211454.png)
+
+## Related links
+
+- [External databases](./index.md) - General external-database configuration and management.
+- [Data source management](../data-source-manager/index.md) - Data-source entry points and management.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field types and field mapping.