Dataset Collection Tags

Dataset Collection Tags is a Commercial Edition feature in FastGPT. You can attach structured metadata tags (such as Applicable Department, Document Category, Security Level, and Effective Date) to collections (files/documents) in a dataset. Beyond quick filtering and batch management inside the dataset, you can precisely narrow the retrieval scope during Dataset Search in Chat Agents, Simple Apps, and Workflows using Manual Input or Variable Reference.

Why Use Collection Tags?

In real-world scenarios, a single dataset often holds hundreds of documents spanning multiple departments, versions, or confidentiality levels. Relying solely on vector or full-text search can lead to:

• Cross-department noise: An engineer asking about a "project review process" retrieves a marketing campaign review policy.
• Outdated document interference: Legacy policies and new 2026 policies coexist in the dataset, causing outdated rules to be recalled.
• Access & scope isolation: Multiple user groups or external customers share one Q&A assistant, requiring retrieval scope isolation based on user identity.

With Collection Tags, FastGPT first narrows down candidate collections through metadata filtering, and then runs semantic and full-text search strictly within those matched files—significantly improving accuracy and data governance.

Step 1: Plan and Manage Tags

Open your dataset detail page and click the Tag Management button in the top-right corner of the Collection list (requires dataset write permission).

1. Choosing Tag Attributes

Click + Add Tag in the bottom-left corner, enter a tag name (up to 20 characters), and choose a tag attribute. FastGPT supports 3 tag attributes:

2. Preset and Maintain Options

For Options tags, click the gear icon on the right side of the row to open Option Management:

• Add Preset Options: Pre-populate standard category values (e.g., department names) so team members can tag files consistently.
• Rename Options: Renaming an option automatically updates all collections currently using that option—no manual re-tagging required.
• Delete Options: Deleting an option automatically removes that option value from any collections that had it selected.

Step 2: Assign Tags to Collections

Once your tags are defined, you can assign tag values to collections in three ways:

1. Set Tags on a Single Collection

Open the Tag Settings modal on the target file in the collection list:

• Click + Add Tag to attach tags to the file and select options, enter a number, or pick a date.
• Quick Inline Option Creation: When assigning values to an Options tag, you can type a new option name directly into the input box and press Enter to create and bind the option on the fly.
• Need a brand-new tag? Click Tag Management at the bottom-left of the modal to jump straight to tag creation.

2. Batch Modify Tags

To tag or clean up multiple files at once, select the target files in the collection list and click Batch Modify Tags in the bottom floating bar:

The batch modal provides two tabs:

• Batch Add Tags:
  • Options attribute tags: Choose between Append (default)—which keeps each file's existing options and merges the new ones—or Overwrite—which replaces existing options on that tag with the newly selected ones.
  • Number / Date attribute tags: Since each file holds a single value for these attributes, batch adding overwrites the existing value.
• Batch Remove Tags:
  • Aggregates all tags currently bound to the selected files.
  • For Options tags, you can either remove the entire tag or expand the row to remove only specific option values while keeping the rest.

3. Set Tags via OpenAPI When Importing or Updating Collections

When calling OpenAPI endpoints to create or update a collection, pass the tags field directly in the request body:

{
  "datasetId": "69ddb01e2d241386ca47adbe",
  "name": "Employee-Attendance-Policy-2026.pdf",
  "tags": [
    { "tag": "Applicable Dept", "value": ["All", "HR"] },
    { "tag": "Security Level", "value": 1 },
    { "tag": "Effective Date", "value": 1767229200000 }
  ]
}

• If a tag name does not yet exist in the dataset, FastGPT automatically creates it based on the data format of value (string array → Options, number → Number).

Step 3: Filter Collections by Tag in the File List

Click the Tag | All filter button above the collection table header to filter files by tag:

• Select a tag in the left column (the badge shows how many values are selected under that tag), and search/check specific values in the right column.
• Filtering Logic:
  • Multiple values within the same tag: Combined with OR (matches files containing any of the checked values).
  • Across different tags: Combined with AND (matches files satisfying all selected tag filters simultaneously).

Step 4: Filter by Tags During Dataset Search

When building an application or workflow, enabling Tag Filter restricts retrieval to collections that satisfy your filter rules.

1. Where to Configure

• Workflow: On the Dataset Search node, click Enable in the top-right corner of the Tag Filter section.
• Chat Agent / Simple App: In the Dataset section of the app configuration page, click Params to open the Dataset Search Configuration modal, and switch to the Tag Filter tab.

2. Condition Structure (Custom Tags + System Tags)

The filter builder is divided into two sections, combined with a fixed AND relationship between them:

1. Custom Tags:
   • Click + Add Filter Condition to select a custom tag, comparison operator, and target value (supports switching between Manual Input and Variable Reference).
   • When multiple custom tag conditions exist, click the AND / OR toggle in the top-left corner of the section to switch whether collections must match all (AND) or any (OR) of the custom tag conditions.
2. System Tags:
   • Filter by built-in collection attributes (multiple system tag conditions are always combined with AND):
     • Creation Time: Filter by the file's creation time in the dataset using >= or <=.
     • Collection ID: Uses the in operator with a referenced variable containing allowed collection IDs (or folder IDs, which automatically expand to include all descendant collections).

3. Supported Operators by Tag Attribute

Advanced: Passing a Complete JSON Filter Expression via Variable Reference

On the Workflow Dataset Search node, if you need to construct complex filter expressions programmatically (for example, via an upstream Code Sandbox node), switch the input mode next to the Tag Filter header from Manual Input to Variable Reference and pass a JSON object or JSON string:

{
  "tags": {
    "$and": [
      { "Applicable Dept": { "$in": ["All", "R&D"] } },
      { "Security Level": { "$lte": 2 } },
      { "Effective Date": { "$gt": "2026-01-01 00:00" } }
    ]
  },
  "createTime": {
    "$gte": "2026-01-01 00:00",
    "$lte": "2026-12-31 23:59"
  },
  "collectionIds": ["6593e137231a2be9c5603ba9"]
}

JSON Fields and Operators Reference

1. Top-Level Fields (always combined with AND)

2. Custom Tag Operators

FAQ

1. Why is a tag missing from the Tag Filter dropdown?

When an app or workflow node has multiple datasets associated, the Custom Tags dropdown only displays tags that share the exact same tag name and tag attribute across all selected datasets (for Options attribute tags, selectable values are the union of options across the datasets). Check that all associated datasets have defined the tag with the same name and attribute.

2. What happens to legacy string tags after upgrading from an older version?

During upgrade, legacy string tags are automatically migrated into an Options attribute tag named default_tag, preserving all existing file-tag associations. You can rename default_tag in Tag Management at any time.

3. Does renaming a tag or option affect existing Tag Filter rules?

Tag Filter rules match by tag name and option text. If you rename a tag or an option in Tag Management, remember to update any apps or workflows that reference that tag name or option value in their Tag Filter rules.