​

Context Engineering

Collate AI answers questions about your data—but the quality of those answers depends on what it knows. This guide explains how Collate finds the right assets when you search or ask a question, how the assistant builds context before it replies, and how you can improve answers by curating your catalog.

​

How It Works

• Collate searches with both keywords and meaning. When you search or ask a question, Collate runs two searches at once—one that matches your exact words and one that matches the meaning behind them. The results are blended so the most relevant assets rise to the top.
• The assistant plans before it acts. For complex questions, it breaks the work into steps and delegates each to a specialized helper—search, analytics, governance, and more. Each step’s findings feed into one combined answer.
• Answers come from your data, not guesswork. Before writing SQL or answering a question, the assistant loads the asset’s documented keys, joins, business definitions, and real column values from the Profiler. It doesn’t invent information.
• You steer it with metadata. Asset names, descriptions, glossary terms, metrics, memories, and profiler runs all directly affect search ranking and answer quality. The better your catalog is curated, the better your answers will be.

---

​

How Collate Finds the Right Data

​

Hybrid Search

When you type a request, Collate interprets it as natural language, extracts filter-like conditions—“owned by me,” “tier 1 tables,” “in the marketing domain”—and runs two searches simultaneously:

1. Keyword matching finds assets whose names, descriptions, or tags contain your words exactly.
2. Meaning matching finds assets about what you asked, even when they use different words.

Collate merges both result lists using Reciprocal Rank Fusion (RRF), a standard blending method that rewards assets that rank strongly in either list. Items strong in both rise to the top. That’s why “customer revenue” can surface a table named orders_summary alongside one literally called customer_revenue. Three quality signals boost the final ranking:

• Tier: higher-tier assets rank higher.
• Popularity: frequently used assets are favored.
• Endorsements: assets with more upvotes rank higher.

Deleted assets are excluded by default.

​

What One Search Covers

A single search reaches every asset in your catalog at once—tables, dashboards, and glossary terms can appear in the same result list, ranked purely by relevance. Collate searches across 22 asset types: Notice the last row: your business context—metrics, glossary terms, knowledge articles, and saved memories—is searchable alongside your data. This is what makes it possible to improve AI answers by curating your catalog. See Improving AI Answers.

​

What Meaning Matching Looks At

For meaning-based search, Collate builds a plain-language summary of each asset and matches your query against it. The summary includes:

• What it is: asset type and display name.
• Tags and linked glossary terms.
• Domain, tier, and certification status.
• Description (formatting removed).
• Columns: for tables, the column names.
• Contents: for containers—a database lists its schemas, a schema lists its tables.

Some types get tailored extras: glossary terms include synonyms and related terms; metrics include type, unit, and granularity; knowledge articles include title and description; context memories include the question, answer, and summary. Because the summary captures business context—not just the raw name—a concept search can land on the right asset even when your wording is completely different from its label. Every field you improve feeds directly into this summary.

​

Tuning Search (Admins)

Admins can adjust how search works under Settings > Preferences > Search. The main settings:

• Keyword vs. semantic blend: Set the relative weight of exact-match and concept-match results. Lean toward keyword if your users search by precise names and codes; lean toward semantic if they ask in natural language.
• Matching fields and boosts, per asset type: Choose which fields are searched, how much each one counts, and the match style per field (exact, phrase, fuzzy, or standard).
• Term boosts: Add a fixed ranking lift for assets where a field equals a specific value—for example, boost tier.tagFQN = Tier.Tier1 or certified assets.
• Field value boosts: Fold numeric signals like usage counts or vote tallies into the ranking score, with configurable multipliers and caps.

​

Persona AI Context: Before Search Even Runs

Search isn’t the assistant’s first move. Admins can attach an AI Context definition to each user persona (Data Analyst, Data Engineer, and others): a set of rules that pre-loads curated assets and knowledge into every conversation for users with that persona. When you open a conversation, the assistant reads this Preloaded Assets block before doing any search. This does two things:

• Cuts search round-trips. Common questions like “What customer data do we have?” can be answered instantly from the preload—no search needed and no ranking uncertainty.
• Gives every conversation a knowledge foundation. Rules can include descriptions, schema, glossary terms, metrics, and articles alongside each preloaded asset. The assistant starts every session with your organization’s definitions already in scope.

Two rule settings control what’s always present:

