How to Use Solid & Common Questions

Purpose: Quick answers for business users, semantic modelers, and platform owners. Version context: April 2026 product capabilities.

How to use this page

This is not a linear document. It is not required to read from top to bottom. Treat it like an indexed handbook: pick your goal, then jump.

• Use the right-hand outline / section navigation—it lists the same headings as the goal list below.

Find commands within your browser can help you find a heading fast: Ctrl+F / Cmd+F on a keyword (warehouse, MCP, benchmark, SSO, …) if you already know the term you need.

If you’re trying to…

Getting started

What problem does Solid solve?

Enterprise warehouses are huge and inconsistent; AI that reads raw schemas hallucinates (wrong joins, wrong metrics, opaque names). Solid builds a governed semantic layer so agents and users ask in natural language and receive grounded SQL via chat or MCP, tied to approved business definitions.

What is a “semantic model” in Solid?

A use-case–scoped package (typically 5–10 tables, 50–100 columns) with relationships, metrics, descriptions, certified SQL examples, benchmark questions, and optional custom instructions. It is not a full data catalog of every table.

Why are models scoped to use cases?

To limit context, reduce hallucination, and make routing (picking the right model) reliable. Overly broad models negatively impact routing and accuracy.

What are Solid Build, Solid Analyze, and the MCP server?

• Solid Build: Where modelers connect warehouses, edit models, run benchmarks, apply fixes, and manage lifecycle (In Progress → Pending Review → Certified).
• Solid Analyze: Business users ask plain-language questions against certified models; answers are grounded in those models.
• Solid MCP server: Exposes four tools to any MCP-compatible agent (SQL generation, glossary, asset info, semantic model QA).

What is the DB Agent?

A detachable, read-only bridge near your warehouse. It validates generated SQL (Pass/Fail + errors only). It does not return raw query results to Solid; execution for real answers happens under the user’s identity at the agent/warehouse.

---

Quick facts

---

Standard Uses

Use this as the default playbook for rolling out and operating Solid. Each step assumes one semantic model per use case (narrow scope, clear description, intended business questions).

1. Before you start (everyone) — Solid Analyze and MCP SQL generation use certified semantic models. Build and Iterate happen in Solid Build. Keep models focused; see How many columns should a model have? and Can one model cover everything?.

2. Business users — Ask (Analyze) — Open a certified model → Ask. Read the SQL, summary, and rationale / “why this query” when you need to debug phrasing. Use history and thumbs feedback. Ask is stateless (no chat memory): for follow-ups, use Ask new question and include needed context in the prompt. If answers are repeatedly wrong or off-domain, escalate to a modeler (routing, scope, or permissions).

3. Modelers — Draft (Build) — If your org has a non-production Solid environment, use it to experiment before promoting work. When creating a model: optional table list, business questions, and Describe / business context are all valuable—rich context helps Auto-Create. Expect a strong first draft, but plan for manual refinement (relationships, metrics, column audit, benchmarks).

4. Modelers — Refine — Use the graph and relationships to verify joins; audit columns (remove noise; stay near the ~100 column guideline). Add synonyms on tables/columns where people use different words. Add or curate certified / golden SQL from real patterns. Use custom instructions / business context for ambiguous metrics or entities (e.g. when “account” means different things in different parts of the company—spell out what it means in this model). Save regularly; model changes apply immediately.

5. Modelers — Benchmark — Review auto-generated benchmark questions. Every active question needs ground-truth SQL that runs and validates. Inactive rows are normal when SQL is missing or failed validation. If validation says a column isn’t in the model, add the column (or adjust the model), then re-validate. Aim for meaningful coverage—15–20+ validated questions is a practical starting band (heuristic, not a hard SLA). Only add expected SQL you believe is correct; wrong ground truth makes scores meaningless. Run the benchmark, read failures, and use compare runs when iterating so you can see what changed between attempts.

6. Modelers — Iterate & certify — Tune business context, synonyms, relationships, or ground truth (when question and SQL were misaligned). Re-run benchmarks after meaningful edits—especially after Describe / business context changes, since that text is sent with generation. Use Auto-Maintain and fix recommendations as your deployment provides them; all changes stay human-approved. Advance lifecycle In Progress → Pending Review → Certified when quality and governance criteria are met.

When things go wrong: Use the Troubleshooting cheat sheet.

---

Semantic model building

What inputs does Solid need?

Required: warehouse schema/metadata and query logs.
Optional but valuable: non-PII samples, wikis/docs, BI reports, catalog exports — better glossary, metrics, and descriptions.

What does Solid NOT ingest?

Raw production data as a general rule; PII is detected and dropped from samples; sources outside your configured scope. Unstructured data sources (e.g. docs) feed glossary/context, not as queryable tables.

How does Solid pick tables and columns?

