Once you've mastered the basics of using Liquid variables to access your Content Storage, you're ready to explore the sophisticated formatting and advanced techniques that can transform your prompts from simple question-and-answer tools into powerful, context-aware AI assistants.
This guide will show you how to control exactly how your retrieved content appears in your prompts and teach you advanced strategies for building complex, multi-layered searches that adapt to different scenarios and user needs.
Understanding Output Formats
When you retrieve content from your storage, you have four different ways to format that information. Think of these formats as different ways to present the same information - like choosing between a formal report, a casual summary, raw notes, or structured data.
markdown: Best for most use cases - readable, structured, and informative
textWithMetadata: When you want metadata but prefer plain text over markdown
text: When content should flow naturally without any attribution or metadata
json: When building custom processing logic or need structured data
💡 All examples below show the same search results formatted differently. This is a search for "API authentication" that returned two relevant chunks.
📌 Markdown Format (Default)
This is your go-to format for most situations. It presents your content with clear headers, organized metadata, and professional formatting that's easy to read and understand.
When to use markdown:
Most general-purpose prompts
When you want users to see source information
For customer-facing responses where credibility matters
When you need well-structured, readable content
The markdown format includes helpful details like:
Document titles as clear headers
Folder locations so you know where information came from
Tags that show content categories
Similarity scores that indicate relevance strength
Example:
## API Authentication Guide
**Folder:** api-docs | **Tags:** auth, security | **Similarity:** 87%
To authenticate API requests, include your API key in the Authorization header. The header should be formatted as: Authorization: Bearer YOUR_API_KEY. All requests without valid authentication will return a 401 Unauthorized error.
---
## Rate Limiting
**Folder:** api-docs | **Tags:** api, limits | **Similarity:** 82%
The API enforces rate limits of 1000 requests per hour per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response. Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
📌 Text With Metadata Format
This format gives you a cleaner, simpler presentation while still showing where your information comes from. It's like having footnotes in a research paper - the essential source information is there, but it doesn't dominate the content.
When to use textWithMetadata:
For internal tools where you need source tracking
When building prompts that will be further processed
For debugging or auditing your content searches
Example:
[Doc: API Authentication Guide | Folder: api-docs | Tags: auth, security | Score: 87%]
To authenticate API requests, include your API key in the Authorization header. The header should be formatted as: Authorization: Bearer YOUR_API_KEY. All requests without valid authentication will return a 401 Unauthorized error.
[Doc: Rate Limiting | Folder: api-docs | Tags: api, limits | Score: 82%]
The API enforces rate limits of 1000 requests per hour per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response. Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
📌 Plain Text Format
This is your invisible integration option. The content flows naturally without any indication of where it came from, making it perfect for seamless incorporation into your prompts.
When to use plain text:
Embedding glossaries naturally within instructions
Including background context without breaking conversational flow
Inserting style guides or writing standards
Adding technical definitions that should feel part of the original prompt
Example:
To authenticate API requests, include your API key in the Authorization header. The header should be formatted as: Authorization: Bearer YOUR_API_KEY. All requests without valid authentication will return a 401 Unauthorized error.
The API enforces rate limits of 1000 requests per hour per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response. Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.
📌 JSON Format
This structured data format is perfect when you need to manipulate or process your results in sophisticated ways.
When to use JSON:
Building custom processing logic
Creating dynamic responses based on search results
Integrating with other systems or tools
When you need to count results or perform calculations
Example:
{
"results": [
{
"content": "To authenticate API requests, include your API key in the Authorization header. The header should be formatted as: Authorization: Bearer YOUR_API_KEY. All requests without valid authentication will return a 401 Unauthorized error.",
"document": "API Authentication Guide",
"folder": "api-docs",
"tags": ["auth", "security"],
"similarity": 0.87
},
{
"content": "The API enforces rate limits of 1000 requests per hour per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response. Rate limit information is included in response headers: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.",
"document": "Rate Limiting",
"folder": "api-docs",
"tags": ["api", "limits"],
"similarity": 0.82
}
]
}
Advanced Search Strategies
📌 Adjusting Content Volume Based on Context
You can dynamically control how much content you retrieve based on what you're trying to accomplish:
<!-- Concise answer: fewer chunks, faster processing -->
{{ query | content_search: "docs", "", 3 }}
<!-- Comprehensive analysis: more chunks, richer context -->
{{ query | content_search: "docs", "", 15 }}
For quick, focused answers: Use fewer content chunks (3-5) to get faster processing and more concise responses. This works well for simple questions or when you want brief, to-the-point answers.
For comprehensive analysis: Retrieve more chunks (10-15) when you need thorough coverage of a topic or want to provide detailed, well-researched responses.
📌 Strategic Similarity Threshold Setting
The similarity threshold is like a quality filter for your search results.
Similarity Guidelines:
0-30%: Very broad (may include loosely related content)
40-60%: Exploratory searches, discovering connections
70-80%: Standard searches for relevant content (recommended)
90%: Very strict matching (may return few or no results)
<!-- Broad, exploratory searches -->
{{ query | content_search: "research", "", 10, 40 }}
<!-- Standard searches (default) -->
{{ query | content_search: "docs", "", 5, 70 }}
<!-- Precise, exact-match searches -->
{{ query | content_search: "legal", "", 3, 90 }}
Broad exploration (40-60% similarity): Perfect for discovery sessions, brainstorming, or when you're not sure exactly what you're looking for. This casts a wide net and might surface unexpected but relevant connections.
Standard searches (70-80% similarity): This is your sweet spot for most business applications. It ensures relevance while still capturing related concepts and comprehensive coverage.
Precision searches (90%+ similarity): Use this for technical documentation, compliance materials, or when you need exact matches. Be aware that very high thresholds might return few or no results if your query doesn't closely match your stored content.
📌 Clean Integration Techniques
When using the plain text format, you're essentially weaving your stored knowledge directly into your prompt instructions. This creates a seamless experience where your AI assistant appears to have built-in expertise about your specific business, products, or processes.
The key is to place these content insertions strategically within your prompt so they feel like natural parts of your instructions rather than obvious additions.
When answering, use these definitions:
{{ query | content_search: "glossary", "technical-terms", 5, 70, "text" }}
Now, please explain {{ technical_concept }} using the terminology above.
This is particularly useful for:
Inserting glossaries: Define terms seamlessly within instructions
Embedding terminologies: Include industry-specific language naturally
Adding context: Weave background information into prompts
Style guides: Inject writing guidelines without breaking flow
📌 Multiple Searches for Comprehensive Coverage
One powerful technique is running separate searches within the same prompt to compare different sources or perspectives:
**Internal Documentation:**
{{ query | content_search: "internal-docs", "", 3, 80 }}
**Public Knowledge Base:**
{{ query | content_search: "public-kb", "", 3, 70 }}
Compare these sources and identify any discrepancies...
You might search both internal documentation and public knowledge bases, then ask your AI to identify any discrepancies or gaps between them. This approach is invaluable for:
Quality assurance - ensuring internal and external communications align
Competitive analysis - comparing your documentation with industry standards
Compliance checks - verifying consistency across different document types
📌 Conditional Content Retrieval
You can make your prompts smart and adaptive by searching different content based on user inputs or conditions.
{% if topic == "technical" %}
{{ user_query | content_search: "engineering;api-docs", "", 5 }}
{% elsif topic == "sales" %}
{{ user_query | content_search: "sales-materials;pricing", "", 5 }}
{% else %}
{{ user_query | content_search: "", "", 5 }}
{% endif %}
For instance, if users indicate they're asking about technical topics, you might search engineering documentation, while sales questions would trigger searches in pricing and product materials.
This conditional approach lets you build single prompts that can handle multiple departments, user types, or topic categories without overwhelming users with irrelevant information.
🔔 Choosing the Right Approach
Consider plain text formatting when you want your AI to sound like it naturally knows your business inside and out, without constantly referencing where information came from.
Use JSON formatting when you're building sophisticated workflows that need to count results, compare sources, or integrate with other business systems.
Example when you need to parse and manipulate results:
{% assign results = query | content_search: "data", "", 5, 70, "json" %}
<!-- You can now reference specific fields or build custom output -->
The search found information from {{ results.results.size }} sources.
By mastering these output formats and advanced techniques, you'll transform your basic content searches into powerful, flexible AI assistants that can handle complex business scenarios with precision and elegance.
✅ Next Steps and Related Articles
After familiarizing yourself with the basics of using Liquid variables for content retrieval, you can deepen your skills with the following help articles:
Understand the core concepts of Liquid variables, including how they function and the basic syntax needed to get started. Learn about the different search parameters and how they affect your content retrieval process.
Enhance your practical knowledge through a variety of examples, showcasing both simple and more sophisticated uses of Liquid variables for customizing content access.
Gain insights into organizing your content storage effectively, common pitfalls to avoid, and tips to optimize the performance and accuracy of your AI prompts.
These resources will equip you with the knowledge to use Liquid variables more effectively, allowing you to build powerful AI-driven solutions with precision and reliability.