Architecture Overview

What is Veezoo?

Veezoo is an Agentic Analytics platform that allows anyone to ask questions in natural language and get precise, trustworthy answers directly from their data warehouse. At the heart of this architecture is the Veezoo Knowledge Graph, which provides the foundation that makes every answer accurate, understandable, and aligned with a company's business logic and permissioning.

The Knowledge Graph

The Knowledge Graph serves as a semantic layer that abstracts the data warehouse complexity for business users, incorporating governance and trust. Furthermore, it serves as the contextual foundation that enables the Veezoo AI to understand and respond to user questions accurately. Companies can have one or multiple knowledge graphs depending on use-case and architectural preferences. E.g. A company might have Knowledge Graphs for sales, finance, HR and permission them accordingly.

A Knowledge Graph captures:

• Business concepts: Classes (e.g. Customer, Order, Product), their specific entities (e.g. Coca_Cola, Pepsi, Microsoft), and relationships between classes, all mapped to underlying data warehouse tables and columns
• Semantic definitions: Business glossary, concept descriptions, and operational context that align with company terminology and processes
• Metrics & KPIs: Reusable measure definitions with precise calculation logic (e.g., "Revenue" always excludes returns and taxes)
• Governance rules: Role-based access controls, row-level permissions, and data visibility restrictions
• AI behavior guidance: Instructions for how the AI should approach analysis, interpret questions, respond to users, and what tone of voice to use
• Business logic: Complex calculations, data validation rules, and domain-specific transformations

The Knowledge Graph presents a normalized, relationship-rich view of your business concepts regardless of your underlying data warehouse structure. Whether your data warehouse uses a single denormalized table, star schema, or data vault architecture, the Knowledge Graph models intuitive business relationships like "Customer places Order for Product" that users can naturally explore.

Modeling Tip

Prefer modeling relationships only at their natural level of granularity. If a clear path already exists, avoid adding redundant direct relationships. For example, prefer Line Item → Order and Order → Store rather than also adding Line Item → Store — unless line items can belong to different stores. This keeps the graph simpler, avoids ambiguity, and ensures consistent results.

The Knowledge Graph is defined in VKL (Veezoo Knowledge Language) and can be queried to get results from the underlying data sources using VQL (Veezoo Query Language). VQL acts as an intermediate language that the AI uses to bridge natural language questions and SQL queries, operating on Knowledge Graph concepts rather than raw database tables.

These layered abstractions — from raw tables to business concepts and reusable measures — let Veezoo answer complex questions using simple, high‑level terms while hiding all technical complexity.

No Data Copying

The Knowledge Graph contains semantic metadata and business logic definitions, not the company's raw transactional data. It provides a semantic layer that maps business concepts to the underlying data warehouse.

How Veezoo Processes a Question

When a user asks a question, Veezoo processes it through a sequence of steps, each involving sophisticated technology working behind the scenes:

Query Processing Sequence

1. Natural Language Input
   A user submits a question in plain language.

2. Semantic Interpretation
   Veezoo parses the question to identify relevant classes (Customer, Product), specific entities (Bill_Gates, Coca_Cola, Pepsi), metrics (Revenue), time periods (Q4 2023), and other building blocks using the Knowledge Graph as a reference.

3. Agentic Plan
   Based on the Knowledge Graph, the chat history, and the current question, Veezoo builds an execution plan determining which VQL queries to run and in what order. Simple questions use straightforward plans, while complex analyses may require adaptive plans that adjust based on intermediate results.

4. VQL to SQL Compilation
   Each VQL step is compiled deterministically into SQL, taking all business logic and governance rules into account.

5. Execution
   The SQL runs directly in the customer's data warehouse. No data movement or duplication is required.

6. Visualization
   Veezoo picks the best-fitting visualization for the retrieved results and may also generate natural language summaries.

Key Architectural Principle

The AI does not write SQL. The AI only reasons over business concepts in the Knowledge Graph; compilation from VQL to SQL is deterministic and happens without AI involvement. This is why you can't "jailbreak" it into listing raw tables and why Veezoo computes your KPIs accurately every time. Users never interact with the data warehouse directly; they interact with the modeled and exposed business concepts. This separation of concerns ensures KPI definitions are applied exactly as modeled.

