@nocobase/plugin-ai 2.3.0-alpha.1 → 3.0.0-alpha.2

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

@@ -1,100 +1,130 @@
 ---
-pkg: "@nocobase/plugin-data-source-main"
+title: "Main database"
+description: "The NocoBase main database stores system and business data. It supports MySQL, PostgreSQL, MariaDB, KingbaseES, and OceanBase, table synchronization, and collection creation."
+keywords: "main database,MySQL,PostgreSQL,MariaDB,KingbaseES,OceanBase,table synchronization,NocoBase"
 ---
 
-# Main DataBase
+# Main database
 
 ## Introduction
 
-NocoBase's main database can be used to store both business data and the metadata of the application, including system table data and custom table data. The main database supports relational databases such as MySQL, PostgreSQL, etc. During the installation of the NocoBase application, the main database must be installed synchronously and cannot be deleted.
+The database configured when [deploying NocoBase](/ai/install-nocobase-app) stores NocoBase system tables and can also store application business tables.
 
-## Installation
+| Database | Supported version | Community | Standard | Professional | Enterprise |
+| --- | --- | --- | --- | --- | --- |
+| MySQL | >= 8.0.17 | Yes | Yes | Yes | Yes |
+| PostgreSQL | >= 10 | Yes | Yes | Yes | Yes |
+| MariaDB | >= 10.9 | Yes | Yes | Yes | Yes |
+| KingbaseES | >= V9 | No | No | Yes | Yes |
+| OceanBase | >= 4.3 | No | No | No | Yes |
 
-This is a built-in plugin, no separate installation is required.
+:::tip Tip
 
-## Collection Management
+KingbaseES supports only PostgreSQL compatibility mode. OceanBase supports only MySQL compatibility mode.
 
-The main data source provides complete collection management functionality, allowing you to create new tables through NocoBase and sync existing table structures from the database.
+:::
 
