How LangGraph + Waii Turn Natural Language into Complex SQL Queries

0 Preface

In today’s fast‑moving data‑analysis landscape, the ability to interact with data through natural language is increasingly valuable. Conversational analytics aims to make complex data structures accessible to users without specialized skills.

LangGraph is a framework for building stateful, multi‑agent applications that use language models. Waii provides text‑to‑SQL and text‑to‑chart functions, allowing users to query databases and generate visualizations via natural language.

This article explores how Waii enhances LangGraph applications for conversational analytics, focusing on Waii’s handling of complex joins—a critical aspect of generating accurate SQL from natural language.

1 Waii’s Text‑to‑SQL Capabilities

Waii offers a comprehensive text‑to‑SQL solution that excels in several areas:

High‑precision complex pattern joins

Scalable table selection for large databases

Custom compiler for syntax correctness and query optimization

Agent flows tailored to filters, sorting, and common metrics

The following sections dive into how Waii processes complex joins, illustrating the approach with a concrete example.

2 Deep Dive: Join Handling

Example

Imagine a streaming‑platform data team tasked with building a dashboard that evaluates director performance by combining movies, TV shows, genres, keywords, awards, and actor collaborations.

Instructions

Create a view that, for the top 5 directors by title count, returns:

Director name

Total title count

Most frequent genre

Most frequent keyword

Award count

Total movie revenue

List of collaborating actors

Generated Query (excerpt)

...</code>
<code>FROM ranked_directors AS rd</code>
<code>INNER JOIN movie_db.movies_and_tv.people AS p ON rd.people_id = p.people_id</code>
<code>LEFT JOIN combined_director_genres AS cdg ON rd.people_id = cdg.people_id AND cdg.genre_rank = 1</code>
<code>LEFT JOIN combined_director_keywords AS cdk ON rd.people_id = cdk.people_id AND cdk.keyword_rank = 1</code>
<code>LEFT JOIN director_awards AS da ON rd.people_id = da.people_id</code>
<code>LEFT JOIN director_revenue AS dr ON rd.people_id = dr.people_id</code>
<code>LEFT JOIN director_actors AS d_actors ON rd.people_id = d_actors.people_id</code>
<code>...

Query Analysis

Complex join graph: Uses 14 tables with varied qualifiers and semantics.

Bridge tables: Resolve many‑to‑many relationships (e.g., director ↔ movies/TV shows ↔ actors).

Dimension table joins: Enrich data with descriptive information from genre and keyword tables.

Deep join chains: Connect distant entities, such as linking directors to actors through collaborations.

Full outer joins: Combine director work across movies and TV shows for comprehensive coverage.

Left joins for optional data: Include awards and revenue only when available.

Additional considerations include the distinction between ON and WHERE clauses, join order, non‑equijoins, and horizontal joins for semi‑structured data.

3 Knowledge‑Graph Construction

Waii automatically builds a comprehensive knowledge graph of database objects, incorporating:

Schema information

Constraints (primary/foreign keys)

Predictions based on column names and data patterns

Ranked join graphs extracted from query history

Database documentation

Declared relationships in the data catalog

Feedback gathered from system usage over time

The graph is continuously updated as schemas change, new queries are issued, and feedback is collected.

4 Agent Flow for Query Construction

With the knowledge graph, Waii follows a multi‑step agent process:

Table selection: Analyze the user request to identify the most relevant tables, using known join relationships and semantic understanding.

Join‑graph analysis: Propose and evaluate potential join paths between selected tables, scoring them against prior patterns and semantic alignment.

Condition evaluation/refinement: Verify that outer joins and join predicates are correctly applied, distinguishing ON versus WHERE clauses.

Query building: Assemble the final SQL statement based on the chosen join graph and conditions.

Compilation and optimization: Ensure syntactic correctness, apply performance optimizations, and enforce user‑level constraints (e.g., max rows, partition limits).

The result is an accurate, performance‑tuned SQL query that directly answers the user’s natural‑language question.

5 Building Conversational‑Analytics Applications

Integrating Waii with LangGraph enables developers to create agents that maintain interaction context while executing complex queries, thereby enhancing overall application intelligence.

6 Implementation Details

Key components for a production system include:

LangGraph framework for multi‑agent orchestration and state management.

Waii API integration for text‑to‑SQL and text‑to‑chart capabilities.

Natural‑language processing to interpret user input and generate readable responses.

Waii execution API to run generated SQL with security policies (row/column restrictions).

State management to preserve context across multiple user turns.

A typical interaction loop:

User submits a natural‑language question.

LangGraph classifier decides whether to answer from memory or the database.

(Optional) Waii generates an optimized SQL query.

(Optional) Waii executor applies security constraints and runs the query.

(Optional) Result classifier determines whether to return raw data or a visualization.

(Optional) Waii chart generator creates a relevant chart.

LangGraph insight‑generation agent compiles the final response.

Loop repeats for follow‑up questions.

The conversation manager maintains state, enabling context‑aware follow‑ups and smoother interactions.

7 Benefits and Use Cases

Combining LangGraph and Waii offers several advantages:

Accessibility: Non‑technical users can perform complex data analysis via natural language.

Analytical depth: The system handles challenging queries that would be difficult to craft manually.

Context awareness: State maintenance allows more natural, context‑sensitive data conversations.

Visual insights: Automatically generated charts enhance data comprehension.

Scalability: The architecture adapts to large, complex databases without increasing user burden.

Potential applications span business intelligence, healthcare research, finance, e‑commerce, and education.

8 Conclusion

The synergy of LangGraph’s multi‑agent capabilities and Waii’s advanced text‑to‑SQL and visualization features opens new possibilities for data analysis and processing. By making sophisticated analytics accessible through natural language, this approach significantly lowers the barrier to extracting high‑quality insights from data.