Tags and Filtering

Tags provide a powerful way to organize your documents and create precise filtering for your vector searches. By combining tag-based filtering with semantic search, you can retrieve exactly the content you need from your knowledgebase.

Adding Tags to Documents

You can add custom tags to any document in your knowledgebase to organize and categorize your content for easier retrieval. Open a document in your knowledgebase and use the tag fields to assign values.

Tag Management

• Custom tags: Create your own tag system that fits your workflow
• Multiple tags per document: Apply as many tags as needed to each document, there are 7 tag slots available per knowledgebase that are shared by all documents in the knowledgebase
• Tag organization: Group related documents with consistent tagging

Tag Best Practices

• Consistent naming: Use standardized tag names across your documents
• Descriptive tags: Use clear, meaningful tag names
• Regular cleanup: Remove unused or outdated tags periodically

Search API and Knowledge Blocks

The search API accepts document tag filters through its filters field, a record of tag names and values. It supports tag-only, vector-only, and combined searches.

In Advanced mode, the Knowledge block accepts tagFilters rows with tagName and tagValue and converts them to the API's filters map. The block supports text equality only; unknown tags, malformed filters, and unsupported operators are rejected. Query-only, tag-only, and combined searches all use the modes below.

Search Modes

The search API selects a mode based on the query and filters provided. All modes return chunks, not complete documents. topK defaults to 10 and accepts 1-100; several returned chunks can belong to the same document. Search is not an exhaustive document-listing operation.

1. Tag-Only Search

When you only provide tags (no search query):

• Limited retrieval: Fetches up to topK chunks from documents with the specified tags
• No vector search: Results are based purely on tag matching
• Fast performance: Quick retrieval without semantic processing
• Exact matching: Returned chunks belong to documents matching all specified tag filters

Use case: When you need a limited set of chunks from a specific category or project

2. Vector Search Only

When you only provide a search query (no tags):

• Semantic search: Finds content based on meaning and context
• Full knowledgebase: Searches across all documents
• Relevance ranking: Results ordered by semantic similarity
• Natural language: Use questions or phrases to find relevant content

Use case: When you need the most relevant content regardless of organization

3. Combined Tag Filtering + Vector Search

When you provide both tags and a search query:

1. First: Filter documents to only those with the specified tags
2. Then: Perform vector search within that filtered subset
3. Result: Semantically relevant content from your tagged documents only

Use case: When you need relevant content from a specific category or project

Search Configuration

Tag Filtering

• Multiple tag slots: When filtering on multiple tag slots, AND logic is applied (all specified tag filters must match)
• OR within a tag: A single tag slot supports OR logic, matching any of multiple specified values
• Case sensitivity: Tag matching is case-insensitive
• Exact matching: Tag values must match exactly (no partial or substring matching)

Vector Search Parameters

• Query complexity: Natural language questions work best
• Result limits: Configure how many chunks to retrieve
• Relevance threshold: Selected internally; there is no user-configurable similarity threshold
• Chunk size: Configure during document processing, not as a search parameter

Integration with Workflows

Knowledge Block Configuration

1. Select knowledgebase: Choose which knowledgebase to search
2. Choose search inputs: Provide a query, text-equality tag filters in Advanced mode, or both
3. Configure results: Set the number of chunks to retrieve (1-100, default: 10)
4. Map results: Explicitly reference the returned chunks in downstream inputs or prompts
5. Test search: Inspect the results before relying on them

Dynamic Tag Usage

• Variable tags: Use workflow references in the block's tag values; direct API clients send the resolved values through filters
• Conditional filtering: Apply different tags based on workflow logic
• Context-aware search: Adjust tags based on conversation context
• Multi-step filtering: Refine searches through workflow steps

Performance Optimization

• Efficient filtering: Tag filtering happens before vector search for better performance
• Result limits: Request only the chunks you need to keep downstream context manageable

Getting Started with Tags

1. Plan your tag structure: Decide on consistent naming conventions
2. Start tagging: Add relevant tags to your existing documents
3. Test combinations: Experiment with tag + search query combinations
4. Integrate into workflows: Configure the Knowledge block's tag filters and inspect the returned chunks; direct API clients use filters
5. Refine over time: Adjust your tagging approach based on search results

Tags transform your knowledgebase from a simple document store into a precisely organized, searchable intelligence system that your AI workflows can navigate with surgical precision.