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

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection-fields/validation.md

@@ -1,115 +1,128 @@
-# Field Validation
-To ensure data accuracy, security, and consistency in collections, NocoBase provides field validation functionality. This feature consists of two main parts: rule configuration and rule application.
+---
+title: "Field validation"
+description: "Field validation rules based on Joi configuration and validation rules. Supports minimum and maximum length, required values, and other rules for string, number, date, and other types."
+keywords: "field validation,field validation rules,Joi,validation rules,configuration rules,NocoBase"
+---
 
-## Rule Configuration
+# Field validation
 
-![20250819181342](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819181342.png)
+To ensure collection accuracy, security, and consistency, NocoBase provides field validation. It has two parts: configuration rules and validation rules.
 
+## Configuration rules
 
-NocoBase system fields integrate [Joi](https://joi.dev/api/) rules, with support as follows:
+![Field validation settings](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819181342.png)
 
-### String
-Joi string types correspond to the following NocoBase field types: Single Line Text, Long Text, Phone, Email, URL, Password, and UUID.
-#### Common Rules
-- Min length
-- Max length
+NocoBase field rules integrate [Joi](https://joi.dev/api/). The supported rules are as follows.
+
+### String types
+
+NocoBase Field interfaces corresponding to Joi string types include Input, Textarea, Phone, Email, URL, Password, and UUID.
+
+#### Common rules
+
+- Minimum length
+- Maximum length
 - Length
-- Pattern
+- Regular expression
 - Required
 
 #### Email
 
-![20250819192011](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819192011.png)
+![Email validation settings](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819192011.png)
 
 [View more options](https://joi.dev/api/?v=17.13.3#stringemailoptions)
 
 #### URL
 
-![20250819192409](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819192409.png)
+![URL validation settings](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819192409.png)
 
 [View more options](https://joi.dev/api/?v=17.13.3#stringurioptions)
 
 #### UUID
 
-![20250819192731](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819192731.png)
+![UUID validation settings](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819192731.png)
 
 [View more options](https://joi.dev/api/?v=17.13.3#stringguid---aliases-uuid)
 
-### Number
-Joi number types correspond to the following NocoBase field types: Integer, Number, and Percentage.
-#### Common Rules
+### Number types
+
+NocoBase Field interfaces corresponding to Joi number types include Integer, Number, and Percent.
+
+#### Common rules
+
 - Greater than
 - Less than
-- Max value
-- Min value
+- Maximum value
+- Minimum value
 - Multiple
 
 #### Integer
-In addition to common rules, integer fields additionally support [integer validation](https://joi.dev/api/?v=17.13.3#numberinteger) and [unsafe integer validation](https://joi.dev/api/?v=17.13.3#numberunsafeenabled).
 
-![20250819193758](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819193758.png)
+In addition to common rules, Integer fields support [integer validation](https://joi.dev/api/?v=17.13.3#numberinteger) and [unsafe-integer validation](https://joi.dev/api/?v=17.13.3#numberunsafeenabled).
+
+![Integer validation settings](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819193758.png)
+
+#### Number and Percent
 
+In addition to common rules, Number and Percent fields support [precision validation](https://joi.dev/api/?v=17.13.3#numberinteger).
 
-#### Number & Percentage
-In addition to common rules, number and percentage fields additionally support [precision validation](https://joi.dev/api/?v=17.13.3#numberinteger).
+![Number and Percent validation settings](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819193954.png)
 
-![20250819193954](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819193954.png)
+### Date types
 
+NocoBase Field interfaces corresponding to Joi date types include DateTime (with time zone), DateTime (without time zone), Date only, and Unix timestamp.
 
-### Date
-Joi date types correspond to the following NocoBase field types: Date (with timezone), Date (without timezone), Date only, and Unix timestamp.
+Supported validation rules are:
 
-Supported validation rules:
 - Greater than
 - Less than
-- Max value
-- Min value
-- Timestamp
+- Maximum value
+- Minimum value
+- Timestamp format validation
 - Required
 
-### Association Fields
-Association fields only support required validation. Note that required validation for association fields is currently not supported in sub-form or sub-table scenarios.
-
-![20250819184344](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819184344.png)
-
-
-## Applying Validation Rules
-After configuring field rules, the corresponding validation rules will be triggered when adding or modifying data.
+### Relation fields
 
-![20250819201027](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819201027.png)
+Relation fields support required validation only. Note that required validation for relation fields is not currently supported in Subform or Subtable scenarios.
 
+![Relation field validation settings](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819184344.png)
 
-Validation rules also apply to sub-table and sub-form components:
+## Apply validation rules
 
-![20250819202514](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819202514.png)
+After you configure field rules, the corresponding validation rules are triggered when data is created or changed.
 
+![Validation triggered when changing data](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819201027.png)
 
+When a field is used in a form, its validation rules also appear in the field validation settings. They are displayed as read-only under **Server-side field validation rules**. To change these rules, return to **Data source / Collection configuration** and edit the field.
 
-![20250819202357](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819202357.png)
+You can still add additional rules for the current form field under **Client-side validation rules**. These rules affect only the current field component. The validation rules that ultimately take effect combine **Server-side field validation rules** and **Client-side validation rules**.
 
+Validation rules also apply to Subtable and Subform components:
 
-Note that in sub-form or sub-table scenarios, required validation for association fields does not take effect.
+![Validation in a Subtable](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819202514.png)
 
-![20250819203016](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203016.png)
+![Validation in a Subform](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819202357.png)
 
+Note that required validation for relation fields does not take effect in Subform or Subtable scenarios.
 
-## Differences from Client-Side Field Validation
-Client-side and server-side field validation are applied in different scenarios, with significant differences in implementation and rule trigger timing, so they need to be managed separately.
+![Relation required validation in a Subform or Subtable](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203016.png)
 
-### Configuration Method Differences
-- **Client-side validation**: Configure rules in edit forms (as shown in the figure below)
-- **Server-side field validation**: Set field rules in Data Source → Collection Configuration
+## Difference between server-side field validation rules and client-side validation rules
 
-![20250819203836](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203836.png)
+Server-side field validation rules and client-side validation rules are configured in different places and have different scopes.
 
+### Configuration differences
 
+- **Server-side field validation rules**: Set field rules in **Data source / Collection configuration**. These rules are the base rules of the field
+- **Client-side validation rules**: Add additional rules in form-field settings. These rules affect only the current field component
 
-![20250819203845](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203845.png)
+![Configure server-side field validation rules](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203836.png)
 
+![Configure client-side validation rules](https://nocobase-docs.oss-cn-beijing.aliyuncs.com/20250819203845.png)
 
+### Validation timing differences
 
-### Validation Trigger Timing Differences
-- **Client-side validation**: Triggers validation in real-time as users fill in fields, displaying error messages immediately.
-- **Server-side field validation**: Validates on the server side before data entry after data submission, with error messages returned through API responses.
-- **Application scope**: Server-side field validation takes effect not only during form submission but also triggers in all scenarios involving data addition or modification, such as workflows and data imports.
-- **Error messages**: Client-side validation supports custom error messages, while server-side validation does not currently support custom error messages.
+- **Server-side field validation rules**: Trigger client-side validation when the field is used in a form, and trigger validation before data is written. These rules also apply when data is created or changed through workflows, data import, and other paths
+- **Client-side validation rules**: Trigger client-side validation only in the current form field
+- **Rule display**: Server-side field validation rules are displayed read-only as inherited rules. Client-side validation rules are displayed separately and can be edited here
+- **Error messages**: Client-side validation rules support custom error messages. Server-side field validation rules do not currently support custom error messages

package/dist/ai/docs/nocobase/data-sources/data-modeling/collection.md

@@ -1,19 +1,38 @@
-# Collection Overview
+---
+title: "Collections"
+description: "Learn the purpose of NocoBase collections, collection structure types, the difference between main and external collections, and how to choose general, inheritance, tree, file, SQL, and database-view collections."
+keywords: "collection,general collection,inheritance collection,tree collection,file collection,SQL collection,database view,NocoBase"
+---
 
-NocoBase provides a unique DSL to describe the structure of data, known as Collection, which unifies the data structure from various sources, providing a reliable foundation for data management, analysis, and application.
+# Collections
 
+## Introduction
 
-![20240512161522](https://static-docs.nocobase.com/20240512161522.png)
+In NocoBase, a **Collection** is the data model used to describe one category of business data. It is more than a database table name: it is NocoBase's unified description of a category of data.
 
+A collection usually defines three things:
 
-To conveniently use various data models, it supports various types of collections:
+| Definition | Description |
+| --- | --- |
+| Where data is stored | Data can come from a main-database table, external-database table, SQL query result, database view, REST API resource, or external NocoBase application. |
+| Which fields it has | Fields describe the information in each record, such as a customer name, mobile number, order amount, creation time, or owner. |
+| How NocoBase uses it | Blocks, permissions, workflows, APIs, and relation fields all work with collections. |
 
-- [General collection](/data-sources/data-source-main/general-collection): Built-in common system fields;
-- [Inheritance collection](/data-sources/data-source-main/inheritance-collection): You can create a parent collection and then derive a child collection from the parent collection. The child collection will inherit the structure of the parent collection and can also define its own columns.
-- [Tree collection](/data-sources/collection-tree): Tree structure collection, currently only supports adjacency list design;
-- [Calendar collection](/data-sources/calendar/calendar-collection): Used to create calendar-related event collections;
-- [File collection](/data-sources/file-manager/file-collection): Used for file storage management;
-- : Used for dynamic expression scenarios in workflows;
-- [SQL collection](/data-sources/collection-sql): Not an actual database collection, but quickly presents SQL queries in a structured manner;
-- [View collection](/data-sources/collection-view): Connects to existing database views;
-- [External collection](/data-sources/collection-fdw): Allows the database system to directly access and query data in external data sources, based on FDW technology.
+You can think of a collection as the data structure for a business object. For example, **Customers**, **Orders**, **Contracts**, and **Tasks** can each be a collection.
+
+After you create or connect a collection, you usually need to do three more things:
+
+- Configure fields so that the collection can store the required business information
+- [Add blocks](../../interface-builder/blocks/index.md#add-blocks) to pages so that users can view, enter, and process data
+- Configure permissions, workflows, and APIs so that data can be accessed and processed according to business rules
+
+## Collection structure types
+
+- **General collection** - Suitable for standard business data such as customers, orders, contracts, work orders, expense claims, projects, and tasks
+- **Tree collection** - Suitable for hierarchical data such as organizational structures, product categories, regional hierarchies, department directories, and knowledge-base directories
+- **Calendar collection** - Suitable for time-range data such as meeting-room reservations, project schedules, course schedules, duty rosters, and event calendars
+- **Comment collection** - Suitable for discussion content around business records, such as task comments, article comments, approval opinions, and customer feedback. Create a [relation field](./collection-fields/associations/index.md) in a business collection (general, tree, or calendar) to relate it to a comment collection, then add a [comment block](../../plugins/@nocobase/plugin-comments/index.md) in a business-collection popup page to comment on business data
+- **File collection** - Suitable for file metadata such as contract attachments, invoice files, product images, and employee certificates. The files themselves are stored by the file-storage engine. Create a [relation field](./collection-fields/associations/index.md) in a business collection (general, tree, or calendar) to relate it to a file collection, then configure the relation field for file upload in a business-collection block. File metadata is automatically saved to the file collection
+- **Database view** - An existing database view, such as a financial-report view, filtered customer view, or aggregated view synchronized across systems
+- **SQL collection** - Suitable for using SQL query results as collections, such as sales summaries, inventory alerts, cross-table statistical reports, and operational dashboards
+- **Inheritance collection** - Suitable when several business objects share a group of common fields but each also has its own fields, such as an asset parent collection that has computer-asset, vehicle-asset, and office-furniture child collections

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

@@ -1,53 +1,61 @@
+---
+title: "Data modeling overview"
+description: "Data modeling covers designing data models, connecting data sources, visualizing ER diagrams, and creating collections for main and external databases."
+keywords: "data modeling,Collection,data model,ER diagram,main database,external database,NocoBase"
+---
+
 # Overview
 
-Data modeling is a key step in designing databases, involving a deep analysis and abstraction process of various types of data and their interrelationships in the real world. In this process, we try to reveal the intrinsic connections between data and formalize them into data models, laying the foundation for the database structure of the information system. NocoBase is a platform driven by data models, with the following features:
+Data modeling is a key step in database design. It involves analyzing and abstracting real-world data and the relationships between it. This process reveals the internal connections between data and formalizes them as a data model, providing the foundation for an information system's database structure. NocoBase is a data-model-driven platform with the following capabilities.
 
-## Supports Access to Data from Various Sources
+## Connect data from many sources
 
-NocoBase supports data sources from various origins, including common databases, API/SDK platforms, and files.
+NocoBase data sources can be common databases, API (SDK) platforms, and files.
 
-![20240512085558](https://static-docs.nocobase.com/20240512085558.png)
+![Data sources](https://static-docs.nocobase.com/20240512085558.png)
 
-NocoBase provides a [data source manager](/data-sources/data-source-manager) for managing various data sources and their collections. The data source manager plugin only provides a management interface for all data sources and does not provide the ability to directly access data sources. It needs to be used in conjunction with various data source plugins. The currently supported data sources include:
+NocoBase provides the [Data source management plugin](../data-source-manager/index.md) to manage data sources and their collections. It provides the management interface for all data sources, but does not connect a data source by itself; use it with the corresponding data-source plugins. Supported data sources include:
 
-- [Main Database](/data-sources/data-source-main): NocoBase's main database, supporting relational databases such as MySQL, PostgreSQL, and MariaDB.
-- [KingbaseES](/data-sources/data-source-kingbase): Use KingbaseES database as a data source, which can be used as both a main database and an external database.
-- [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.
+- [Main data source](../main/index.md): The NocoBase main database. It supports relational databases such as MySQL, PostgreSQL, and MariaDB
+- [KingbaseES](../main/kingbase.md): Uses KingbaseES as a data source. It can be used as a main or external database
+- [External MySQL](../external/mysql.md): Uses an external MySQL database as a data source
+- [External MariaDB](../external/mariadb.md): Uses an external MariaDB database as a data source
+- [External PostgreSQL](../external/postgresql.md): Uses an external PostgreSQL database as a data source
+- [External MSSQL](../external/mssql.md): Uses an external MSSQL (SQL Server) database as a data source
+- [External Oracle](../external/oracle.md): Uses an external Oracle database as a data source
 
-![20240512083651](https://static-docs.nocobase.com/20240512083651.png)
+![Data source management](https://static-docs.nocobase.com/20240512083651.png)
 
-## Provides a Variety of Data Modeling Tools
+## Data-modeling tools
 
-**Simple collection management interface**: Used to create various models (collections) or connect to existing ones.
+**A simple collection management interface**: Create different models (collections) or connect existing models (collections).
 
-![20240512090751](https://static-docs.nocobase.com/20240512090751.png)
+![Collection management](https://static-docs.nocobase.com/20240512090751.png)
 
-**ER-style visual interface**: Used to extract entities and their relationships from user and business requirements. It provides an intuitive and easy-to-understand way to describe data models. Through ER diagrams, you can more clearly understand the main data entities in the system and their relationships.
+**An ER-diagram-like visual interface**: Extract entities and their relationships from user and business needs. It provides an intuitive way to describe data models so that you can understand the main data entities in the system and their connections more clearly.
 
-![20240512091042](https://static-docs.nocobase.com/20240410075906.png)
+![ER diagram](https://static-docs.nocobase.com/20240410075906.png)
 
-## Supports Various Types of Collections
+## Create different collection types
 
-- [General collection](/data-sources/data-source-main/general-collection): Built-in common system fields;
-- [Calendar collection](/data-sources/calendar/calendar-collection): Used to create calendar-related event collections;
-- Comment collection: Used for storing comments or feedback on data;
-- [Tree collection](/data-sources/collection-tree): Tree-structured collection, currently only supports the adjacency list model;
-- [File collection](/data-sources/file-manager/file-collection): Used for file storage management;
-- [SQL collection](/data-sources/collection-sql): Not an actual database collection, but visualizes SQL queries in a structured manner;
-- [Connect to database view](/data-sources/collection-view): Connects to existing database views;
-- Expression collection: Used for dynamic expression scenarios in workflows;
-- [Connect to foreign data](/data-sources/collection-fdw): Allows the database system to directly access and query data in external data sources based on FDW technology.
+| Collection | Description |
+| --- | --- |
+| [General collection](../data-source-main/general-collection.md) | Includes common system fields. |
+| [Calendar collection](../calendar/calendar-collection.md) | Creates event collections for calendar-related data. |
+| Comment collection | Stores comments or feedback about data. |
+| [Tree collection](../collection-tree/index.md) | A hierarchical collection that currently supports the adjacency-list model only. |
+| [File collection](../file-manager/file-collection.md) | Manages file storage. |
+| [SQL collection](../collection-sql/index.md) | Does not create an actual database table. It presents SQL query results in a structured way. |
+| [Connect a database view](../collection-view/index.md) | Connects an existing database view. |
+| Expression collection | Used for dynamic expression scenarios in workflows. |
+| Connect external data | Connects remote data tables through database FDW technology. |
 
-![20240512102212](https://static-docs.nocobase.com/20240512102212.png)
+![Collection types](https://static-docs.nocobase.com/20240512102212.png)
 
-For more content, see the "[Collection / Overview](/data-sources/data-modeling/collection)" section.
+For more information, see [Collections](./collection.md).
 
-## Provides a Rich Variety of Field Types
+## Rich field types
 
-![20240512110352](https://static-docs.nocobase.com/20240512110352.png)
+![Field interface types](https://static-docs.nocobase.com/20240512110352.png)
 
-For more content, see the "[Collection Fields / Overview](/data-sources/data-modeling/collection-fields)" section.
+For more information, see [Fields](./collection-fields/index.md).

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

@@ -1,18 +1,126 @@
 ---
 pkg: "@nocobase/plugin-data-source-external-mariadb"
+title: "External data source - MariaDB"
+description: "Learn how to connect MariaDB as an external database in NocoBase, including supported versions, plugin installation, connection settings, collection scope, permissions, and field mapping."
+keywords: "external data source,MariaDB,external database,field mapping,NocoBase"
 ---
 
-# External Data Source - MariaDB
+# MariaDB
 
 ## Introduction
 
-Use an external MariaDB database as a data source. Currently supported versions: MariaDB >= 10.3
+MariaDB can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from MariaDB and makes them available as collections in the external data source.
 
-## Installation
+Unlike a [main data source](../main/index.md), the actual schema of an external MariaDB database continues to be maintained by the original business system, database client, or migration scripts. NocoBase reads the schema, stores field metadata, and lets you configure blocks, permissions, workflows, and APIs.
 
-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)
+| Setting | Description |
+| --- | --- |
+| Supported version | MariaDB >= 10.3. |
+| Commercial editions | Available in Standard, Professional, and Enterprise editions. |
+| Plugin | `@nocobase/plugin-data-source-external-mariadb`. |
+| Compatible protocol | Connects through the MySQL protocol. Field mapping generally follows MySQL compatibility rules. |
 
+External MariaDB is suitable when you need to:
 
-## Usage Instructions
+- Connect a MariaDB database used by an existing ERP, MES, WMS, CRM, or other business system
+- Build management pages in NocoBase without migrating historical data
+- Apply permissions, workflow processing, data corrections, or reporting to existing tables
+- Keep the database schema maintained by DBAs, migration scripts, or the original system
 
-Refer to the [Data Source / External Database](/data-sources/data-source-manager/external-database) section.
+:::warning Note
+
+An external MariaDB database is not a NocoBase system database. NocoBase does not manage its backups, restores, migrations, or schema changes.
+
+:::
+
+## 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 MariaDB, and then enter the connection details.
+
+![Add an external MariaDB data source](https://static-docs.nocobase.com/20260709204413.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 `ERP MariaDB` or `Order database`. |
+| Host / Port | The MariaDB host address and port. The default port is usually `3306`. |
+| Database | The name of the MariaDB database to connect to. |
+| Username / Password | The account credentials used to connect to MariaDB. 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 and views that match the prefix, and removes the prefix from the generated NocoBase collection names. |
+| Collections / Add all collections | Controls the connection scope. With **Add all collections** enabled, NocoBase connects all tables and views in the current scope. When disabled, it connects only the objects selected in **Collections**. |
+| 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
+
+When MariaDB contains many objects, narrow the scope through `Database`, `Table prefix`, and **Collections** first. Connecting only the tables and views used by the current application keeps permissions, page building, and synchronization easier to maintain.
+
+:::
+
+## Select collections
+
+After entering connection details, click **Load Collections** to read available tables and views from MariaDB. The results depend on the connection account, `Database`, `Table prefix`, and **Collections** settings.
+
+By default, **Add all collections** is enabled, which connects all tables and views in the current scope. To connect only selected objects, disable **Add all collections** and select the required tables or views from the list.
+
+![Select external MariaDB collections](https://static-docs.nocobase.com/20260709204452.png)
+
+:::warning Note
+
+An external data source can connect up to 500 tables or views at a time. When MariaDB contains many objects, narrow the scope through `Database`, `Table prefix`, or **Collections** first.
+
+:::
+
+## Synchronize and configure fields
+
+The external MariaDB schema is maintained in MariaDB. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the MariaDB 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 MariaDB 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 MariaDB tables.
+
+## Field type mapping
+
+NocoBase automatically maps MariaDB types to appropriate Field types and Field interfaces. Common MariaDB mappings are largely the same as MySQL mappings, and you can adjust the display interface in field settings.
+
+| MariaDB type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `TINYINT`, `SMALLINT`, `MEDIUMINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT`, `INTEGER` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `snowflakeId`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `FLOAT`, `DOUBLE` | `float` | Number, Percent. |
+| `DECIMAL` | `decimal` | Number, Percent, Currency. |
+| `CHAR`, `VARCHAR` | `string`, `uuid`, `nanoid`, `encryption` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TINYTEXT`, `TEXT`, `MEDIUMTEXT`, `LONGTEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME` | `datetimeNoTz`, `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `TIMESTAMP` | `datetimeTz`, `date` | Date, Time, Created at, Updated at. |
+| `YEAR` | `string`, `integer` | Input, Integer, Date. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported MariaDB types are displayed separately in field settings. They require development support before they can be used as regular NocoBase fields.
+
+:::
+
+## Primary key and Record unique key
+
+Collections used for block display and editing should have a primary key or unique field. NocoBase uses the primary key as the Record unique key when available.
+
+For views, tables without a primary key, or composite-primary-key tables, configure **Record unique key** manually in the collection settings. Without a usable identifier, blocks might not view, edit, or delete records correctly.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709205835.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709205854.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/data-source-external-mssql/index.md

@@ -1,18 +1,129 @@
 ---
 pkg: "@nocobase/plugin-data-source-external-mssql"
+title: "External data source - MSSQL"
+description: "Learn how to connect MSSQL/SQL Server as an external database in NocoBase, including supported versions, plugin installation, connection settings, encrypted connections, permissions, and field mapping."
+keywords: "external data source,MSSQL,SQL Server,external database,field mapping,NocoBase"
 ---
 
-# External Data Source - MSSQL
+# MSSQL
 
 ## Introduction
 
-Use an external MSSQL database as a data source. Currently supported versions: SQL Server 2014-2019
+MSSQL (SQL Server) can be connected to NocoBase as an external database. NocoBase reads tables, fields, and views from SQL Server and makes them available as collections in the external data source.
 
-## Installation
+Unlike a [main data source](../main/index.md), the actual schema of an external MSSQL database continues to be maintained by the original business system, database client, or migration scripts. NocoBase reads the schema, stores field metadata, and lets you configure blocks, permissions, workflows, and APIs.
 
-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)
+| Setting | Description |
+| --- | --- |
+| Supported version | SQL Server 2014-2019. |
+| Commercial editions | Available in Standard, Professional, and Enterprise editions. |
+| Plugin | `@nocobase/plugin-data-source-external-mssql`. |
+| Connection features | Supports **Encrypt connection** and **Trust server certificate**. |
 
+External MSSQL is suitable when you need to:
 
-## Usage Instructions
+- Connect an SQL Server database used by an existing ERP, MES, WMS, CRM, or other business system
+- Build management pages in NocoBase without migrating historical data
+- Apply permissions, workflow processing, data corrections, or reporting to existing tables
+- Keep the database schema maintained by DBAs, migration scripts, or the original system
 
-Refer to the [Data Source / External Database](/data-sources/data-source-manager/external-database) section.
+:::warning Note
+
+An external MSSQL database is not a NocoBase system database. NocoBase does not manage its backups, restores, migrations, or schema changes.
+
+:::
+
+## 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 MSSQL, and then enter the connection details.
+
+![Add an external MSSQL data source](https://static-docs.nocobase.com/20260709210022.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 `ERP SQL Server` or `Finance database`. |
+| Host / Port | The SQL Server host address and port. The default port is usually `1433`. |
+| Database | The name of the SQL Server database to connect to. |
+| Username / Password | The account credentials used to connect to SQL Server. 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 and views that match the prefix, and removes the prefix from the generated NocoBase collection names. |
+| Encrypt connection | Whether to enable an encrypted connection. Enable it when the database enforces encryption or the network connection requires encryption. |
+| Trust server certificate | Whether to trust the server certificate. You might need to enable it for test environments or self-signed certificates; use a trusted certificate in production. |
+| Collections / Add all collections | Controls the connection scope. With **Add all collections** enabled, NocoBase connects all tables and views in the current scope. When disabled, it connects only the objects selected in **Collections**. |
+| 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
+
+When SQL Server contains many objects, narrow the scope through `Database`, `Table prefix`, and **Collections** first. Connecting only the tables and views used by the current application keeps permissions, page building, and synchronization easier to maintain.
+
+:::
+
+## Select collections
+
+After entering connection details, click **Load Collections** to read available tables and views from SQL Server. The results depend on the connection account, `Database`, `Table prefix`, and **Collections** settings.
+
+By default, **Add all collections** is enabled, which connects all tables and views in the current scope. To connect only selected objects, disable **Add all collections** and select the required tables or views from the list.
+
+![Select external SQL Server collections](https://static-docs.nocobase.com/add_new_database_configure_load_collection.png)
+
+:::warning Note
+
+An external data source can connect up to 500 tables or views at a time. When SQL Server contains many objects, narrow the scope through `Database`, `Table prefix`, or **Collections** first.
+
+:::
+
+## Synchronize and configure fields
+
+The external MSSQL schema is maintained in SQL Server. NocoBase does not create fields, change field types, or delete actual fields in the external database.
+
+When the SQL Server 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 SQL Server 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 SQL Server tables.
+
+## Field type mapping
+
+NocoBase automatically maps SQL Server types to appropriate Field types and Field interfaces. You can adjust the display interface in field settings.
+
+| SQL Server type | NocoBase Field type | Available Field interfaces |
+| --- | --- | --- |
+| `BIT` | `bit` | Checkbox, Switch. |
+| `TINYINT`, `SMALLINT` | `integer`, `boolean`, `sort` | Integer, Sort, Checkbox, Switch, Select, Radio group. |
+| `INT` | `integer`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Select, Radio group. |
+| `BIGINT` | `bigInt`, `unixTimestamp`, `sort` | Integer, Sort, Unix timestamp, Created at, Updated at. |
+| `DECIMAL`, `MONEY`, `SMALLMONEY` | `decimal` | Number, Percent, Currency. |
+| `NUMERIC`, `FLOAT`, `REAL` | `float` | Number, Percent. |
+| `CHAR`, `VARCHAR`, `NCHAR`, `NVARCHAR` | `string`, `uuid`, `nanoid` | Input, Email, Phone, Password, Color, Icon, Select, Radio group, UUID, Nano ID. |
+| `TEXT`, `NTEXT` | `text` | Textarea, Markdown, Vditor, Rich text, URL. |
+| `DATE` | `dateOnly` | Date. |
+| `TIME` | `time` | Time. |
+| `DATETIME`, `DATETIME2` | `datetimeNoTz` | Date, Time, Created at, Updated at. |
+| `DATETIMEOFFSET` | `datetimeTz` | Date, Time, Created at, Updated at. |
+| `UNIQUEIDENTIFIER` | `uuid`, `string` | UUID, Input. |
+| `JSON` | `json`, `array` | JSON. |
+
+:::warning Note
+
+Unsupported SQL Server types are displayed separately in field settings. They require development support before they can be used as regular NocoBase fields.
+
+:::
+
+## Primary key and Record unique key
+
+Collections used for block display and editing should have a primary key or unique field. NocoBase uses the primary key as the Record unique key when available.
+
+For views, tables without a primary key, or composite-primary-key tables, configure **Record unique key** manually in the collection settings. Without a usable identifier, blocks might not view, edit, or delete records correctly.
+
+![Primary key and Record unique key](https://static-docs.nocobase.com/20260709210154.png)
+![Configure Record unique key](https://static-docs.nocobase.com/20260709210214.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.