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

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

@@ -1,14 +1,111 @@
 ---
 pkg: "@nocobase/plugin-calendar"
+title: "Calendar collection"
+description: "Use a Calendar collection to store time-range data such as meetings, schedules, courses, and shifts, then display and edit event records with Calendar blocks."
+keywords: "Calendar collection,Calendar Collection,calendar events,recurring events,Calendar block,NocoBase"
 ---
 
 # Calendar collection
 
 ## Introduction
 
-A calendar Collection is a specialized data table designed to store dates and date-related information. It is commonly used to manage and track time within applications or systems. The primary goal of the calendar table is to offer flexible and efficient access to date information, allowing for the swift retrieval of relevant data as needed.
+Calendar collections are suitable for time-range data, such as meeting-room reservations, project schedules, course schedules, duty rosters, and event calendars. They are still collections, but include fields related to calendar events so that they can be used with Calendar blocks later.
 
-## User Manual
+You can create Calendar collections only from the main data source. External databases, REST API data sources, and External NocoBase data sources do not support creating Calendar collections.
 
+## Use cases
 
-![20240512182454](https://static-docs.nocobase.com/20240512182454.png)
+Calendar collections are suitable for these business scenarios:
+
+- Meeting-room, vehicle, and equipment reservations
+- Project schedules, task plans, and milestone arrangements
+- Timetables, training plans, and event calendars
+- Duty rosters, shift records, and inspection plans
+- Event records that need to be viewed by day, week, or month
+
+## Create and configure
+
+In the main data source, click **Create collection** and select **Calendar collection** to create a Calendar collection.
+
+Calendar collection settings are mostly the same as those for a general collection. `Preset fields` controls common system fields, and Calendar collections also include fields for storing recurring-event data.
+
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed for the collection, such as `Meeting room reservations`, `Course schedule`, or `Duty roster`. |
+| Collection name | The collection identifier used internally by APIs, relation fields, permissions, and workflows. |
+| Inherits | Select a parent collection to inherit. This setting is visible only when the main database is PostgreSQL. |
+| Categories | Collection categories affect only organization in Data source management; they do not change the collection structure. |
+| Description | A description of the collection. State which events it stores, who maintains it, and which business processes it relates to. |
+| Preset fields | Preset fields. Keep system fields and Calendar collection built-in fields when creating a Calendar collection. |
+
+### Built-in fields
+
+After a Calendar collection is created, it usually includes the following built-in fields. `cron` and `exclude` store recurrence rules and excluded dates.
+
+| Field | Field name | Description |
+| --- | --- | --- |
+| ID | `id` | The default primary key that uniquely identifies an event record. |
+| Created at | `createdAt` | Automatically records when the event record was created. |
+| Created by | `createdBy` | Automatically records the user who created the event record. |
+| Updated at | `updatedAt` | Automatically records when the event record was last updated. |
+| Updated by | `updatedBy` | Automatically records the user who last updated the event record. |
+| Sort | `sort` | Stores the sort value for an event record and supports capabilities such as drag-and-drop ordering. |
+| Repeats | `cron` | Stores recurrence rules, such as daily, weekly, monthly, or yearly repetition. |
+| Exclude | `exclude` | Stores excluded dates in a recurring event. It is normally maintained automatically through calendar interactions. |
+| Space | `space` | Available after enabling the [Multi-space plugin](../../multi-app/multi-space/index.md). It isolates data by space and does not appear when Multi-space is not enabled. |
+
+When a Calendar block uses a Calendar collection, specify the business fields used to display events:
+
+| Setting | Description |
+| --- | --- |
+| Title field | Determines the event title in the calendar, such as `Meeting subject` or `Course name`. |
+| Start date field | Determines when the event starts. Usually use a date-time field. |
+| End date field | Determines when the event ends. Usually use a date-time field. |
+
+:::warning Note
+
+`cron` and `exclude` are normally maintained by Calendar capabilities and should not be edited directly as ordinary business fields. Create and configure title, start-date, and end-date fields according to your business needs; otherwise, Calendar blocks cannot display events correctly.
+
+:::
+
+### Primary key field
+
+Like a general collection, a Calendar collection needs a primary key. Keep the ID preset field when creating the collection; its default primary-key type is `Snowflake ID (53-bit)`.
+
+If a Calendar collection has no primary key, set **Record unique key** when editing the collection. Otherwise, Calendar blocks might not open, edit, or locate event records correctly.
+
+## Edit configuration
+
+In the collection list, click **Edit** next to a Calendar collection to change its display name, category, description, simple pagination mode, **Record unique key**, and other settings.
+
+Calendar built-in fields such as `cron` and `exclude` are normally used by Calendar capabilities and should not be repurposed for other business meanings. To extend event information, add ordinary business fields such as location, participants, meeting room, or status.
+
+## Delete a collection
+
+In the collection list, click **Delete** next to a Calendar collection to delete it.
+
+Deleting a Calendar collection deletes event records, Calendar built-in field data, and related collection metadata. Before deleting it, confirm whether Calendar blocks, Table blocks, permissions, workflows, or APIs still depend on the collection.
+
+:::danger Warning
+
+Calendar collections usually store time data for schedules, reservations, and shifts. After deletion, historical events and recurrence rules are lost. Confirm that the data is backed up or no longer needed before proceeding.
+
+:::
+
+## Use in pages
+
+A Calendar collection can use most data blocks for a [general collection](../data-source-main/general-collection.md) to create, read, update, and delete records. It is also usually used with Calendar blocks:
+
+| Block | Use |
+| --- | --- |
+| [Calendar block](../../interface-builder/blocks/data-blocks/calendar.md) | Displays event records in day, week, month, and other views, and creates, views, and edits events in the calendar. |
+| [Table block](../../interface-builder/blocks/data-blocks/table.md) | Views, filters, and maintains event records in a list. |
+| [Form block](../../interface-builder/blocks/data-blocks/form.md) | Creates or edits one event record. |
+| [Details block](../../interface-builder/blocks/data-blocks/details.md) | Views details of one event. |
+
+## Related links
+
+- [General collection](../data-source-main/general-collection.md) - General configuration and block usage.
+- [Date and time fields](../data-modeling/collection-fields/datetime/datetime.md) - Create event start and end fields.
+- [Calendar block](../../interface-builder/blocks/data-blocks/calendar.md) - Display data in a calendar on a page.
+- [Multi-space](../../multi-app/multi-space/index.md) - Learn about the Space field and data isolation by space.

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

@@ -1,66 +1,119 @@
 ---
 pkg: "@nocobase/plugin-comments"
+title: "Comment collection"
+description: "A Comment collection stores comments, replies, and feedback for business records. It supports rich-text content, user tracking, multi-level comments, and Comment blocks."
+keywords: "Comment collection,comments,rich text comments,multi-level comments,Collection Comment,NocoBase"
 ---
 
-# Comment Collection
+# Comment collection
 
 ## Introduction
 
-Comment collection is a specialized data table template designed for storing user comments and feedback. With the comment feature, you can add commenting capabilities to any data table, allowing users to discuss, provide feedback, or annotate specific records. The comment collection supports rich text editing, providing flexible content creation capabilities.
+Comment collections are suitable for storing discussions, feedback, and annotations around business records. For example, you can use a Comment collection for task comments, approval opinions, article comments, and customer feedback.
 
-![comment-collection-2025-11-01-00-39-01](https://static-docs.nocobase.com/comment-collection-2025-11-01-00-39-01.png)
+A Comment collection is usually not used as an independent main business collection. A more common approach is to create a Comment collection, configure a relation field in the business collection, and then add a Comment block to the details page or popup for business records.
 
-## Features
+![Comment collection workflow](https://static-docs.nocobase.com/comment-collection-2025-11-01-00-39-01.png)
 
-- **Rich Text Editing**: Includes Markdown (vditor) editor by default, supporting rich text content creation
-- **Link to Any Data Table**: Can associate comments with records in any data table through relationship fields
-- **Multi-level Comments**: Supports replying to comments, building a comment tree structure
-- **User Tracking**: Automatically records comment creator and creation time
+## Use cases
 
-## User Guide
+Comment collections are suitable for these business scenarios:
 
-### Creating a Comment Collection
+- Collaboration discussions on tasks, requirements, and defects
+- Processing opinions on approval forms, work orders, and contracts
+- Comments on articles, knowledge bases, and announcements
+- Customer feedback, after-sales follow-up, and internal notes
 
-![comment-collection-2025-11-01-00-37-10](https://static-docs.nocobase.com/comment-collection-2025-11-01-00-37-10.png)
+## Usage flow
 
-1. Go to the data table management page
-2. Click the "Create Collection" button
-3. Select the "Comment Collection" template
-4. Enter the table name (e.g., "Task Comments", "Article Comments", etc.)
-5. The system will automatically create a comment table with the following default fields:
-   - Comment content (Markdown vditor type)
-   - Created by (linked to user table)
-   - Created at (datetime type)
+Comment collections are typically used together with a business collection and a Comment block:
 
-### Configuring Relationships
+1. Create a Comment collection to store comment content, reply relations, creators, creation time, and other information.
+2. Create a relation field in the business collection and relate it to the Comment collection. For example, relate a `Task comments` collection to the `Tasks` collection.
+3. Add a Comment block to a details page or popup for the business collection.
+4. When users post or reply in the Comment block, comment data is written to the Comment collection and related to the current business record.
+5. Configure Comment collection permissions as needed to control who can view, create, or delete comments.
 
-To link comments to a target data table, you need to configure relationship fields:
+## Create and configure
+
+In the main data source, click **Create collection** and select **Comment collection** to create a Comment collection.
+
+![Create a Comment collection](https://static-docs.nocobase.com/comment-collection-2025-11-01-00-37-10.png)
+
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed for the collection, such as `Task comments`, `Approval opinions`, or `Article comments`. |
+| Collection name | The collection identifier used internally by APIs, relation fields, permissions, and workflows. |
+| Inherits | Select a parent collection to inherit. This setting is visible only when the main database is PostgreSQL. |
+| Categories | Collection categories affect only organization in Data source management; they do not change the collection structure. |
+| Description | A description of the collection. State which business object it serves, who maintains it, and how comment permissions are designed. |
+| Preset fields | Preset fields. Keep system fields and Comment collection built-in fields when creating a Comment collection. |
+
+### Built-in fields
+
+After a Comment collection is created, it usually includes the following built-in fields. Comment blocks mainly use `content`, `createdBy`, and `createdAt` to display comment text, commenter, and comment time.
+
+| Field | Field name | Description |
+| --- | --- | --- |
+| ID | `id` | The default primary key that uniquely identifies a comment record. |
+| Comment content | `content` | Stores the comment text entered by users. It uses the Markdown Vditor interface by default. |
+| Created at | `createdAt` | Automatically records when the comment was created. Comment blocks use it to display the comment time. |
+| Created by | `createdBy` | Automatically records the user who posted the comment. Comment blocks use it to display the commenter. |
+| Updated at | `updatedAt` | Automatically records when the comment was last updated. |
+| Updated by | `updatedBy` | Automatically records the user who last updated the comment. |
+| Space | `space` | Available after enabling the [Multi-space plugin](../../multi-app/multi-space/index.md). It isolates data by space and does not appear when Multi-space is not enabled. |
+
+:::warning Note
+
+Comment collection built-in fields are normally maintained by Comment blocks and should not be deleted or repurposed casually. To store information such as comment category or processing status, add business fields instead.
+
+:::
+
+### Primary key field
+
+Like a general collection, a Comment collection needs a primary key. Comment blocks use the primary key to locate comment records and reply relationships.
+
+If a Comment collection has no primary key, set **Record unique key** when editing the collection. Otherwise, Comment blocks might not view, reply to, or delete comments correctly.
+
+## Create a relation
+
+Create a relation field in the business collection and relate it to the Comment collection.
 
 ![](https://static-docs.nocobase.com/Solution/demoE3v1-19N.gif)
 
-1. Add a "Many-to-One" relationship field in the comment table
-2. Select the target data table to link to (e.g., tasks table, articles table, etc.)
-3. Set the field name (e.g., "Belongs to Task", "Belongs to Article", etc.)
+## Use in pages
+
+Comment collections are usually used through Comment blocks. Add a Comment block to a details page, popup, or record page of a business collection to let users comment on the current record.
+
+![Enable the Comments collection](https://static-docs.nocobase.com/Solution/demoE3v1-20.gif)
+
+| Configuration location | Use |
+| --- | --- |
+| [Details block](../../interface-builder/blocks/data-blocks/details.md) | Shows a comment entry in business-record details. |
+| [Form block](../../interface-builder/blocks/data-blocks/form.md) | Uses the comment relation field in business-collection editing flows. |
+| Comment block | Displays the comment list and lets users post and reply to comments. |
+
+## Edit configuration
+
+In the collection list, click **Edit** next to a Comment collection to change its display name, category, description, simple pagination mode, **Record unique key**, and other settings.
+
+After a Comment collection is in use, do not casually change its comment-content field or reply-relation field. Comment blocks, permissions, workflows, and APIs might depend on these fields.
 
-### Using Comment Blocks on Pages
+## Delete a collection
 
-![Enable Comments Collection](https://static-docs.nocobase.com/Solution/demoE3v1-20.gif)
+In the collection list, click **Delete** next to a Comment collection to delete it.
 
-1. Go to the page where you want to add comment functionality
-2. Add a block in the details or popup of the target record
-3. Select the "Comments" block type
-4. Choose the comment collection you just created
+Deleting a Comment collection deletes comment records, reply relations, and related collection metadata. Before deleting it, confirm whether relation fields in business collections, Comment blocks, permissions, workflows, or APIs still depend on it.
 
+:::danger Warning
 
-### Typical Use Cases
+Deleting a Comment collection removes comment data from existing business records. Comments often contain collaboration history and processing opinions. Confirm whether the data needs to be backed up or archived before proceeding.
 
-- **Task Management Systems**: Team members discuss and provide feedback on tasks
-- **Content Management Systems**: Readers comment and interact with articles
-- **Approval Workflows**: Approvers annotate and provide opinions on application forms
-- **Customer Feedback**: Collect customer reviews of products or services
+:::
 
-## Notes
+## Related links
 
-- Comment collection is a commercial plugin feature and requires the comments plugin to be enabled
-- It's recommended to set appropriate permissions for the comment table to control who can view, create, and delete comments
-- For scenarios with a large number of comments, it's recommended to enable pagination for better performance
+- [General collection](../data-source-main/general-collection.md) - General configuration and block usage.
+- [Relation fields](../data-modeling/collection-fields/associations/index.md) - Learn how business collections relate to Comment collections.
+- [Comments plugin](../../plugins/@nocobase/plugin-comments/index.md) - Learn about Comment blocks and commenting capabilities.
+- [Multi-space](../../multi-app/multi-space/index.md) - Learn about the Space field and data isolation by space.

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

@@ -1,58 +1,179 @@
 ---
 pkg: "@nocobase/plugin-collection-sql"
+title: "SQL collection"
+description: "Create a collection from SQL query results. Configure field sources, field mapping, and Record unique key for joins, aggregations, and reports."
+keywords: "SQL collection,SQL query,field mapping,report,NocoBase"
 ---
 
-# SQL Collection
+# SQL collection
 
 ## Introduction
 
-The SQL collection provides a powerful method for retrieving data using SQL queries. By extracting data fields through SQL queries and configuring the associated field metadata, users can utilize these fields as though they were working with a standard table. This feature is particularly beneficial for scenarios involving complex join queries, statistical analysis, and more.
+Write a SQL query to create an SQL collection. It does not create a real database table. NocoBase reads the query result and makes it available in Tables, Details, Charts, and Workflows. It is suitable for aggregate data and statistical reports.
 
-## User Manual
+:::warning Note
 
-### Creating a New SQL Collection
+SQL collections support only `SELECT` statements and `WITH ... SELECT` statements. They support query display only and do not support creating, editing, or deleting data.
 
-<img src="https://static-docs.nocobase.com/202405191452918.png"/>
+:::
 
-1.  Enter your SQL query in the provided input box and click Execute. The system will analyze the query to determine the tables and fields involved, automatically extracting the relevant field metadata from the source tables.
+## Create an SQL collection
 
-<img src="https://static-docs.nocobase.com/202405191453556.png"/>
+1. Open the data-source home page from the **Data sources** menu in system settings.
+2. Select the **Main** data source in the data-source list and click **Configure** to open the main database.
+3. In main database management, click **Create collection** and select **SQL collection**.
 
-2.  If the system's analysis of the source tables and fields is incorrect, you can manually select the appropriate tables and fields to ensure the correct metadata is used. Start by selecting the source table, then choose the corresponding fields in the field source section below.
+![Configure the Main data source](https://static-docs.nocobase.com/configure_main_datasource.png)
+![Create an SQL collection](https://static-docs.nocobase.com/create_sql_collection.png)
+![Configure an SQL collection](https://static-docs.nocobase.com/create_sql_collection_configure.png)
 
-<img src="https://static-docs.nocobase.com/202405191453579.png"/>
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed for the SQL collection, such as `Sales summary` or `Inventory alert`. Use a name that explains the meaning of the query result. |
+| Collection name | The identifier of the SQL collection in NocoBase, used internally by APIs, relation fields, permissions, and workflows. It is generated automatically and can be changed manually. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Categories | Collection categories affect only organization in Data source management; they do not change the SQL query. |
+| Description | A collection description. State which data the SQL queries, who maintains it, and which page or report uses it. |
+| Record unique key | The unique identifier for a record. SQL query results have no actual primary key, so choose a field or combination of fields that can uniquely locate a record. Without it, blocks might not view records correctly. |
+| SQL | The query used by the SQL collection. NocoBase executes this SQL, configures fields from the result, and uses the result as a collection. |
+| Source collections | The sources of SQL query result fields. This relates result fields to fields in existing collections so that NocoBase can identify field sources and interface types. |
+| Fields | Field-mapping settings. Confirm the name, source, interface type, and display name for each field. |
+| Preview | Preview SQL query results. Before saving, confirm that field mappings and display results meet expectations. |
 
-3.  For fields that do not have a direct source, the system will infer the field type based on the data type. If this inference is incorrect, you can manually select the proper field type.
+### Write the SQL query
 
-<img src="https://static-docs.nocobase.com/202405191454703.png"/>
+Enter the SQL query and click **Execute** to run it and attempt to parse returned fields and source collections. Clicking **Execute** is used only for preview and field parsing. After confirming that the SQL query is valid, click **Confirm** before the form can submit it as the confirmed query.
 
-4.  As you configure each field, you can preview its display in the preview area, allowing you to see the immediate impact of your settings.
+![Execute a SQL statement](https://static-docs.nocobase.com/202405191453556.png)
 
-<img src="https://static-docs.nocobase.com/202405191455439.png"/>
+:::tip Tip
 
-5.  After you have completed the configuration and confirmed that everything is correct, click the Confirm button below the SQL input box to finalize the submission.
+`Source collections` are source collections inferred from the SQL query. NocoBase identifies which existing collections most query-result fields originate from and limits the selectable `Field source` values during field mapping.
 
-<img src="https://static-docs.nocobase.com/202405191455302.png"/>
+The inference result helps configure a query quickly. If the SQL query contains aliases, subqueries, calculated fields, aggregate functions, or complex joins, the result might be incomplete, inaccurate, or impossible to infer. You can specify `Source collections` manually.
 
-### Editing
+:::
 
-1.  If you need to modify the SQL query, click the Edit button to directly alter the SQL statement and reconfigure the fields as needed.
+### Field mapping
 
-2.  To adjust the field metadata, use the Configure Fields option, which allows you to update the field settings just as you would for a regular table.
+Field mapping must be confirmed after creating an SQL collection. An SQL query result only tells NocoBase which columns it returns. To use those columns like ordinary fields in the interface, confirm a `Field source` or configure the `Field interface` and field display name.
 
-### Synchronization
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
 
-If the SQL query remains unchanged but the underlying database table structure has been modified, you can synchronize and reconfigure the fields by selecting Configure Fields - Sync from Database.
+![Configure an SQL field source](https://static-docs.nocobase.com/202405191453579.png)
+![Configure an SQL field interface](https://static-docs.nocobase.com/202405191454703.png)
 
-<img src="https://static-docs.nocobase.com/202405191456216.png"/>
+| Setting | Description |
+| --- | --- |
+| Field source | Select the existing collection and field from which the SQL result field originates. After choosing a source, NocoBase can reuse its Field interface. |
+| Field interface | Confirm how the field is displayed and entered in pages, such as Input, Number, Date, or Select. |
+| Field display name | The name displayed for the field. Use a name that business users can recognize. |
 
-### SQL Collection vs. Linked Database Views
+For example, if an SQL query returns `customers.name as customer_name` and it comes from the **Customer name** field in the Customers collection, map it to that field. NocoBase can then reuse the source field's title and interface configuration.
 
-| Template Type | Best Suited For | Implementation Method | Support for CRUD Operations |
-| :--- | :--- | :--- | :--- |
-| SQL | Simple models, lightweight use cases<br />Limited interaction with the database<br />Avoiding maintenance of views<br />Prefer UI-driven operations | SQL subquery | Not Supported |
-| Connect to database view | Complex models<br />Requires database interaction<br />Data modification needed<br />Requires stronger and more stable database support | Database view | Partially Supported |
+For a calculated result such as `count(*) as total` or `sum(amount) as amount_total`, there is normally no explicit source field, so choose an appropriate Field interface manually.
 
-:::warning
-When using SQL collection, be sure to select tables that are manageable within NocoBase. Using tables from the same database that are not connected to NocoBase may lead to inaccurate SQL query parsing. If this is a concern, consider creating and linking to a view.
-:::
+:::tip Tip
+
+`Field source` depends on `Source collections`. Select source collections first so that source fields under those collections appear in the field-mapping table.
+
+When field inference identifies a `Field source`, NocoBase preferentially reuses the source field's Field interface. When it cannot infer a source field, specify `Field source` manually. When the inferred result does not match the business meaning, remove `Field source`, specify another source manually, or select the `Field interface` and configure the `Field display name` manually.
+
+:::
+
+### Record unique key
+
+An SQL collection requires a Record unique key. Without one, you cannot create blocks in pages or view records correctly. You can select one field or a combination of fields as the unique key. Suitable Record unique key fields usually meet these conditions:
+
+- Each row in the query result is unique
+- Field values are stable and do not change due to pagination, sorting, or statistical-calculation changes
+- Fields are not empty
+- Fields are always returned by the query result
+
+For a single-table query result, return the original table primary key first. For a query result based on multi-table joins or aggregations, retain a stable business ID in the SQL or return several fields that can jointly locate a record.
+
+:::warning Note
+
+Do not use values such as `row_number()` that change with sorting, filtering, or aggregation scope as a long-term stable Record unique key. When a Record unique key changes, page blocks, permissions, workflows, and external APIs might not locate the same record.
+
+:::
+
+### Preview query results
+
+Before saving, use **Preview** to inspect SQL query results. Check the following:
+
+- SQL executes normally
+- Returned fields are complete
+- Field interface and display name match the business meaning
+- A Record unique key exists and is unique
+- The query result is suitable for page display
+
+![Preview SQL collection results](https://static-docs.nocobase.com/202405191455439.png)
+
+## Configure fields
+
+After creating an SQL collection, click **Configure fields** beside it in the collection list to open field settings. Field settings maintain the fields in the SQL collection, how they display in the interface, and how SQL query results map to NocoBase Field interfaces.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+### Change the UI type
+
+After creating an SQL collection, you can still adjust field-interface configuration in field settings. This page is mainly used to change the Field interface, display name, description, and field-specific settings.
+
+![Configure SQL collection fields](https://static-docs.nocobase.com/configure_field_sql.png)
+
+Use it in these situations:
+
+- The Field interface set when creating the SQL collection is incorrect
+- A field display name does not follow business terminology and needs a clearer name
+- The business meaning of a query-result field changes and its display method needs confirmation again
+- Field descriptions or field-specific settings need adjustment, such as Select options
+
+### Synchronize from database
+
+If the SQL query is unchanged but the underlying table structure or fields change, open **Configure fields** and click **Sync from database** to run the SQL again and synchronize fields. For field mapping, see [Create an SQL collection](#field-mapping).
+
+![Synchronize SQL collection fields](https://static-docs.nocobase.com/202405191456216.png)
+
+### Edit a field
+
+Click **Edit** beside a field to edit its configuration. Field editing is suitable for adjusting how a field displays and is used in NocoBase, such as its display name, description, validation rules, or field-specific settings.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+:::warning Note
+
+Editing field configuration does not change the SQL query, source-table column name, source-table column definition, or database index. To change the actual columns in a query result, change the SQL query first, then run it again and synchronize fields.
+
+:::
+
+### Delete a field
+
+Click **Delete** beside a field to delete it. Deleting a field removes only the field stored in NocoBase; it does not delete the SQL query or actual columns in source tables.
+
+[Learn more about field configuration](../data-modeling/collection-fields/index.md)
+
+:::warning Note
+
+Deleting a field can affect page blocks, filters, sorting, permissions, workflows, APIs, and existing configuration. Before deleting it, confirm whether the field is still used. If the SQL query still returns the column, NocoBase might identify the field again when you later run **Sync from database**.
+
+:::
+
+## Edit an SQL collection
+
+In the collection list, click **Edit** beside an SQL collection to adjust its metadata and runtime settings in NocoBase. Editing uses mostly the same settings as creating an SQL collection, except that `Collection name` cannot be changed.
+
+When the SQL query changes, click **Execute** again and confirm the field mapping, Record unique key, and preview result.
+
+![Edit an SQL collection](https://static-docs.nocobase.com/202405191455302.png)
+
+:::warning Note
+
+Changing an SQL query can change field names, field mapping, or the Record unique key. After changing it, recheck whether page blocks, charts, permissions, and workflows still work.
+
+:::
+
+## Delete an SQL collection
+
+In the collection list, click **Delete** beside an SQL collection. This deletes only the SQL collection configuration and fields in NocoBase; it does not delete underlying source tables or data in those tables.
+
+You can also select multiple SQL collections and delete them together. Before deleting, check whether page blocks, charts, permissions, workflows, or external APIs still use the SQL collection.

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

@@ -1,18 +1,106 @@
 ---
 pkg: "@nocobase/plugin-collection-tree"
+title: "Tree collection"
+description: "Use a Tree collection for hierarchical data such as organizational structures, product categories, regional hierarchies, and department directories. It uses the adjacency-list model to store parent-child relationships."
+keywords: "Tree collection,tree collection,adjacency list,hierarchical data,NocoBase"
 ---
 
-# Tree Collection
+# Tree collection
 
 ## Introduction
 
-A tree structure collection is a data collection design pattern used for organizing hierarchical data. This collection structure mirrors a tree, where each data item may have one or more child items, and those child items can, in turn, have their own descendants.
+Tree collections are suitable for data with parent-child relationships, such as organizational structures, product categories, regional hierarchies, department directories, and knowledge-base directories. A Tree collection uses the adjacency-list model to store parent-child relationships, and each record can point to its own parent node.
 
-## User Manual
+You can create Tree collections only from the main data source. External databases, REST API data sources, and External NocoBase data sources do not support creating Tree collections.
 
+## Use cases
 
-![20240324143228](https://static-docs.nocobase.com/20240324143228.png)
+Tree collections are suitable for these business scenarios:
 
+- Company organizational structures and department hierarchies
+- Product categories, knowledge-base directories, and document directories
+- Province, city, and district hierarchies; sales territories; and service-outlet hierarchies
+- BOM categories, equipment categories, and asset categories
 
+## Create and configure
 
-![20240324143555](https://static-docs.nocobase.com/20240324143555.png)
+In the main data source, click **Create collection** and select **Tree collection** to create a Tree collection.
+
+![Create a Tree collection](https://static-docs.nocobase.com/20240324143228.png)
+
+The creation settings for a Tree collection are mostly the same as those for a general collection.
+
+| Setting | Description |
+| --- | --- |
+| Collection display name | The name displayed for the collection, such as `Organization`, `Product categories`, or `Regional hierarchy`. |
+| Collection name | The collection identifier used internally by APIs, relation fields, permissions, and workflows. |
+| Inherits | Select a parent collection to inherit. This setting is visible only when the main database is PostgreSQL. |
+| Categories | Collection categories affect only organization in Data source management; they do not change the collection structure. |
+| Description | A description of the collection. State which hierarchy data it stores, who maintains it, and which page filters use it. |
+| Preset fields | Preset fields. Keep system fields and Tree collection built-in fields when creating a Tree collection. |
+
+### Built-in fields
+
+After a Tree collection is created, it usually includes the following built-in fields. `parentId`, `parent`, and `children` store the hierarchy.
+
+| Field | Field name | Description |
+| --- | --- | --- |
+| ID | `id` | The default primary key that uniquely identifies a record. |
+| Created at | `createdAt` | Automatically records when the record was created. |
+| Created by | `createdBy` | Automatically records the user who created the record. |
+| Updated at | `updatedAt` | Automatically records when the record was last updated. |
+| Updated by | `updatedBy` | Automatically records the user who last updated the record. |
+| Parent ID | `parentId` | Stores the parent-node ID. It is usually empty for root nodes. |
+| Parent | `parent` | A many-to-one relation field that points to a parent node in the current collection. |
+| Children | `children` | A one-to-many relation field representing child nodes of the current node. |
+| Space | `space` | Available after enabling the [Multi-space plugin](../../multi-app/multi-space/index.md). It isolates data by space and does not appear when Multi-space is not enabled. |
+
+![Tree collection built-in fields](https://static-docs.nocobase.com/20240324143555.png)
+
+:::warning Note
+
+Avoid circular relationships in Tree collection data. For example, do not make B the parent of A and A the parent of B. Circular relationships cause incorrect tree displays and filter results.
+
+:::
+
+### Primary key field
+
+Like a general collection, a Tree collection needs a primary key. Tree relation fields use the parent-node ID to relate to the primary-key record in the same collection.
+
+If a Tree collection has no primary key, set **Record unique key** when editing the collection. Otherwise, blocks might not view or edit records correctly, and tree displays might not locate nodes reliably.
+
+## Use in pages
+
+A Tree collection can use most of the data blocks for a [general collection](../data-source-main/general-collection.md) to create, read, update, and delete records. It can also work with tree-specific features:
+
+| Block | Use |
+| --- | --- |
+| [Table block](../../interface-builder/blocks/data-blocks/table.md#enable-tree-table) | Displays hierarchical records for viewing and maintaining parent-child structures. |
+| [Form block](../../interface-builder/blocks/data-blocks/form.md) | Creates or edits one Tree node record. |
+| [Details block](../../interface-builder/blocks/data-blocks/details.md) | Views details of one Tree node. |
+| [Tree Filter block](../../interface-builder/blocks/filter-blocks/tree.md) | Filters other data blocks with a tree structure. It is commonly used for category, organization, regional, and other hierarchical filters. |
+
+## Edit configuration
+
+In the collection list, click **Edit** next to a Tree collection to change its display name, category, description, simple pagination mode, **Record unique key**, and other settings.
+
+Do not delete Tree collection parent-child relation fields or repurpose them casually. To adjust the hierarchy, update parent-node relations in the record data first.
+
+## Delete a collection
+
+In the collection list, click **Delete** next to a Tree collection to delete it.
+
+Deleting a Tree collection deletes its collection metadata, actual database table, and hierarchy data. Before deleting it, confirm whether page blocks, Tree Filter blocks, relation fields, permissions, workflows, or APIs still depend on it.
+
+:::danger Warning
+
+Tree collections are often used as filter conditions for other blocks. After deleting a Tree collection, related Tree Filter blocks and page configurations that depend on its category hierarchy might stop working.
+
+:::
+
+## Related links
+
+- [General collection](../data-source-main/general-collection.md) - General configuration and block usage.
+- [Table block](../../interface-builder/blocks/data-blocks/table.md) - Enable Tree collection display in a table.
+- [Tree Filter block](../../interface-builder/blocks/filter-blocks/tree.md) - Filter data with a tree structure.
+- [Multi-space](../../multi-app/multi-space/index.md) - Learn about the Space field and data isolation by space.