• Always in context: Assets from this rule load into every request and are the last to drop when the context budget fills up. Use it for the foundational assets your team should never work without.
• Fully rendered: The rule loads each matched asset’s complete documentation instead of selected sections. Use sparingly—it’s the most thorough and the most context-budget-intensive option.

The preload is budget-managed: rules cap their matches (maxAssets, default 200), the document has a character limit (default 400k) and a cache (default 30 minutes), both configurable. Lower-priority content degrades to a compact or name-only form rather than dropping silently. For setup steps, see Fix: Your Whole Team Gets Generic Answers. For the full configuration reference, see AI Context in the admin guide.

​

How the AI Assistant Works

When you ask a question, Collate AI doesn’t just pass it to a language model. It routes the work through specialized helpers, checks each step, and produces one combined answer.

​

Planning and Executing a Request

For anything beyond a simple lookup, the assistant follows this process:

1. Classify the request: answer directly (simple lookups and clarifications), confirm before acting (metadata changes), or make a plan.
2. Plan in steps, each assigned to a specialized helper:
   • Search Agent: discovery, asset details, lineage, and company knowledge.
   • Analytics Agent: SQL generation and execution, saved-metric runs, and charts.
   • Quality Agent: profiles, sample data, data-quality tests, and root-cause analysis.
   • Governance Agent: metadata edits, glossary term creation, and metric creation.
   • Memory Agent: saving, updating, and deleting context memories.
   • Plus insights, automations, marketplace, and integration helpers.
3. Execute the steps in dependency order—independent steps run in parallel.
4. Check progress between stages: continue, adjust the plan, stop, or ask for clarification.
5. Synthesize one answer composed only from what the helpers returned.

This is what lets it handle multi-part requests like “find our most-used customer tables and tell me which ones lack documentation”—search and analysis each go to the right helper, and their findings come back combined.

​

What the Assistant Can and Can’t Do

The Analytics Agent works like a senior analyst, but within defined limits:

​

What the Assistant Knows Before It Acts

Every run starts with layered context, assembled in a fixed order:

1. Your identity: name, email, teams, roles, domains, and today’s date. This is how phrases like “my assets” and “last quarter” resolve without a lookup.
2. Persona preloaded assets: the admin-curated index of assets and knowledge relevant to your role. The assistant prefers these for discovery and reuses asset names instead of re-searching—but detail questions (schema, profile, lineage) still trigger a live fetch.
3. Your saved preferences: up to five of your most recent personal memories—for example, “our fiscal year starts in February” or “keep answers concise”—injected into every run.

Then, just before querying a table, the Analytics Agent loads four more things in parallel: If no profile data exists, the agent runs one lightweight sampling query first to discover real values. That’s slower and less complete than a full profiler run—which is why running the Profiler helps.

​

Why the Assistant Sometimes Says No

These behaviors are intentional:

• It won’t answer from general knowledge. Every answer must come from your platform data—search results, loaded context, or prior tool results. If nothing is found, it says so. That’s the correct outcome, and your signal to add missing context.
• It won’t invent identifiers. Asset names and links can only come from a tool result, your message, the conversation, or your preloaded assets. No guessing, no constructed links.
• It asks before changing anything. Every metadata write—editing descriptions, creating glossary terms, saving metrics—needs your explicit confirmation in a separate message.
• It only sees what you can see. Catalog calls run under your permissions. Memories and articles you can’t view are filtered out before they enter your answer.
• It flags data quality issues. Answers include advisories when warranted: “no profile data, consider running the Profiler,” “profiled on a 10% sample,” “profile is 45 days old.”
• It stops on ambiguity. When two sources define the same concept differently, the assistant asks which one applies instead of silently picking one. See Fix: The Assistant Keeps Asking You to Clarify a Definition to resolve this.

​

Improving AI Answers

Search ranking and AI reasoning respond directly to the Knowledge Graph you maintain. When an answer is wrong, find your symptom below. Each fix follows a Why → Try → Validate pattern so you can confirm the change worked.

​

Fix: Search Keeps Surfacing the Wrong Table

Why: the authoritative asset is under-described, so ranking signals favor a look-alike. The actions below are ordered from most to least impactful. Try (in this order):

