Optimizing Amazon Quick Response Time
Amazon Quick provides multiple layers for configuring metadata that helps the AI agent understand your data, apply business logic, and respond accurately. Each layer has a different impact on response speed. Placing the right information in the right layer is the single most impactful optimization you can make. This guide provides a decision framework with practical examples using an HR People Analytics case.
A Metadata Placement Guide for Faster and Accurate AI Answers
Category: Best Practices
Author: Manasi Karale, Specialist Solutions Architect, Amazon Quick
Services: Amazon Quick, Amazon Quick Sight, SPICE
Published: July 01, 2026
Overview: The Metadata Stack
Amazon Quick processes metadata in a layered hierarchy. Information closer to the data (dataset/field level) is processed fastest because it is pre-indexed. Information in custom instructions and persona requires LLM interpretation at query time.
FASTEST: Dataset/Field Descriptions > Topic Relationships > Dataset Custom Instructions > Topic Custom Instructions > Agent Reference Docs > Space Files > Agent Persona: SLOWEST
Principle: If it can be expressed as structured metadata, do that. Reserve instructions for logic that cannot be captured any other way.
Quick Reference Table
| Layer | What Goes Here | Char Limit | Speed | HR Example |
|---|---|---|---|---|
| Dataset Description | What this dataset contains, its grain, when to use it | 500 characters | ⚡ Fastest: pre-indexed | "Monthly attrition by dept and location. One row per dept per month." |
| Field Description | Clarify ambiguous column names | 500 chars | ⚡ Fastest: pre-indexed | "term_date: Date employee exited. NOT date termination initiated. NULL = active." |
| Dataset Custom Instructions | Per-dataset rules, formulas, filters, business logic | 50,000 chars | ⚡ Fast: scoped per dataset | "Attrition rate = voluntary_exits / headcount_start * 100. Only for Attrition Monthly." |
| Field Custom Instructions | Per-field rules the agent applies when using this column | 2000 characters | ⚡ Fast: scoped to specific fields | "When users ask about attrition rate, compute: voluntary_exits / headcount_SOP * 100" |
| Topic Custom Instructions | Cross-dataset logic, fiscal calendars, routing rules, term disambiguation | 5,000 chars | ⚙️ Moderate: read every query | "FY starts Apr 1. Active = status Active AND term_date IS NULL." |
| Topic Relationships | Join keys and cardinality between datasets | Per-pair | ⚡ Fast: pre-defined joins | Employee_Master ↔ Compensation on employee_id (1:N) |
| Agent Reference Docs | Static domain knowledge for THIS agent (templates, glossaries, SOPs) | File-based | ⚙️ Moderate: retrieval per query | HR response template, approved terminology glossary, FAQ doc |
| Space File Uploads | Shared team docs retrieved via RAG when needed | File-based | 🐢 Slower: RAG pipeline | Full leave policy PDF, employee handbook, org chart |
| Agent Persona | Agent identity, behavioral rules, tone, guardrails | 50,000 chars | 🐢 Slower: every turn | "You are an HR analytics assistant. Always filter to active employees." |
1. Dataset Description
Purpose
Tells the agent what this dataset contains and when to select it. The primary signal for dataset routing in multi-dataset Topics.
Character Limit: 500 (DataSetSemanticDescription)
FASTEST: Pre-indexed at ingestion. The agent reads descriptions to route questions before querying. Clear descriptions eliminate wasted round-trips.
Best Practices
- State the grain: one row per - employee, month, transaction etc.
- Name key dimensions and measures
- State what questions this dataset answers
- Differentiate from sibling datasets
- Speed tip: Keep to 1-2 sentences. Every character matters with a 500 char limit.
HR Example
"Monthly employee attrition by department and location. One row per department per month. Use for turnover trends, NOT individual employee lookups."
Dataset Description
Figure 1: The HR Employee Dataset in Amazon Quick, showing the Dataset Description and Custom Instructions fields. The Description clearly states the grain (85 employee records for a Canadian organization), the currency (Canadian Dollars), and the time span (January 2015 to September 2024). This is what the agent reads first to decide whether this dataset can answer a question.
2. Data Field Description
Purpose
Clarifies what a column means when the name alone is ambiguous. This is how the agent maps user questions to the right columns.
Character Limit: 500
FASTEST: Pre-indexed per field. Eliminates ambiguity at column selection time, preventing multiple interpretation attempts.
Best Practices
- Describe what the field IS and what it IS NOT
- Include units (USD, days, percentage)
- Note special values (NULL = never terminated, 0 = not applicable)
- Only describe ambiguous fields: skip obvious ones
HR Examples
| Field | Description (max 500 chars) |
|---|---|
| term_date | The date the employee formally exited the company. NOT the date termination was initiated. NULL means currently active. |
| comp_ratio | Employee base salary / midpoint of pay band. Values > 1.0 = above midpoint. Decimal format (1.15 = 115%). |
| regrettable_flag | 1 = manager marked departure as regrettable (high performer). 0 = non-regrettable. Only populated for voluntary exits. |
Datafield Description
Figure 2: The field-level detail view for the 'city' column. The Description specifies what the field means ('The city where the employee is physically located or assigned') and lists valid values (Montreal, Toronto, Edmonton, etc.). The Geospatial type is set to 'City' and Additional notes include usage context and synonyms (location, office, work city, site). This pre-indexed metadata allows the agent to instantly map 'Which office has the most employees?' to this field without guessing.
3. Dataset Custom Instructions
Purpose
Per-dataset instructions that tell the agent HOW to use THIS specific dataset: formulas, default filters, business rules, and metric definitions scoped to this dataset only.
Character Limit: 50,000
FAST: Scoped per dataset. The agent only reads these instructions when this specific dataset is being considered for a query. More targeted = less overhead than topic-level instructions.
Best Practices
- Put metric formulas and business rules that apply to THIS dataset only
- Specify default filters or conditions unique to this dataset
- Note relationships to other datasets (for join context)
- Include exact column names and cell values
- Do NOT repeat topic-level instructions
- Speed tip: Keep focused and distinct from siblings. Overlap causes redundant processing.
HR Examples
| Dataset | Custom Instruction Example |
|---|---|
| Employee Master | One row per employee (active or terminated). Use for individual lookups, demographics, org structure. Active employees: status = "Active" AND term_date IS NULL. Join to other datasets on employee_id. |
| Attrition Monthly | Aggregated monthly attrition by department. Attrition rate = voluntary_exits / headcount_start * 100. Use headcount_start as denominator, NOT headcount_end. |
| Compensation | Historical comp records. Multiple rows per employee (one per change). Current comp = row with most recent effective_date per employee_id. comp_ratio = base_salary / band_midpoint. |
Dataset Custom Instruction
Figure 3: The Dataset Custom Instructions panel within the HR Employee Dataset. These per-dataset rules define: what 'Active' means (employment_status 'Active' and termination_date NULL), rating scales, satisfaction score ranges, formulas (Total comp = salary + bonus, Attrition = terminated/total), data exclusions (Executive dept from averages), and synonyms. These instructions are only read when the agent is considering THIS dataset for a query.
4. Data Field Custom Instructions
Purpose
Per-field rules that tell the agent HOW to use a column: formulas, filters to apply, or conditions. Goes beyond describing what a field is, to prescribing how to compute with it.
Character Limit: 2,000
FAST: Scoped to specific fields, so the agent only reads these instructions when the relevant field is involved in a query. More targeted = less processing overhead.
Best Practices
- Use for derived metric formulas that reference this field
- Keep instructions tied to ONE field: cross-field logic belongs in Topic instructions
- Use exact column names and exact cell values
- State the correct aggregation explicitly
HR Examples
| Field | Custom Instruction |
|---|---|
| voluntary_exits | Attrition Rate = voluntary_exits / headcount_start * 100. Always use headcount_start as denominator, NOT headcount_end. |
| offer_accept_date | Time to Fill = date_diff(days, requisition_open_date, offer_accept_date). Only calculate for status = "Filled". |
| perf_rating | Rating scale: 1=TT (Least Effective), 2=HV1 (Below), 3=HV2 (Effective), 4=HV3 (Highly Effective), 5=TT (Top Talent). Default aggregation: use distribution counts, NOT average. |
Data Field Custom Instructions
Figure 4: The field-level detail view for the 'city' column, showing the Additional notes section (which functions as field-level custom instructions). The notes specify usage context ('Use for location-based analysis, office headcount, and geographic compensation benchmarking') and synonyms ('location, office, work city, office location, site'). These are scoped: the agent only reads them when the 'city' field is involved in a query.
5. Topic Custom Instructions
Purpose
Topic-level business logic that applies across ALL queries: fiscal calendars, term definitions, dataset routing rules, and cross-dataset guidance.
Character Limit: 5,000
MODERATE: The LLM reads the FULL topic instructions on EVERY query. Longer = more tokens per question = slower. Keep concise and high-impact.
Best Practices
- Put cross-dataset logic here (routing rules, term definitions)
- Encode fiscal year logic and custom time definitions
- Structure with headers for LLM readability
- Do NOT duplicate what dataset descriptions or field descriptions already say
- Speed tip: Every character is read every query. Trim ruthlessly. Move per-dataset rules to dataset custom instructions instead.
HR Example
Fiscal Year: FY starts April 1. Q1=Apr-Jun, Q2=Jul-Sep, Q3=Oct-Dec, Q4=Jan-Mar. Terminology: - "Active employee": status = 'Active' AND term_date IS NULL - "Attrition": voluntary_exits only (exit_type = 'Voluntary') - "Headcount": COUNT DISTINCT employee_id WHERE status = 'Active' Dataset Routing: - Individual employee questions: Employee Master - Turnover trends/rates: Attrition Monthly - Compensation analysis: Compensation - Recruiting pipeline: Talent Acquisition
Topic Custom Instructions
Figure 5: The 'HR People Analytics' Topic with the Custom Instructions tab selected. This Topic contains 5 datasets and the instructions define cross-dataset rules: rating scales, what NULL values mean across datasets, the recruitment funnel sequence, how to filter for current headcount, and how to pair salary/bonus with currency for cross-region comparisons. These 5,000-character instructions are read on every query to this Topic.
6. Topic Relationships (Multi-Dataset Topics)
Purpose
Define join keys, cardinality, and direction between datasets. The agent uses these for runtime joins across datasets.
FAST: Pre-defined join paths eliminate guesswork. Explicit relationships = no inference needed = faster execution.
HR Example
| Dataset A | Dataset B | Join Key | Cardinality | Use Case |
|---|---|---|---|---|
| Employee Master | Compensation | employee_id | 1:N | Comp history per person |
| Employee Master | Attrition Monthly | department_id | 1:N | Turnover by dept |
| Talent Acquisition | Employee Master | employee_id | 1:1 | Hire source to performance |
Topic Relationships
Figure 6: The Relationships tab of the HR People Analytics Topic, showing the visual data model. The HR Employee Dataset is the central hub, connected to HR Employee Performance, HR Training Dataset, HR Leave Dataset, and HR Recruitment Dataset, all joined on employee_id (except Recruitment, which joins on hired_employee_id). These pre-defined join paths allow the agent to perform runtime joins across datasets without guessing which columns to use.
7. Chat Agent Reference Documents
Purpose
Files uploaded directly to a Chat Agent's configuration. Persistent knowledge the agent always has access to, without the user needing to attach anything. Unlike Space files (shared, RAG-retrieved on demand), these are scoped to this agent and always available.
MODERATE: The agent retrieves relevant chunks per query. Scoped to this agent only, so retrieval is more focused than Spaces. Fewer, focused docs = faster retrieval.
Best Practices
- Use for static reference material specific to THIS agent's domain
- 3-5 well-structured docs outperform 20 loosely related ones
- Good for: style guides, response templates, glossaries, SOPs, FAQ docs
- Do NOT put data definitions here (belongs in dataset/field descriptions)
- Do NOT put business rules here (belongs in dataset/topic custom instructions)
- Update by re-uploading: takes effect for all future conversations
- Speed tip: Keep lean and domain-specific. Every extra doc adds retrieval overhead.
HR Example: What Belongs Here vs. Elsewhere
| Good for Reference Docs | Put Elsewhere Instead |
|---|---|
| HR report formatting template (structure, tone) | Metric definitions: put in Dataset Custom Instructions |
| Approved terminology glossary (50 terms) | Fiscal year logic: put in Topic Custom Instructions |
| FAQ with pre-approved answers | Full employee handbook (200 pages): put in a Space |
| Data governance rules for HR data | PII guardrails: put in Persona Instructions |
Reference Docs vs. Space Files vs. Persona
| Aspect | Reference Docs | Space Files | Persona |
|---|---|---|---|
| Scope | This agent only | Any chat with Space attached | This agent, every turn |
| Availability | Always (no user action needed) | Only when user attaches Space | Always (system prompt) |
| Best for | Static domain knowledge | Shared team docs, dynamic content | Behavioral rules, tone, guardrails |
| Speed | Moderate (retrieval) | Slower (RAG across all attached) | Slower (read every turn) |
| Update | Re-upload to agent | Replace file in Space | Edit agent config |
Agent Reference Document
Figure 7: The 'AnyHR Company Team Space' showing uploaded reference files: an HR KPI Benchmarks spreadsheet (xlsx), a Leave and Time-Off Policy (PDF), and an L&D Policy document (docx). These files are retrieved via RAG when a user asks questions that require policy context (e.g., 'How many vacation days after 5 years?'). The chat panel on the right is scoped to the Space for targeted retrieval.
8. Space File Uploads
Purpose
Shared reference documents retrieved via RAG when a user question requires context beyond structured data: policies, procedures, guides. Shared across users and conversations.
SLOWER: Requires RAG retrieval (index lookup + chunk parsing + LLM synthesis). Use only for information that cannot be expressed as metadata or instructions.
Best Practices
- Use for lengthy policy docs, SOPs, and reference guides
- Do NOT put data definitions here: those belong in field/dataset descriptions
- Do NOT put business rules here: those belong in custom instructions
- Smaller, topic-specific files outperform one giant document
- Speed tip: Only attach Spaces relevant to the conversation. Every attached Space adds retrieval latency.
HR Examples
Full company leave policy (20 pages)
Employee handbook (benefits, procedures)
Historical policy change log
Org chart that changes quarterly
Space File Uploads
Figure 8: The 'AnyHR People Analytics Advisor' chat agent configuration showing the Agent Persona instructions. The persona defines: Role (strategic HR Business Partner), Tone (professional, concise, data-driven), Response Format (answer first, then evidence, then recommendation), and Guardrails (never reveal PII, default to current FY, flag metrics outside thresholds, escalation protocol for policy questions). This is injected on every turn to enforce consistent behavior.
9. Chat Agent Persona Instructions
Purpose
Define the agent's identity, tone, behavioral rules, and guardrails. This is the system prompt injected into EVERY conversation turn.
Character Limit: 50,000
SLOWER: Injected every turn. A 50K persona is processed on EVERY question. Keep lean: 500-2,000 characters for optimal speed.
Best Practices
- Define BEHAVIOR, not knowledge
- Include: role identity, response format, tone, guardrails, default filters
- Exclude: metric formulas, fiscal logic, data definitions
- Speed tip: Move ALL factual content to Reference Docs or Topic/Dataset instructions. Persona = purely behavioral.
HR Example
You are an HR Analytics Assistant. Rules: - Always filter to active employees unless explicitly asked about terminated - Never reveal individual PII (salary, SSN, address) - Default time frame: current fiscal year - Response format: answer first, then supporting data - If data unavailable, say so clearly Tone: Professional, concise, data-driven.
Agent Persona Instructions
Figure 9: The full Reference Document uploaded to the AnyHR People Analytics Advisor agent. It contains: HR KPI Definitions and Thresholds with Green/Yellow/Red ranges, Compensation metric formulas and benchmarks, Response Templates for standardized answers (headcount summary, attrition alerts, recruitment pipeline, training ROI), Fiscal Year and Time Definitions, Department Codes and Hierarchy with headcount targets, Escalation Matrix mapping scenarios to actions, and Approved Terminology. This is the 'always-on handbook' the agent consults for context that is too detailed for custom instructions but needed every session.
Testing Your Configuration
To validate that each metadata layer is working correctly, test with questions that specifically target each layer:
| # | Layer | Test Question | Expected Behavior |
|---|---|---|---|
| 1 | Fast: Dataset/Field Descriptions | "What is the average salary by region?" | Agent instantly knows "salary" is CAD and "region" is geographic. No interpretation needed: pre-indexed. |
| 2 | Fast: Dataset Custom Instructions | "What is our current attrition rate?" | Agent applies formula (terminated / headcount x 100) automatically: stored as per-dataset rule. |
| 3 | Moderate: Topic Custom Instructions | "What is our Q2 headcount trend?" | Agent knows Q2 = Jul-Sep (not Apr-Jun): fiscal calendar defined as cross-dataset logic. |
| 4 | Moderate: Agent Reference Docs | "Is our attrition rate healthy?" | Agent flags 12.3% as warning (10-15% threshold): KPI benchmarks in reference doc. |
| 5 | Slower: Space Files | "How many vacation days after 5 years?" | Agent retrieves "25 days" from Leave Policy PDF via RAG. Perfect for Space document. |
| 6 | Slower: Agent Persona | "List all employee salaries" | Agent refuses per PII guardrail. Persona fires every turn to enforce behavioral boundaries. |
Performance Optimization Summary
Do / Don't for Speed
| DO (Faster) | DON'T (Slower) |
|---|---|
| Put metric formulas in Dataset Custom Instructions (50K, scoped) | Put formulas in Topic Instructions (5K, read every query) |
| Use Dataset Descriptions for routing (256 chars, pre-indexed) | Write routing logic in Topic Instructions (adds to every query) |
| Define relationships in Topic (pre-defined join paths) | Write join logic in custom instructions (LLM must interpret text) |
| Keep persona under 2K chars (behavioral only) | Stuff knowledge into 40K persona (processed every turn) |
| Use SPICE (pre-cached) | Use Direct Query (hits source DB per question) |
| Use 3-5 focused Reference Docs per agent | Upload 20 loosely related docs (retrieval overhead) |
| Attach only relevant Spaces per conversation | Attach 10 Spaces "just in case" (RAG searches all) |
Key takeaway: Place information at the lowest layer possible. Dataset/field descriptions are fastest (pre-indexed). Custom instructions are moderate (LLM-read per query). Persona and RAG are slowest (processed every turn).
Conclusion
The Amazon Quick metadata stack gives you nine distinct layers to configure how the AI agent understands and responds to questions. The key optimization principle is simple: place information at the lowest, most structured layer that can express it. Dataset and field descriptions are pre-indexed and essentially free in terms of response latency. Custom instructions add moderate overhead. Persona and RAG add the most. By deliberately placing each piece of metadata in the right layer, you can achieve significantly faster response times while maintaining accuracy, giving your users a responsive, trustworthy analytics experience.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article