From schema plus query qualification on history — a funnel from millions of raw queries down to high-value representative queries that teach joins, metrics, and certified SQL seeds.

What is the Metrics Library?

Metrics are extracted once, stored centrally, and referenced by models — so “MRR” means the same thing across models.

What is the Company Glossary?

Auto-built mapping of business terms to schema elements, used in generation and exposed via the Glossary MCP tool.

What are “custom instructions”?

Modeler-written rules that steer SQL generation for that model (definitions, filters, conventions).

Can one model cover everything?

Not recommended. Prefer granular, specific models. Routing signals are model description and business questions the model is meant to answer.

Does one SQL generation call span multiple semantic models?

Multi-model in a single generation call is on the roadmap—not available yet. Not in current state: each Ask or MCP SQL generation run is scoped to one semantic model. Broader questions should route to the right single model today, or your agent or application should break work into steps (e.g. multiple calls or separate questions)—not rely on Solid to fuse multiple models in one query until that capability ships.

How should I use “Describe this model” / business context?

Everything in Describe / business context is sent with generation—treat it like a spec: literal, non-contradictory, and aligned with how the tables and metrics actually work. After edits, re-run benchmarks (and spot-check Ask) because small wording changes can shift behavior. If instructions are vague, you get vague SQL—debug ambiguous prompts the same way you would an engineering spec.

What if the same word means different things in our company (e.g. “account”)?

Use synonyms on the right table/column and add business context for this model (e.g. “In this model, ‘account’ always refers to …”). Org-wide alignment belongs in shared glossary and metrics; model-specific disambiguation belongs in custom instructions for that use case.

How many columns should a model have?

Best practice: under ~100 columns per model for routing precision and accuracy.

---

Lifecycle & approvals

What are the model states?

In Progress → Pending Review → Certified → exposed to agents via MCP. Only certified models are served to MCP consumers.

Does Solid ever change my model without approval?

No. Automated outputs are reviewed; one-click apply still means a human gate before changes take effect.

What is the end-to-end flow (short version)?

Auto-generate draft → human edit → auto-generate benchmark Qs + ground truth → human review → run benchmark → apply fix recommendations → certify → auto-maintain as things change.

After I save model changes, do Ask and benchmarks use the new version?

Yes—changes apply immediately. Re-run an Ask answer if the model changed (use the refresh / rerun control where available). Re-run benchmarks after meaningful edits, especially Describe / business context, so scores reflect the current model.

---

Asking questions (Analyze & agents)

Should I use generic “chat with data” or Ask the model?

When a governed semantic model exists, Ask the model (Analyze) is preferred: it uses the certified model you selected. Generic chat that builds a just-in-time semantic layer is usually less reliable for recurring, governed questions.

Is Ask the model a multi-turn chat with memory?

No. Ask is stateless: it does not remember prior turns. For follow-ups, start Ask new question (or equivalent) and restate filters, entities, and time ranges in the prompt.

Why might my question fail or feel “wrong”?

Common causes: question is outside certified model scope, ambiguous (missing time grain, entity, metric definition), wrong model routed, or warehouse permissions block the data. Of course, all AI systems can make mistakes. When something looks off, submit feedback via the Solid UI—either in Ask the Model or in the MCP Usage tab—so the Solid team can investigate. You can also contact Solid directly; see Who to contact internally.

Does Solid ask clarifying questions?

The system can use clarification for underspecified questions (e.g. vague “sales”).

Where do answers come from?

Solid returns validated SQL (and explanation). Data is retrieved when your agent or client runs that SQL on the warehouse with appropriate credentials.

What does “reasoning transparency” mean?

Solid can explain how the question was interpreted, which model was used, which terms resolved, and why certain joins/filters were chosen. Use rationale / “why this query” (where available) to see limitations (e.g. case sensitivity in a grouping column) and how to phrase a clearer question next time.

What if two users give conflicting thumbs up / down on the same answer?

Thumbs help triage unexpected behavior. Conflicting subjective reads usually need a business owner or modeler to decide correct logic and SQL; update the model, benchmark ground truth, or permissions accordingly—not an automatic vote tally on correctness.

---

MCP tools — how agents should use them

What are the four tools?

1. SQL Generation — natural language → grounded SQL + explanation (and optional inline glossary context).
2. Glossary — define a business term in your org’s context.
3. Asset Information — metadata about a table/column/model (dimensions, usage, descriptions).
4. Semantic Model QA — what models exist, what they’re for, which business questions they support.

Typical call pattern

Optional: Semantic Model QA → optional Glossary → SQL Generation (for one target model per call) → execute SQL with user creds → optional Asset Information for follow-ups. If a user question spans domains, resolve that in routing or multiple agent steps—not by expecting one SQL generation to merge unrelated models automatically.

How accurate is MCP SQL generation?

About 97% with the full validation and correction loop in internal architecture testing. Your benchmarks on certified models are how you prove the ≥85% minimum bar (and improvement over time) for your automation—not one isolated headline number.

