@nocobase/plugin-ai 2.2.0-beta.9 → 3.0.0-alpha.1

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

@@ -0,0 +1,245 @@
+---
+title: "REST API data source"
+description: "Connect REST API data and map RESTful resources to collections. Configure List, Get, Create, Update, and Destroy API mappings to support CRUD operations."
+keywords: "REST API data source,external API,API mapping,collection mapping,NocoBase"
+---
+
+# REST API data source
+
+<PluginInfo commercial="true" name="data-source-rest-api"></PluginInfo>
+
+## Introduction
+
+Use this data source to connect data provided by REST APIs.
+
+## 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 REST API source
+
+After activating the plugin, choose **REST API** from the **Add new** menu in Data source management.
+
+![Choose the REST API data source](https://static-docs.nocobase.com/20240721171420.png)
+
+Configure the REST API source.
+
+![Configure the REST API source](https://static-docs.nocobase.com/20240721171507.png)
+
+## Add a collection
+
+A RESTful resource maps to a NocoBase collection. For example, consider a Users resource:
+
+```bash
+GET /users
+POST /users
+GET /users/1
+PUT /users/1
+DELETE /users/1
+```
+
+It maps to the following NocoBase API configuration:
+
+```bash
+GET /users:list
+POST /users:create
+POST /users:get?filterByTk=1
+POST /users:update?filterByTk=1
+POST /users:destroy?filterByTk=1
+```
+
+For the complete NocoBase API design specification, see the API documentation.
+
+![API documentation entry](https://static-docs.nocobase.com/20240716213344.png)
+
+See the **NocoBase API - Core** section.
+
+![NocoBase API - Core](https://static-docs.nocobase.com/20240716213258.png)
+
+The REST API data-source collection is configured as follows.
+
+### List
+
+Configure the API mapping for retrieving a resource list.
+
+![Configure the List API](https://static-docs.nocobase.com/20251201162457.png)
+
+### Get
+
+Configure the API mapping for retrieving resource details.
+
+![Configure the Get API](https://static-docs.nocobase.com/20251201162744.png)
+
+### Create
+
+Configure the API mapping for creating a resource.
+
+![Configure the Create API](https://static-docs.nocobase.com/20251201163000.png)
+
+### Update
+
+Configure the API mapping for updating a resource.
+
+![Configure the Update API](https://static-docs.nocobase.com/20251201163058.png)
+
+### Destroy
+
+Configure the API mapping for deleting a resource.
+
+![Configure the Destroy API](https://static-docs.nocobase.com/20251201163204.png)
+
+List and Get are required API mappings.
+
+## Debug APIs
+
+### Request parameter integration
+
+For example, configure pagination parameters for the List API. If the third-party API itself does not support pagination, NocoBase paginates the returned list data.
+
+![Configure List pagination parameters](https://static-docs.nocobase.com/20251201163500.png)
+
+Only variables added to the API take effect.
+
+| Third-party API parameter | NocoBase parameter |
+| --- | --- |
+| page | {{request.params.page}} |
+| limit | {{request.params.pageSize}} |
+
+Click **Try it out** to debug the API and inspect the response.
+
+![Debug an API request](https://static-docs.nocobase.com/20251201163635.png)
+
+<video width="100%" height="440" controls>
+      <source src="https://static-docs.nocobase.com/20241121211034.mp4" type="video/mp4">
+</video>
+
+### Response format conversion
+
+The response format of a third-party API might not match the NocoBase standard. Convert it before it can be displayed correctly in the client.
+
+![Configure response conversion](https://static-docs.nocobase.com/20251201164529.png)
+
+Adjust the conversion rules according to the third-party API response so that it matches the NocoBase output standard.
+
+![Response conversion rules](https://static-docs.nocobase.com/20251201164629.png)
+
+Debugging flow.
+
+![Response conversion debugging flow](https://static-docs.nocobase.com/20240717110051.png)
+
+### Error information conversion
+
+When a third-party API returns an error, its error response might not match the NocoBase standard. Convert it before the client can display it correctly.
+
+![Configure error conversion](https://static-docs.nocobase.com/20251201170545.png)
+
+When error conversion is not configured, the error is converted by default to an error message that includes the HTTP status code.
+
+![Default error conversion](https://static-docs.nocobase.com/20251201170732.png)
+
+After configuring error conversion to match the NocoBase output standard, the client can display third-party API error information correctly.
+
+![Error conversion rules](https://static-docs.nocobase.com/20251201170946.png)
+![Converted third-party API error](https://static-docs.nocobase.com/20251201171113.png)
+
+## Variables
+
+The REST API data source provides three variable categories for API integration:
+
+- Data-source custom variables
+- NocoBase requests
+- Third-party responses
+
+### Data-source custom variables
+
+![Data-source custom variables](https://static-docs.nocobase.com/20240716221937.png)
+
+![Configure a data-source custom variable](https://static-docs.nocobase.com/20240716221858.png)
+
+### NocoBase requests
+
+- Params: URL query parameters (Search Params). The available Params differ between APIs
+- Headers: request headers, primarily providing NocoBase custom `X-` information
+- Body: the request body
+- Token: the API token of the current NocoBase request
+
+![NocoBase request variables](https://static-docs.nocobase.com/20251201164833.png)
+
+### Third-party responses
+
+Currently, only the response Body is available.
+
+![Third-party response variables](https://static-docs.nocobase.com/20251201164915.png)
+
+The available variables for each API integration are as follows.
+
+### List
+
+| Parameter | Description |
+| --- | --- |
+| request.params.page | Current page number |
+| request.params.pageSize | Number of records per page |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
+| request.params.sort | Sorting rules. They must use the NocoBase Sort format. |
+| request.params.appends | Fields loaded on demand, typically for loading relationship fields on demand |
+| request.params.fields | Fields that the API returns, as an allowlist |
+| request.params.except | Fields to exclude, as a denylist |
+
+### Get
+
+| Parameter | Description |
+| --- | --- |
+| request.params.filterByTk | Required. Usually the ID of the current record |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
+| request.params.appends | Fields loaded on demand, typically for loading relationship fields on demand |
+| request.params.fields | Fields that the API returns, as an allowlist |
+| request.params.except | Fields to exclude, as a denylist |
+
+### Create
+
+| Parameter | Description |
+| --- | --- |
+| request.params.whiteList | Allowlist |
+| request.params.blacklist | Denylist |
+| request.body | Initial data for creating the record |
+
+### Update
+
+| Parameter | Description |
+| --- | --- |
+| request.params.filterByTk | Required. Usually the ID of the current record |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
+| request.params.whiteList | Allowlist |
+| request.params.blacklist | Denylist |
+| request.body | Data to update |
+
+### Destroy
+
+| Parameter | Description |
+| --- | --- |
+| request.params.filterByTk | Required. Usually the ID of the current record |
+| request.params.filter | Filter conditions. They must use the NocoBase Filter format. |
+
+## Configure fields
+
+Extract field metadata (Fields) from data returned by the adapted resource CRUD APIs and use it as the fields of the collection.
+
+![Extract collection fields](https://static-docs.nocobase.com/20240716223636.png)
+
+Extract field metadata.
+
+![Extract field metadata](https://static-docs.nocobase.com/20251201165133.png)
+
+Fields and preview.
+
+![Fields and preview](https://static-docs.nocobase.com/20240716224403.png)
+
+Edit fields in the same way as for other data sources.
+
+![Edit REST API fields](https://static-docs.nocobase.com/20240716224704.png)
+
+## Add REST API data-source blocks
+
+After configuring the collection, you can add blocks to pages.
+
+![Add a REST API data-source block](https://static-docs.nocobase.com/20240716225120.png)

package/dist/ai/docs/nocobase/data-sources/field-attachment-url/index.md

@@ -1,27 +1,115 @@
 ---
-pkg: "@nocobase/plugin-field-attachment-url"
+title: "Attachment URL"
+description: "The Attachment URL field stores external file addresses for files hosted outside NocoBase."
+keywords: "Attachment URL,attachmentUrl,field,Field interface,NocoBase"
 ---
 
-# Data Field: Attachment (URL)
+# Attachment URL
 
 ## Introduction
 
-Supports attachments in URL format.
+In NocoBase, **Attachment URL** stores an external file access address.
 
-## Installation
+It is suitable when files are already stored in an external system, object storage, or CDN and NocoBase only needs the access address. Use Attachment when NocoBase needs to upload and manage files, or URL for an ordinary web address.
 
-This plugin is a commercial plugin.
+## Use cases
 
-## User Manual
+Attachment URL fields are suitable for these business scenarios:
 
-### Field Configuration
+- Files hosted in external systems
+- Object-storage file addresses
+- CDN image and document addresses
+- External attachments referenced by business records
 
-![20241017092323](https://static-docs.nocobase.com/20241017092323.png)
+## Create and configure
 
-### External Data Source
+On the collection's **Configure fields** page, click **Add field** and select **Attachment URL** to create this field.
 
-![20241017092456](https://static-docs.nocobase.com/20241017092456.png)
+![Configure a Attachment URL field](https://static-docs.nocobase.com/20241017092323.png)
 
-### Interface
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Attachment URL uses `attachmentUrl`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `File address`, `Image URL`, or `External attachment`. Use a name that business users can recognize. |
+| Field name | The field identifier used internally by APIs, relation fields, permissions, and workflows. It usually cannot be changed after creation. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | The data-layer type. Attachment URL uses `string` by default. |
+| Default value | The default value. When a new record has no value, NocoBase can fill this value automatically. |
+| Validation rules | Validation rules. Supports URL-format, length, and required validation. |
+| Description | A field description. Record the field meaning, entry requirements, data source, or maintainer. |
 
-![20241017092759](https://static-docs.nocobase.com/20241017092759.png)
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+The default behavior of a Attachment URL field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `attachmentUrl`. |
+| Default Field type | `string`. |
+| Available Field types | `string`, `text`. |
+| Page component | Uses an attachment-URL component for entry and display. |
+| Filtering | Supports URL and text filters where supported by the data source. |
+| Sorting | Supports sorting in Table blocks where supported by the data source. |
+| Validation | Supports URL-format, length, and required validation. |
+
+## Edit configuration
+
+After creation, click **Edit** beside the field to edit its configuration. Edit fields to adjust how they are displayed and used in NocoBase, such as the display name, description, default value, validation rules, or field-specific settings.
+
+When a field comes from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The field identifier normally cannot be changed in the edit form after creation. |
+| Field interface | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Changes affect page input, display, and validation. |
+| Field type | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Confirm that existing values can be used by the new type first. |
+| Default value | Yes | Adjusts the default value for new records. |
+| Validation rules | Yes | Adjusts field validation rules. |
+| Description | Yes | Adds the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Changing a Field type or Field interface is more than changing a display name. It affects field storage, input components, validation rules, filters, and workflow-variable usage. When the field contains substantial existing data, confirm that its data format is compatible first.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a Attachment URL field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Attachment URL field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the corresponding data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced by business configuration before deleting it.
+
+:::
+
+## Use in pages
+
+Attachment URL fields are suitable for external-file display, preview, and download.
+
+![Use a Attachment URL field in a page](https://static-docs.nocobase.com/20260709231803.png)
+
+![Attachment URL configuration](https://static-docs.nocobase.com/20241017092456.png)
+![Attachment URL configuration](https://static-docs.nocobase.com/20241017092759.png)
+
+| Scenario | Use |
+| --- | --- |
+| Form block | Enter an external file address. |
+| Details block | Display, preview, or download an external file. |
+| Table block | Display external attachment values. |
+| Workflows and APIs | Pass external file addresses to business logic. |
+
+## Related links
+
+- [Fields](../data-modeling/collection-fields/index.md) - Learn about field categories and mapping.
+- [General collection](../data-source-main/general-collection.md) - Create and manage fields in a collection.
+- [Attachment](../file-manager/field-attachment.md) - Upload and manage files in NocoBase.
+- [URL](../data-modeling/collection-fields/basic/url.md) - Store ordinary web addresses.

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

@@ -1,99 +1,100 @@
 ---
 pkg: "@nocobase/plugin-field-encryption"
+title: "Field encryption"
+description: "Encrypt sensitive business data such as phone numbers, email addresses, and card numbers before storing it as ciphertext in the database."
+keywords: "field encryption,Encryption,sensitive data,ciphertext storage,NocoBase"
 ---
 
 # Encryption
 
 ## Introduction
 
-You can encrypt sensitive business data—such as customer phone numbers, email addresses, or card numbers—so that it is stored in the database as ciphertext.
+Sensitive business data, such as customer phone numbers, email addresses, and card numbers, can be encrypted and stored in the database as ciphertext.
 
-![20251104192513](https://static-docs.nocobase.com/20251104192513.png)
+![Encrypted field](https://static-docs.nocobase.com/20251104192513.png)
 
-## Encryption Method
+## Encryption method
 
-:::warning
-The plugin automatically generates an `application key`, which is stored under the directory `/storage/apps/main/encryption-field-keys`.
+:::warning Note
 
-Each `application key` is saved as a file whose name is the key ID, with the `.key` extension. Do not rename these files.
+The plugin generates an **application key** automatically. The key is stored in `/storage/apps/main/encryption-field-keys`.
 
-Keep your `application key` files safe. If an `application key` file is lost, encrypted data cannot be decrypted.
+An application-key file uses the key ID as its file name and has the `.key` extension. Do not change the file name.
+
+Keep application-key files safe. If an application-key file is lost, encrypted data cannot be decrypted.
+
+When the plugin is enabled for a sub-application, the default key directory is `/storage/apps/${sub-application-name}/encryption-field-keys`.
 
-If the plugin is enabled in a sub-application, the key is stored under:
-`/storage/apps/${sub-app-name}/encryption-field-keys`
 :::
 
-### How It Works
+### How it works
 
-This plugin uses an **envelope encryption** scheme.
+The plugin uses envelope encryption.
 
-![20251118151143](https://static-docs.nocobase.com/20251118151143.png)
+![Envelope encryption](https://static-docs.nocobase.com/20251118151339.png)
 
-### Application and Field Key Creation
+### Key creation flow
 
-  1. When you create your first encrypted field, NocoBase automatically generates a 32-byte `application key`, stores it in the default directory, and encodes it in base64.
-1. Each time you create a new encrypted field, the system generates a random 32-byte `field key`, encrypts it using the `application key` and a randomly generated 16-byte `field IV` (AES), and stores the encrypted result in the `options` column of the `fields` table.
+1. When you create an encrypted field for the first time, the system generates a 32-byte **application key** and saves it, Base64 encoded, in the default storage directory.
+2. When you create an encrypted field, the system generates a random 32-byte **field key**. It encrypts this key with the application key and a randomly generated 16-byte **field initialization vector** using AES, then saves it in the `options` field of the `fields` table.
 
-### Field Encryption Process
+### Field encryption flow
 
-   1. When writing data to an encrypted field, NocoBase retrieves the encrypted `field key` and `field IV` from the `options` column of the `fields` table.
-2. The system decrypts the `field key` using the `application key` and `field IV`. It then encrypts the actual data using the `field key` and a randomly generated 16-byte `data IV` (AES).
-3. The decrypted `field key` is also used to sign the plaintext using `HMAC-SHA256`, producing a base64-encoded `data signature` (used later for querying).
-4. The 16-byte `data IV` and `ciphertext` are concatenated and encoded in base64.
-5. The base64 `data signature` and base64 `ciphertext` are joined with a `.` separator.
-6. The final string is stored in the database.
+1. When data is written to an encrypted field, the system reads the encrypted field key and field initialization vector from the `options` field of the `fields` table.
+2. It decrypts the encrypted field key with the application key and field initialization vector, then encrypts the data with the field key and a randomly generated 16-byte **data initialization vector** using AES.
+3. It signs the data with the decrypted field key using HMAC-SHA256, then Base64 encodes the result. This **data signature** is used for data lookup.
+4. It concatenates the 16-byte data initialization vector and encrypted data ciphertext as binary data, then Base64 encodes the result.
+5. It joins the Base64 data signature and Base64 data ciphertext with `.`.
+6. It saves the final concatenated string in the database.
 
-## Environment Variables
+## Environment variable
 
-If you want to specify your own `application key`, you can set the environment variable `ENCRYPTION_FIELD_KEY_PATH`. The plugin will load all `.key` files in this directory as application keys.
+To specify an application key, use the `ENCRYPTION_FIELD_KEY_PATH` environment variable. The plugin loads the file at this path as the application key.
 
-**Application key file requirements:**
+Application-key file requirements:
 
 1. The file extension must be `.key`.
-2. The filename is treated as the key ID; using a UUID is recommended.
-3. The file content must be base64-encoded 32-byte binary data.
+2. The file name is used as the key ID. Use a UUID to keep it unique.
+3. The file content must be Base64-encoded 32-byte binary data.
 
 ```bash
 ENCRYPTION_FIELD_KEY_PATH=/path/to/my/app-keys/270263524860909922913.key
 ```
 
-## Field Configuration
+## Field configuration
+
+![Configure an encrypted field](https://static-docs.nocobase.com/20240802173721.png)
 
-![20240802173721](https://static-docs.nocobase.com/20240802173721.png)
+## Effect on filtering
 
-## How Encryption Affects Filtering
+Encrypted fields support only equals, does not equal, exists, and does not exist filters.
 
-Encrypted fields only support the following filter operators:
+![Encrypted field filtering](https://static-docs.nocobase.com/20240802174042.png)
 
-* Equal to
-* Not equal to
-* Exists
-* Does not exist
+Data is filtered as follows:
 
-![20240802174042](https://static-docs.nocobase.com/20240802174042.png)
+1. Read the field key for the encrypted field and decrypt it with the application key.
+2. Sign the user-entered lookup text with the field key using HMAC-SHA256.
+3. Append `.` to the signed lookup text and perform a prefix-match lookup against the encrypted database value.
 
-### How Filtering Works Internally
+## Key rotation
 
-1. Retrieve the encrypted `field key` and decrypt it using the `application key`.
-2. Use the `field key` to generate an `HMAC-SHA256 signature` for the user’s input.
-3. Concatenate the signature with `.` and perform a **prefix search** on the encrypted field value in the database.
+:::warning Note
 
-## Key Rotation
+Before using `nocobase key-rotation`, confirm that the application has loaded this plugin.
 
-:::warning
-Before running the key rotation command `nocobase key-rotation`, ensure that this plugin is already enabled in the application.
 :::
 
-When migrating an application to a new environment, you may want to replace the old application key. You can use the `nocobase key-rotation` command to generate a new application key.
+After an application is migrated to a new environment, use `nocobase key-rotation` when you do not want to continue using the old environment's application key.
 
-The command requires the application key from the old environment. After running it, NocoBase generates a new application key and replaces the old one. The new key is stored in the default directory and base64-encoded.
+Key rotation requires the old application's application key. The command generates a new application key, replaces the old key, and saves the new key Base64 encoded in the default storage directory.
 
 ```bash
-# --key-path points to the old application key file corresponding to the encrypted data in the database
+# --key-path specifies the old application-key file corresponding to encrypted database data
 yarn nocobase key-rotation --key-path /path/to/old-app-keys/270263524860909922913.key
 ```
 
-For rotating a sub-application’s key, add the `--app-name` parameter:
+To replace a sub-application application key, add `--app-name` and specify the sub-application `name`.
 
 ```bash
 yarn nocobase key-rotation --app-name a_w0r211vv0az --key-path /path/to/old-app-keys/270263524860909922913.key

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

@@ -1,17 +1,111 @@
 ---
-pkg: "@nocobase/plugin-field-formula"
+title: "Formula"
+description: "The Formula field calculates a field value from an expression."
+keywords: "Formula,formula,field,Field interface,NocoBase"
 ---
 
 # Formula
 
 ## Introduction
 
-## Field Configuration
+In NocoBase, **Formula** calculates a field value from an expression.
 
+It is suitable for amount calculations, score calculations, text concatenation, and conditional calculations. Its value is normally generated by an expression and is not suitable for manual entry. For complex calculations, use a workflow or database view.
 
-![20240512173541](https://static-docs.nocobase.com/20240512173541.png)
+## Use cases
 
+Formula fields are suitable for these business scenarios:
 
-## Example
+- Amount calculations
+- Score calculations
+- Text concatenation
+- Conditional calculations
 
-To be added.
+## Create and configure
+
+On the collection's **Configure fields** page, click **Add field** and select **Formula** to create this field.
+
+![Configure a Formula field](https://static-docs.nocobase.com/20240512173541.png)
+
+| Setting | Description |
+| --- | --- |
+| Field interface | The field interface. Formula uses `formula`, which determines how the field is entered and displayed in pages. |
+| Field display name | The name displayed for the field, such as `Order subtotal`, `Overall score`, or `Display name`. Use a name that business users can recognize. |
+| Field name | The field identifier used internally by APIs, relation fields, permissions, and workflows. It usually cannot be changed after creation. It supports only letters, numbers, and underscores, and must begin with a letter. |
+| Field type | The data-layer type. Formula uses `formula` by default. |
+| Default value | The default value. When a new record has no value, NocoBase can fill this value automatically. |
+| Validation rules | Validation rules. Confirm that the formula expression is complete and referenced fields exist. |
+| Description | A field description. Record the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Field names are referenced by page blocks, permissions, workflows, and APIs after creation. Confirm the name before creating the field to avoid later configuration changes.
+
+:::
+
+## Field behavior
+
+The default behavior of a Formula field is as follows:
+
+| Behavior | Description |
+| --- | --- |
+| Default Field interface | `formula`. |
+| Default Field type | `formula`. |
+| Available Field types | `formula`. |
+| Page component | Displays the result calculated from a formula expression. |
+| Filtering | Filtering depends on the formula result and data-source capabilities. |
+| Sorting | Supports sorting where the formula result type permits. |
+| Validation | Confirm that the formula expression is complete and referenced fields exist. |
+
+## Edit configuration
+
+After creation, click **Edit** beside the field to edit its configuration. Edit fields to adjust how they are displayed and used in NocoBase, such as the display name, description, default value, validation rules, or field-specific settings.
+
+When a field comes from a synchronized main-database table, editing usually maps the database field to a NocoBase Field type and Field interface.
+
+| Setting | Can be edited | Description |
+| --- | --- | --- |
+| Field display name | Yes | Changes the name displayed in the interface without changing the field identifier. |
+| Field name | No | The field identifier normally cannot be changed in the edit form after creation. |
+| Field interface | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Changes affect page input, display, and validation. |
+| Field type | Conditional | Main-database fields and synchronized fields can be adjusted during field mapping. Confirm that existing values can be used by the new type first. |
+| Default value | Yes | Adjusts the default value for new records. |
+| Validation rules | Yes | Adjusts field validation rules. |
+| Description | Yes | Adds the field meaning, entry requirements, data source, or maintainer. |
+
+:::warning Note
+
+Changing a Field type or Field interface is more than changing a display name. It affects field storage, input components, validation rules, filters, and workflow-variable usage. When the field contains substantial existing data, confirm that its data format is compatible first.
+
+:::
+
+## Delete field
+
+Click **Delete** beside a Formula field to delete it. You can also select multiple fields and delete them in the main data source.
+
+Deleting a Formula field created in the main database usually also deletes the actual database column and its values. For a synchronized or external-data-source field, the impact depends on the corresponding data source and field origin.
+
+:::danger Warning
+
+Deleting a field can affect page blocks, forms, filters, permissions, workflows, APIs, imports and exports, and existing data. Confirm that the field is no longer referenced by business configuration before deleting it.
+
+:::
+
+## Use in pages
+
+Formula fields are suitable for calculated values in pages, reports, and business logic.
+
+![Use a Formula field in a page](https://static-docs.nocobase.com/20260710151619.png)
+
+
+| Scenario | Use |
+| --- | --- |
+| Details block | Display a calculated value. |
+| Table block | Display and sort a formula result where supported. |
+| Charts | Use a formula result for presentation. |
+| Workflows and APIs | Read calculated values in business logic. |
+
+## Related links
+
+- [Fields](../data-modeling/collection-fields/index.md) - Learn about field categories and mapping.
+- [General collection](../data-source-main/general-collection.md) - Create and manage fields in a collection.