-![20240322230134](https://static-docs.nocobase.com/20240322230134.png)
+## Plugin installation
 
-### Syncing Existing Tables from Database
+| Database | Plugin | Installation |
+| --- | --- | --- |
+| MySQL | None | Built in; no separate installation is required. |
+| PostgreSQL | None | Built in; no separate installation is required. |
+| MariaDB | None | Built in; no separate installation is required. |
+| KingbaseES | `@nocobase/plugin-data-source-kingbase` | Requires a commercial license and is enabled after installation. |
+| OceanBase | `@nocobase/plugin-data-source-oceanbase` | Requires a commercial license and is enabled after installation. |
 
-![nocobase_doc-2025-10-29-19-46-34](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-46-34.png)
+## Access the main data source
 
-An important feature of the main data source is the ability to sync tables that already exist in the database into NocoBase for management. This means:
+1. Open the **Data sources** menu.
+2. Select **Main** in the data-source list and click **Configure** to manage the main database.
 
-- **Protect Existing Investment**: If you already have numerous business tables in your database, there's no need to recreate them - you can sync and use them directly
-- **Flexible Integration**: Tables created through other tools (such as SQL scripts, database management tools, etc.) can be brought under NocoBase management
-- **Progressive Migration**: Support for gradually migrating existing systems to NocoBase, rather than all-at-once refactoring
+![Configure the main data source](https://static-docs.nocobase.com/configure_main_datasource.png)
 
-Through the "Load from Database" feature, you can:
-1. Browse all tables in the database
-2. Select the tables you need to sync
-3. Automatically identify table structures and field types
-4. Import them into NocoBase for management with one click
+## Main data-source management
 
-### Support for Multiple Collection Types
+The main database manages collections and fields. You can:
 
-![nocobase_doc-2025-10-29-19-47-14](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-47-14.png)
+- **Filter**: search collections managed by the NocoBase main database.
+- **Create collection**: add a business collection.
+- **Edit**: change business collection metadata.
+- **Delete**: delete a business collection.
+- **Sync from database**: synchronize the structure of an existing database table.
+- **Configure fields**: create, change, and delete collection fields.
+- **+**: create, edit, and delete collection categories from the collection tabs.
 
-NocoBase supports creating and managing various types of collections:
-- **General collection**: built-in commonly used system fields
-- **Inheritance collection**: allows creation of a parent table from which child tables can be derived. Child tables inherit the parent table's structure and can define their own columns
-- **Tree collection**: tree-structured table, currently only supports adjacency list design
-- **Calendar collection**: for creating calendar-related event tables
-- **File collection**: for managing file storage
-- **Expression collection**: for dynamic expression scenarios in workflows
-- **SQL Collection**: not an actual database table, but quickly presents SQL queries in a structured manner
-- **Database View collection**: connects to existing database views
-- **FDW collection**: allows the database system to directly access and query data in external data sources, based on FDW technology
+![Main data source management](https://static-docs.nocobase.com/main_datasource_management.png)
 
-### Supporting Classification Management of Collections
+### Synchronize existing tables from the database
 
-![20240322231520](https://static-docs.nocobase.com/20240322231520.png)
+![Synchronize existing tables](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-46-34.png)
 
-### Rich Field Types
+Synchronizing existing database tables lets you manage them in NocoBase without recreating them.
 
-![nocobase_doc-2025-10-29-19-48-51](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-48-51.png)
+- **Protect existing investment**: use existing business tables directly.
+- **Flexible integration**: bring in tables created by SQL scripts or database-management tools.
+- **Gradual migration**: migrate an existing system to NocoBase step by step rather than refactoring everything at once.
 
-#### Flexible Field Type Conversion
+With **Load from database**, you can:
 
-NocoBase supports flexible field type conversion based on the same database type.
+1. Browse all tables in the database.
+2. Select the tables to synchronize.
+3. Identify table structures and field types automatically.
+4. Import them into NocoBase for management.
 
-**Example: String Type Field Conversion Options**
+### Supported collection types
 
-When a database field is of String type, it can be converted to any of the following forms in NocoBase:
+![Collection types](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-47-14.png)
 
-- **Basic**: Single line text, Long text, Phone, Email, URL, Password, Color, Icon
-- **Choices**: Single select, Radio group
-- **Media**: Markdown, Markdown(Vditor), Rich Text, Attachment (URL)
-- **Date & Time**: Datetime (with time zone), Datetime (without time zone)
-- **Advanced**: Sequence, Collection selector, Encryption
+NocoBase supports creating and managing these collection types:
 
-This flexible conversion mechanism means:
-- **No Database Structure Modification Required**: The field's underlying storage type remains unchanged; only its representation in NocoBase changes
-- **Adapt to Business Changes**: As business needs evolve, you can quickly adjust field display and interaction methods
-- **Data Safety**: The conversion process does not affect the integrity of existing data
+- **General collection**: includes commonly used system fields.
+- **Inheritance collection**: derives child collections from a parent collection. Child collections inherit the parent structure and can define their own fields.
+- **Tree collection**: a hierarchical collection that currently supports the adjacency-list design.
+- **Calendar collection**: stores calendar-related event records.
+- **File collection**: manages file storage.
+- **SQL collection**: presents an SQL query result in a structured form; it is not a real database table.
+- **Database view collection**: connects an existing database view.
 
-### Flexible Field-Level Synchronization
+### Collection categories
 
-NocoBase not only syncs entire tables but also supports granular field-level sync management:
+![Collection categories](https://static-docs.nocobase.com/20240322231520.png)
 
-![nocobase_doc-2025-10-29-19-49-56](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-49-56.png)
+### Rich field types
 
-#### Field Synchronization Features:
+![Field types](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-48-51.png)
 
-1. **Real-time Sync**: When the database table structure changes, newly added fields can be synced at any time
-2. **Selective Sync**: You can selectively sync the fields you need, rather than all fields
-3. **Automatic Type Recognition**: Automatically identifies database field types and maps them to NocoBase field types
-4. **Maintain Data Integrity**: The sync process does not affect existing data
+#### Flexible field type conversion
 
-#### Use Cases:
+NocoBase supports flexible Field interface conversion when the underlying database type is compatible.
 
-- **Database Schema Evolution**: When business needs change and new fields need to be added to the database, they can be quickly synced to NocoBase
-- **Team Collaboration**: When other team members or DBAs add fields to the database, they can be synced promptly
-- **Hybrid Management Mode**: Some fields managed through NocoBase, others through traditional methods - flexible combinations
+For example, a database string field can be presented as:
 
-This flexible synchronization mechanism allows NocoBase to integrate well into existing technical architectures, without requiring changes to existing database management practices, while still enjoying the convenience of low-code development that NocoBase provides.
+- **Basic types**: Single line text, Multiline text, Phone, Email, URL, Password, Color, or Icon.
+- **Choice types**: Select or Radio group.
+- **Media types**: Markdown, Markdown (Vditor), Rich text, or Attachment URL.
+- **Date and time types**: Date time with timezone or Date time without timezone.
+- **Advanced types**: Sequence, Collection selector, or Encryption.
 
-See more in the [Collection Fields / Overview](/data-sources/data-modeling/collection-fields) section.
+This conversion does not change the underlying database storage type. It lets you adjust presentation and interaction as business requirements change while preserving existing data.
+
+### Field-level synchronization
+
+NocoBase can synchronize fields individually as well as synchronize an entire collection.
+
+![Field-level synchronization](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-49-56.png)
+
+#### Field synchronization behavior
+
+1. Synchronize newly added fields after the database schema changes.
+2. Select only the fields you need rather than synchronizing every field.
+3. Identify database field types and map them to NocoBase Field types automatically.
+4. Preserve existing data during synchronization.
+
+#### Use cases
+
+- **Database schema evolution**: synchronize fields added for new business requirements.
+- **Team collaboration**: synchronize fields added by another team member or DBA.
+- **Hybrid management**: combine fields managed in NocoBase with fields managed by traditional database tools.
+
+See [Collection fields](../data-modeling/collection-fields/index.md) for details.

package/dist/ai/docs/nocobase/data-sources/data-source-main/inheritance-collection.md

@@ -1,22 +1,109 @@
 ---
 pkg: "@nocobase/plugin-data-source-main"
+title: "Inheritance collection"
+description: "Create child collections from a parent collection. Child collections inherit parent fields and can define their own fields; this is supported only by a PostgreSQL main database."
+keywords: "Inheritance collection,table inheritance,PostgreSQL,NocoBase"
 ---
 
-# Inheritance Collection
+# Inheritance collection
 
 ## Introduction
 
-You can create a parent collection and derive child collection from that parent collection. The child collection will inherit the structure of the parent collection, and can also define its own columns. This design pattern helps organize and manage data with similar structures but possible differences.
+An **Inheritance collection** extends a general collection. Use it when several collections share stable common fields while each child collection also needs its own fields.
 
-Here are some common features of support for inheritable collections:
+For example, create an **Assets** parent collection with asset number, asset name, purchase date, and owner. Then derive **Computer assets**, **Vehicle assets**, and **Office furniture** child collections. Each child inherits the parent fields and can add its own fields.
 
-- Parent Collection: The parent collection contains common columns and data, defining the basic structure of the entire inheritance hierarchy.
-- Child Collection: The child collection inherits the structure of the parent collection, but can also define its own columns. This allows each child collection to have the common properties of the parent collection while containing attributes specific to the subclass.
-- Querying: When querying, you can choose to query the entire inheritance hierarchy, just the parent collection, or a specific child collection. This allows different levels of data to be retrieved and processed as needed.
-- Inheritance Relationship: An inheritance relationship is established between the parent collection and the child collection, meaning that the structure of the parent collection can be used to define consistent attributes, while allowing the child collection to extend or override these attributes.
+:::warning Note
 
-This design pattern helps to reduce data redundancy, simplify the database model, and make the data easier to maintain. However, it needs to be used with caution as inheritable collections can increase the complexity of queries, especially when dealing with the entire inheritance hierarchy. Databases that support inheritable collections generally provide specific syntax and tools to manage and query these collection structures.
+Inheritance collections can be created only when the main database is PostgreSQL. Other main databases, external databases, REST API data sources, and external NocoBase data sources do not support them.
 
-## User Manual
+:::
 
-![20240324085907](https://static-docs.nocobase.com/20240324085907.png)
+## Use cases
+
+- Derive Computer assets, Vehicle assets, and Office furniture from an Assets parent collection.
+- Derive Employees, Contractors, and Visitors from a People parent collection.
+- Derive Tasks, Defects, and Requirements from an Items parent collection.
+- Derive Purchase, Sales, and Service contracts from a Contracts parent collection.
+
+Use inheritance when the objects have stable shared fields and differ mainly in a small set of dedicated fields.
+
+## Create and configure
+
+In the main data source, click **Create collection** and choose a general-collection or inheritance-enabled entry. Select the parent collection in `Inherits`.
+
+![Create an inheritance collection](https://static-docs.nocobase.com/20240324085907.png)
+
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed in the interface, such as Computer assets, Vehicle assets, or Office furniture. |
+| Collection name | The internal identifier used by APIs, relation fields, permissions, and workflows. |
+| Inherits | The parent collection. The child inherits its field structure and can define additional fields. |
+| Categories | Organizes collections in the management interface without changing their schema. |
+| Description | Document what the child collection stores, which parent it derives from, and who maintains it. |
+| Preset fields | Usually keeps ID, created-at, created-by, updated-at, and updated-by fields. |
+
+Inheritance collections use the same blocks and field configuration as [General collections](./general-collection.md). In page blocks, they are normal collections that support record creation, reading, updating, and deletion.
+
+:::warning Note
+
+Use inheritance only for highly similar business objects. If objects have substantially different workflows, permissions, and pages, separate general collections connected by relation fields are usually clearer.
+
+:::
+
+### Built-in fields
+
+An inheritance collection inherits fields from its parent and can add fields of its own.
+
+| Field source | Description |
+| --- | --- |
+| Parent fields | Shared fields inherited by the child, such as asset number, asset name, and owner. |
+| Child fields | Dedicated child fields, such as CPU model for a computer asset or license plate for a vehicle asset. |
+| System fields | When `Preset fields` are retained, ID, created-at, created-by, updated-at, and updated-by fields are included. |
+
+:::warning Note
+
+Parent fields affect every child that inherits them. Before changing a parent field, check whether child pages, permissions, workflows, and APIs depend on it.
+
+:::
+
+### Primary key field
+
+Inheritance collections require a primary key just as general collections do. Keep the ID preset field when creating the collection; its default primary-key interface is `Snowflake ID (53-bit)`.
+
+If an imported or synchronized inheritance collection has no primary key, set a **Record unique key** when editing the collection. Otherwise page blocks might not view or edit records correctly.
+
+## Use in pages
+
+Inheritance collections can use most blocks supported by general collections. A common approach is to configure each child collection as its own table, form, details, or Kanban block.
+
+| Block | Use |
+| --- | --- |
+| [Table](../../interface-builder/blocks/data-blocks/table.md) | View, filter, sort, and batch-process child records. |
+| [Form](../../interface-builder/blocks/data-blocks/form.md) | Create or edit one child record. |
+| [Details](../../interface-builder/blocks/data-blocks/details.md) | View one child record in detail. |
+| [Kanban](../../interface-builder/blocks/data-blocks/kanban.md) | Group child records by status, stage, owner, or another field. |
+
+## Edit configuration
+
+Click **Edit** beside an inheritance collection to change its display name, category, description, simple-pagination mode, and Record unique key.
+
+Do not change inheritance relationships frequently after business configuration is in use. Page blocks, relation fields, permissions, and workflows can depend on the current field structure.
+
+## Delete a collection
+
+Click **Delete** beside an inheritance collection to delete it.
+
+Deleting an inheritance collection removes the child collection metadata and the real child table in the main database. Before deleting it, confirm that no page blocks, relation fields, permissions, workflows, or APIs still use the child collection.
+
+:::danger Warning
+
+Deleting a child collection does not automatically mean deleting its parent. Whether dependent objects are deleted depends on the option in the confirmation dialog. Confirm that the parent and other child collections should remain before continuing.
+
+:::
+
+## Related links
+
+- [General collection](./general-collection.md) - General collection configuration.
+- [Main database](./index.md) - Supported main database types.
+- [Collection fields](../data-modeling/collection-fields/index.md) - Field configuration.

package/dist/ai/docs/nocobase/data-sources/data-source-manager/external-database.md

@@ -1,101 +1,140 @@
-# External Database
+---
+title: "External databases"
+description: "Connect existing MySQL, PostgreSQL, MariaDB, KingbaseES, OceanBase, MSSQL, Oracle, ClickHouse, and Doris databases to NocoBase, then map their fields and relations."
+keywords: "external database,MySQL,PostgreSQL,MariaDB,KingbaseES,OceanBase,MSSQL,Oracle,ClickHouse,Doris,field mapping,NocoBase"
+---
 
-## Introduction
+# External databases
 
-Use an existing external database as a data source. Currently supported external databases include MySQL, MariaDB, PostgreSQL, MSSQL, and Oracle.
+## Introduction
 
-## Usage Instructions
+An **external database** connects an existing business database to NocoBase. NocoBase reads tables, fields, and views so they can be used in page blocks, permissions, workflows, and APIs.
 
-### Adding an External Database
+Unlike the [main database](../data-source-main/index.md), the original system and database tools maintain the external schema. NocoBase reads the structure and views; it does not change real tables in the external database.
 
-After activating the plugin, you can select and add it from the "Add new" dropdown menu in data source management.
+| Database | Supported version | Community | Standard | Professional | Enterprise |
+| --- | --- | --- | --- | --- | --- |
+| MySQL | >= 5.7 | No | Yes | Yes | Yes |
+| PostgreSQL | >= 9.5 | No | Yes | Yes | Yes |
+| MariaDB | >= 10.3 | No | Yes | Yes | Yes |
+| MSSQL | 2014-2019 | No | Yes | Yes | Yes |
+| KingbaseES | >= V9 | No | No | Yes | Yes |
+| OceanBase | >= 4.3 | No | No | No | Yes |
+| Oracle | >= 11g | No | No | No | Yes |
+| ClickHouse | >= 20.2 | No | No | No | Yes |
+| Doris | >= 2.1.0 | No | No | No | Yes |
 
+:::tip Tip
 
-![20240507204316](https://static-docs.nocobase.com/20240507204316.png)
+KingbaseES supports only PostgreSQL compatibility mode. OceanBase, ClickHouse, and Doris support only MySQL compatibility mode.
 
+:::
 
-Fill in the information for the database you need to connect to.
+Typical use cases include:
 
+- Connect an existing ERP, MES, WMS, or CRM database and build management pages, permissions, workflows, and reports without changing its schema.
+- Add lightweight approval, data-correction, exception-handling, or operations-dashboard capabilities without replacing the original system.
+- Query, analyze, or display existing data for reporting or BI.
+- Migrate a historical system gradually: keep the old database connected first, then put new business data in the main database over time.
+- Leave the database structure to DBAs, migration scripts, or the original system while NocoBase provides pages and data usage.
 
-![20240507204820](https://static-docs.nocobase.com/20240507204820.png)
+:::warning Note
 
+An external database is not the NocoBase system database. NocoBase does not manage its backup, restore, migrations, or schema changes.
 
-### Collection Synchronization
+:::
 
-After establishing a connection with an external database, all collections within the data source will be read directly. External databases do not support adding collections or modifying the table structure directly. If modifications are needed, you can perform them through a database client and then click the "Refresh" button in the interface to synchronize.
+## Plugin installation
 
+Each external database is supplied by a data-source plugin. Install and enable the plugin before its database type appears in **Data source management** > **Add new**.
 
-![20240507204725](https://static-docs.nocobase.com/20240507204725.png)
+| Database | Plugin | Installation |
+| --- | --- | --- |
+| MySQL | `@nocobase/plugin-data-source-external-mysql` | Requires a commercial license; install and enable it. |
+| PostgreSQL | `@nocobase/plugin-data-source-external-postgres` | Requires a commercial license; install and enable it. |
+| MariaDB | `@nocobase/plugin-data-source-external-mariadb` | Requires a commercial license; install and enable it. |
+| KingbaseES | `@nocobase/plugin-data-source-kingbase` | Requires a commercial license; install and enable it. |
+| OceanBase | `@nocobase/plugin-data-source-oceanbase` | Requires a commercial license; install and enable it. |
+| MSSQL | `@nocobase/plugin-data-source-external-mssql` | Requires a commercial license; install and enable it. |
+| Oracle | `@nocobase/plugin-data-source-external-oracle` | Requires a commercial license; install and enable it. |
+| ClickHouse | `@nocobase/plugin-data-source-external-clickhouse` | Requires a commercial license; install and enable it. |
+| Doris | `@nocobase/plugin-data-source-external-doris` | Requires a commercial license; install and enable it. |
 
+![Add a database](https://static-docs.nocobase.com/add_new_database.png)
 
-### Configuring Fields
+If a database type is missing from **Add new**, check that its plugin is installed and enabled, the commercial license includes it, and the current user can manage data sources.
 
-The external database will automatically read and display the fields of existing collections. You can quickly view and configure the field's title, data type (Field type), and UI type (Field interface). You can also click the "Edit" button to modify more configurations.
+## Usage
 
+### Add an external database
 
-![20240507210537](https://static-docs.nocobase.com/20240507210537.png)
+After the plugin is activated, choose the database type from **Add new** and provide its connection information.
 
+![Add an external database](https://static-docs.nocobase.com/20240507204316.png)
 
-Because external databases do not support modifying the table structure, the only available type when adding a new field is the association field. Association fields are not actual fields but are used to establish connections between collections.
+![Configure an external database](https://static-docs.nocobase.com/20240507204820.png)
 
+### Synchronize collections
 
-![20240507220140](https://static-docs.nocobase.com/20240507220140.png)
+After an external database is connected, NocoBase reads its collections. It cannot create collections or change the external schema. Make schema changes through database tools, then use the refresh action to synchronize metadata.
 
+![Synchronize external collections](https://static-docs.nocobase.com/20240507204725.png)
 
-For more details, see the [Collection Fields/Overview](/data-sources/data-modeling/collection-fields) chapter.
+### Configure fields
 
-### Field Type Mapping
+NocoBase reads and displays existing fields. You can configure their title, **Field type**, and **Field interface**, or use **Edit** for additional configuration.
 
-NocoBase automatically maps the field types from the external database to the corresponding data type (Field type) and UI type (Field Interface).
+![Configure external fields](https://static-docs.nocobase.com/20240507210537.png)
 
-- Data type (Field type): Defines the kind, format, and structure of data that a field can store.
-- UI type (Field interface): Refers to the type of control used in the user interface to display and input field values.
+Because an external database schema cannot be changed from NocoBase, the only field type you can add is a relation field. A relation field is not a real database column; it connects collections in NocoBase.
 
-| PostgreSQL | MySQL/MariaDB | NocoBase Data Type | NocoBase Interface Type |
-| - | - | - | - |
-| BOOLEAN | BOOLEAN<br/>TINYINT(1) | boolean | checkbox <br/> switch |
-| SMALLINT<br/>INTEGER<br/>SERIAL<br/>SMALLSERIAL | TINYINT<br/>SMALLINT<br/>MEDIUMINT<br/>INTEGER | integer<br/>boolean<br/>sort | integer<br/>sort<br/>checkbox<br/>switch<br/>select<br/>radioGroup |
-| BIGINT<br/>BIGSERIAL | BIGINT | bigInt<br/>sort | integer<br/>sort<br/>checkbox<br/>switch<br/>select<br/>radioGroup<br/>unixTimestamp<br/>createdAt<br/>updatedAt |
-| REAL | FLOAT | float | number<br/>percent |
-| DOUBLE PRECISION | DOUBLE PRECISION | double | number<br/>percent |
-| DECIMAL<br/>NUMERIC | DECIMAL | decimal | number<br/>percent<br/>currency |
-| VARCHAR<br/>CHAR | VARCHAR<br/>CHAR | string<br/>password<br/>uuid<br/>nanoid | input<br/>email<br/>phone<br/>password<br/>color<br/>icon<br/>select<br/>radioGroup<br/>uuid<br/>nanoid |
-| TEXT | TEXT<br/>TINYTEXT<br/>MEDIUMTEXT<br/>LONGTEXT | text<br/>json | textarea<br/>markdown<br/>vditor<br/>richText<br/>url<br/>json |
-| UUID | - | uuid | uuid |
-| JSON<br/>JSONB | JSON | json | json |
-| TIMESTAMP | DATETIME<br/>TIMESTAMP | date | date<br/>time<br/>createdAt<br/>updatedAt |
-| DATE | DATE | dateOnly | datetime |
-| TIME | TIME | time | time |
-| - | YEAR |  | datetime |
-| CIRCLE |  | circle | json<br/>circle |
-| PATH<br/>GEOMETRY(LINESTRING) | LINESTRING | lineString | Json<br/>lineString |
-| POINT<br/>GEOMETRY(POINT) | POINT | point | json<br/>point |
-| POLYGON<br/>GEOMETRY(POLYGON) | POLYGON | polygon | json<br/>polygon |
-| GEOMETRY | GEOMETRY |  -  |  -  |
-| BLOB | BLOB | blob |  -  |
-| ENUM | ENUM | enum | select<br/>radioGroup |
-| ARRAY |  -  | array | multipleSelect<br/>checkboxGroup |
-| BIT | BIT | - | - |
-| SET | SET | set | multipleSelect<br/>checkboxGroup |
-| RANGE | - | - | - |
+![Add an external relation field](https://static-docs.nocobase.com/20240507220140.png)
 
-### Unsupported Field Types
+See [Collection fields](../data-modeling/collection-fields/index.md) for details.
 
-Unsupported field types are displayed separately. These fields require development adaptation before they can be used.
+### Field type mapping
 
+NocoBase maps external database types to a corresponding **Field type** and **Field interface**. Field type defines the kind, format, and structure of stored data; Field interface defines the control used to display and enter the value.
 
-![20240507221854](https://static-docs.nocobase.com/20240507221854.png)
-
+| PostgreSQL | MySQL / MariaDB | NocoBase Field type | NocoBase Field interface |
+| --- | --- | --- | --- |
+| BOOLEAN | BOOLEAN, TINYINT(1) | `boolean` | `checkbox`, `switch` |
+| SMALLINT, INTEGER, SERIAL, SMALLSERIAL | TINYINT, SMALLINT, MEDIUMINT, INTEGER | `integer`, `boolean`, `sort` | `integer`, `sort`, `checkbox`, `switch`, `select`, `radioGroup` |
+| BIGINT, BIGSERIAL | BIGINT | `bigInt`, `sort` | `integer`, `sort`, `checkbox`, `switch`, `select`, `radioGroup`, `unixTimestamp`, `createdAt`, `updatedAt` |
+| REAL | FLOAT | `float` | `number`, `percent` |
+| DOUBLE PRECISION | DOUBLE PRECISION | `double` | `number`, `percent` |
+| DECIMAL, NUMERIC | DECIMAL | `decimal` | `number`, `percent`, `currency` |
+| VARCHAR, CHAR | VARCHAR, CHAR | `string`, `password`, `uuid`, `nanoid` | `input`, `email`, `phone`, `password`, `color`, `icon`, `select`, `radioGroup`, `uuid`, `nanoid` |
+| TEXT | TEXT, TINYTEXT, MEDIUMTEXT, LONGTEXT | `text`, `json` | `textarea`, `markdown`, `vditor`, `richText`, `url`, `json` |
+| UUID | - | `uuid` | `uuid` |
+| JSON, JSONB | JSON | `json` | `json` |
+| TIMESTAMP | DATETIME, TIMESTAMP | `date` | `date`, `time`, `createdAt`, `updatedAt` |
+| DATE | DATE | `dateOnly` | `datetime` |
+| TIME | TIME | `time` | `time` |
+| - | YEAR | - | `datetime` |
+| CIRCLE | - | `circle` | `json`, `circle` |
+| POINT, GEOMETRY(POINT) | POINT | `point` | `json`, `point` |
+| PATH, GEOMETRY(LINESTRING) | LINESTRING | `lineString` | `json`, `lineString` |
+| POLYGON, GEOMETRY(POLYGON) | POLYGON | `polygon` | `json`, `polygon` |
+| GEOMETRY | GEOMETRY | - | - |
+| BLOB | BLOB | `blob` | - |
+| ARRAY | - | `array` | `multipleSelect`, `checkboxGroup` |
+| BIT | BIT | - | - |
+| SET | SET | `set` | `multipleSelect`, `checkboxGroup` |
+| RANGE | - | - | - |
 
-### Filter Target Key
+### Unsupported field types
 
-Collections displayed as blocks must have a Filter target key configured. The filter target key is used to filter data based on a specific field, and the field value must be unique. By default, the filter target key is the collection's primary key field. For views, collections without a primary key, or collections with a composite primary key, you need to define a custom filter target key.
+Unsupported field types are shown separately. They require development support before they can be used.
 
+![Unsupported field types](https://static-docs.nocobase.com/20240507221854.png)
 
-![20240507210230](https://static-docs.nocobase.com/20240507210230.png)
+### Record unique key
 
+A collection shown in a block needs a **Record unique key** to locate a record, usually a primary key or unique field.
 
-Only collections that have a filter target key configured can be added to the page.
+For a view, table without a primary key, or composite-primary-key table, set the Record unique key manually in the collection configuration. Without a usable unique key, blocks might not be created correctly or might not be able to view and edit records.
 
+![Edit a collection](https://static-docs.nocobase.com/edit_collection.png)
 
-![20240507222827](https://static-docs.nocobase.com/20240507222827.png)
+![Configure a collection](https://static-docs.nocobase.com/edit_collection_configure.png)

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

@@ -1,47 +1,55 @@
 ---
 pkg: "@nocobase/plugin-data-source-manager"
+title: "Data source management"
+description: "Use the Data Source Manager to manage the main database, external databases, REST API data sources, and external NocoBase data sources from one interface."
+keywords: "data source management,main database,external database,table synchronization,REST API data source,NocoBase"
 ---
 
-# Data Source Manager
+# Data source management
 
 ## Introduction
 
-NocoBase provides a data source management plugin for managing data sources and their collections. The data source management plugin only provides a management interface for all data sources and does not provide the ability to access data sources. It needs to be used in conjunction with various data source plugins. The data sources currently supported for access include:
+NocoBase provides the **Data Source Manager** plugin to manage data sources and their collections. It provides the management interface for all data sources; it does not connect to a data source by itself. Use it together with the applicable data-source plugin.
 
-- [Main Database](/data-sources/data-source-main): NocoBase's main database, supporting relational databases such as MySQL, PostgreSQL, and MariaDB.
-- [External MySQL](/data-sources/data-source-external-mysql): Use an external MySQL database as a data source.
-- [External MariaDB](/data-sources/data-source-external-mariadb): Use an external MariaDB database as a data source.
-- [External PostgreSQL](/data-sources/data-source-external-postgres): Use an external PostgreSQL database as a data source.
-- [External MSSQL](/data-sources/data-source-external-mssql): Use an external MSSQL (SQL Server) database as a data source.
-- [External Oracle](/data-sources/data-source-external-oracle): Use an external Oracle database as a data source.
-- [External NocoBase](/data-sources/data-source-external-nocobase/): Use another NocoBase application as an external data source through the remote NocoBase API.
+Supported data sources include:
 
-In addition, more types can be extended through plugins, which can be common types of databases or platforms that provide APIs (SDKs).
+- [Main database](../data-source-main/index.md): The NocoBase main database. It supports MySQL, PostgreSQL, MariaDB, KingbaseES, and OceanBase.
+- [External PostgreSQL](../data-source-external-postgres/index.md): Uses an external PostgreSQL database as a data source.
+- [External MySQL](../data-source-external-mysql/index.md): Uses an external MySQL database as a data source.
+- [External MariaDB](../data-source-external-mariadb/index.md): Uses an external MariaDB database as a data source.
+- [External MSSQL](../data-source-external-mssql/index.md): Uses an external MSSQL (SQL Server) database as a data source.
+- [External KingbaseES](../data-source-kingbase/index.md): Uses an external KingbaseES database as a data source.
+- [External OceanBase](../external/oceanbase.md): Uses an external OceanBase database as a data source.
+- [External Oracle](../data-source-external-oracle/index.md): Uses an external Oracle database as a data source.
+- [External ClickHouse](../external/clickhouse.md): Uses an external ClickHouse database, typically for queries, statistics, and reports.
+- [External Doris](../external/doris.md): Uses an external Doris database, typically for queries, statistics, and reports.
+- [REST API data source](../data-source-rest-api/index.md): Connects data supplied by a REST API to NocoBase.
+- [External NocoBase](../data-source-external-nocobase/index.md): Uses the remote NocoBase API to connect another NocoBase application as an external data source.
 
-## Installation
-
-Built-in plugin, no separate installation required.
+Plugins can extend this list with other database types and platforms that provide APIs or SDKs.
 
-## Usage Instructions
-
-When the application is initialized and installed, a data source is provided by default to store NocoBase data, known as the main database. For more information, see the [Main Database](/data-sources/data-source-main/index.md) documentation.
+## Installation
 
-### External Data Sources
+This plugin is built in and does not require a separate installation.
 
-External databases are supported as data sources. For more information, see the [External Database / Introduction](/data-sources/data-source-manager/external-database) documentation.
+## Usage
 
+During application initialization, NocoBase provides a data source for storing NocoBase data. This source is called the **main database**. See [Main database](../data-source-main/index.md) for details.
 
-![nocobase_doc-2025-10-29-19-45-33](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-45-33.png)
+### External data sources
 
+NocoBase supports external databases as data sources. See [External databases](./external-database.md) for details.
 
-### Support for Syncing Custom Database Tables
+![External data sources](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-45-33.png)
 
+### Synchronize custom database tables
 
-![nocobase_doc-2025-10-29-19-46-34](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-46-34.png)
+You can synchronize tables that were created in the database outside NocoBase.
 
+![Synchronize custom database tables](https://static-docs.nocobase.com/nocobase_doc-2025-10-29-19-46-34.png)
 
-You can also access data from HTTP API sources. For more information, see the [REST API Data Source](/data-sources/data-source-rest-api/index.md) documentation.
+You can also connect data supplied by an HTTP API. See [REST API data source](../data-source-rest-api/index.md) for details.
 
-### External NocoBase Data Source
+### External NocoBase data source
 
-You can use another NocoBase application as an external data source through the remote NocoBase API. For more information, see the [External NocoBase](/data-sources/data-source-external-nocobase/) documentation.
+Use the remote NocoBase API to connect another NocoBase application as an external data source. See [External NocoBase](../data-source-external-nocobase/index.md) for details.