1. Name and label clearly (strongest signal). Display name carries the heaviest keyword weight. Use the term people actually search—Customer Orders, not cust_ord_v2.
2. Write a real description. It feeds both keyword matching and the meaning summary. An empty description is a structural disadvantage.
3. Add tags and link glossary terms. These connect “how the business talks about this” to “what the asset is called in the system.”
4. Assign a domain. This helps domain-scoped queries land on the right asset.
5. Set the tier deliberately. Tier 1 > Tier 2 > Tier 3 acts as a tie-breaker. Over-tiering everything removes the advantage.
6. Certify trusted assets. Certification marks the “official” version among look-alikes.
7. Drive usage and endorsements. Direct teammates to the canonical asset and ask them to upvote it.
8. Curate column names. Column names are part of the meaning summary for tables.

Validate: run the exact search again—the asset should rank at or near the top. Then ask the assistant the same discovery question (“do we have a customer orders table?”) in a new conversation. The asset should appear, ideally flagged as Attached knowledge if you linked terms or metrics. Changes take effect as soon as the asset re-indexes, which is near-immediate.

​

Fix: The AI Computed a KPI Differently Than You Do

Why: without a governed definition, the assistant derives calculations from schema and column names. The result is plausible, but it isn’t your formula. A saved metric is executable truth—the assistant prefers it over generating new SQL. Try:

1. Ask the question and refine in chat until the SQL is correct: “Revenue should exclude refunds—recompute with amount > 0.”
2. When the result looks right, say: “Save this as a metric called ‘Net Revenue’.” The assistant usually offers to do this after a successful query. It checks for similar existing metrics, shows you what it’s about to create, and asks for your confirmation.

Validate:

• Open a new conversation and ask the same question: “What’s our net revenue by month?” The run should skip schema exploration and go straight to the saved metric. The chart’s SQL should match the metric’s stored SQL.
• Try a variation: “net revenue by month for EMEA only.” The assistant should keep the metric’s formula and add only the region filter.
• Search the metric by name. Its result should show linked tables. Asking “How do we calculate net revenue?” should return your metric’s definition.

​

Fix: The AI Misunderstood a Business Concept

Why: terms like “active user,” “churn,” and “qualified lead” mean something specific at your company. Without a definition, the assistant maps the phrase to whatever columns look plausible. A glossary term attached to the right tables forces the SQL generator to apply your definition exactly. Try:

1. Create the term under Govern > Glossary. The description is the definition—write it precisely: “An active user has at least one session in the trailing 28 days, excluding internal accounts (is_internal = false).” Add synonyms; they improve meaning matching for alternative phrasings.
2. Tag the relevant tables and columns with the term. The attachment is what injects the definition at query time—an unattached term only improves search, not SQL.
3. Alternatively, ask the assistant to create the term and tag the tables for you.

Validate: in a new conversation, ask “How many active users did we have last week?” against the tagged table. The generated SQL (visible on the chart widget) should apply the 28-day window and the is_internal exclusion. Asking “What does active user mean here?” should return your definition with a link.

​

Fix: Filters Return Wrong Values or Zero Rows

Why: without profiler results, the assistant guesses filter values (“EMEA” vs. “emea” vs. “Europe/Middle East”). It runs one silent sampling query to mitigate this, but sampling is slower and less complete than a full profile. Try: enable the Profiler pipeline on the table’s service, or on the individual table. Schedule it to run at least every 30 days—the assistant flags profiles older than that in its advisories. Validate: re-ask the failing question. The WHERE clause should now use exact values with correct casing, and the advisory “No profiling data available, consider running the Profiler” should be gone. Asking “What values does the region column take?” should return an instant, grounded answer.

​

Fix: The AI Ignores Something Your Whole Team Knows

Why: tribal knowledge—“the 2023 rows are backfilled and unreliable,” “always exclude test accounts”—isn’t visible to the assistant until it’s saved as a context memory. Memories attached to an asset are auto-recalled every time anyone queries that asset. Try:

1. In chat: “Remember that in snowflake_prod.finance.mart.sales, rows before 2024 are backfilled—always filter order_date >= '2024-01-01' unless asked otherwise.”
2. The Memory Agent checks for near-duplicate memories first. If it finds similar ones, it shows them and asks whether to update instead—it never picks automatically.
3. Set visibility deliberately. A private memory applies only to your queries. Say “make this visible to the team” (or promote it in Context Center) to make it shared—only then does it apply to your teammates’ queries too.
4. To update a memory later: “Update that memory: the cutoff is 2024-03-01.” To remove it: “Delete the memory about the sales backfill.”

Validate: open a new conversation—ideally as a teammate—and query the table. The answer should apply the filter, and the run’s context should show “Institutional knowledge for this entity.” Check Context Center > Memories to confirm the right scope and visibility.

​

