Building Production-Grade Conversational Analytics with LangGraph and Waii

waii · Tech · 2024 · source Agentic: yes · promotional bias: high · source-backed · extracted with prompt 0.5.5 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Conversational analytics and text-to-SQL for complex enterprise databases

Waii wanted a LangGraph-based conversational analytics application that lets users ask natural-language questions over complex database schemas while still generating accurate SQL joins, visualizations, follow-up conversations, security-constrained execution, and optimized queries.

Constraints:

• Natural-language analytics must hide SQL complexity from non-technical users without collapsing complex multi-table relationships.
• The SQL generator has to handle bridge tables, dimension joins, full outer joins, left joins for optional data, and long join chains.
• The runtime must preserve conversational state so follow-up questions and iterative analysis remain contextual.
• Generated SQL must be syntactically valid, optimized, and constrained by user-level row/column access policies.
• The article is vendor-authored and demonstrates one successful query path without independent accuracy or production reliability benchmarks.

Architecture

The application wraps Waii's text-to-SQL, query execution, and chart-generation APIs inside a LangGraph state machine. A question classifier decides whether a request needs database access, visualization, or a general LLM response. Database questions flow to Waii's SQL generator, which relies on a continuously refined database knowledge graph, join-path analysis, join-condition refinement, and a compiler/optimizer. The SQL executor applies security constraints and returns rows; a result classifier chooses data or chart presentation; a synthesizer returns the answer and loops back into the stateful conversation.

Diagram confidence: explicit (topology described by the source).

flowchart LR
  user-question["User question"] --> langgraph-state["LangGraph state"]
  langgraph-state --> question-classifier["Question Classifier"]
  waii-catalog-context["Waii catalog context"] --> question-classifier
  question-classifier --> waii-sql-generator["Waii SQL Generator"]
  question-classifier --> insight-generator["Insight Generator"]
  waii-knowledge-graph["Waii knowledge graph"] --> join-graph-analyzer["Join Graph Analyzer"]
  join-graph-analyzer --> waii-sql-generator
  waii-sql-generator --> compiler-and-optimizer["Compiler and Optimizer"]
  compiler-and-optimizer --> security-constraints["Security Constraints"]
  security-constraints --> waii-sql-executor["Waii SQL Executor"]
  waii-sql-executor --> result-classifier["Result Classifier"]
  result-classifier --> waii-chart-generator["Waii Chart Generator"]
  result-classifier --> result-synthesizer["Result Synthesizer"]
  waii-chart-generator --> result-synthesizer
  insight-generator --> result-synthesizer
  result-synthesizer --> langgraph-state

Components

Data flow

A user question enters the LangGraph workflow state. The question classifier fetches Waii catalog context and classifies the request as database, visualization, or general. Database requests go to Waii Query.generate, whose table-selection and join-analysis flows use schema, constraints, query history, documentation, catalog relationships, and feedback. The compiler/optimizer checks SQL syntax, performance, and operational limits. The executor injects row/column security constraints and runs the query. A result classifier chooses data or visualization, Waii can generate charts from returned data, and the result synthesizer produces a response before the workflow loops for the next turn. On errors, LangGraph can rewrite and regenerate objects.

Why this architecture

The architecture separates workflow control from domain-specific SQL generation. LangGraph supplies stateful routing, loops, and multi-node orchestration, while Waii supplies specialized text-to-SQL, join planning, execution, and visualization capabilities. This is appropriate because the hardest part of the case is not generic conversation but accurate database relationship handling across complex schemas and join types.

Models used: OpenAI ChatGPT via ChatOpenAI · Waii text-to-SQL engine · Waii text-to-chart engine · LangGraph state machine

Scale

• The demonstration query spans 14 database tables.
  “14 tables used in the query with different qualifiers, arity and semantics.”article, stated
• The example asks for the top 5 directors by title count.
  “Create a view that provides the following information for the top 5 directors (by the highest number of titles):”article, stated
• Waii positions table selection for large databases as a required capability.
  “Scalable table selection for large databases”article, stated
• Operational constraints include maximum output rows and maximum input partitions.
  “We also enforce operational constraints placed by the user on the query (e.g., max output rows, max input partitions).”article, stated

Alternatives considered (roads not taken)

Use a generic LLM to write SQL from natural language without a specialized database relationship layer.

Rejected because: The article argues complex joins require table selection, join graph analysis, join-condition refinement, and compilation/optimization rather than only prompting a model.

Rely only on direct semantic matches between the user question and table names.

Rejected because: Waii uses relationship semantics and common join paths to find tables that may not be directly mentioned or semantically linked in the user input.

Present all SQL results as raw data.

Rejected because: The application classifies whether the result should be presented as data or a visualization and can call Waii chart generation when a chart is more appropriate.

Treat execution as a direct run of generated SQL.

Rejected because: The design inserts security constraints and operational limits around execution, so generation and execution are not a single unconstrained step.

Patterns

tool-use-orchestration (architecture)

LangGraph routes each conversation turn across classifiers, Waii SQL generation, Waii execution, Waii charting, and LLM synthesis rather than relying on one monolithic prompt.