Frequently Asked Questions

These are some of our most common questions. If yours isn't listed, please reach out to support@veezoo.com.

"How can we trust AI-generated analytics results? What prevents hallucinations?"

The concern: AI tools often generate plausible-sounding but incorrect answers, making them unreliable for business-critical decisions.

Veezoo's approach: Veezoo's architecture eliminates AI hallucinations through deterministic result generation and abstraction layers:

• Pre-Defined Business Logic: The AI operates exclusively on pre-defined business concepts and measures within the Knowledge Graph, preventing results from deviating from established business definitions
• Deterministic Computation: The VQL → SQL pipeline follows rule-based compilation that can be inspected at every step — technical users can examine both the VQL and the generated SQL for complete result traceability
• Transparent Dynamic Calculations: When the AI creates dynamic measures (sums, averages, percentages), it provides clear explanations and uses reusable measure abstractions, maintaining consistency across users and questions. For example, if the graph defines an Order concept, Veezoo can compute "Number of Orders" without a pre‑defined measure and show the exact formula. This balances central governance of core KPIs with decentralized freedom to explore.
• Consistent Presentation: Chart titles, filters, and labels are constructed directly from Knowledge Graph metadata and executed VQL, eliminating dependence on unpredictable language model generation — deterministically rendered from VQL to always match the charts.

"How can we make sure that users only see what they are allowed to see?"

The concern: Different teams need access to different data sets, and we can't risk unauthorized access to sensitive information.

Veezoo's approach: Multi-layered security that prevents prompt injection attacks and unauthorized access:

• Knowledge Graph Level Access: Control which Knowledge Graphs users can ask questions about based on role. Assign Finance teams to the "Financial Analytics" graph while restricting HR teams to the "People Analytics" graph
• Column-Level Security: Granularly control attribute visibility. Restrict Profit_Margin to only "management" and "finance" roles, or limit PII fields like Customer_SSN to "admin" users only, making sensitive concepts completely invisible to unauthorized users
• Row-Level Security: Implement filtering based on user attributes. C-level executives see data across all customers while account executives only see their own portfolio where account_owner matches their user ID
• Prompt Injection Protection: Because the AI never writes SQL directly and operates only on pre-defined business concepts, users cannot "jailbreak" the system to access unauthorized data

"What happens when our database schema changes? Will everything break?"

The concern: Schema changes typically break analytics tools and require extensive updates across multiple systems.

Veezoo's approach: Resilient architecture that adapts to database evolution:

• Isolated Impact: When underlying table structures change, only the VKL mappings need updating — dashboards, user queries and business logic remain intact
• Continuous Availability: Business users can continue asking questions while data teams update the semantic mappings behind the scenes
• Change Management: The Knowledge Graph acts as a buffer between business users and technical schema changes, maintaining consistent business definitions even as data structures evolve
• Business Continuity: Users continue working with the same familiar business concepts regardless of technical changes underneath

"Do we need to move our data or create additional infrastructure?"

The concern: Data movement creates security risks, compliance issues, and additional infrastructure costs.

Veezoo's approach: Works directly with your existing data warehouse:

• No Data Duplication: All processing happens directly in your existing data warehouse — no ETL pipelines to maintain
• Real-Time Insights: Every query returns the most current data from your source systems, ensuring decisions are based on live information
• Single Source of Truth: Users access the same data warehouse that powers your other critical systems, eliminating inconsistencies between analytics tools
• Native Processing: Leverages your warehouse's native compute power and optimizations for maximum performance

"How can we audit and validate the results that AI provides?"

The concern: We need full transparency and auditability for compliance and trust in business-critical decisions.

Veezoo's approach: Complete visibility into every step of query processing:

• VQL Visibility: Technical Users can inspect the intermediate Veezoo Query Language (VQL) that represents their question
• SQL Generation: View the exact SQL query that Veezoo compiles from VQL, ensuring full auditability of results
• Deterministic Pipeline: The VQL → SQL transformation is rule-based and repeatable, not dependent on unpredictable AI model behavior

"Can my data team see what users are asking and how Veezoo is being used?"

The concern: We need visibility into adoption, questions, and performance to drive success.

Veezoo's approach: MetaVeezoo provides transparent monitoring and actionable insights:

• Usage analytics: Track logins, number of questions, feedback trends, and adoption over time
• Question intelligence: See asked questions and unrecognized concepts to proactively extend the Knowledge Graph
• Experience optimization: Identify friction, personalize onboarding, and measure content effectiveness
• Performance monitoring: Monitor SQL durations and system behavior to catch issues before users do
• Custom dashboards: Build tailored monitoring boards to focus on the KPIs that matter to your org

"Will investing in names, descriptions and context actually improve business adoption and AI accuracy?"

The concern: We don't want to spend time documenting concepts if users won't benefit.

Veezoo's approach: It's a two‑for‑one — the same Knowledge Graph metadata powers both the user experience and the AI's reasoning:

• Improved Data Literacy: Users interact with clear business concepts (e.g., Customer, Revenue, Orders) instead of cryptic tables/columns
• Consistent Definitions: KPIs are defined once in the Knowledge Graph and reused everywhere, eliminating multiple versions of truth
• AI‑Powered Accuracy: Richer descriptions, synonyms, and business rules increase answer precision and reduce misunderstandings
• Two‑for‑one Documentation: Descriptions are displayed to users and consumed by the AI to interpret questions correctly

"Do we need a specific data model for Veezoo to work (star schema, naming, conventions)?"

The concern: We don't want to remodel our warehouse just to adopt Veezoo.

Veezoo's approach: No redesign required — Veezoo works with a wide range of modeling styles:

• Flexible modeling: Supports denormalized flat tables, star/snowflake, data vault, and mixed/legacy models
• Name abstraction: Table and column names can be cryptic; VKL maps clean business concepts to any physical names
• Relationship modeling: The Knowledge Graph expresses business relationships regardless of the underlying physical structure

Best practice: If you can choose, a normalized model is preferable as it will have the lowest complexity and require the least amount of configuration to setup.

"How long does it take to set up, and how easy is it to maintain?"

The concern: We need fast time‑to‑value and a low‑overhead way to keep things current.

Veezoo's approach: Rapid setup and streamlined maintenance:

• Minutes to first answers: Once the data warehouse connection is established, Veezoo Studio can auto‑generate your initial Knowledge Graph so teams can start asking questions the same day
• Guided modeling UI: Use Studio to refine names, relationships, measures, and permissions with smart suggestions, previews, and validations
• Copilot‑assisted changes: A powerful Copilot helps implement VKL changes and best practices quickly (e.g., synonyms, defaults, tests) — all trackable in Git
• Safe rollout: Develop in branches and promote changes via reviews and tests without impacting business users
• Low operations: No data movement; deterministic VQL→SQL. Ongoing updates like entity syncs are automatated and tweaks are quick and auditable

"How does entity awareness improve the user experience and reduce errors?"

Veezoo models real‑world entities in the Knowledge Graph — not just strings. Entities are the actual distinct values behind your classes (e.g., "Amazon" as a Customer, "iPhone 15" as a Product), synced/indexed from your warehouse. This brings practical benefits for business users and governance:

• Context‑Aware Autocomplete: Suggests valid entities, measures, and relationships as users type, accelerating analysis
• Entity Recognition: Knows which specific customers/products actually exist based on synced entities, avoiding blind string search and mismatches
• ID-to-Entity Resolution: Maps technical IDs (e.g., Customer ID 723) to real entities (e.g., "Acme GmbH"), so users can ask with names or IDs while results and filters remain human-readable
• Disambiguation & Synonyms: Resolves ambiguous terms and supports business lingo via synonyms so users can ask naturally
• Error Prevention: Prevents invalid queries before execution by validating against known entities and semantics
• Consistent Metrics by Entity: Ensures entity-scoped measures behave consistently across questions and visualizations

"Can our data team manage the Knowledge Graph as code and promote changes safely without impacting business users?"

Yes. The entire Knowledge Graph is defined as VKL code and stored in a Git-backed repository, so it fits naturally into standard software development workflows:

• Version control: Every change to VKL files is tracked, diffable, and auditable
• Safe collaboration: Multiple contributors work on Git branches without impacting the live graph; business users continue using the main branch
• Code review & CI: Review VKL diffs and run validations/tests before merging
• Isolated testing: Use Veezoo's development branches and tests to validate changes against real questions and boards prior to rollout