---

Benchmarking

What is a benchmark?

A set of test questions, each with certified ground-truth SQL. Solid runs its generated SQL, compares results to ground truth, and scores accuracy.

What counts as “pass”?

Primary: Result sets match between generated SQL and certified SQL. Secondary confidence: SQL structure and alignment with the semantic model.

What accuracy should we aim for?

Treat ≥85% as the minimum bar for automated SQL you rely on in production (certification, benchmarks, and human review or follow-on steps as your governance requires). 85–90% is a common early pilot band; higher is achievable with iteration.

What is “benchmark health”?

Quality of the test set: coverage (entities touched), validity (wording vs SQL), volume (enough questions), completeness (every question has ground-truth SQL). Unhealthy benchmarks can mislead you — fix them before trusting the score.

Where do benchmark questions come from?

Auto-generated from qualified SQL patterns; modelers edit, add, remove, and fix ground truth before trusting runs.

Why are some benchmark questions inactive?

If Solid could not attach or validate executable ground-truth SQL, a row may stay inactive. Only active, validated questions should drive the score. Add or fix SQL with run and validate before relying on the question.

What if ground-truth SQL references a column not in the model?

Add the column (or fix the model), then re-validate the question. You can add a question inactive first, fix the model, then activate it after validation succeeds.

Should I add a benchmark row if I know the expected SQL is wrong?

No. Benchmarks measure against trusted answers. Wrong ground truth produces misleading failures or false passes. Fix the SQL or the question wording first.

How many benchmark questions should we start with?

15–20+ validated, on-use-case questions is a reasonable starting band (heuristic). Expand coverage as the model’s real usage grows.

Can I compare two benchmark runs?

Yes. Comparing runs helps when iterating—e.g. a question passed then failed after a change, or the opposite—so you can tie behavior to edits or ground-truth fixes.

---

SQL generation, validation & correction

Is generation “one LLM call”?

No. It’s an agentic flow with static checks and a correction loop (up to 3 attempts).

What happens before the DB Agent runs?

Syntax analysis, DDL alignment, alignment to semantic model bounds (no inventing tables/columns outside the model).

What kinds of fixes run in the loop?

Syntax, content (wrong tables/joins), execution (wrong/empty results treated as failure), performance (timeouts/plan issues — customer-configurable timeouts).

How is “best” SQL chosen among attempts?

Success, non-empty results when appropriate, and alignment signals from the model.

What grounding improves accuracy?

Information: bounded schema scope, relationships, metrics, golden SQLs, glossary/synonyms, categorical values.
Process: self-correction, custom instructions, routing, benchmarking, explanations.

---

Auto-Maintain (schema drift & production learning)

What triggers maintenance suggestions?

• A — Benchmark failures → root cause + proposed fix.
• B — Warehouse changes → drift detected on a schedule (daily/weekly configurable).
• C — Production usage gaps → concepts agents ask for that models don’t cover.

Are fixes automatic?

Proposed automatically; applied only after modeler action (e.g. one-click).

---

Security, privacy & compliance (FAQ)

Does production data flow through Solid?

Query results for business answers: No — those flow agent ↔ warehouse under user identity. Solid validates with the DB Agent and does not use raw results as a data product.

Is SQL always read-only?

SELECT-only is enforced by non-LLM static analysis.

PII and samples?

PII detection on samples; suspect columns discarded. Metadata and patterns drive the model.

SSO?

SAML 2.0 and OAuth 2.0 via the platform’s identity integration (e.g. Okta, Entra).

What compliance and security practices apply?

SOC 2 Type II, annual penetration tests, supply-chain and code scanning, SIEM, encryption at rest (including customer-managed keys where applicable), TLS 1.2+ in transit. Details vary by deployment; confirm with your vendor security packet.

Deployment options (high level)

SaaS (Solid-managed Azure), private cloud (customer-hosted, Azure/AWS), and hybrid (control plane + customer data plane). Topology, connectivity, and required cloud services vary by deployment—confirm in your implementation plan with Solid and your infrastructure team.

---

Warehouses, exports & ecosystem

Which warehouses?

Snowflake, Redshift, BigQuery, Databricks (Unity Catalog), Microsoft Fabric / Synapse.

Cross-warehouse in one SQL?

Not in scope inside Solid. Orchestrate multiple MCP calls (one per warehouse/model) at the agent layer.

Where can models be exported?

Examples include Snowflake Semantic View, dbt YAML, Tableau .tds, LookML, Solid YAML, and runtime MCP. Customer owns the models.

---

Troubleshooting cheat sheet

---

Glossary (short)

---

Who to contact internally

Use your organization’s Solid admin or customer success contact for: access, SSO, DB Agent networking, warehouse allowlists, pilot success criteria, and escalation paths described in your agreement.