prompt-chaining (architecture)

The workflow chains a question-classification prompt, SQL generation, result classification, optional chart generation, insight generation, and final synthesis.

query-rewriting (reliability)

On errors or exceptions, the LangGraph loop can rewrite the input and regenerate the required SQL/chart objects.

guardrails-io-filtering (safety)

The query execution path injects row and column access policies and enforces operational limits before running generated SQL.

data-quality-loop (operations)

The database relationship graph is updated from schema changes, query history, documentation, catalog relationships, and feedback from system usage.

Tradeoffs

Use specialized Waii SQL services inside LangGraph rather than asking a generic LLM to own the full analytics path.

Chose LangGraph orchestration plus Waii text-to-SQL/text-to-chart APIs over A single generic LLM prompt that classifies, writes SQL, executes, visualizes, and answers.

Rationale: The article's core risk is complex database join correctness, so a specialized relationship graph, join planning, compiler, and execution layer are a better fit than a generic one-shot prompt.

Represent database relationships as a continuously refined knowledge graph.

Chose A graph fed by schema, constraints, predictions, query history, documentation, catalogs, and feedback over Static schema-only metadata.

Rationale: The graph lets Waii reason about implicit relationships, historical joins, and feedback over time, which is necessary for paths not directly obvious from the user's words.

Split query generation into agentic subflows.

Chose Table selection, join graph analysis, join-condition refinement, query construction, and compilation/optimization over One undifferentiated SQL-generation step.

Rationale: Separating these steps makes it possible to reason about table relevance, join paths, outer join conditions, syntax, optimization, and operational limits independently.

Route returned results through a visualization decision.

Chose A result classifier that chooses data or chart generation over Always returning tables of rows.

Rationale: Conversational analytics users may need visual insight rather than raw rows, so the workflow branches to chart generation when the answer is better expressed visually.

Keep security and operational constraints in the execution path.

Chose Injected user-level policies and max row/partition constraints over Trusting the generated SQL text alone.

Rationale: Even if generated SQL is syntactically correct, the runtime still needs governance and resource limits before executing against real databases.

Gotchas (what bit them)

Complex text-to-SQL fails if join semantics are treated as a shallow table-name matching problem.

Root cause: Many business questions require bridge tables, dimension tables, full outer joins, optional left joins, and chains between distant entities.

Resolution: Build and refine a database relationship graph, then run table selection, join graph analysis, join-condition refinement, query construction, and compilation as separate flows.

Outer joins can silently become wrong if conditions are placed in the wrong clause.

Root cause: Outer join logic depends on subtle differences between ON and WHERE conditions, especially when optional data is involved.

Resolution: Use a dedicated join-condition evaluation/refinement step that checks outer joins and ON-vs-WHERE behavior.

Conversational analytics needs state, not just one-shot SQL generation.

Root cause: Users ask follow-up questions and iterative analytic requests that depend on prior context.

Resolution: Keep a LangGraph state object and conversation-management loop across query, SQL, data, chart, insight, response, error, and routing fields.

Generated SQL can bypass governance if execution security is bolted on too late.

Root cause: A natural-language SQL workflow can produce queries whose row and column access must still respect user-level policies.

Resolution: Inject user-level row/column access constraints into the Waii execution API and enforce operational query limits.

The case study's accuracy claims should not be treated as independent production evidence.

Root cause: The article is vendor-authored and presents a single successful complex query without comparative benchmarks or failure-rate measurements.

Resolution: Use the architecture and concrete query mechanics, but treat claims such as high accuracy and scalability as promotional unless independently evaluated.

Evaluation

The article evaluates by walking through a complex director-performance query and implementation code rather than reporting an independent benchmark. The observable checks are structural: 14-table join coverage, bridge/dimension/full-outer/left join handling, syntactic compilation, optimization, operational constraints, security injection, and visualization routing.

Metrics: 14 tables used in the example SQL query · Top 5 directors by title count in the example request · Coverage of bridge table joins, dimension joins, complex join chains, full outer joins, and left joins for optional data · Syntactic correctness and query optimization through a compiler · Operational constraints such as maximum output rows and maximum input partitions · Row and column access security injection at execution time · Routing accuracy between database, visualization, and general-answer paths · Ability to loop, rewrite, and regenerate on errors or exceptions

Outcomes

• The article demonstrates a LangGraph workflow that routes natural-language analytics requests through Waii SQL generation, execution, charting, and response synthesis.
• The example query combines movies, TV series, genres, keywords, awards, revenue, and actors for director-performance analysis.
• The generated SQL uses CTEs and multiple join types, including full outer joins and optional left joins.
• The implementation includes state management, error restart behavior, user-level security constraints, and chart generation.
• The article claims accessibility, depth of analysis, contextual understanding, visual insights, and scalability as benefits, but does not provide independent measured production outcomes.

The concrete scale evidence is the 14-table example query, top-5 director request, large-database table-selection claim, and operational row/partition constraints. The article does not report latency, accuracy, usage volume, cost, or production adoption numbers.