Fix: The AI Joins Tables the Wrong Way

Why: join paths come from declared primary and foreign keys plus joins observed in real query history. Without declared keys or query history, the assistant guesses based on column names. Try: define primary key and foreign key constraints on the tables in Collate, or confirm that ingestion picks them up from the source database. The more the correct join runs in your warehouse, the stronger the evidence becomes. Validate: ask a question that requires the join. The SQL should use the declared keys. On the asset page under AI context, you’ll see the keys and observed joins the assistant will use.

​

Fix: The Assistant Keeps Asking You to Clarify a Definition

Why: this is a guardrail, not a bug. Two or more knowledge items define the same concept differently—for example, two “revenue” metrics with different SQL—and the assistant won’t silently pick one. Try: decide which definition is canonical. Update or retire the other one (merge glossary terms, deprecate the stale metric, or fix the outdated article). Tier or certify the canonical one. Validate: re-ask the question—the clarification prompt should be gone, and the answer should apply the surviving definition.

​

Fix: Your Whole Team Gets Generic Answers

Why: without a curated AI Context definition on their persona, teammates start each conversation with no preloaded knowledge. The assistant searches from scratch every time. Try (admin): go to Persona settings > AI Context and add up to 25 rules. Each rule specifies an asset type, an Explore-builder filter, and which sections to include (schema, glossary terms, metrics, articles, and profile). Flag the most foundational rule as always in context so its assets are always present; reserve fully rendered for the few entities that warrant complete documentation. Use preview to confirm what each rule matches before saving. The default budget is 400k characters with a 30-minute cache—both are configurable. Validate: as a persona member, ask “What data do we have about X?” The curated assets should appear instantly from the Preloaded Assets block, with no search step. Asking a deeper question—“Show me its schema”—should trigger a live fetch. That’s correct behavior: the preload is an index, not a copy.

​

Fix: A Change You Made Isn’t Showing Up

Why: the assistant holds context stable during a conversation on purpose—a change made mid-chat doesn’t rewrite the context already in use. Persona AI Context and preloaded assets are also cached for about 30 minutes server-side, so a new change might not appear immediately in a new conversation either. Memories and preferences update with every question; search re-indexing is near-immediate—those lag least. Try (in order):

1. Open a new conversation. Context rebuilds from scratch, picking up new memories, preferences, tags, and metrics. This fixes most cases.
2. Wait up to 30 minutes after a persona or preloaded-asset change, then try again in a new conversation so the cache window passes.
3. Confirm the change was saved. Metadata changes only persist after you approve them in a second message. If you never confirmed, nothing was written.

Validate: the fresh conversation should reflect the change. If it still doesn’t after the cache window, the cause isn’t timing—check that the term or metric is linked to the right table, that the memory is shared rather than private, or that there’s no conflicting duplicate definition.

​

Choose the Right Approach

Rule of thumb: use the most governed form that fits. Metrics and glossary terms are applied strictly by the SQL generator. Memories and articles are strong hints. Good names and descriptions improve search for everything.

​

A Complete Example

Prompt: “Show revenue and margin % by region for last quarter”—with a curated catalog (glossary term Net Revenue, metric Gross Margin %, profiled sales table, one shared memory).

1. Route and plan: the assistant identifies this as an analytical question and creates a two-step plan: search → analytics, carrying your prompt through verbatim.
2. Search: hybrid search finds the sales table with Net Revenue and Gross Margin % attached, and passes both definitions to the analytics step.
3. Analytics: the assistant checks saved metrics first. Gross Margin % covers the margin calculation but not the region-by-quarter breakdown, so it generates SQL that applies the metric’s formula verbatim. In parallel, it loads:
   • The schema
   • The profiler results (region exact values, so casing is correct)
   • The shared memory (“EMEA excludes UK since the 2025 reorg”—applied)
   • The context profile (declared foreign key plus observed join to dim_region—used)
   The query uses date functions instead of hard-coded dates, so it stays valid if you save and re-run it later.
4. Chart: because currency and percentage use different scales, the assistant renders a composed dual-axis chart automatically.
5. Synthesis: a prose summary from the actual results, with the table linked, an advisory (“profiled on 10% sample”), and an offer—“Want me to save this as a metric?”
6. You: “Yes. And remember that finance dashboards always exclude intercompany accounts.” Two confirmations later, a new governed metric exists and a shared memory guards every future query on that table.

Each thing you add makes the next question—yours or a teammate’s—start from a smarter place.