> This is part 1 of 29 of the full documentation (pages 1–100 of 2858). > The content is paginated: fetch every part to see all of it. > Next part: https://help.tellius.com/llms-full.txt/1 > Page index: https://help.tellius.com/llms.txt # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation This site has an agentic ask interface you may use to query the documentation dynamically by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.tellius.com/index.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. --- # Say Hello to Tellius New to Tellius? Explore our glossary, navigation tips, and guided tours to get started quickly and confidently. Welcome to Tellius! 😊 Whether you're opening Tellius for the first time or checking what's changed, this page gets you there fast. {% hint style="success" %} **Latest release: Tellius 6.4** · **Latest patch: 6.3.2** Patch 6.3.2 brings read-only conversation sharing with a "Continue this Conversation" option, shareable Vizpad Custom Views, section-level Selective Export, platform-wide Scheduled Jobs management for Super Users, and Mission attribution in Kaiya answers — plus a guided home page tour for new users. → [See everything in Patch 6.3.2](https://help.tellius.com/whats-new/release-6.3/patch-6.3.2) → [Explore Release 6.4](https://help.tellius.com/whats-new/release-6.4) {% endhint %} ### Learn by doing Guided tours walk you through the platform hands-on, right inside Tellius. Signing in for the first time? A home page tour starts automatically and introduces the essentials. ### Stay current Every release and patch is documented under [✨ What's New](https://help.tellius.com/whats-new/release-6.3). This page always points to the latest. # Tellius Glossary Explore key Tellius terms with our easy-to-read glossary and learn how each feature helps you navigate the platform, analyze data, and gain insights. To help you navigate the platform and understand its features better, we have compiled a glossary of all the Tellius-specific terms and their definitions. **Search Query:** A question or request relating to the data of interest. **Search Guide:** A user guide containing tips on how to ask different types of questions, which also includes a set of pre-defined and customizable search examples for the selected Business View. **Search Inspector:** The configuration of the output that is shown to a user after executing a search, and can be hidden on the screen or reopened at any time. **Vizpad:** An interactive dashboard with multiple chart types and various filter options. It also integrates with the rest of the platform - with unlimited drilling through dimensions, anomaly detection, one-click insights, and predictive modeling. All Vizpads can be accessed under "Explore". **Viz:** An individual chart within a Vizpad. **Insight:** Insights refer to the outcomes derived from machine learning or statistical inference techniques to extract a better understanding of your data. **Key Driver:** These are the critical factors significantly impacting a business or event. For example, identifying the key characteristics of returning customers can help businesses to understand their customer base. **Trend:** Trend analysis helps you identify the factors driving changes in your business KPIs over time. For example, it can help you investigate the reasons behind a sudden surge in revenue in March 2021 as compared to February 2021. **Comparison:** Understand the differences between two or more groups or segments based on your business KPIs. For example, you can compare the revenue generated by millennials for cell phones versus headphones to identify which product category is more profitable for this group. **Anomalies/Correlations:** While exploring search or visualization, anomalies help identify key relationships or significant changes in dimensions. **Regression:** A type of supervised machine learning that involves predicting a continuous variable based on other input variables. For example, predicting the price of a house based on its size, location, and other relevant factors. **Classification:** A type of supervised machine learning that involves predicting a discrete (binary or multi-class) label or category for a given input. For example, predicting customer churn. **Time Series Regression:** a statistical method for predicting future values of a time series based on its historical trend. For example, predicting the temperature for the next hour based on its past values. {% hint style="info" %} **Time Series Regression** differs from **Regression** in that it only uses the historical trend of the time series itself for prediction and is only applicable to time-based data. {% endhint %} **Clustering:** An unsupervised machine learning technique that involves identifying natural groupings or patterns in data. **Target (dependent variable):** The output variable that you are trying to predict. It is stored as an individual field in your data. For example, in a model that predicts house prices, the target variable would be the price. **Feature (independent variable):** An input variable representing a property or characteristic to help predict the target variable. It is stored as an individual field in your data. For example, in a model that predicts house prices, the features could include the size, location, number of bedrooms etc. Machine learning models often have many features as inputs. **Connector:** A source system or application from which data can be imported into Tellius. **Datasource:** A unique combination of a Connector and the credentials used to authorize the connection to that source. For example, you may have different data warehouses or schemas that different users have access to, with the same Connector. **Datasets:** Single table-like structures of data with rows and columns. **Business View:** A Business View is a logical layer that defines how datasets relate to one another (similar to a data model). It helps users create and build logical data models to start their analysis, enabling them to identify their logical schema and connect their datasets accurately from various sources together into one view of data that can be easily accessed and analyzed. # Tellius 101 Tellius: AI analytics platform that connects data sources, with natural-language search, predictive models, and self-service BI to surface actionable insights. **What is Tellius?** Tellius is an advanced analytics platform designed to help businesses of all sizes unlock the full value of their data and make informed decisions. By connecting to a variety of data sources and using machine learning algorithms, Tellius helps users quickly uncover insights and patterns in their data. At its core, Tellius is built on a highly scalable and modular architecture that can handle large and complex datasets. Whether you're looking to improve customer experiences, optimize supply chains, or make better financial decisions, Tellius can provide the insights and recommendations you need to succeed. **What can Tellius do?** Some key features of Tellius include: * **Data integration:** Tellius can connect to various data sources, including databases, cloud platforms, and file systems. Users can easily blend and transform their data to make it more useful and actionable. * **AI-driven insights:** Tellius uses advanced machine learning algorithms to automatically identify trends and patterns in data, and provides real-time recommendations to help users make better decisions. * **Natural language processing:** Tellius offers a conversational interface that allows users to ask questions in plain English and get instant answers. This makes it easier for non-technical users to work with data. * **Predictive analytics:** Tellius can automatically generate predictive models that help users anticipate future outcomes and optimize business strategies. * **Self-service BI:** Tellius enables business users to create and share interactive dashboards, reports, and visualizations without relying on IT or data science teams. This makes it easier for organizations to democratize their data and empower their employees. * **Data governance:** Tellius provides robust security and compliance features that help organizations maintain data privacy and regulatory compliance. This is important for businesses operating in highly regulated industries. **How to perform analysis on Tellius** Follow the step-by-step process outlined below to get the most out of Tellius: 1. **Connect to a datasource.** Identify where your data lies and import into Tellius. 2. **Refine your datasets**: Clean, prepare, and transform your data to create well-defined datasets. 3. **Create Business Views.** Join multiple datasets to create clearly defined Business Views that can help you throughout your analysis journey. 4. **Start asking your questions in Search.** Type in your question in natural language in the Search bar and get your answers visualized in charts. 5. **Build Vizpads.** Create charts and construct Vizpads from a single or multiple Business Views. Use local and global filters to drill down your analysis. 6. **Identify patterns.** Now you have seen the "What" part, get ready for the "Why" part. Go to Insights to discover trends, compare, or find anomalies to understand the reason behind your results. 7. **Build ML (Machine Learning) models.** Once you have understood the historical and current trends, predict the future trends using the existing data. 8. **Save to Projects.** When you have multiple objects (Vizpads/Insights/Models) pertaining to the same concept, organize them into a Project for easy access. 9. **Share and collaborate.** Share the saved objects with your team members and assign the required permissions. # Navigating around Tellius Explore how to navigate Tellius—from Search and Vizpads to Insights, Predict, Data, and Projects—with a clear overview of every module and homepage feature. Tellius provides a user-friendly interface to make it easy for you to navigate around the platform. This page breaks down each component that you can see on the home page (the first page that greets you with when you log into Tellius).

Tellius Homepage

1. **Left navigation pane** The left navigation pane consists of the following tabs. Click on any of the tabs to go to the respective page. * **Search** - It's the place where you can type in your queries in natural language and get them answered. Before typing in the questions, it is necessary to choose the relevant Business View from where the data is to be considered. An initial set of suggested questions are also displayed related to the selected Business View. * **Explore (Vizpads)** - Vizpads allow you to build effective dashboards using multiple charts (Viz) and conduct visual exploration analysis by applying various filters to drill down the results. A Vizpad can be built from multiple Business Views. Here, you can access all Vizpads created by you/shared with you. * **Discover (Insights)** - With Insights, users can discover answers to deeper questions and identify important patterns/relationships in your data. Here, you can access all Insights created by you/shared with you. The Insights are organized into categories such as key drivers, trends, comparisons, and anomalies/correlations. * **Predict -** Tellius offers a range of machine learning models to its users, including regression, classification, time series regression, and clustering, which can be built easily via AutoML or Point-n-Click. With these models, users can forecast future trends and make predictions based on their current data. Here, you can access all models created by you/shared with you. If you hover over **Search**, **Explore**, **Discover**, or **Predict**, you can find a little orange inverted triangle at the bottom right of every tab. Click on it to view and navigate to the objects marked "Favorite" and the recently opened objects.

Marking objects "Favorite"

* **Feed** - Set up automated tracking of your important KPIs and get notified (via emails) of any detected anomalies. Here, you can create and manage the metrics to be tracked. * **Assistant** - Consider it your personal assistant to whom you can converse in natural language, as it will provide relevant suggestions and recommendations based on the questions asked. * **Data** - All operations related to the data—from connecting to data sources, uploading data, building Business Views, cleaning data, transforming data, and scheduling data flow—can be performed (depending on the permission level of each user) here. * **Projects -** Think Projects like folders, where you can organize related content together in one Project. A Project may consist of multiple Vizpads, Insights, and Models. Objects which are not a part of any specific Project (unassigned objects) can also be found here. * **Backup -** As a part of Disaster Recovery, Tellius offers you with a couple of backup options. From here, you can backup data and restore them as required. * **Monitor -** Displays the system health, where you can monitor and understand the memory utilized for different functions performed on the platform. * **Help -** Click here if you ever feel stuck. Get access to our product videos, guided tour, FAQs, and user guide. From this page, you can also raise a ticket or provide feedback/suggestions. * **Notifications -** All the details of every operation that has been performed on the platform can be accessed here. The information on each notification includes the owner of the job, the timestamp of execution, type of object, and the status of the job (success or failure). * **User icon -** Indicates the current user account logged onto Tellius. It's the place where you could configure settings and assign user roles. 2. **Search bar** As you start to type in a question, Tellius will display relevant suggestions. We just brought the Search bar from Search to the home page for easier and faster access. 3. **You might be interested in** A quick glance of all the recent Projects, Vizpads, Insights, Models to help you get started. 4. **Quick start** Follow the workflow to get a headstart with defining the Business View and importing data. Get personalized suggestions for Search and Insights based on your interests. 5. **Tutorials** Guided step-by-step walkthroughs that explain each component that can be found in every module. Irrespective of the page you are in, you can open Tutorials tab and click on the required module to get a run-through. Each walkthrough comes with an overview video and the status bars signify the progress made in a workflow. 6. **Chatbot** When in doubt or if you need any assistance, open up our chatbot and ask away your questions. Our team will be glad to assist you and resolve your queries.
# Guided tours for quick onboarding Quickly master Tellius modules with guided walkthroughs. Access interactive tutorials from the homepage to learn features, track progress, and view helpful videos. It’s only normal to get overwhelmed with the features and modules once you step into any new platform. To break the ice and get you familiar with the functionalities, Tellius has introduced a guided walkthrough right from the home page. The guide can be revisited when required, and the progress will be maintained. 1. From the homepage, click on the **Tutorials** tab on the right pane to expand. Alternatively, you can click on the **Help** tab in the left pane.
In-app product tutorial for quick onboarding

Guided walkthroughs

2. A list of modules appears as shown, and you can click on the **Start** button of Tellius Overview to get started. Also, you can click on the **Start** button of any module to learn further. 3. The progress bar displays the number of modules completed. Once you complete a module, you can find a checkmark near the module name.
Guided tutorials for each module

Tutorials menu from the sidebar

Progress bar displays the modules completed

Progress bars for each module

4. The following window appears, and you can click on **Let’s Go** to take a tour across Tellius.
Beginning of the guided tour

The first widget

5. Every widget will be presented with a video that gives you an overview of the module and a link to the corresponding Help Guide.
Quick navigation to video and help guide

Overview video for every module


# Quick Start Guides Jumpstart your Tellius journey, explore Search, Vizpads, and Insights to master core analytics features. Welcome to our Quick Start Guide! Whether you're diving into Search, exploring Vizpads, or discovering Insights, this guide offers a concise introduction to each tab's functionalities. Navigate with confidence and jump-start your journey in mastering our platform's core features. Let's get started! # Search Search lets you ask natural-language questions, apply filters, compare periods, analyze trends, and drill into granular data—without SQL or dashboards. **Search** offers a smart, Google-like interface that enables users to ask ad-hoc questions and effortlessly drill down to the granular details. Prioritizing user convenience and efficiency, Search eliminates the need for navigating through pre-established dashboards or generating SQL scripts to access data. ### Understanding keywords In your search queries, incorporate the following keywords as required to gain an in-depth analysis of your data. 1. **For filtering data: 'FOR' and 'IN'** * 'FOR': "Show me sales for 2022" * 'IN': "Show me sales in Canada" 2. **For grouping data: 'BY'** * 'BY': "Show me sales by product category" 3. **For comparing datasets or values: 'COMPARED TO' or 'VS'** * 'COMPARED TO': "Show me Q1 sales compared to Q2 sales" * 'VS': "Show me sales of Product A vs Product B" 4. **For analyzing trends: Specify a date** * Specify a date: "Show me sales trend since January 2023" 5. **For analyzing time series: 'BY MONTH' or 'BY WEEK'** * 'BY MONTH': "Show me sales by month for 2022" * 'BY WEEK': "Show me weekly revenue for Q1 of 2023" 6. **For analyzing differences or variations: 'GROWTH' and 'CHANGE'** * 'GROWTH': "Show me growth in sales from 2022 to 2023" * 'CHANGE': "Show me the change in profit from Q1 to Q2 of 2023" **Commonly used keywords and their applications** * **avg (Average)** To get the average value, such as average sales, use 'avg'. Example: `What are the avg sales?` * **total** For summation, use 'total'. Example: `Show me total sales in the US` * **min (Minimum)** To find the smallest value, use 'min'. Example: `What are the min sales in 2022?` * **max (Maximum)** To determine the highest value, use 'max'. Example: `What is the max sales in June 2023?` * **growth** For monthly growth analysis, use 'growth'. Example: `Monthly growth of sales last year` * **market share** For market share analysis, use 'market share'. Example: `Market share of dollar sales for BrandABC` * **unique count** To count distinct items, use 'unique count'. Example: `Unique count of returning_customers` * **percentage change** To find the percentage change in sales between two periods, phrase your query as follows: `Percentage change of sales for this year vs last year` * **absolute change** To determine the absolute change in sales between two periods, phrase it as: `Absolute change of sales for 2020 vs 2021` * **top/bottom N** To filter by top or bottom performers, use 'top/bottom N'. Example: `Show me top 5 products in sales by retailer` * **contains** To search for a specific substring in your data, use 'contains'. Example: `Show me sales for brand contains "fit"` * **after/before** To filter data after or before a certain date, use 'after/before'. Example: `Show me sales after March 2020` * **between** To filter data between two specific dates, use 'between'. Example: `Sales between March 2020 and March 2021` * **trend** These queries help track changes over time or identify patterns within your data. Example: `Show trend of monthly sales for New York vs Los Angeles.` ### Getting Started with Search

How to get started with Search

# Vizpads (Explore) Vizpads are interactive dashboards that let you explore data visually—add, resize, filter, format charts, and combine datasets for deeper insights. A Vizpad is an interactive dashboard that transforms your data into illustrative and actionable insights. It merges multiple datasets and integrates with our AI, Insights, and Search features, providing a comprehensive analysis on a unified platform. Vizpads are dynamically built, allowing you to easily resize, add, or remove elements without pre-setting your canvas structure. Happy data exploring! ### **Getting started with Vizpads**

How to get started with Vizpads

### **Commonly performed actions in Vizpads** Several actions can be performed to enhance your Vizpad experience: * Adding and cloning charts * Formatting charts * Applying global and local filters * Adjusting data granularity on an individual chart * Sharing and exporting Vizpads * Resizing and repositioning the chart on a Vizpad # Insights (Discover) Explore Tellius Insights to uncover key drivers, trends, cohorts, and anomalies—revealing patterns, root causes, and correlations hidden in your data. Tellius Insights analyzes your data through sophisticated machine-learning techniques, allowing you to effortlessly decode the narratives hidden within your data. With a single click, it is designed to uncover root causes, key drivers, and underlying trends. In the **Discover** tab, there are four main categories of Insights: key drivers, trends, comparisons, and anomalies/correlations. ### **Understanding the different types of Insights** In Tellius, you'll encounter a variety of insightful analytical types, each designed to answer different business questions and enhance your understanding of your data. Let's break them down: 1. **Key Driver Insights:** Ascertain the significant factors that sway a business outcome and reveal underlying patterns. These insights help identify variables that majorly impact specific business outcomes. For instance, you might want to find out the key drivers influencing sales in a particular product segment. 2. **Trend Insights:** Explore the reasons behind fluctuations in crucial business metrics over specific time periods. This gives you an understanding of what caused changes in your key business metrics. For example, you could determine why the number of unit sales increased last month. 3. **Cohort Insights:** Grasp the reasons behind differing performances among two cohorts. This analysis helps compare the behavior or characteristics of two distinct groups. For example, you could investigate the differences in sales between Product A and Product B. 4. **Discoveries:** Uncover hidden anomalies, trends, and correlations within your data. This type of insight aims to highlight unexpected patterns or data points. For instance, you could uncover anomalies in the sales volume for 2023. # Tellius Best Practices Explore Tellius' Best Practices to maximize efficiency across Search, Vizpads, Insights, Data, and Predict modules. Dive into our **Best Practices** section to maximize your efficiency and proficiency. Whether you're working with Search, Vizpads, Insights, Data, or Predict modules, we've curated essential tips and strategies to ensure you're leveraging each module to its full potential. Unlock the art of seamless navigation and optimal results with our expert recommendations. # Search Learn how to ace searches in Tellius using natural language, synonyms, calculated columns, and interactive tools for more accurate data insights. Tellius allows users to search and analyze data through natural language queries. * **Leverage Synonyms and Calculated Columns:** For a more tailored search experience, consider the use of synonyms, display names, and calculated columns from your dataset to help you formulate more precise queries. * **Read the Search Guide “How to Search” section:** The **Search Guide** provides easy-to-reference words and phrases that accommodate a majority of searches. Going through this section will help users formulate better queries and get more accurate results. * **Start simple:** Instead of asking an extremely complex question, start with simple queries to help get familiar with the system and build confidence. * **Utilize the Search Inspector:** The **Search Inspector** is a helpful tool that allows users to see how their queries are being interpreted by the system. This can help users refine their queries and get more accurate results. * **Use interactive features:** Tellius provides several interactive features such as drilling, switching chart types, and saving to Vizpad on the visualizations. These features allow users to continue exploring after their initial search without having to ask a new query. # Vizpads (Explore) Learn practical tips for building clean, fast, and organized Vizpads in Tellius—optimize layouts, filters, tabs, and visuals to create efficient, user-friendly dashboards. Visualizing data is an essential part of making sense of it. Tellius offers **Vizpads**, which are interactive dashboards that let users illustrate their data by adding visualizations, colors, and other interactive elements. Users can create Vizpads by selecting a Business View, adding and organizing interactive content, and then saving their work. * Consider whether all the content should be available in one Vizpad, or on one tab, or spread across multiple Vizpads and tabs. * Limit the number of visualizations on each Vizpad to the minimum possible to prevent performance issues, especially with complex chart types and many filter options. * If you're building Vizpads with multiple Business Views, designate one Business View as the primary * For quick access and better visibility, ensure that your critical charts are located at the top of the Vizpad.  * To save time, consider cloning existing Vizpads instead of building each one from scratch. This ensures continuity and uniformity across multiple Vizpads. * To create a structured and clean Vizpad, organize your additional visualizations into distinct tabs.  * Use the global filter when you need to apply the same filter across the entire Vizpad. However, if the filter is intended for a specific chart, opt for the local filter. Understanding both types of filters will help you manage your visualizations more effectively and tailor them to your specific needs. * Use the **Favorite** icon to select up to 5 of your most regularly used Vizpads that can be easily accessed from the left navigation pane. * Save or move Vizpads into **Projects** to organize content that can easily be shared with users or user groups. # Insights (Discover) Learn how Insights help you uncover the “why” behind your data. Explore trends, diagnose changes, refine hypotheses, and organize findings for faster decision-making. Insights serve as a vital tool to decode the narratives hidden within your data, helping you make informed, data-driven decisions. * Understand the granularity of the data as it determines the insights that you will get as a result. Ensure that the data is properly aggregated to understand the key characteristics of certain types of invoices or transactions. * Utilize the Insights generation feature from **Search** or **Vizpads** that help explore the “why” from ad-hoc questions. Selecting anomalies provides the “**Understand Why**” option, which is a one-click trend insight that uses all features. * Configuring Insights from the **Discover** tab allows for a more “hypothesis” driven approach to answering questions. * To accelerate the Insights generation, it is recommended to exclude unnecessary or irrelevant columns (e.g., columns named "user ID", "product number") during the creation of Insights. * Use the **Edit** option for pre-existing Insights. This allows quick iteration through Insights by including or excluding more columns, changing time periods, or filters from the original Insight rather than reconfiguring from scratch each time. * Save/move **Insights** to **Projects**, which is an effective way to organize content that can easily be shared with users or user groups. # Predict Learn key tips to improve your machine learning models in Tellius, from data granularity and model selection to evaluation, training, and predictions. Tellius offers various types of machine learning models, including regression, classification, time series regression, and clustering. Each model comes with its own unique characteristics and applications. * Ensure the granularity of the data matches the desired outcome for predictions. If you intend to forecast monthly revenue for five different regions, you cannot use transaction-level data because the granularity of transaction data is not the same as data aggregated at the month and region levels. Aggregation functions or SQL/Python modules can help achieve the desired granularity of data. * Create a separate Business View for training and testing. This allows you to explicitly control for the logic used to separate data used for model training and evaluation. It is common to use mutually exclusive date ranges for these datasets where time is an important factor in the model. * Understand the business value that the model will help with. This is important for identifying the most appropriate model evaluation metric. Accuracy can be a misleading metric for model performance if the target classes are very imbalanced. AUROC is a more appropriate metric in that situation. * Use the Tellius platform to handle nulls and basic feature transformations for things like one-hot encoding. * Select multiple algorithms that align with your use case to identify the best-performing model. These selections are available specifically for Point-N-Click models, whereas AutoML automatically does this algorithm selection for a user. * If interpretability is very critical to the business problem you are solving with a model, choosing a neural network model will make that challenging. Logistic regression or ensemble tree algorithms would be a more appropriate fit in that situation. * Check the Notifications page to verify your models were trained successfully. * Save the trained model object once the training process has been completed. * Apply the model to the appropriate Business Views so your predictions are available for analysis by selecting the ellipses on the saved model object. The predictions are available in the Business View “Predictions” tab. * Save/Move Models into Projects to organize content that can easily be shared with users or user groups. # Data Learn best practices for structuring, preparing, and governing data in Tellius—from defining granularity and data types to managing sources, refreshes, and Business Views. 1. **Start with the end requirements:** Work backward to figure out how the data is intended to be used. Use cases that require search may have different requirements for structuring the data than those that require training machine learning models. It is essential to have a scope of how the data will be used in advance. 2. **Answer key questions:** Answer, at a minimum, these questions about the data: * Where are the data sources needed for this use case? (e.g., Snowflake, Redshift, S3, etc.) * Should data be loaded into Tellius in-memory or via push-down queries? * How often is the data refreshed in the source system? * How often should it be refreshed in Tellius? * What makes every record unique in each dataset? * What are the appropriate data types for each field? * How do datasets relate to one another? * What is the primary date field? Identify this appropriately at the Business View level. * Are there any geographic attributes (longitude, latitude, state, etc.)? Identify these appropriately at the Business View level. * Identify common synonyms or aliases to define in the data preparation layer (if known in advance) * Are there any custom fields that need to be specified? * Are there any custom calculations that need to be implemented? 3. **Understand the granularity of each dataset:** It is essential to understand the granularity of each dataset to avoid duplicating data when joining multiple multiple tables. Avoid joins that duplicate data, which can impact data volume capacity, decrease performance, and increase the bandwidth required to manage the system effectively. 4. **Create a column with the value of 1 for every row:** Create a column with the value of 1 for every row, naming that column something that represents the data. For example, for a dataset containing orders placed on a website, create a column called Orders, so a user can reference that field naturally in search, such as "show me orders by day," and that count will pull from that column. 5. **Governance:** Establish data connections with a dedicated set of admin or power users where possible. Minimize the number of unique datasources and datasets. Review usage by dataset and/or Business View and remove unused entities every few months (recommended at a minimum every six months). Admins should review system capacity with the Customer Support Manager in the Usage data (recommended at a minimum every month). 6. Understand your data sources and their relationships to build an accurate Business View. 7. Collaborate with technical resources to ensure the Business View is set up to support the types of questions and phrases that end users are likely to ask. 8. Regularly review and update the Business View as new data sources are added or changes are made to existing ones. 9. Use clear and consistent naming conventions for datasets and fields to avoid confusion and improve usability. # Admin Guide Get started with the Tellius Admin Guide, review system requirements, install Tellius step-by-step, and customize your setup for optimal performance. Before diving into Tellius, it's vital to ensure your system is primed for a seamless experience. This section provides a comprehensive roadmap to getting started.\ \ Check out System Requirements to understand the software and hardware prerequisites and ensure compatibility. Follow our step-by-step installation guide to get Tellius installed and running on a system. Finally, customize the appearance of Tellius screens to suit your preferences. # Tellius architecture Overview of the Tellius architecture, including the Web UI, search engine, ML engines, distributed storage, and scalable deployment across on-prem or cloud environments. The Tellius architecture is designed to be user-friendly and easily accessible, allowing for seamless integration with existing systems.

Tellius Architecture

The Tellius architecture consists of the following components: * The main entry point to Tellius is the **HTML5-based Web UI**, which runs in a web browser. * **Natural Language Search** allows users to input natural language queries, which the engine then converts into backend queries for processing. * The **Genius Insights** engine uses advanced machine learning algorithms to automatically discover actionable insights. * The **Predictive Machine Learning** engine enables the training of custom machine learning models for making predictions * **Distributed Filesystem** is responsible for storing intermediate data generated by Machine Learning and Genius Insights engine. Optionally, it can be used for storing data when explicitly enabled. * **Fast Query Database** is a columnar store for storing data in indexed format for real-time search and visualization on big data. This is a cost-effective option when data cannot fit in available memory and high performance is still desired. ### **Deployment architecture of Tellius** Tellius can be deployed on-premises behind a firewall or in any of the major cloud technologies such as, * Amazon Web Services * Microsoft Azure * Google Cloud Here is an illustration of the deployment architecture of Tellius:

Deployment architecture of Tellius

The components are, 1. **Kubernetes Cluster:** It is a cluster of Kubernetes on one or more nodes. 2. **Tellius Microservices:** All the services related to Tellius will be running on the Kubernetes cluster, including, * **Fast Query Engine (FQE) microservice**, which is responsible for running the FQE engine cluster to handle high-performance data querying. * **In-Memory Compute Engine (ICE)** **microservice**, which is responsible for running an ICE engine cluster to handle computationally intensive machine learning tasks Other auxiliary services, like Tellius Web UI and Python environment, are also available.  # System requirements Review the system requirements needed to install and deploy Tellius, including compute, storage, OS, firewall ports, and access guidelines for secure and reliable operation. The following are the minimum requirements for installing and deploying Tellius. The guidelines are designed to ensure a secure and reliable installation. Tellius team requires certain access privileges, which shall be revoked or limited after successful installation. If you have any questions, feel free to email us at ****. As a best practice, access the application via DNS name and perform DNS mapping with support from your IT team. SSL certificates need to be generated and shared (.key, .pem files) with the Tellius team. ## **For single-instance deployments** ### **Infrastructure requirements** * 64 Core CPU (amd64 architecture) * 512 GB RAM * 50 GB Root disk size * 2 TB external disk size for Tellius data storage (persistent disk), formatted using ext4 filesystem * Ubuntu-20 operating system (Alternatively, RHEL 7.x) * Internet connectivity during installation of container runtime and Kubernetes software ### **Accessing Tellius UI** * Access using the IP address of the instance unless you have any hardware load balancer in place. ### **Ports to be opened via firewall** * 443 for Tellius frontend application * 956938892320.dkr.ecr.us-east-1.amazonaws.com for private container registry hosted by Tellius to store application Docker images * Any other required ports depending on the type of data source connectivity ### **Level of access** * Tellius team will be given sudo privileges during the installation of container runtime and Kubernetes. * Tellius deployment and platform management can be done by non-root user accounts with the least sudo privileges. * Tellius team can directly access customer-provisioned instances using IP white-listing or any preferred method used in your environment. ## **For AWS deployment** ### **Infrastructure requirements** * R4 or R5.16xlarge instance type * EKS cluster with either single or multiple worker nodes * Kubernetes version 1.21 or 1.22 (depends on the latest stable version available) * Amazon Certificate Manager ARN for accessing Tellius UI securely * Tellius team creates dynamic EBS volume for all Tellius stateful set applications ### **Accessing Tellius UI** Since Tellius uses AWS Certificate Manager (ACM), the UI can be accessed securely. * Tellius team will be creating a Kubernetes load balancer serviceType for the frontend application. It can be done internal-facing or external-facing as required. ### **Ports to be opened via firewall** * 443 for Tellius frontend application * 956938892320.dkr.ecr.us-east-1.amazonaws.com for private container registry hosted by Tellius to store application Docker images * Any other required ports depending on the type of data source connectivity ### **Tools required** * Kubernetes command-line tool (kubectl v1.20 or higher) installed on a jump-host/bastion * Kubeconfig file for connecting to EKS cluster from jump-host/bastion * Git command-line tool for accessing Kubernetes manifest stored on Tellius's private GitHub repository ## **For Azure Deployment** ### **Infrastructure** * standard\_e64s\_v3 instance type (64 CPU cores, 512 GB RAM) * AKS cluster with single or multiple nodes inside a node pool * Kubernetes version 1.21 or 1.22 (depends on the latest stable version available) * Tellius team will create dynamic Azure disks for all Tellius stateful set applications ### **Accessing Tellius UI** * Tellius team will be creating a Kubernetes load balancer serviceType for the frontend application. It can be done internal-facing or external-facing as required. ### **Ports to be opened via firewall** * 443 for Tellius frontend application * 956938892320.dkr.ecr.us-east-1.amazonaws.com for private container registry hosted by Tellius to store application Docker images * Any other required ports depending on the type of data source connectivity ### **Tools required** * Kubernetes command-line tool (kubectl v1.20 or higher ) installed on a jump-host/bastion. * Kubeconfig file for connecting to EKS cluster from jump-host/bastion * Git command-line tool for accessing Kubernetes manifest stored on Tellius private GitHub repository ## **Deployment guidelines** ### **For cloud-based deployment** * Tellius deploys nginx ingress controller which internally creates a network load balancer. * Tellius’s deployment manifest is stored inside a private registry on GitHub. * Disk encryption will be enabled for all dynamic volumes created by stateful set applications. * Tellius follows the GitOps principle where automated application deployment is done via ArgoCD (in addition to supporting other CD tools). * Access is required for Tellius team members to manage application deployment and troubleshooting * The application Docker images are stored inside a private registry managed by Tellius on AWS (ECR). ### **For on-prem deployment** * Tellius team members require access for installing platform components installation (Kubernetes, container run-time) and managing/troubleshooting application deployment. * Tellius’s deployment manifest is stored inside a private registry on GitHub. * The application Docker images are stored inside a private registry managed by Tellius on AWS (ECR). * The deployment will be done manually by the Tellius team. # Installation steps for Tellius Discover how to install Tellius on Kubernetes with deployment options, prerequisites, cluster setup, resource installation, validation, and troubleshooting. Tellius requires deployment on a Kubernetes cluster. This can be hosted on a managed service like AWS EKS or Azure AKS, or on a single VM (single node) cluster for initial pilot use cases. There are two deployment options: * Customer Hosted * Tellius Hosted ## **Customer Hosted** If the infrastructure is hosted on the customer’s cloud or on-prem setup, the customer has complete control over the infrastructure (instances, subnets, networking etc.). In this case, Tellius team will only be responsible for deploying the application and will need proper access to the cluster to do the installation. ## **Tellius Hosted** If Tellius handles the ownership of the infrastructure, usually on AWS EKS or Azure AKS, the Tellius team is responsible for both deploying the application and managing the infrastructure. ## **Deployment Options** There are two components in Tellius that can be deployed in **standalone** or **distributed** mode: * ClickHouse * Spark ### **ClickHouse Standalone** In ClickHouse Standalone mode, the pods clickhouse-set-0 are deployed in the Kubernetes cluster. ### **ClickHouse Distributed** In ClickHouse Distributed mode, a ClickHouse operator is installed and shards are used to replicate data across ClickHouse nodes. In this type of installation, pods like chi-repl-05-replicated-0-0-0 are deployed, depending on the number of ClickHouse replicas that have been decided for the Tellius deployment. ### **Spark Standalone** In the standalone version, only the spark-restserver-0 pod is present, which runs all the Spark-related jobs. This is a good fit for low-intensity data operations. ### **Spark Distributed** When using Spark in distributed mode, there will be additional components deployed along with the spark-restserver-0 pod. These include the spark-master deployment and one or more spark-worker pods. The workload of the spark jobs and tasks will be distributed across these pods instead of running in a single location, making it suitable for processing large amounts of data. ## **Deployment Steps** ### **Prerequisites** * Working Kubernetes Cluster * Access to the Kubernetes Cluster * Access to the internet * Access to Tellius Private Elastic Container Registry (ECR) for Docker Images * Download the Tellius-deploy zip file provided by the Tellius team. The Tellius-deploy zip file will contain the manifests needed to setup the Kubernetes resources on the cluster. ### **Steps to install** 1. Unzip the zip file and navigate to the folder from the command line. 2. Install the following resources by running the kubectl commands. Based on your type of installation, choose **CHOICE A** or **CHOICE B**. ```bash # install the docker cronjob to create the ECR secret kubectl create -f cron-jobs kubectl create job -n docker-registry --from=cronjob/aws-registry-credential-cron aws-registry-credential-cron-001 # setup telemetry services kubectl create ns observability kubectl create -f telemetry/jaeger-development.yml -n observability # install tellius services kubectl create -f rabbitmq kubectl create -f secrets kuebctl create -f telemetry/app-jaeger-config.yml kubectl create -f sqe kubectl create -f spark-restserver kubectl create -f frontend kubectl create -f azkaban kubectl create -f opencpu kubectl create -f bot-server kubectl create -f hdfs kubectl create -f cdn kubectl create -f python-evaluator kubectl create -f viz-engine kubectl create -f resource_tracking kubectl create -f data-loader kubectl create -f clickhouse-autoscaler # [CHOICE A] for standalone mode kubectl create -f sqe/clickhouse.yaml # [CHOICE B] for distributed mode # install spark-cluster and clickhouse operator kubectl create -f spark-cluster kubectl create -f clickhouse-operator # setup monitoring kubectl create namespace monitoring kubectl create -f monitoring ``` ## **Validation** After completing the setup, you can verify the status of the pods by running the command `kubectl get pods`. Ensure that all the pods are running without any errors. If everything has been configured correctly, the setup should be up and running within 30 minutes. You can access the Tellius UI by using the load balancer IP or DNS domain name that has been set up. Additionally, after creating a new instance, Tellius QA conducts a comprehensive checklist on the environment to ensure that there are no issues with the configuration or networking. ## **Troubleshooting and Assistance** If you encounter any issues during the setup process, you can contact the Tellius DevOps team for assistance in resolving the issues and getting the application up and running. {% hint style="info" %} Please note that the above-mentioned steps may be subject to change based on the version of Tellius or the configuration of your infrastructure. Additional functionality, such as connecting to data sources outside of the cluster or through other gateways, will need to be handled on a case-by-case basis by the Tellius DevOps Team. {% endhint %} {% hint style="warning" %} Please use your individual username to access Tellius. Sharing usernames can lead to complications and unintended consequences on the platform. For a secure and seamless experience, each user must log in with a unique username. {% endhint %} # Customizing Tellius Customize Tellius by uploading your organization’s logo and selecting a color palette. Super users can update branding for the login page, UI, and overall experience. To make Tellius more personalized for your organization, you can customize its appearance by adding your own logo and changing the color scheme. {% hint style="warning" %} Please note that the customization can only be performed by super users. {% endhint %} ### **Changing the logo** Here are the steps to customize your logo and theme in Tellius: 1. In the left panel, click on the user icon in the bottom corner. 2. Select **Settings → Application Settings → Styles**.
3. Under **Square Logo**, click on **Replace** button and choose the required image. Or, click on **Revert to Default logo** to restore the Tellius logo. {% hint style="info" %} Upload a **square-sized image** of your logo, preferably in 1:1 aspect ratio for optimal display. The supported file formats are .png, .jpg, .svg and the maximum file size is 5 MB. {% endhint %} 4. The square logo will be visible in the following areas: * Home icon (top left corner in the pane) * In the menu when users click on the user icon in the bottom left corner (near the version number) * Favicon (icon in the browser tab)

Display of square logo in the Tellius screen

5. Under **Full Logo**, click on **Replace** button and choose the required image. Or, click on **Revert to Default logo** to restore the Tellius logo. {% hint style="info" %} Upload a **rectangular-sized image** suitable for wider display areas. The supported file formats are .png, .jpg, and .svg and the maximum file size is 5 MB. {% endhint %} 6. The full logo will be visible in the following areas: * Login page * Error pages * Clicking on the user icon (bottom left corner) and selecting "About" option.

Login page

A sample error page

"About" page

### **Changing the color palette**

Changing the color palette

1. In the left panel, click on the user icon in the bottom corner. 2. Select **Settings → Application Settings → Styles**. 3. Under **Default Color Palette**, click on the dropdown icon to view and select the required palette. 4. The selected palette would be used across Tellius. However, for every individual Vizpad or chart in a Vizpad, users can change the color scheme as required. # Choosing the right Tellius cluster size Determine the ideal Tellius cluster size for your organization by considering data volume, usage patterns, workloads, and ETL frequency for optimal performance. Tellius runs on a high-performance compute engine designed to quickly answer business questions. Because each organization has different data volumes, usage patterns, and peak activity windows, there’s no one-size-fits-all approach to cluster sizing. The following three key factors play a major role in determining the right configuration: ### **How much infrastructure will I use?** Tellius features fully automated scaling, allowing infrastructure resources to increase or decrease based on demand. As you begin loading data and using the platform, you’ll gain insights into your environment’s typical resource consumption throughout the day—tailored to your specific use case. ### **What kind of workload do I have?** * **Search-focused**: Most users rely on Natural Language Search and Vizpad dashboards. Only a few users create Insights. * **Balanced (Search & Insights)**: Your user base is evenly split between those using Natural Language Search and those building Insights. * **Insights-focused**: Most users create their own Insights or machine learning models, with minimal use of Natural Language Search. ### **What is my ETL pattern?** * **Once or twice per day**: You load data during only one or two periods throughout the day. This load usually happens when usage is low. * **Three or more times per day**: You load data during three or more periods throughout the day. This load may happen when usage is high. # Monitoring usage and system resources Monitor system usage, dataset growth, user activity, and refresh performance using Postgres-based SQL queries. Build dashboards to track adoption and resource trends. This guide helps Tellius admins track system usage, monitor dataset growth, audit user activity, and optimize platform performance. By running the provided SQL queries via a secure Postgres data source, you can create reusable datasets and dashboards that offer visibility into how Tellius is being used across your organization. {% hint style="info" %} These queries require access to the system metadata database. Contact your Tellius admin or support team to set up a secure, validated Postgres connection. {% endhint %} ## Connecting to the metadata database To run the queries in this guide, you’ll need to create a Postgres data source that connects to your Tellius instance’s internal metadata store. 1. Under **Data → Connect**, choose **Postgres** as the connection type. 2. Provide the host, port, database name, username, and password (your Tellius admin or support team will supply these). 3. Save and test the connection. 4. Once connected, you can use the **Custom SQL** option in the dataset creation flow to execute the queries below. ## Setting up the metadata connection To run system-level queries (like usage tracking, dataset stats, user activity, etc.), you'll need to connect to Tellius internal metadata databases using a Postgres data source. **Databases you may connect to:** * **`middleware_prod`** – Stores core platform metadata such as users, datasets, Business Views, and configurations. * **`middleware_tracking_prod`** – (Optional) May contain event tracking or usage-related metadata depending on deployment. * **`usage_tracker`** – Logs detailed activity, such as search queries, refresh events, Vizpad usage, and user logins. ## Metadata schema overview Once connected, you can query internal tables that define user access, roles, and group mappings in your Tellius environment. | Table | Description | | -------------- | ------------------------------------------------------------------------- | | `users` | Stores all registered users and their metadata (e.g., name, email, roles) | | `groups` | Represents logical user groups used for access control | | `users_groups` | Maps which users belong to which groups | ## Monitoring datasets This query lists each dataset in the system with key metadata such as name, owner, number of rows and columns, and size (in kilobytes). ```sql SELECT dm."datasetName" AS DatasetName, us.username AS OwnerUsername, ((dm.current->'size')::jsonb::text::bigint)/1024 AS SizeKB, jsonb_array_length(dm.current->'columns') AS NoOfColumns, (dm.current->'numberOfRows')::jsonb::text::bigint AS NoOfRows, dm.inserted_at AS Created, dm.updated_at AS Updated FROM dataset_metadata dm JOIN users us ON dm.owner_id = us.id; ``` Use this to identify: * Large or old datasets that may be archived or refreshed * Ownership and accountability of data assets * Data growth trends over time ## Dataset size estimation in GB This more advanced query estimates total dataset size by calculating per-row memory cost based on data types, then multiplying by row count. ```sql -- Estimates dataset size in bytes and gigabytes. -- Identifies if the dataset is live (in-database) or in-memory. SELECT *, (row_count * row_size) AS total_size_bytes, (row_count * row_size)/1024.0/1024.0/1024.0 AS total_size_gb FROM ( SELECT dm."datasetId" AS id, dm."datasetName" AS name, us.username AS owner, SUM(CASE WHEN type = 'boolean' THEN 1 WHEN type = 'short' THEN 1 WHEN type = 'integer' THEN 2 WHEN type = 'float' THEN 4 WHEN type = 'long' THEN 8 WHEN type = 'double' THEN 8 WHEN type = 'date' THEN 12 WHEN type = 'timestamp' THEN 15 WHEN type = 'string' THEN 15 ELSE 0 END) AS row_size, ((dm.current->>'numberOfRows')::bigint) AS row_count, CASE WHEN "additionalParams"->>'indb' = 'true' THEN 'live' ELSE 'in-memory' END AS dataset_type FROM dataset_metadata dm JOIN users us ON dm.owner_id = us.id, LATERAL jsonb_array_elements_text(current->'columns') AS json_value, LATERAL (SELECT json_value::jsonb->'typeStats'->>'mainType' AS type) AS types GROUP BY dm."datasetId", dm."datasetName", us.username, dm.current, "additionalParams" ) a; ``` {% hint style="success" %} You can build dashboards to monitor memory usage trends, identify heavy datasets, and improve performance by targeting optimizations. {% endhint %} ## User activity monitoring Lists Tellius users along with their email addresses and names. Use this to track platform adoption, audit access, or manage licenses. ```sql SELECT username AS "UserName", email AS "Email", "firstName" AS "FirstName", "lastName" AS "LastName" FROM users; ``` Monitor usage of natural language search by tracking what queries users submit and when. Combine with user logs to understand adoption of search and identify training opportunities. ```sql SELECT query, time, username FROM query_history q JOIN users u ON q.userid = u.id; ``` ## Daily usage analytics This query aggregates daily activity across various Tellius features such as Search, Insights, data operations, Vizpads, and user logins. Visualize this in a line chart to observe daily or weekly usage patterns. ```sql SELECT DATE_TRUNC('day', action_at) AS day, COUNT(CASE WHEN resource_type = 'insight' THEN 1 END) AS insight_operations, COUNT(CASE WHEN resource_type IN ('dataset', 'datasource', 'businessView') THEN 1 END) AS data_operations, COUNT(CASE WHEN resource_type = 'search_query' THEN 1 END) AS search_queries, COUNT(CASE WHEN resource_type = 'model' THEN 1 END) AS model_operations, COUNT(CASE WHEN resource_type = 'vizpad' AND operation_type = 'created' THEN 1 END) AS vizpad_created, COUNT(CASE WHEN resource_type = 'vizpad' AND operation_type = 'viewed' THEN 1 END) AS vizpad_viewed, COUNT(CASE WHEN resource_type = 'user' AND operation_type = 'login_success' THEN 1 END) AS user_logins, COUNT(DISTINCT user_id) AS unique_users FROM usage_tracking WHERE action_at >= '2023-01-01' GROUP BY 1 ORDER BY 1; ``` ## Kaiya conversational AI usage Track how often users engage with Kaiya ```sql SELECT DATE_TRUNC('day', inserted_at) AS day, COUNT(DISTINCT conversation_id) AS conversations, COUNT(CASE WHEN sender = 'bot' AND LOWER(status) != 'failure' THEN 1 END) AS kaiya_responses FROM messages WHERE inserted_at >= '2023-01-01' GROUP BY 1 ORDER BY 1; ``` ## Monitoring Business View Monitor how large each Business View is to optimize performance. ```sql SELECT id, name, metadata ->> 'length' AS bv_size, us.username AS owner_username FROM business_views bvs JOIN users us ON bvs.owner_id = us.id; ``` Understand which Business Views are shared with which groups. Use this to audit access control and sharing practices. ```sql SELECT business_view_id, "sharedWithKind", "objectKind", gps.name AS group_name FROM sharings shs JOIN groups gps ON shs.shared_with_group_id = gps.id WHERE "objectKind" = 'businessView' AND "sharedWithKind" = 'group'; ``` ## **Business View ↔ Vizpad mapping** This helps you understand which Vizpads rely on which Business Views, and how many charts, KPIs, etc. each one contains. This helps you to analyze impact before modifying or deleting a BusinessView * Design optimization (e.g., identifying Vizpads using large or outdated views) * Auditing dependencies for dashboard maintenance ```sql SELECT bv.name AS businessview_name, vp.title AS vizpad_title, COALESCE(vc.viz_count, 0) AS viz_count, bv.id AS business_view_id, vp.id AS vizpad_id FROM vizpads vp JOIN business_views bv ON (bv.id = ANY(vp.business_view_ids) OR bv.id = vp.business_view_id) LEFT JOIN ( SELECT vt.vizpad_id, COUNT(*) AS viz_count FROM viz_tab vt JOIN viz_item vi ON vt.id = vi.tab_id GROUP BY vt.vizpad_id ) vc ON vp.id = vc.vizpad_id; ``` {% hint style="info" %} To merge Business View size and sharing details for offline audit or reporting, use the provided Python script to join exported `.csv` files and calculate sizes in GB. Useful for access control reviews or cleaning up unused assets. {% endhint %} ## **Snowflake data source metadata** Track how Snowflake is used in your environment, including: * How many datasets are built on each connection * Who owns the connections * Which auth methods are in use ```sql SELECT ds."datasourceId" AS datasource_id, ds.name AS name, ds.inserted_at AS creation_time, MAX(us.email) AS owner_email, COUNT(*) AS no_of_datasets_loaded, options->>'sfURL' AS url, options->>'sfUser' AS user, options->>'sfSchema' AS schema, options->>'sfDatabase' AS database, options->>'sfRole' AS role, options->>'auth' AS auth_method FROM datasources ds LEFT JOIN dataset_metadata dm ON ds."datasourceId" = dm.datasource_id JOIN users us ON ds.owner_id = us.id WHERE "sourceType" = 'snowflake' GROUP BY ds."datasourceId"; ``` ## Scheduled refresh monitoring Monitor refresh jobs across datasets, models, Vizpads, and Insights. ```sql SELECT sc.id, sc.name, sc.frequency, CASE sc.frequencyunit WHEN 'm' THEN 'Minutes' WHEN 'h' THEN 'Hours' WHEN 'd' THEN 'Days' WHEN 'w' THEN 'Weeks' WHEN 'M' THEN 'Months' ELSE sc.frequencyunit END AS frequency_unit, sc.object->>'objectType' AS object_type, COALESCE(vp.title, dm."datasetName", mod."modelId", ds.name, ins.name) AS object_name, us.username AS owner_name FROM schedules sc JOIN users us ON sc.owner_id = us.id LEFT JOIN vizpads vp ON vp.id = sc.vizpad_id LEFT JOIN dataset_metadata dm ON dm."datasetId" = sc.dataset_id LEFT JOIN models mod ON mod."modelId" = sc.model_id LEFT JOIN datasources ds ON ds."datasourceId" = sc.datasource_id LEFT JOIN insights ins ON ins."insightId" = sc.insight_id; ``` ## Estimating cluster resource handling capacity The amount of data Tellius cluster can handle depends on two factors: 1. Whether cluster autoscaling is enabled or disabled 2. The number of allocated CPU cores in the cluster The following formulas help estimate how much data your cluster can process and store efficiently. * **numberOfCores**: Total number of CPU cores in your Tellius cluster. * **3.125**: This is the baseline GB-to-core multiplier. ### 🚫 Cluster autoscaling d**isabled** When autoscaling is turned off, the system cannot automatically add or remove resources based on workload. You must size the cluster manually to meet expected demand. **Ideal data capacity:** ``` Ideal Capacity (GB) = 3.125 × 1.20 × numberOfCores ``` The `1.20` factor accounts for additional memory overhead used by background operations and system processes. #### For maximum supported data with degradation: ``` Max Capacity (GB) = 3.125 × 1.20 × 1.25 × numberOfCores ``` The `1.25` multiplier allows for up to 25% more data to be handled, though performance (e.g., response time or refresh speed) may slightly degrade. For a cluster with 64 cores: * **Ideal capacity** = 3.125 × 1.20 × 64 = 240 GB * **Max capacity** (with some degradation) = 3.125 × 1.20 × 1.25 × 64 = 300 GB ### ✅ Cluster autoscaling e**nabled** When autoscaling is enabled, the cluster can dynamically adjust resources based on demand. In this setup, system overhead is already managed, so the formula is simpler. #### Ideal data capacity: ``` Ideal Capacity (GB) = 3.125 × numberOfCores ``` #### For maximum supported data with degradation: ``` Max Capacity (GB) = 3.125 × 1.25 × numberOfCores ``` {% hint style="info" %} These values are **estimates**, not strict limits. Actual performance may vary based on: * Data format (CSV vs. Parquet) * Number of columns * Query complexity * Number of concurrent users {% endhint %} {% hint style="warning" %} Always monitor performance during peak usage and benchmark with real workloads before finalizing cluster sizing. For production workloads with heavy ETL, AutoML, or frequent refreshes, consider staying well below max capacity to maintain responsiveness. {% endhint %} ## **Cluster sizing reference table** Here’s a simple comparison to help you estimate how much data your cluster can handle, depending on whether autoscaling is enabled or not:
# CoresAutoscalingIdeal capacity Max capacity (with 25% buffer)
32Enabled100 GB125 GB
32Disabled120 GB150 GB
64Enabled200 GB250 GB
64Disabled240 GB300 GB
128Enabled400 GB500 GB
128Disabled480 GB600 GB
{% hint style="success" %} * These queries are designed for read-only analysis and should not modify any system data. * Only accessible to users with proper admin privileges. * For additional visibility, create datasets and Business Views from these queries to power monitoring dashboards in Tellius. {% endhint %} ## **Calculated columns** This query shows all **custom formulas** used in Business Views. ```sql SELECT DISTINCT "formulaType", formula FROM business_views_columns WHERE formula IS NOT NULL; ``` # What is ICE? Discover how the ICE In-Memory Compute Engine in Tellius powers fast, low-latency analytics with vectorized caching for search, visualizations, and Insights. The ICE (In-Memory Compute Engine) powers interactive analytics in Tellius. It keeps frequently used data hot in a vectorized columnar format so queries, search, and visualizations run fast. **Purpose:** Low-latency, in-memory analytics.\ **Storage type:** Hot cache (memory/disk), not permanent storage.\ **Data flow:** Source → ICE (optimize/compress/partition) → Cache → Interactive compute → (optional) Publish to FQE. ### What it does * Loads data in parallel from databases, cloud stores, and files. * Stores and compresses data in a vectorized columnar format with fast in-memory compression for low-latency access. * Shards and partitions data to maximize parallelism and data locality across the cluster. * Caches data in memory, on local disk, or in a hybrid mode for predictable performance. * Serves interactive workloads such as search, visualizations, transformations (ETL), Insights, and AutoML. * Publishes denormalized Business Views to the query engine (FQE) for sub-second queries. ### How caching works * **Memory cache:** Keeps optimized, compressed columns in RAM for the fastest response. * **Disk cache:** Stores the same optimized format on local disks to extend capacity with strong performance. * **Hybrid:** Uses a configurable portion of RAM and spills the rest to disk for balanced speed and scale. * **Eviction policy:** Least-recently used datasets are evicted automatically to make space for new workloads. * **Copy to System (optional):** Keeps a Parquet copy in distributed storage to accelerate cache rebuilds without re-hitting source systems. ### When to use ICE * Interactive exploration with dashboards and search. * Fast iteration on transformations and feature engineering. * Running Insights and AutoML on hot data. * Preparing denormalized Business Views for FQE. # How much memory does your data use in the ICE? Learn how to estimate ICE in-memory data usage in Tellius—plan for about 50% of your CSV size and add headroom for transforms, AutoML, and refreshes. Plan for the ICE in-memory cache to be roughly half of your uncompressed CSV size, and add headroom for transforms, AutoML, Insights, and refreshes. ### What “data size” means in our guidelines For capacity planning, use the size of your data as uncompressed CSV as the baseline. This gives a consistent, easy-to-compare reference across sources such as Snowflake, Redshift, Parquet, or compressed files. {% hint style="warning" %} Dimension environments from the uncompressed CSV size, not the storage-optimized size reported by source systems. {% endhint %} ### Hot vs. cold compression: different goals The ICE keeps frequently accessed data hot for interactive analytics. Data is stored in a vectorized columnar format and compressed with fast in-memory compression to deliver low-latency queries. Cold storage (for example, archived files on disk) often uses heavier compression to minimize size at rest. That approach optimizes for minimum disk, not interactive speed. The ICE optimizes for responsiveness, which is what users experience in Tellius. ### A practical rule of thumb for in-memory footprint Plan for the ICE in-memory cache to use **about 45%–60% of the uncompressed CSV size**.\ A typical midpoint for many analytic datasets is **\~50% of CSV**. This is an estimate; actual results vary by schema and data characteristics. #### Example * CSV baseline: **200 GB** * Expected ICE in-memory footprint: **\~90–120 GB** * A common outcome around **\~100 GB** is normal and within expectations. ### Why footprints vary Actual memory use depends on the shape of your data. **Often smaller footprints:** * Integer columns with small ranges. * Low-cardinality categorical strings (codes or enums). * Columns with many repeated values or nulls. **Often larger footprints:** * High-cardinality free-text strings and UUIDs. * Many variable-length string columns. * Very high-precision numeric columns with mostly unique values. ### Plan headroom for processing Interactive analytics is one part of the picture. Transformations (ETL), AutoML, Insights, and refresh operations use additional working memory. During a full (non-incremental) refresh, Tellius may temporarily hold old and new copies while transformations apply. For reliable operations, provision extra headroom above the steady-state cache estimate. ### How this relates to the Fast Query Engine (FQE) The FQE stores denormalized Business Views on disk for fast query latency. Disk compression there is effective, and the storage layout is optimized for query speed. Because Business Views are denormalized for performance, their on-disk size is not directly comparable to the CSV baseline or to the in-memory ICE cache. Each layer is tuned for its purpose. ### FAQs 1. **Is it normal that my dataset looks larger in ICE than it does in compressed storage?**\ Yes. Compressed storage optimizes for minimum size at rest. ICE optimizes for fast, interactive analytics, which requires a different balance between speed and compactness. 2. **Can I get an exact footprint before loading?**\ The best pre-load estimate is **CSV size × 0.45–0.60**. After first load, you can confirm the precise footprint for your data. 3. **Do added columns change the estimate?**\ Yes. New columns, especially high-cardinality text, increase the in-memory footprint. Factor this in when planning growth. # Universal Search Find any resource instantly with Tellius Universal Search. Use Ctrl+K to access fast, intelligent, keyboard-driven search across all artifacts and insights. The Universal Search feature in Tellius 5.4 helps users locate and interact with resources across the platform. It is designed for fast, centralized, keyboard-driven access—letting you instantly find artifacts across Tellius with just a few keystrokes. ### How to access Universal Search? You can invoke Universal Search from anywhere in Tellius. 1. Press **Ctrl + K** (Windows/Linux) or **Cmd + K** (Mac). Once triggered, a search bar will appear, ready for input. 2. Start typing a keyword related to the artifact name, metric, or topic. 3. As you type, search results will auto-populate, grouped by artifact type (e.g., Vizpads, Insights).
4. Use the arrow keys to navigate through the results. 5. Press **Enter** to open the selected artifact directly. {% hint style="success" %} * **Autocomplete suggestions:** Tellius predicts what you're searching for based on frequently accessed items and recent queries. Frequent queries are cached for faster retrieval. * **Fuzzy search:** Supports minor spelling errors and partial matches. For example, typing "sals report" will still suggest "Sales Report". {% endhint %} ### What can you search? Universal Search indexes metadata across various artifact types. Below are the supported artifacts: * Vizpads * Insights * Business Views * Kaiya Conversations * Predictive Models {% hint style="danger" %} You will only see artifacts that your user role and permissions allow. Restricted or sensitive artifacts will not appear in your search results. {% endhint %} ### Keyboard Shortcuts | **Function** | **Shortcut** | | ---------------- | ------------------ | | Open Search Bar | Ctrl + K / Cmd + K | | Navigate Results | ↑ / ↓ | | Select & Open | Enter | | Close Search | Esc | {% hint style="warning" %} If the intended artifact doesn't appear, please review the search terms or contact admin for indexing status. {% endhint %} # Tellius Home Page Explore the redesigned Tellius Homepage with global search, pinned KPIs, and quick access to Vizpads, Insights, and Business Views for faster decisions. The Tellius home page has been redesigned to act as your starting point for every session. Instead of a static landing screen, the new home surfaces what matters right now: outputs from your scheduled Missions, the content you most recently worked on, and personalized suggestions based on what others in the same Business View environment are using. The page also adapts to where you are in your journey, so a brand-new user, a user who just connected their first data source, and a long-time power user each see a home page suited to their stage. This guide walks through every section, menu, button, and state of the new home page, the Kaiya-powered onboarding flow for new users, and the **Kaiya Architect** and **Connect** screens that the onboarding flow opens. ### What's on the new home page When you log in with data sources and at least one Business View already in place, you land on the full home page. The screen is organized top to bottom into a personalized greeting, the **Ask Kaiya** input, sample prompts, a briefings section, and the content tabs (**Recently Viewed** and **Suggested for You**).
#### Global search bar In the top-right corner of the page is the **Search anything…** bar. Use it to find any artifact in your workspace without opening each module separately: conversations, Vizpads, Business Views, Missions, Apps, and more. You can also open this search from anywhere using the keyboard shortcut shown beside the bar (**⌘ K** on macOS, **Ctrl + K** on Windows). #### Ask Kaiya input The large input box in the center of the page is where you talk to Kaiya. The placeholder text reads **"Ask Kaiya anything…"** Type a business question in natural language and Kaiya answers it against your data. The input box has the following controls: * **Auto detect BV***:* Kaiya auto-selects which Business View should be used to answer your question. By default it is set to **Auto detect BV**, which lets Kaiya choose the most relevant Business View for your question automatically. Click the dropdown to pick a specific Business View instead. * **Voice / live input control:** The signal icon next to the send button lets you provide voice or live input rather than typing. * **Send**: The button activates once your prompt is ready to send. {% hint style="warning" %} When no data source is connected, the input is disabled and the controls are inactive. See **The Day 0 (new user) home page** for what this state looks like. {% endhint %} #### Mode pills Directly beneath the **Ask Kaiya** input are four mode pills. Each pill routes your request to a specific Kaiya capability: * **Deep Insight:** Kaiya launches an in-depth, multi-step, multi-agent analysis of your data. * **Mission:** Sets up a recurring job that analyses your data and delivers a briefing when something changes. * **App:** Opens the Kaiya App experience. * **Kaiya Architect:** Opens **Kaiya Architect**, where you connect data and build or refine a Business View through conversation. #### Sample prompts Below the mode pills, Tellius shows up to three ready-made questions you can click to run immediately. These prompts are generated from your Business View and reference the real dimensions, metrics, and entities in your data, so the questions are relevant to what you actually have connected. Click any prompt to send it to Kaiya as your question. #### Briefings The briefings section collects the outputs of your scheduled Missions and delivers them directly to the home screen, so you do not have to open the Missions module to see the latest results.
* **View all in Missions:** The link on the right of the section header opens the full list of briefings inside the Missions module. * **Briefing cards:** Each card represents one Mission output and shows: * A headline describing the finding, such as *"Feature adoption tied to lower churn".* * A short summary of the result. * A **Read briefing** link that opens the full briefing in Missions page. * The name of the Mission. {% hint style="warning" %} Briefings only appear here after a Mission has run. If you have not set up a Mission yet, this section shows an empty state instead. {% endhint %} #### Content tabs: Recently Viewed and Suggested for You At the bottom of the home page are two tabs that act as a launchpad into your content. The active tab is underlined, and a **FILTER ↓** control on the right lets you narrow the cards that are shown.
**Recently Viewed** This tab picks up where you left off, surfacing the Apps, Vizpads, Business Views, and conversations you were last working on. Each card shows the artifact type, the artifact name, a small preview of its content, and how long ago you opened it. Click a card to reopen that artifact. **Suggested for You** This tab surfaces high-interaction resources from across your workspace: shared Vizpads, Missions, Apps, conversations, and Business Views that other users in your environment are actively engaging with. It helps you discover conversations, Vizpads etc. that colleagues working in the same Business View environment find useful. {% hint style="success" %} **Suggested for You** is a rename and continuation of the **Trending** tab from previous releases. The underlying behavior, which surfaces the most-engaged resources across the workspace is the same. {% endhint %} {% hint style="danger" %} All content surfaced on the home page respects role-based access control (RBAC). You only see artifacts and resources you have permission to access. {% endhint %} ### The Day 0 (new user) home page Tellius adapts the home page to where you are in your lifecycle. A brand-new user: one who has logged in but has not yet configured any data sources or Business Views sees a guided "Day 0" version of the home page whose entire purpose is to get data connected. This solves the blank-slate problem. A new user can move directly from a fresh login to a live Kaiya conversation, with starter questions auto-generated from the new Business View. #### The Day 0 flow A new user is routed into **Kaiya Architect** on first login. From there, the flow is: 1. **Configure a data source.** You can set up the data connection directly from the Kaiya Architect chat, with real-time validation as you enter the connection details. 2. **Build a first Business View** through the Kaiya Architect conversation. 3. **An "Open in Kaiya" link appears** once the Business View is published. 4. **Kaiya opens with six auto-generated starter questions** waiting in the thread. These questions reference the real dimensions, metrics, and entities you just configured.
The **Search anything…** bar (**⌘ K**) is available in the top-right corner. However, because no data is connected, the **Ask Kaiya** input is disabled. Its placeholder reads **"Connect a data source to start asking Kaiya anything,"** the status text in the box reads **"No dataset connected,"** and the attach, voice, and send controls are inactive. The four mode pills (**Deep Insight**, **Mission**, **App**, **Kaiya Architect**) are also shown in a dimmed, inactive state. #### Connect data to bring Kaiya to life The center of the Day 0 page is a prominent card that directs you to connect data. The card offers two buttons: 1. **Connect a data source →** Opens the **Add new connectors** screen, where you choose a structured or unstructured source to connect.
2. **Open Kaiya Architect** **→** Opens **Kaiya Architect**, where you connect data and build your first Business View conversationally.
When you open Kaiya Architect, you first see the welcome screen. Two buttons let you choose how to begin: * **Browse Data**: Browse your existing data before building. * **Quick Start**: Start building a Business View from scratch. Once you begin, Kaiya Architect opens into a two-panel workspace.
The left side is the **Chat** panel, where you converse with Kaiya to build your Business View. It has a **＋** button and a **paperclip (attach)** icon beside the input, plus a **send** (up-arrow) button. The right side displays what Kaiya is building as you talk. It has four tabs and a close (**✕**) button in the top-right corner: * **Plan:** The Kaiya-generated plan for your Business View. * **Diagram:** A visual diagram of the Business View being built. * **YAML:** The underlying YAML definition of the Business View. * **Data Sources:** The data sources connected to the Business View. #### Empty briefings state Below the card, the **Latest briefings** section shows an empty state because no Mission has run yet. The **Recently Viewed** and **Suggested for You** tabs and the **FILTER ↓** control are present at the bottom but contain no items yet. ### The Day 1 (getting started) home page Once you have created your first Business View, the home page moves into its "Day 1" state. The **Ask Kaiya** input and mode pills are now active, and **sample prompts** appear that are curated to the Business View you just created. Apps shared by your team also begin to surface in the content tabs. Until your first Mission runs, however, the briefings section still shows an empty state.
In this state, the briefings section reads **"No missions running yet"**. Two buttons help you start: * **Create your first mission →** Begins setting up your first Mission. * **Browse mission templates:** Opens a set of ready-made Mission templates you can start from. {% hint style="info" %} As you continue using Tellius, connecting more sources, running Missions, and working in Vizpads and Apps, the home page fills out into the full **Day 30+** power-user view described in **Part 1**, with populated briefings, recents, and activity-based suggestions all in one place. {% endhint %} #### How the home page adapts | Stage | Who sees it | What the home page shows | | --------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Day 0 - New user** | A user with no data sources or Business Views | Routed toward Kaiya Architect to connect a source and conversationally build a first Business View; disabled Kaiya input and a "Connect data" card. | | **Day 1 - Getting started** | A user who has just created a Business View | Starter briefings and suggested content curated to the new Business View; sample prompts and Apps shared by the team surface immediately. | | **Day 30+ Power user** | An established user | The full personalized library: briefings, recents, activity-based suggestions, and shared team resources in a single view. | {% hint style="warning" %} A lightweight version of the home page is available for customers who do not have Kaiya enabled. **KPI pinning is deprecated.** The ability to pin and track KPIs on the home page has been deprecated. You can still mark and access **Favorites**. As part of the redesign, the platform-wide font family has been updated, bringing typographic consistency across all modules and pages. {% endhint %} # FAQs Explore Frequently Asked Questions covering Kaiya AI, Search, Vizpads, Insights, Embedding, Data Caching and more # Kaiya Conversational AI Get answers to common Kaiya Conversational AI questions. Learn how feedback improves results, how Kaiya adapts, and best practices for smarter search. We hope these FAQs help you navigate and make the most of Kaiya Conversational Search. Your engagement and feedback are vital in helping Kaiya grow and better serve your data exploration needs. Keep exploring, and don't hesitate to reach out with more questions or suggestions! ### 1. How does giving a thumbs up or thumbs down help Kaiya improve? When you interact with Kaiya's responses using the thumbs up or thumbs down icons, you're directly helping it learn and improve. Clicking thumbs up tells Kaiya that it provided a satisfactory answer, reinforcing its understanding of your preferences. If you select **Thumbs down → Fix it**, you can provide corrections or alternate mappings. Kaiya remembers these adjustments and applies them to similar queries in the future. Selecting **Thumbs down → Give feedback** sends your input to our team, which we use to enhance Kaiya's mappings and result displays. Your feedback plays a crucial role in making Kaiya smarter and more personalized to your needs. ### 2. How does Kaiya learn and evolve as I use it? Kaiya is designed to adapt to your unique usage patterns and preferences. As you interact with it—through the queries you make, the feedback you provide, and the adjustments you request—Kaiya observes and learns from these interactions. Over time, it becomes more attuned to your specific business needs, offering more personalized and relevant responses. Think of Kaiya as a dynamic assistant that grows with you, continuously evolving to better support your data exploration journey. ### 3. What happens if I enter a query without selecting a Business View first? We know—it can be easy to forget to select the right Business View (BV) before diving into your query. Right now, if you type a query without choosing a BV, Kaiya will gently remind you to pick one first. But here's some exciting news: we're working on bringing **SmartSelect** to Kaiya! Soon, Kaiya will automatically select the most relevant BV based on your query and keywords. That means you can just start typing naturally, without worrying about pre-selecting a BV. ### 4. How flexible is Kaiya when exploring data? Incredibly flexible! While Kaiya works within the data you've uploaded, there's a whole world of possibilities. You can: * **Summarize results** to get a quick overview. * **Customize summaries** to highlight what's important to you. * **Modify previous queries on the fly**—no need to start from scratch. * **Dive deeper** into specific data points for detailed insights. * **Apply filters** to narrow down results. And much more! The possibilities are vast, and the more you use Kaiya, the more capabilities you'll discover. Just a heads-up: Kaiya cannot predict the weather, give you a recipe, or do anything outside of your analytical needs! ### 5. Can I ask Kaiya "why" and "how" questions? Yes, you will soon be able to ask Kaiya "why" and "how" questions to gain deeper insights. We're in the process of rolling out this feature where you can uncover hidden patterns and get detailed explanations behind your data. ### 6. Is there a way to view the available columns in the Business View as I type my query? Absolutely! We've got you covered! After selecting a Business View, just click on the **Business View** icon in the top right corner. This will display all the columns available in that BV, so you can easily reference them while crafting your query. We want to make sure you have all the tools you need right at your fingertips. ### 7. Is there a best practices checklist for using Kaiya conversational Search? 1. Ensure you’ve selected the correct BV before typing or speaking a query. 2. Use the **"Show Popular Queries"** button to access frequently used or shared queries. Add queries to the library which will be helpful for your (and your team’s) future exploration. 3. Use the thumbs-up/thumbs-down option to validate your results. Flag insights that seem off or confirm ones that are helpful. 4. Explore **“Search Inspector”** section for critical information like query execution time, rows analyzed, and the SQL context generated. 5. Use voice commands when possible as they can save time and simplify your effort. 6. Consolidate your best charts into Vizpads for reporting or sharing with stakeholders. This avoids having scattered charts across multiple chats. 7. Delete or rename outdated queries and conversations to keep your workspace streamlined. ###
# Data Preparation FAQs Explore how actionTypes enable interaction with Vizpads, retrieve filters, set resolutions, and access Business View columns through embedding postMessage calls. #### **What is a Business View?** A Business View is a logical data model. Consider a logical collection of tables that are linked by a common key (date, ID etc). When building a Business View, one has to build a dataset for modeling rather than creating a relational database. #### **What happens if Business Views are downloaded as CSV?** The portion displayed under Data -> Business View will be downloaded as a single table. #### **What is the difference between a Business View and a Project?** A Business View is the logical data model used to drive Search, Vizpads, Insights, and Models. A Project is akin to a folder that contains a collection of Vizpads, Insights, and Models for a particular Business View. Once a project is shared with other users, all of its contents are shared automatically. #### **Can I create a new dataset within Tellius using SQL or Python?** No, you can only add or remove columns in the existing dataset. A self-join of datasets is possible in some instances. #### **What is the difference between column type and feature type?** Column types can be measures or dimensions. Feature types can be categorical or continuous. Check out the documentation on [column type](https://help.tellius.com/article/t079cqyb64-metadata-view#column_type) and [feature type](https://help.tellius.com/article/t079cqyb64-metadata-view#feature_type). #### **How do I refer to null values in the signature function? I have tried multiple versions, and none work (null, NULL, “NULL”, “null”).** For this purpose, you need to use SQL or Python. Functions do not support reference to null values. #### **How do I set the incremental data refresh, i.e., do not replace it, but append it during a refresh?** Only full replacement is available for local files. Incremental can be set up for databases. #### **Where is the data located after the connection is established?** The data is loaded into memory and also stored on disk. #### **How to handle actual time stamp columns? For example, converting a string "12:12:11" to a timestamp, using hh:mm:ss format does not work as the date is set to Jan 1, 1970.** This manipulation need to be done using SQL or Python. #### **If I need to go back into the data pipeline and modify a node, will the subsequent node be updated?** Yes. SQL, Python, and advanced filter nodes can be modified in the middle of the data pipeline without having to modify the subsequent node. If a node is no longer needed, keep the node without a script. #### **The values with dollar signs are imported as strings. How to handle the transformation into a num?** It's recommended to remove the dollar sign, comma, and periods (for decimals) using find & replace via SQL or Python. Then, it needs to be converted into a number. Or, you could directly convert it into a number via SQL or Python. #### **What is Live query mode? What are the cons of that approach?** Live datasets reside in the source, and they are not imported to Tellius. So for each query, the data needs to be fetched from the source, which could take a bit of time (when compared to non-live datasets). It can only be used for driving Search and Vizpads, but not Insights or ML models. #### **What are the databases that work with the Live query engine?** Redshift, Snowflake, Bigquery, Teradata work with Live query engines. #### **What is the difference between measures and dimensions?** Measures are quantitative values (e.g., profit, sales, weight) for which you can apply aggregation. Dimensions are qualitative values (e.g., city, name) for which aggregation cannot be applied. Check out [this section](https://help.tellius.com/article/t079cqyb64-metadata-view#column_type) for more details. #### **Is there a way to see an audit trail of each transformation made on the dataset so I can undo/revert changes?** Yes. Data Pipeline contains the audit trail of all transformations done to a dataset. The pipeline is tied to a dataset. So, if a dataset is deleted, its pipeline will also be deleted. #### **Can we incorporate formulas, nested queries, or complex joins within the search criteria and join them with specific keywords?** It is absolutely possible to create formulas, nested queries, and complex joins, which can be used in search queries. New business KPIs and calculated metrics can also be created and used in Search and Vizpads. #### **Does Tellius support the loading of large data sets in bulk? If so, what are the relative speeds?** Yes. Tellius supports live connections and loading in bulk. The speed depends on the size of the data, resources for the instance, and underlying data source. #### **When using a SQL script for a live connection, how does it run, and what's the impact on performance? For instance, will a window function in the script execute with every front-end query?** In live connections, any SQL script, including a window function, will execute with each Search/Vizpad query run. To avoid this, consider creating a Materialized View on the source system and then load it to Tellius. #### **What SQL dialect is used for calculated columns within live connections?** The SQL dialect for calculated columns is compatible with both Spark and the source system from which the data is loaded. #### **What is the expected behavior when the FQE is toggled on for a live Business View (BV)?** Enabling FQE on a live BV is not applicable. If toggled on, the system will not ingest the data into FQE; live connection status will be maintained. Please avoid using the FQE toggle for live BVs. # Environment FAQs Explore Tellius environment setup, server specs, cloud deployment, scaling options, failover features, monitoring tools, and SSO or SAML authentication support. #### **What is the default size of the server?** 200GB, 64 core, 512 GB ram for a cluster. The number of clusters needed depends on the size of the data, number of users, and the kind of work they do on a daily basis. #### **What cloud providers can we deploy on?** Amazon (preferred) and Azure. #### **Can the workload be distributed into multiple nodes?** Tellius can be deployed on a single machine for smaller datasets. For complex machine learning and larger datasets, we do recommend a multi-node deployment. Additionally, Tellius supports both horizontal and vertical scaling. Tellius uses a distributed in-memory architecture using Apache Spark and other highly distributed technologies. The system can be horizontally scaled to guarantee customer performance requirements. #### **Does Tellius support automatic node failover and backups?** Yes. Tellius supports high availability, failover, and backups. Kubernetes master runs in different zones to ensure that the Kubernetes is always up. Each Tellius service runs as Kubernetes Replication Set allowing more than one instance to be available at a time (in the same or different regions). #### **Does Tellius provide native dashboards that can help monitor the health of the system and the usage logs?** Tellius uses Kubernetes dashboard to monitor the machines and clusters. Tellius uses Prometheus for all the service-level monitoring. #### **Does the technology support SSO (i.e., LDAP & SAML)?** Tellius platform supports standard authentication and authorization protocols. As a part of authentication, LDAP and/or any other SAML 2.0 based IDP systems can be set up. This will allow users/groups/roles to be authenticated against organizational IDP systems and keep them in sync. **Is Tellius admin or superUser?** Tellius gets to be the superUser. You are provided with admin access. Although superUser has more capabilities than admin roles, admins can still manage system config options and grant/revoke user access.
# Search FAQs Explore Search FAQs to learn how AI-driven search adapts over time, supports synonyms, and enables user feedback for smarter analytics. #### **Does the search AI learn (i.e., get better over time) through crowd-sourced interaction and feedback?** In addition to displaying suggestions for the entire search query, Tellius displays suggestions for the current word being typed and the next word to be typed. The suggestions are provided based on multiple sophisticated algorithms. Tellius also displays the history of questions, trending questions, top questions, most frequently asked questions, questions based on users/frequency etc. #### **Is there an easy way for me to “teach” Tellius if the answer returned is good/bad?** Tellius' Search can learn from a user's language and dictionary. During data preparation, multiple synonyms can be added to a column, and those words can be used in search query instead of the actual column. Check out [this section](https://help.tellius.com/article/t079cqyb64-metadata-view#synonyms) for more details. In addition, for any search query, users can tag various words/phrases and teach Tellius the meaning for each phrase. Next time when the phrase is used, it will train Tellius to display the intended results. #### **What does 'last date' used in search queries represent?** By default, the last date refers to the current date. However, it can be customized in the admin interface. # Vizpads FAQs Find answers to common Vizpads questions in Tellius—learn about chart limits, row-level security, multi-Business View support, and interactive features. #### **What is the limit on the number of charts I can add to a vizpad and within one tab?** A Vizpad can have 10 tabs, and each tab can have upto 25 charts. #### **Does the row-level data security apply to Search and Vizpads?** Yes, it does. However, it needs to be set up by the admin. Row-level policy is defined for a group over a Business View so that when users search and run analysis on datasets, they only see the data associated with them (and not the data that is private to a different user). #### **Can selection on one chart act as a filter on another?** Yes, it can be done by selecting **Keep** or **Drill-in** after clicking on a slice of a chart. #### **The calculated columns that are displayed during data preparation does not show up when I’m editing a Vizpad. How do I make them visible?** Go to the required **Business View** and select **Edit**. Add all columns or check the columns you need to pick. #### **Is there a way to rename the tabs?** Yes, click on the dropdown in a tab and select **Rename**. #### **Can I build a Vizpad using multiple Business Views?** Yes, check out our [multi-Business View Vizpads](https://help.tellius.com/vizpads-explore/creating-vizpads#multi-business-view-vizpads). #### **Can I develop my own custom visualizations via rest-based APIs?** Tellius offers two forms of embedding: * Embedding Tellius modules (UI) into external applications (via Embedding URLs) * External applications querying and getting results/output via APIs # Data Caching FAQs Explore data caching FAQs to understand caching vs. ingestion, 'Copy to System,' Fast Query Engine, and performance optimization tips. This page contains a set of FAQs focused on the nuances of data caching within the Tellius platform. #### **1. How is data caching different from data ingestion in Tellius memory?** Data caching involves storing data in memory for quick access, ensuring faster response times for repeated queries. On the other hand, data ingestion refers to the process of bringing in data on demand, which may not be immediately stored in memory. While both processes are integral to Tellius, caching provides a performance advantage by reducing the need to repeatedly ingest data. #### **2. What happens if I disable data caching from these settings?** Disabling data caching can lead to performance issues. Each time you publish a dataset, create a Business View, or run Insights, Tellius will fetch the entire data from the source, apply necessary transformations, and then continue with subsequent operations. This can significantly slow down performance and exert undue pressure on the data source. #### **3. How is the "Copy to System" option different from data caching when creating a new scripted dataset or during data ingestion?** "Copy to System" refers to persisting data to the disk rather than just in memory. When this option is enabled, a copy of the data is saved on the disk. This ensures that even if the service restarts (which might clear the memory cache), the system doesn't have to retrieve data from the source again. #### **4. Are "Copy to Disk" and "Copy to System" the same?** Yes, **"Copy to Disk"** and **"Copy to System"** are synonymous. They might be represented differently in Settings and the Load page, but they perform the same function of saving data to disk. #### **5. How does enabling caching for insights and ML models help?** Caching saves datasets for faster access. However, Business Views are treated differently. Since both Insights and ML models use Business Views and go through the data multiple times, enabling caching makes these processes run much faster. Without caching, things could slow down noticeably. #### **6. What does the "Save to Fast Query Engine" setting mean for a dataset with BV enabled?** The "Save to Fast Query Engine" (FQE) setting determines whether a Business View should be saved to FQE by default. Unless there are specific issues with it, it is always recommended to save to FQE to ensure faster query performance. It's important to understand that some of these settings might evolve over time based on system upgrades and improvements. For instance, the option for "Copy to System" has been superseded in the 4.3 release with the introduction of the "Permanent Data Storage" feature, which always saves data to disk irrespective of user selection. # Embedding FAQs Explore embedding FAQs to understand embedding methods, security measures, and best practices for integrating analytics into your app. #### **What type of embedding should I choose?** Based on your requirement - if you want to show a static dashboard (revenue, leads captured etc.) that is common to all users, then you can go with the static token method. For user-specific/interactive charts, dynamic token method can be used. Also, consider the following criteria before choosing an embedding method: * The data consumers of the app (specific to a team/user or common audience) * The technical expertise of the team (ability to build customized UI, generating unique jwt etc.) * The estimated time of completion (few hours or few months) * The level of customization required (no customization or inputs-only or full level of control) #### **Can we do multiple types of embedding in a single application?** Yes, multiple types of embedding can be deployed in a single application. Each iFrame component can be configured separately. #### **What are the security measures taken on embedding?** Tellius can be configured to allow embedding only from same/listed origins and restrict cross-origin requests. The tokens also comes with an expiration. # Insights FAQs Explore Insights FAQs to understand Discovery, Key Driver, Trend, and Comparison Insights, and learn how to create and interpret them. #### **What happens when a refresh is set up for an Insight?** The Insight will refresh/re-run at the scheduled time, irrespective of data refresh, and you will receive a notification. If the data remains unchanged, the resulting insight will be the same. #### **Why does comparison insight show me the number of rows?** It could be useful in some cases to assess the frequency comparison between cohorts. #### **How do you know when to use discovery insights vs. autoML?** Tellius Insights is still a descriptive output, although it uses predictive modeling on the back end. Use Insights to uncover and quantify relationships between metrics and dimensions in order to explain a particular scenario in the data. ML is used when a certain outcome needs to be predicted (example: predict if a loan is going to be charged off, predict sales for 30 days into the future) #### **Can you use a custom model for Discovery Insights?** No, Insights is a fine-tuned framework that produces four types of output at the moment: discovery, segment driver, comparison, and trend. # Understanding AI Agents & Agentic Flows Learn how to build, manage, and trigger AI Agents and agentic workflows in Kaiya to automate insights, streamline analysis, and boost business intelligence. Under Kaiya, click on the open side bar, and select "**Missions"** from the menu. The following window will be displayed.
The **Mission Library** is the central place where users can explore, manage, and create AI-powered agentic Missions. Each agentic Mission automates and analyzes specific business questions—such as sales trends, product performance, or market behavior. 1. **Published Missions:** Displays all functional and available Missions that have been successfully created and published. 2. **Draft Missions:** Displays all unpublished Missions that are still in progress or saved as drafts. 3. **Search bar:** In the top right corner, you can find the search bar using which you can quickly locate a specific Mission. This lets you to filter the displayed agents by keyword. 4. **Compose:** Create a new agentic Mission from scratch. Opens[ **"Composer"**](/kaiya/understanding-ai-agents-and-agentic-flows/kaiya-missions/composer) where you define data source, steps for the workflow, and set up triggers. 5. **Mission:** A published agentic Mission, ready to be executed from Kaiya conversational AI. Displays the name, description, creator and created date in each widget. Clicking on a widget will redirect you to **"Composer"**, where you can edit the workflow. 6. **Three-dot menu:** Allows you to edit, delete, unpublish or duplicate the selected agentic Mission. **Unpublish** deactivates the Mission so it stays in the library. The duplicated agentic Mission will be displayed under **Draft Mission.**
# Kaiya Missions Create Kaiya Missions to set up analytical steps, trigger them with natural-language phrases, and deliver consistent, governed outputs. ### **What is a Mission?** A Kaiya Mission is a **named, reusable analytical workflow**. A user authors it once through conversation with Kaiya — describing the analysis they want, refining Kaiya's proposed plan, and publishing it. Once published, the Mission can be run on demand by anyone with access, or set up to run automatically on a recurring schedule. The same analytical methodology applies on every run, regardless of who triggers it or when. You can also schedule a Mission to run on a recurring cadence instead of waiting for someone to trigger it conversationally. Pick the output format you want (PowerPoint or PDF) in the Mission's **Outputs** tab, and the finished report is emailed to the recipient list on every scheduled run. All Missions can be found under the **Published Missions** tab in **Kaiya → Missions.**
### **What are the ways to interact with a Mission?** * **Authoring** is a one-time setup. The author describes the workflow, refines Kaiya's proposed plan, tests it, and publishes. As part of authoring, the author also decides whether the Mission runs only on demand, or runs on a recurring schedule with output delivered automatically to a list of recipients. * **Running** happens on demand by anyone with access to the published Mission. The runner triggers the Mission, and provides any inputs Kaiya asks for at runtime (region, quarter, segment, etc.), and receives the output. * **Receiving on a schedule** is a third interaction mode for recipients who don't actively run the Mission themselves. Once an author configures a schedule and recipient list, the Mission output is emailed to the recipients on every scheduled run. Recipients consume the result as a finished artifact (PPTX, PDF, or DOCX) without opening Tellius. {% hint style="info" %} User-defined Missions let you hard-code the exact analytical steps Kaiya should run (SQL pulls, Python methods, visualizations, and the final summary), instead of letting the planner assemble them on the fly. You describe the steps in natural language, optionally add required parameters, and map a trigger phrase to the Mission (for example, "*quarterly payer deep dive*").\ \ When a user's question contains that trigger, Kaiya executes your governed sequence in that order, applies your defaults, and asks only for missing inputs. {% endhint %} ### **How to build a Mission?** Tellius 6.3 introduces a new conversational interface for authoring Missions, alongside the existing form-based interface (now labeled **Classical Editor**). Both produce Missions stored in the same **Published Missions** library, both support scheduling, and both can be triggered conversationally. * **Conversational interface.** Describe what the workflow should do in plain language. Kaiya drafts the step sequence, asks clarifying questions back when needed, and refines the plan with you in the same thread. Scheduling, triggering, and output configuration are available as inline tabs within the same conversation thread. * **Classical Editor.** A form-based composer where you configure each section explicitly: Basic Information, Knowledge Sources, Mission Steps, Triggers, Schedule, and Outputs, and save the Mission. The **Schedule** section supports two options: subscribe to an existing schedule in the workspace, or create a new schedule just for this Mission. {% hint style="info" %} An admin-controlled global setting determines which interface users see by default. Both interfaces coexist during the rollout, and existing Missions remain available regardless of which interface a user is on. {% endhint %} ### **How to schedule Missions?** While building the Mission, the author chooses whether the Mission runs only on demand or on a recurring cadence. Two scheduling options are available: * **Subscribe to an existing schedule:** Attach the Mission to a schedule already created in the workspace. Useful when several Missions should run on the same cadence. * **Create a new schedule for this Mission:** Configure a fresh schedule specifically for this Mission, with its own start date, start time, cadence, optional runtime inputs, and email recipient list. {% hint style="info" %} A single Mission can be attached to more than one schedule. A single schedule can drive more than one Mission. {% endhint %} ### **Two ways to consume a Mission** * When a Mission runs on demand, the result appears in the **Mission Draft Editor**'s **Last Briefing** tab. The runner scrolls the narrative, drills into citations on any numeric result, and asks follow-up questions in the same thread to dig deeper without restarting the Mission. * When a Mission is assigned a schedule, the output is generated automatically on every scheduled run as PPTX, PDF, or DOCX and emailed to the configured recipient list. Recipients receive a presentation-ready artifact in their inbox without opening Tellius. The same Mission can drive both modes simultaneously: interactive runs for analysts who want to investigate, and scheduled deliveries for executives who want the finished briefing. {% hint style="info" %} A Mission's output format is configured in the **Outputs** tab during authoring. Three formats are supported in 6.3: PowerPoint (PPTX), PDF, DOCX. {% endhint %} ### **Where Missions live in Tellius** Missions are organized in the **Mission Library**, accessed via **Kaiya → Missions**. The library has three views: * **Published Missions:** Missions that are live and available for users to run. Each Mission shows its name, icon, description, author, and the number of schedules attached to it. * **Draft Missions:** Missions an author has saved but not yet published. * **Scheduled Missions:** A dedicated page listing every Mission schedule active in the workspace, with columns for Mission name, schedule name, frequency, next run, last run, and creator. From here, authors can create new schedules, edit existing ones, and review run cadence across the workspace. # Mission Editor The editor has three tabs: **Last Briefing**, **Configuration**, and **History**. #### Last Briefing The Last Briefing tab shows the output of the most recent run. When a Mission executes, a status line appears at the top of the conversation (for example, *"Executing mission: \[Mission name]"*), followed by the run output. **Step-by-step execution.** Each run is shown as a numbered iteration (Iteration 1, Iteration 2, and so on). Within an iteration, every step is listed with its type and a checkmark once complete. For example: * **Step 1:** Input Collection. Collects the runtime inputs the Mission needs (such as cohort, role, and area selections). * **Step 2:** SQL Query. Pulls the raw governed data for the analysis. * **Step 3:** Python Analysis. Scores, ranks, weights, and pre-renders the analytical output. * **Step 4:** Summary. Renders the final result. Each step row can be expanded with its chevron to see more detail. **Rendered output.** Below the steps, the full briefing renders inline — narrative text, data tables (such as ranked leaderboards), and the supporting explanation of how figures were calculated, including timing context and scoring methodology where relevant. At the end of every briefing, Kaiya auto-generates a list of follow-up questions, giving the user a path to drill deeper without starting a new Mission. You can also directly create App or create a schedule right from this page by clicking on **Create App** and **Create new schedule for Mission**. #### Configuration The Configuration tab is where you set up or adjust every part of the Mission. A left-hand navigation panel organizes the Mission into six sections:
* **Basic Information:** the Mission's identity. Set the **Mission Display Name**, choose an **Icon**, and write a **Mission Description** explaining what the Mission does. * **Knowledge Sources:** the Business View(s) the Mission runs against. * **Mission Steps:** the step sequence. Shown read-only here with an **Edit** button that opens the conversational builder. (See [Composer](/kaiya/understanding-ai-agents-and-agentic-flows/kaiya-missions/composer)) * **Triggers:** the natural-language phrases that invoke the Mission in conversation. * **Schedule:** the recurring cadence and email delivery, if the Mission is scheduled. * **Outputs:** the export format (PPTX, PDF, or DOCX) and report structure. Each section opens in the main panel to the right of the navigation. The active section is highlighted in the left panel. #### History The History tab shows every run the Mission has produced, most recent first. The tab label includes the total run count.
Three headline metrics appear at the top, based on the loaded runs: * **Total runs** — the number of times the Mission has executed. * **Success rate** — the percentage of runs that completed successfully. * **Avg duration** — the average run time. Below the metrics, a table lists each run with the following columns: * **Job name** — the name of the Mission run. * **Status** — the outcome of the run (for example, Success). * **Start time** — when the run began. * **End time** — when the run finished. * **Duration** — how long the run took, in seconds. * **Short summary** — a one-line description of the run's result (for example, *"Specialty Pod ranks first with minimal share decline"*). * **Logged at** — the timestamp the run was recorded. A run's briefing can be opened from the conversation when available. # Composer Composer lets you build, test, and publish custom agentic Missions in Kaiya: defining steps, triggers, and data sources to automate governed analytical tasks. To create a custom Mission, click on the **"Compose"** button at the top right under **Kaiya → Missions**. Fill up the following details to set up the Mission. ### **Basic Information** Set up the foundational identity of your Mission: its name, icon, and a short description of what it does. **Mission Name & Icon:** Enter a clear, meaningful name in the **Mission Display Name** field and choose a static icon for the Mission. **Mission Description:** Briefly explain what this Mission is designed to do.
### **Knowledge Sources** Select the data source for your Mission. Use the dropdown or search bar to select an existing Business View. This becomes the primary input for all agents in the Mission. {% hint style="warning" %} At least one Business View should be selected to save the Mission. {% endhint %}
### **Mission Steps** Define the logic of your Mission as a sequence of steps. In the **Configuration** tab, the Mission Steps section shows the current step plan; clicking **Edit** opens a conversational builder where you refine the steps by describing what you want to Kaiya. When you open **Mission Steps**, the current steps are displayed read-only inside a card titled **Analysis Steps (N)**, where N is the step count. A **copy icon** at the top right of the card copies the full step list.
Each step shows three things: its **step number**, a **type badge**, and a **plain-language description**. The type badge tells you which kind of engine logic the step runs: | Badge | What the step does | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | | **Input** | Collects a runtime input the Mission needs before it can run (a date range, territory, metric choice, etc.). | | **SQL** | Pulls and aggregates governed data from the selected Business View. | | **Python** | Enriches or transforms the data with logic SQL can't easily do: rankings, shares, cumulative calculations, performance classification. | | **Summary** | Turns the results into a narrative with charts and recommendations. | Above the card is the **Edit** button (pencil icon). Click it to open the conversational builder and change the steps. #### **Expanding a step** Click the chevron on any step to expand it into a **"What this step does"** breakdown. This is a plain-language explanation of the step's logic, structured into labeled sections so a reader can understand exactly what the step will do without reading code. Each expanded step has its own **copy icon** to copy the breakdown. {% hint style="info" %} Within the builder, click the **pencil icon** on any step to edit it inline and click on **Save**. Change a metric, add a filter, refine the calculation without rebuilding the whole Mission. {% endhint %} The sections shown depend on the step type: * **Goal:** what the step is trying to understand. * **What data is gathered:** the rows or records pulled. * **Filters applied:** any filters filters * **How it's processed:** the specific aggregations and calculations, with the key measures called out. * **Output:** a description of the resulting dataset. * **Sql instructions:** a collapsible block (with its own copy icon) containing the underlying SQL detail. At the bottom, the step's named output variable is shown. * **Analysis applied:** the transformations performed. #### **Editing steps conversationally** Clicking **Edit** opens a two-pane workspace. The breadcrumb at the top left reads **Mission Library / \[Mission name]** (for example, *Mission Library / state wise profit*). This is where you build and refine the step plan by talking to Kaiya.
In the left side conversation pane, you describe what you want and refine the plan. * Enter what the **Mission** should do. Kaiya responds with a confirmation and builds the steps in the right pane. * Continue the conversation to refine. When you ask for something that doesn't match the current plan, Kaiya explains what the current steps actually do and asks a clarifying question instead of guessing. * The conversation persists in the thread, so the full history of how the plan evolved stays visible. * **Business View selector:** a chip at the bottom left showing the selected Business View(s) with a dropdown to change it. This is the data source the steps run against, carried over from **Knowledge Sources**. * **Voice input:** the microphone icon lets you dictate instead of typing. * **Clear context:** clears the context that has been built up so far and starts afresh * **Chat collapse:** the toggle icon in the Chat pane header collapses the pane. The right pane consists of the **Mission steps** and the **summary** generated**.**
* **Mission Steps:** the generated step sequence, shown in the same **Analysis Steps** card with the copy icon. In edit mode, each step also shows a **pencil icon** on the right for inline editing of that individual step.
* **Summary:** After the Mission runs, switch to the **Summary** tab in the right pane to see the **Generated summary.** The full rendered output of the run. It presents the analysis as a structured business report: an **Executive Overview** in narrative form, followed by **Key Findings** with ranked data tables, performance tiers, and bulleted takeaways. Figures throughout carry **inline citation markers** that trace each number back to its source step. Use the Chat pane to run the Mission; when Kaiya completes the execution, the output appears here. * **Approve & Run:** Approves the current step plan and runs the Mission. * **Save:** saves the current state so you can return later. ### **Triggers** Define the natural language triggers that you might enter in Kaiya Conversational AI to invoke this Mission. Triggers should accurately reflect the goal of the Mission. * Each trigger should be a standalone phrase or question on a new line. * Include variations of phrasing to capture different user intents.
For example, for revenue drop, you can say: * What's causing the revenue drop? * Explain the decline in revenue * Why did our revenue decrease? * Identify reasons for revenue dip * Breakdown revenue loss {% hint style="info" %} You can enter as many variations as you like. This increases the chances your Mission is selected by Kaiya when users input related queries. {% endhint %} ### **Schedule** Choose how you want this Mission to run on a recurring basis. Scheduling lets the Mission execute automatically at a defined cadence and deliver its output to a recipient list by email, without anyone having to trigger it conversationally. You have two options: * **Subscribe to existing schedule:** Pick from a list of schedules that have already been created in your workspace. Useful when several Missions should share the same cadence. * **Create new schedule for Mission:** Set up a fresh schedule just for this Mission.
#### **Subscribe to existing schedule** Clicking this option opens the **Available Mission Schedules** view. Each card shows the schedule name, its recurrence pattern, the next scheduled run date, the delivery method, and the author who created the schedule. Use the arrow controls at the bottom to page through schedules if there are more than fit on one screen. Click a card to subscribe the current Mission to that schedule.
#### **Create new schedule for Mission** Clicking this option opens a single-page form titled **"Creating schedule for \[Mission Name]"**. You'll configure three things:
**Cadence** * **Start Date:** the date the first run should happen. * **Start time:** the time of day the run should happen. * **Cadence:** how often the Mission should run (for example, Daily). **Mission instructions (optional)** Provide any runtime inputs this Mission needs — like a brand name, territory, preferred metric, or time frame. Check your Mission Steps to see what inputs are expected. **Email delivery** * **Email addresses:** pre-filled with your account email. Add more recipients separated by commas. Use the **Cc, Bcc** dropdown to add carbon-copy and blind carbon-copy recipients. * **Subject:** pre-filled based on your Mission name and cadence. Edit as needed. * **Email Message:** pre-filled with a default body. Edit as needed. Once everything is set, click **Schedule Mission** to activate the schedule. ### **Outputs** Configure the format in which the Mission delivers its final result. Whatever you set up here is what gets attached to the email on every scheduled run, and what you receive when the Mission is triggered on-demand.
* **Output Formats:** pick the export format from the dropdown (PPT or PDF). * **Report Template:** choose a template for the report layout from the dropdown. * **Report Storyline:** describe the narrative structure of the report in plain language. This is what guides Kaiya on how to organize the slides — section order, what each slide should cover, and the closing recommendation. ### **Save the Mission** When you've filled in the configuration, click **Save & Publish** at the top right to move the Mission to the **Published Missions** section of the **Mission Library**. Alternatively, click **Save Draft** to save it under **Draft Missions** and finish later. # Scheduling Missions Learn how Kaiya Missions automate recurring analytics workflows, proactive monitoring, and AI-driven business actions inside Tellius. The **Scheduled Missions** page is where you view, filter, and manage every Mission that runs on a recurring schedule. From here you can see when each scheduled Mission last ran, when it's running next, who created it, and at what frequency. To open it, go to **Kaiya → Missions → Mission Library** and click the **Scheduled Mission** button at the top right.
**What you'll see on the page** Each row in the table represents one scheduled Mission, with the following columns:
* **Mission name:** the name of the Mission this schedule belongs to. * **Schedule:** the name of the schedule itself (a single Mission can have more than one schedule attached to it). * **Frequency:** how often the Mission runs. * **Next run:** the date and time of the next scheduled execution. * **Last run:** when the Mission was last executed. Displays "—" if it hasn't run yet. * **Created by:** the user who created the schedule. A three-dot menu at the end of each row lets you take actions on that schedule.
**Filtering and sorting** Three controls at the top of the table help narrow the view: * **Sorting:** sort by date and recency
* **Mission:** filter to schedules belonging to a specific Mission. * **Author:** filter to schedules created by a specific user. Click **Reset** to clear all filters. Use the **Search** bar in the top right to find a schedule by name. ### **How to create a new schedule** Click the **Schedule** button at the top right to open the **Create new schedule** wizard. This is a two-step flow.
#### **Step 1: Basic Information** Configure what the schedule is for: * **Mission Name:** pick the Mission this schedule should run. Once you select one, its details appear in the **Mission Details** panel on the right. * **Information needed to run (optional):** provide any runtime inputs the Mission needs (brand, territory, time frame, etc.). * **Schedule Name:** give the schedule a name. This is what shows up in the **Schedule** column on the table and in the Available Mission Schedules card grid. * **Schedule description (optional):** a short note describing what the schedule is for. Click **Next** to move to Step 2. #### **Step 2: Schedule and Delivery** Configure the cadence and how results are delivered: * **Start Date:** the date the first run should happen. * **Start time:** the time of day the run should happen. * **Frequency:** how often the Mission should run. * **Email addresses:** recipients of the output email. Use the **Cc, Bcc** dropdown to add carbon-copy and blind carbon-copy recipients. * **Subject:** a subject line for the notification email (required). * **Email Message:** the message body included in the email (required). Click **Schedule Mission** to activate the schedule. The new schedule will appear in the table on the Scheduled Missions page and will also become available in the **Available Mission Schedules** card grid that other Missions can subscribe to. For large outputs, export generation runs as a background job with pagination support, so the artifact is processed without blocking. Progress is tracked in the background, and the recipient is notified when the artifact is ready. The scheduled run uses the output format configured in the Mission's **Outputs** tab (PowerPoint, PDF, or DOCX) and attaches it to the delivery email on every run. {% hint style="info" %} A single schedule can be reused across multiple Missions. If you've already created a schedule that fits a new Mission's cadence, subscribe to it from within that Mission's **Schedule** tab instead of creating a duplicate. {% endhint %} To inspect how a scheduled Mission has performed over time, open the Mission and go to the **History** tab in the **Mission Draft Editor**. For scheduled Missions, it shows **Total Runs**, **Success Rate**, and **Average Duration** as headline metrics, with a per-run log listing each execution's job name, status, start and end time, duration, output summary, and timestamp. # Triggering a Kaiya Mission Learn how Kaiya triggers a Mission—from matching user queries to triggers, orchestrating AI agents, executing steps, and delivering structured insights. This page breaks down the entire agentic Mission — from the moment a user invokes a published Mission to when results are returned — and explains what the user sees and controls at each stage. It applies to all Missions regardless of use case (revenue analysis, product discontinuation, churn prediction, and so on). {% hint style="danger" %} To trigger a user-defined Mission or let Kaiya plan and automate the analysis step by step, click the **Deep Insight** button. {% endhint %} There are two ways a Mission runs: * **On demand**, when a user invokes it in a Kaiya conversation. Either by typing a query that matches one of the Mission's trigger phrases, or by running it directly from the Mission Library. * **On a schedule**, when the Mission runs automatically on a recurring cadence and delivers its output by email. This page covers the on-demand flow. The stages below describe what happens end to end. ### 1. User initiates query When the user interacts with Kaiya by entering a natural language query in the chat interface, it is evaluated in real time against a list of triggers configured for published agentic flows. Each Kaiya Mission contains one or more trigger phrases defined during Mission creation in Composer. These triggers allow Kaiya to intelligently map user input to the correct Mission, even if the phrasing is not exact. Trigger variations are supported, meaning you can ask a question in different ways, and Kaiya will still recognize the intent. ### 2. Kaiya maps query to a trigger If a match is found, Kaiya responds with the name and description of the matching agentic Mission, and prompts user confirmation to initiate the Mission execution. This user confirmation ensures control and transparency before any backend processing begins. Choose “**Yes**” to continue, else select “No” to abort the Mission exection.

Matching the trigger with the Mission

### 3. Mission initialization Upon confirmation, Kaiya activates the Planner Agent. The Planner Agent's job is to: * Interpret the Mission's objective * Break it into logical, executable steps * Identify which agents need to be involved * Sequence these agents correctly

Supervision Agent working behind the scenes

The Planner Agent acts as the orchestrator or mission control of the entire agentic flow. It ensures the right agents are activated at the right time in the right order. ### 4. Squad of AI Agents A message appears as follows: “*Squad of AI Agents... Finding the best agent to execute next step.*” This indicates that Kaiya is identifying and activating the most suitable agent for the task at hand. The agents activated depend entirely on the Mission steps defined in **Composer**. Agents begin executing each Mission step , using the logic defined in **Composer**. Commonly involved agents include: | **Agent Name** | **Role** | | ----------------------------------------------- | -------------------------------------------------------------------- | | Validation Agent | Checks query structure, permissions, and data readiness | | Planner Agent | Breaks down requests, assigns agent tasks, sequences execution | | Data Prep Agent | Filters, joins, and loads relevant data from selected Business Views | | Visualization Agent | Generates appropriate visuals (charts, tables, graphs) | | Insights Agent | Performs root cause analysis, trend detection, and pattern mining | | Summary Agent | Converts insights into plain-language narratives and summaries | | Knowledge Graph Agent | Maps relationships, finds entity connections, powers recommendations | Each of these agents has a specific, modular purpose, and they are invoked only if required by the defined step logic.

Analytic Agent working behind the scenes

Conditional logic and dependencies between steps are respected. Prompts for additional user input (e.g., filters, time periods, dimensions) may be triggered dynamically. This modular structure enables Kaiya to adapt Missions based on data state, user interaction, or complexity of analysis. ### **5. Parameterized inputs and clarification** A Mission can require inputs that aren't known until run time: a region, a quarter, a metric choice, a date range. Kaiya handles these during execution in two ways: * **Parameterized inputs.** When a step needs an input the Mission expects, Kaiya asks for it at the point in execution where it's required (for example, *"Which region?"* or *"Which quarter?"*) and uses the answer to drive the rest of the run. * **Clarification when ambiguous.** When something is ambiguous, Kaiya asks a clarifying question instead of guessing, often with a dropdown of suggested options. The user can pick from the dropdown or type an answer directly in the thread. ### **6. Variable passing across steps** Steps in a Mission are connected. The output of one step becomes the input of the next. Each step that produces data names its result (for example, a SQL step that aggregates profit by state produces a named output such as `state_profit`), and the following step consumes that named output. This is why a Mission runs as a coherent workflow rather than a set of disconnected queries — a value derived early is available to every later step automatically, with no manual wiring. ### 7. Result generation Once the Kaiya Mission completes execution, visuals, summaries, and insights are presented back to the user. Responses appear conversational but are powered by structured backend analysis. * Charts and graphs (auto-generated) * Tabular data * Root cause explanations * Text summaries with recommendations * Drill-down links or options

Result generation

**Inline citations.** Numeric results carry inline citation markers that trace each figure back to the step that produced it. Hovering over a cited result reveals the dataframe and the query behind the number, so any figure can be traced to its source. ### 8. Post-execution actions * Ask follow-up questions in the same thread to go deeper. Kaiya answers in the context of the completed run without restarting the Mission * Share results or trigger a different Mission * Request variations or filtered views of the current output

Post-execution actions

# The art of the possible Explore real-world examples of Tellius agentic workflows across industries—showing how AI agents automate analysis, generate insights, and solve complex problems. Missions are intelligent, modular analytics processes composed of AI Agents that understand your questions and deliver insights without writing a single line of code. The **Steps** section in **Composer** lets you describe any workflow like the ones below in natural language. Our AI agents will do the rest: gather the relevant data, run the analysis, generate visuals, and surface insights. Each Mission becomes a living, reusable intelligence asset in your **Agent Library**, ready to trigger when you (or anyone in your team) asks the right question (as mentioned in the **Triggers** section). Below are real, industry-relevant examples showing what you can build—organized by use case domain. #### A worked example: state-wise profit A simple Mission shows the full arc from brief to result. 1. **Brief.** The author types *"state wise profit."* Kaiya generates a three-step plan. 2. **Step 1 (SQL).** Aggregates total profit, revenue, discount, and profit margin by state. 3. **Step 2 (Python).** Enriches the result with profit share, ranking, and performance classification (High / Mid / Low Performer). 4. **Step 3 (Summary).** Produces a structured business summary: an executive overview, ranked top and bottom states, performance tiers, and actionable recommendations, with every figure cited to its source step. The author runs the Mission once to validate the output, then publishes it. From then on, anyone with access runs the same analysis on demand, or receives it on a schedule. ### 💊 **Pharma & Life Sciences** #### Which payer plans are underperforming on TRx and why? Analyze payer plans underperforming on TRx, segment by access restrictions or HCP tiers, and suggest data-backed contract renegotiation points. #### Why is our new product launch lagging in key territories? Identify territories or HCPs (Health Care Professionals) where a new launch is lagging, then break down messaging gaps, rep engagement, or access barriers. #### What’s driving the recent drop in market share for Brand X? Investigate market share erosion by segment, uncover if it's driven by new competitors, loss of exclusivity, or formulary exclusion. #### Why is a high sampling rate not translating to scripts? Analyze sampling and TRx data together to pinpoint why high sample volume isn't translating into prescriptions, by HCP or specialty. ### 💰 **Finance & FP\&A** #### What’s causing the variance between actuals and forecast this quarter? Automatically compute and visualize variances by department or cost center and identify drivers like overspend in labor or marketing. #### Which teams or vendors are causing invoice delays? Track invoice approval SLAs, highlight vendors or departments causing delays, and suggest automation or escalation points. #### Why are our margins shrinking despite stable revenue? Break down decreasing margins by region or SKU and isolate root causes like price cuts, cost increases, or channel mix shifts. ### 🛒 **Retail & CPG** #### Which products should we discontinue to boost margin and reduce clutter? Identify underperforming SKUs with low margin and high cannibalization impact, and generate a shortlist for discontinuation. #### Did our last trade promotion actually drive incremental sales? Measure uplift from trade promotions by channel or retailer and highlight where discounting didn’t drive incremental sales. #### Why are we consistently facing out-of-stock issues for Product Y? Track and explain frequent stockouts at a product or store level, connecting issues to supplier lead times or DC inefficiencies. ### 💼 **Sales** #### Which reps are underperforming in high-potential territories? Match rep performance to territory opportunity, flag underperformers in high-potential areas, and suggest redeployment. #### Where are deals stalling in the pipeline and why? Identify pipeline leaks by stage, region, or deal owner and determine whether the issue is conversion, qualification, or velocity. #### Why did Region A miss their sales target this quarter? Analyze why certain reps or teams missed quota—whether due to low volume, high-value deal loss, or lack of activity. ### 🚚 **Operations & Supply Chain** #### Which warehouses or carriers are failing our delivery SLAs? Track late deliveries, segment by carrier or warehouse, and surface which combinations are failing SLA the most often. #### Where do we have excess inventory building up? Identify aging or excess inventory by category, link to misaligned demand forecasts, and quantify holding costs. #### Why are our supplier lead times increasing? Highlight vendors with increasing lead times, compare to historical norms, and recommend vendor evaluation or escalation. ### 🏦 **Banking & Insurance** #### What’s slowing down our claims approval process? Diagnose delays in claims processing by team or system bottlenecks (manual review, missing info etc.), and suggest routing or staffing optimizations. #### Which customer segments are showing high churn risk? Use attrition analytics to flag customer segments with high churn risk, identify shared behaviors, and suggest outreach. #### What’s behind the spike in fraudulent transactions this week? Break down recent fraud spike by transaction type, location, and device to find patterns and recommend rules. ### 🌐 **E-commerce & Digital Business** #### Why are customers abandoning carts before checkout? Analyze drop-offs by device, page load times, and payment method to pinpoint why customers abandon checkout. #### Why are return rates spiking for certain products? Break down return reasons by product, geography, or channel to find quality or sizing issues affecting profitability. #### Why did our latest email campaign underperform? Understand why open or click rates dropped—by send time, device, campaign type—and test alternatives. ### 🧑‍🤝‍🧑 **HR & People Analytics** #### Why are employees leaving our company in higher numbers? Segment leavers by department, tenure, and performance score to uncover common causes behind churn. #### Where are we losing candidates in the recruitment funnel? Track where candidates drop off in the hiring process and determine whether it's role fit, offer rejection, or slow feedback. #### Why are overtime costs rising in certain departments? Identify teams or locations where overtime is growing unsustainably, and highlight workload or staffing issues. # Best practices Learn best practices for designing agentic workflows—SQL-first logic, focused summaries, efficient Python use, bounded clarifications, and questions that guide intent. When customers define their own agentic workflows, a few structural rules make the runs faster, more reliable, and easier to audit. **1. Start with data, end with story**\ The first step in the workflow should be an SQL step that pulls the governed data at the right grain. The last step should always be a Summary step that turns the results into a narrative, shows the drivers, and adds recommendations. This pattern (SQL → … → Summary) is what the planner expects. **2. Put Python only where it’s needed**\ If the logic can be done in SQL, do it there. Use Python steps only for things SQL cannot handle easily — changepoints, contribution/variance with volume weighting, cohorts/retention, forecasting, clustering, domain Python functions, and so on. This reduces retry loops and improves latency. **3. Keep to one summary step**\ Each workflow should produce one, clear answer. Multiple summary steps can confuse the UI and the user. Collect all findings in the final summary. **4. Design for the 10,000-row envelope**\ Agentic runs currently fetch up to 10,000 rows per query. Build steps that aggregate early and avoid “give me everything” patterns. If more detail is needed, create a follow-up workflow for drilldown. **5. Clarification is bounded**\ If the workflow asks the user for inputs and they don’t answer within the allowed number of clarification turns, Kaiya will still run the workflow with what it has or with defaults. Tell users that this is expected, not an error. ### Ask specific, well-defined questions * **“Compare prescription performance between Q3 and Q4 2024 across top 5 districts”** tells Kaiya the period, the measure, and the slice. Weak questions are vague. * **“Analyze all prescription data”** has no time window, no intent, and no segment, so the plan will be broad. Good questions also include intent. * **“Identify top 3 underperforming regions in Q4 and recommend reallocation”** tells Kaiya to produce an action, not just a chart. Fo example, a weak question like **“Show me some charts”** gives no business outcome. ### Example workflows to model **Standard sales / cancellation deep dive**\ Pull the base series (e.g. weekly cancellation). Pull the same measure by region/product/channel. Run Python to rank contributors. Summarize what changed, where, and who drove it. Output is trends, ranked drivers, and 1–2 charts. **Custom forecasting**\ Load the registration/event data. Build the days-out framework. Calculate historical weights. Generate and backtest the forecast. Summarize with confidence bands and actions. This shows how to embed domain Python. **Risk assessment**\ Validate the material. Retrieve SOP. Calculate risk factors. Produce a risk report with mitigation guidance. This shows how to combine clarification + SQL + Python + summary. ### What you must do to trigger agentic runs * Turn on **Deep Insight** button before asking, otherwise Kaiya will answer in normal chat mode and won’t build a multi-step plan. * Make sure to use the trigger phrase the workflow was published with. * If the dataset is on a source that agentic / text-to-SQL doesn’t support in that environment, the data must be available on a supported source (e.g. Snowflake, Redshift, ClickHouse) for the workflow to execute end-to-end. ### **Authoring conversationally** When building a Mission through the conversational interface, a few habits produce better step plans: * **Lead with a complete brief.** Describe the analysis, the slice, and the deliverable in one go. Kaiya drafts a tighter plan from a full brief than from a vague one. * **Answer Kaiya's clarifying questions specifically.** When Kaiya asks about period defaults, metric units, or how many items to surface, give concrete answers. * **Run once before publishing.** Execute the Mission against sample inputs to validate the output, and refine any step that needs adjusting, before exposing it to other users. * **Declare runtime inputs rather than hard-coding.** If a value changes per run (region, quarter, segment), let it be an input the Mission asks for, rather than fixing it in the step. # Automated workflows Kaiya Agentic Insights turns one question into a multi-step analytical workflow, automating planning, execution, and business-ready explanations in a single run. Kaiya Agentic Insights (also called **Deep Insights** or **Agent Mode**) is the part of Kaiya that turns one real business question into a full, multi-step analytical run. Instead of returning a single chart or a single SQL answer, it reads the question, decides which steps are needed, runs those steps with the right agents (SQL, Python, summary), and then explains the result in business language. {% hint style="success" %} Once you turn on the **Deep Insights** button in Kaiya, it can do this in two ways: it can plan the workflow itself from the question, or it can follow a user-defined workflow that you have already published. {% endhint %} This is designed to remove the “20-question” loop common in chat analytics (ask → shallow answer → follow-up → shallow answer). With Agentic Insights, you ask once and Kaiya does the decomposition internally. # Deep Insight Deep Insights activates Agent Mode, turning Kaiya into an AI analyst that plans, executes, and explains multi-step analysis from a single business question. **Agent Mode** (activated by **Deep Insights**) turns Kaiya into an always-on AI Analyst that plans, executes, validates, and explains multi-step analysis from a single question. It combines the flexibility of agents with the consistency of workflows so you get 20× deeper insights and recommended next steps.
1. Go to Kaiya Conversational AI. 2. Click the **Deep Insights** button (left of the query bar). 3. Select your Business View from the dropdown. If you’re unsure about the required Business View, feel free to leave it at **“All Business Views”**. 4. Type your question and press Enter (or click on **Submit**). {% hint style="warning" %} From v6.1, you no longer need to manually click the **Deep Insight** button for applicable questions. Kaiya determines this on its own based on the complexity and nature of your query. {% endhint %} ### How Kaiya auto-routes your question (from v6.1) Once Kaiya understands your question (including any clarifications you have provided), it automatically determines the best execution path to generate your answer. This routing happens behind the scenes through an orchestration layer, so you do not need to manually select a mode or specify how Kaiya should process your query. Kaiya evaluates your question and the current conversation context, then routes it to one of the following execution paths: **SQL-only execution** is used when the question can be answered by querying your data tables directly (using filters, joins, aggregations, group-bys, and other standard SQL operations). Most common analytical questions (such as "What were total sales by region last quarter?" or "Show me the top 10 products by revenue") are routed through this path. **SQL + Python-style processing** is used when the question requires additional computation beyond what SQL can handle on its own. This includes statistical analysis, forecasting, clustering, custom business logic, advanced text handling, and more complex data transformations. For example, "What is the forecasted TRx for Product X over the next 6 months?" would be routed through this path because it requires a forecasting model in addition to the underlying data query. **Deep Insights mode** is used when the question calls for a multi-step, in-depth analytical exploration rather than a single query. Kaiya can now route to **Deep Insights** automatically when it detects that the question benefits from a structured plan of sub-analyses. {% hint style="success" %} This automatic routing means you can focus on asking questions naturally. Kaiya handles the decision of how to process each question, reducing the friction of switching between modes or guessing which approach will produce the best result. {% endhint %} ### Who is it for? * Business users who want answers that go beyond chat (timing, magnitude, why, and what to do next). * Analysts who need repeatable deep dives without manual orchestration. * Data teams that require governed, audited execution across SQL and Python. ### How Agent Mode works (at a glance) A simple loop, **Ask → Plan → Execute → Validate → Explain → Save,** turns complex questions into governed, multi-step analysis. A multi-agent planner picks **SQL** or **Python** per step, applies transparent checks (samples, joins, fiscal calendar), then returns a clear narrative with next steps. #### Plan * A multi-agent planner breaks the question into steps. * Chooses the right tools: SQL, Python, and visualization. * Applies sensible defaults and only asks brief clarifications when necessary. #### Execute * SQL: Runs warehouse-native work—joins, subqueries, dynamic formulas, nested aggregations. * Python: Handles methods SQL can’t. Changepoints, contribution/variance with volume weighting, sample-size checks, cohorts/retention, correlation/association, causal probes, forecasting with intervals, segmentation/clustering. #### Validate & Reflect * Checks whether each group has a big enough sample so results aren’t noisy. * Prevents bad joins that duplicate rows (fan-out/chasm traps). * Keeps the join at the correct grain so numbers add up. * Uses your fiscal calendar so results respect your business timeline. #### Explain * Delivers timing and magnitude, ranked drivers, and relevant charts/tables. * Includes concise recommended next steps. ### Example walk-through Consider this question:\ “**How did cancellation rate change week-over-week in Q3, and which regions/products/channels contributed most to the WoW delta?**”
**Step 0: Ask**\ You ask the question in plain English. If a detail is missing (e.g., fiscal vs. calendar weeks), Kaiya asks clarification once, then proceeds. **Step 1: Build the baseline**\ Kaiya pulls governed data at weekly grain for Q3, honoring row-level policies and your fiscal calendar. It computes the conversion rate series and applies obvious filters (e.g., exclude tests). Outputs are **audited** and preview-able so you can confirm scope. **Step 2: Create analysis slices**\ Kaiya enriches the baseline with **Region / Product / Channel** via governed joins. It generates only the slices relevant to the question to avoid fan-out and noise.\ Sample sufficiency and grain consistency checks ensure stability. **Step 3: Apply the best method**\ Based on intent (“why + drivers”), Kaiya runs variance/contribution analysis and changepoint detection; routes heavy work to SQL and advanced methods to Python. Guardrails enforce sensible defaults and minimum samples; confidence cues are added where possible. You get a ranked, interpretable driver table aligned to the question. **Step 4: Validate & reflect**\ Kaiya verifies enough data, correct join grain, no double counting, and correct week mapping. All defaults used are disclosed; if something looks off, it adjusts filters/grain/method and reruns the affected step. **Step 5: Explain & package**\ You receive a plain-English narrative with timing & magnitude of the drop, ranked drivers by region/product/channel, clear visuals, and recommended next steps (e.g., staffing fix, promo tweak). All assumptions, steps, and artifacts are disclosed for auditability; you can save this run as a reusable workflow. {% hint style="danger" %} Supported data sources for **Agent Mode** and **Text-to-SQL**: Snowflake, Redshift, ClickHouse. Spark is not yet supported. Please migrate critical datasets to a supported warehouse for these features. {% endhint %} # Understanding Kaiya Agent Mode Kaiya Agent Mode automatically plans, executes, and summarizes multi-step analysis using SQL, Python, and custom workflows, delivering fast, executive-ready insights. ### What it can do * **Dynamic analytical planning –** Kaiya reads the user’s question, determines which datasets and time windows are relevant, and then builds a step-by-step analysis plan on its own. The plan can include multiple SQL pulls (baseline plus breakdowns), optional Python analysis, and a final summary step. The user does not have to create this flow beforehand — Kaiya assembles it from the question.
* **Multi-agent orchestration –** The steps in that plan are executed by different specialized agents, but all against the same plan. SQL agents fetch and aggregate governed data from the source. Python agents run methods that are not practical in SQL, such as changepoint detection, contribution/variance with volume weighting, cohort/retention, or forecasting. The summary agent then turns those results into a human-readable narrative with visuals.
* **Clarification when needed –** Targeted to the missing field. Kaiya will stop briefly only when a required input is missing from the question or workflow. For example, if a step says “analyze risk for material,” and no material was provided, it will ask for the material name and then proceed.
* **Error handling and retries –** When a generated SQL or Python step fails during execution, Kaiya does not end the run immediately. It tries to correct the generated code or query and re-executes the step. This allows multi-step analyses to complete even when one generated step was not perfect on the first attempt.
* **Executive-ready output –** Final response can contain structured results: a short takeaway, tables, 1–4 visuals depending on the analysis depth, a ranked list of drivers, and recommended next steps. For executive-style questions, it can limit itself to 1–2 charts and a condensed summary. {% hint style="success" %} **Custom (user-defined) workflows** – This let you tell Kaiya exactly how to analyze something, step by step. If your team already has a proven sequence. For example, “pull event data → build days-out framework → run forecast → validate → summarize” — you can write those steps once and save them. When a user asks a question that contains the trigger word or phrase you attached to that workflow, Kaiya will execute your saved steps in that order instead of generating a new plan. This is useful for repeatable, domain-specific work where you want the AI to run the analysis, not design it. {% endhint %} ### A glimpse into the architecture Agentic Insights uses a multi-agent pipeline. Every run goes through these logical pieces: **Contextualizer**\ This is the first layer that reads the user’s natural-language question. It decides whether the question should go through the **Agent Mode** (Kaiya’s automated planning path) or whether it matches (or should trigger) a saved, user-defined workflow. **Planner**\ Used for questions that Kaiya plans and executes automatically. It takes the routed query and turns it into an ordered, executable plan. The plan typically has data-gathering steps (SQL), optional analysis steps (Python), and a final summarization step. **Workflow Planner**\ Used when the user has already defined the analysis steps. It loads those steps, detects if any step needs a user input (like material, date range, region), asks for those values up to the allowed limit, and then executes the workflow exactly as written. **SQL Executor**\ This component generates SQL that is valid for the connected datasource and runs it through the governed query layer. It is responsible for pulling the right data at the right grain, honoring security, policies, and calendars. **Python Executor**\ This runs analysis that cannot be done well in SQL. That includes changepoint detection, contribution or variance with volume weighting and sample-size checks, segmentation or clustering, forecasting with intervals, and basic causal or association probes. It operates on the data returned by the SQL steps. **Summary Agent**\ This is the last step. It reads the outputs from SQL and Python and turns them into a human-readable answer. It can produce a narrative, highlight timing and magnitude, list ranked drivers, add recommendations, and include the charts generated in the run. ### Standard query flow * You start with a plain-language question. * The contextualizer looks at that question and decides which planning path fits best. * The planner then breaks the question into executable steps (usually one or more SQL pulls, optional Python for deeper logic, and a summary step). * The SQL agent fetches governed data, the Python agent applies advanced methods if the plan called for them, and finally the summary agent assembles the findings into a clear narrative with visuals. * Finally, you get one complete, end-to-end answer. ### Custom workflow flow * Here, your question matches a trigger phrase from a published workflow. * The **Workflow Planner** loads that workflow and checks whether any step needs user input. * If something is missing, it asks for it, but only up to the configured clarification limit. * After that, it runs exactly the steps defined in the workflow (in the order you wrote them) using SQL, Python, and summary agents. {% hint style="success" %} Executive summary flow
* If the question asks for an “executive summary,” Kaiya still performs the full analysis in the background so the numbers are correct, but the final response is shortened. * It uses business-level wording, highlights the key metrics and drivers, and shows at most one or two charts to keep the answer presentation-ready. {% endhint %} ### How Kaiya gathers requirements for the workflow? **Dynamic parameter detection:** Our workflow engine actually reads the text of each step and looks for inputs that the user has not supplied yet. If a step is written as “ask material name for risk analysis,” it will mark “material name” as mandatory and pause the workflow to collect it before moving on. **Follow-up question management** controls how persistent Kaiya is. It will only ask for inputs that are missing or critical to run the next step, and it will do this only up to the configured limit. If the user does not provide everything within that limit, the workflow does not fail; it proceeds with available or safe values so the user still gets a reliable result. **Default values** give admins or workflow authors a way to pre-fill common fields. A workflow step can say *“If no period is given, use last 12 months”*, and Kaiya will apply the same. In some cases, Kaiya can also infer from the data what a reasonable default is. The user can still override what was prefilled. **Visualization rules** describe how much output the summary agent should create. Executive-style questions get a short answer with 1–2 charts so the result is easy to read. Standard analyses can return 2–4 visuals. If a chart cannot be rendered for that step, Kaiya will return a text description of the same insight. **Custom functions** allow you to plug in your own Python logic and let the agentic flow call it like any other step. This is useful for things like event forecasting, RFM segmentation, or time-series decomposition that you have already coded. The output from that function is then included in the final summary. # What type of questions you can ask Kaiya? These are all in the shape Kaiya Agent Mode expects: compound, multi-metric, multi-dimension, sometimes cross-table (Orders ↔ Products ↔ Channels), and they lead naturally to a plan of SQL → Python → summary. #### 1. Variance & contribution (what moved, when, who drove it) * “How did Cancellation Rate change WoW in Q3, and which regions/products/channels explained the delta?” * “From 2025-07 to 2025-08, break down the +1.8pp cancellation increase by Customer Segment and Marketing Program; flag low-volume segments.” #### 2. Cohorts & retention (who sticks, who churns, why) * “By Tenure (months) cohorts, how does sensitivity to Delivery Lead Time change over time?” * “For customers acquired via Paid Search in H1, what % reordered in 30/60/90 days vs. Organic?” #### 3. Anomaly detection (spikes, dips, outliers) * “Detect weeks in Q3 where cancellations spiked >2σ above trend and show the drivers.” * “Which 10 stores had abnormal return rates in Sept vs their own 3-month baseline?” #### 4. Correlation & association (what moves together vs. noise) * “Are pre-payment orders less correlated with cancellations than pay-on-delivery, controlling for channel?” * “Which factors are most associated with high cancellation — Delivery Lead Time, Reschedule Count, Age Group, or Income Bracket?” #### 5. Causal probes (is X likely driving Y?) * “Using weather-delayed orders as an instrument, what’s the IV estimate of lead time on cancellations?” * “Did the 10% shipping-fee increase cause the rise in cart abandons for Mobile users?” #### 6. Forecasts with intervals (what’s next, with confidence) * “Forecast weekly cancellations for Q4 by channel with 80/95% bands; highlight channels above band.” * “Project new-patient starts for NeuroDrug-X by payer segment for the next 6 weeks, using FY24 access shifts.” #### 7. Segmentation & clustering (meaningful groups) * “Cluster branches on cancellation rate, lead time, reschedule count, and product mix; profile each cluster.” * “Group customers by purchase frequency, discount sensitivity, and channel mix; label ‘high-risk churn’ segment.” #### 8. Benchmarking & cohorts (this group vs. peers) * “Rank channels by total cancellations with confidence bands; surface top-10 outliers vs. target.” * “Compare West vs. All Regions for Q3 delivery SLAs — gaps, variance, and top offending SKUs.” #### 9. What-if scenarios (change inputs, see outcome) * “If average delivery lead time drops from 5 → 3 days for Marketplace orders, what’s the expected % drop in cancellations?” * “What happens to Q4 revenue if we cap cancellations at 2% for Premium segment but leave others unchanged?” # Glossary Comprehensive glossary of Kaiya AI Agents—covering validation, data prep, visualization, insights, summaries, and agentic workflows in Tellius. ## **AI Agents** Native, prebuilt analytical agents in Tellius designed to perform targeted tasks across the data-to-insight journey. These smart agents are reusable components that handle tasks like planning, data preparation, visualization, insight generation, and more. They are pre-trained and require no code to use. Each agent is optimized for a specific analytical function, and multiple agents can be combined to build **Agentic Flows**. #### **Validation Agent** This agent ensures the quality, safety, and feasibility of every query before it runs. It performs: * Structural validation of the input * Verification of user intent * Data availability checks * Permission enforcement By catching issues early, the Validation Agent prevents invalid or unauthorized actions and ensures the workflow is built on reliable, clean foundations. #### **Planner Agent** The strategic coordinator of the workflow. When a user inputs a question or request, this agent: * Understands the task * Breaks it down into subtasks * Maps each task to the appropriate AI agent * Arranges the order of execution #### **Data Prep Agent** This agent handles data readiness. It automates tasks like: * Selecting relevant datasets * Applying filters and joins * Loading Business Views * Preparing structured inputs for downstream agents It eliminates manual effort and ensures that each subsequent step in the workflow operates on clean, correct data. **Visualization Agent** This agent transforms data into visuals by: * Choosing the most appropriate visual format (charts, graphs, tables) * Generating visuals automatically based on context * Highlighting key trends and outliers visually It helps users grasp complex data patterns at a glance without building visuals manually. **Insights Agent** A powerful analytical engine that dives deep into the data to: * Detect patterns, trends, and anomalies * Surface root causes and "why" explanations * Deliver contextual, multi-dimensional insights This agent adds depth to dashboards by moving beyond surface-level metrics. **Summary Agent** This agent takes complex data and insights and converts them into plain-language summaries. It: * Extracts key takeaways * Generates concise narratives * Communicates the essence of analytical outputs quickly Perfect for executive reporting or users who want the “story” behind the data without reading through charts or tables. **Knowledge Graph Agent** A relationship-mapping agent that: * Connects entities (e.g., products, customers, geographies) * Identifies hidden relationships and correlations * Powers smarter, context-aware recommendations It enriches analysis by adding a layer of intelligence that understands the relationships behind data points. ## **Agentic Flow** *(also called: Agentic Workflow)* A complete, executable workflow composed of one or more AI Agents working together to perform a multi-step analytical task. Agentic Flows can automate: * Data validation * Data preparation * Visualization * Insight extraction * Narrative summarization Agentic workflow steps can be defined using natural language, and the appropriate agents are orchestrated automatically. These flows are created in **Composer**, and can be saved, reused, and shared via the **Agent Library**. ## **Agent Library** A centralized workspace that stores and manages all user-defined **Agentic Flows** across the organization. It contains two sections: * **Published Agents**: These are fully configured, ready-to-use workflows available for execution. * **Draft Agents**: These are in-progress flows being built in Composer, not yet finalized or published. Agentic flows can be edited, deleted, or duplicated from **Agent Library.**

Agent Library

## **Composer** A no-code development studio where you can create **Agentic Flows** using simple instructions in natural language. It enables business users, analysts, and data teams to build intelligent workflows without programming. Composer includes: * **Name and Description**: Start by naming the workflow and briefly describing its purpose. * **Data Source**: Connect and configure the data to be used in the workflow. * **Steps**: Each step is a natural language instruction that activates a specific agent. * **Triggers**: Define the phrases or questions that will initiate the flow. Triggers are customizable and flexible—you can set multiple variations to capture different ways you might phrase the same request. Example: For "Products to discontinue", you can set the variations "*Which products should we stop selling?*", "*Drop candidates?*", "*Low-performing SKUs?*". ## Deep Insight The **Deep Insight** button tells Kaiya to run in agentic mode (both user-defined and automated workflows). When it is on, Kaiya does multi-step planning (SQL → optional Python → summary), applies guardrails (row-level policies, fiscal calendars, join-grain checks), and returns timing, magnitude, ranked drivers, visuals, and next steps.
# Kaiya conversational AI Explore data with Kaiya, the conversational AI in Tellius that answers natural-language queries, learns from feedback, and delivers instant insights. Welcome to Kaiya, your AI-powered conversational analytics assistant! Kaiya is transforming the way you search, explore, and analyze your data by making it as simple as having a conversation. Kaiya empowers everyone, from data experts to business users, to uncover insights and make data-driven decisions. With Kaiya, you can: * Explore your data just by typing or speaking your queries in plain language. * Receive AI-powered analytical results in seconds. * Quickly access key metrics, trends, and anomalies without the need for technical expertise. * Kaiya remembers your preferences, learns from your feedback, and adapts to your habits, ensuring a more personalized experience over time. * Apply filters and summarize the results as required. This guide will show you how to use Kaiya seamlessly, maximize its capabilities, and adopt best practices to help you get the most out of Kaiya. The more you use Kaiya, the smarter it becomes—learning from your preferences, patterns, and feedback to deliver insights tailored just for you. Let’s dive in and explore how conversational search is revolutionizing the way we interact with data! ### **Get started with Kaiya** Click on the Kaiya icon in the left pane. The following screen will be displayed to you.

Kaiya conversational Search

1. **Greetings:** Kaiya greets you to start using its conversational Search! Start to type your question in #3 or choose from the curated list of queries in #5. 2. **Business View selection:** Choose the relevant Business View (BV) from the list of all available BVs. 3. **Search box:** Start typing your question in natural language here and click on the arrow button in the bottom right or press **Enter** to execute your query. 4. **Voice command:** Alternatively, you can click the microphone button and start speaking your query. Once done, you can click on the microphone button again to indicate query completion. 5. **Popular queries:** Here, you can find the curated list of queries to kickstart your Kaiya conversational journey. Click on the required query and the same will be populated in the search box. 6. **Show popular queries:**
1. Click on the **“Show popular queries”** button and the **Queries Library** will be displayed. 2. Select the required Business View (BV) to view the queries associated to that specific BV. Search and sort (by new or old queries), if required. 3. Click on the required query and the same will be populated in the the search box. 4. Hover over any query to view the three-dot menu where you can edit or delete a query. 5. Under **Add query**, choose the relevant Business View, type the query to be added to the Queries Library, and click on **Add Query**. 6. Alternatively, you can ask Kaiya to generate relevant starter questions for you. Click on the wand icon in the far right corner and a question related to the BV will be generated. 7. Click on **Preview** button to preview the results of the query in the adjacent tab. Click on **Add Query** to add the query to the library. 7. **Previous chats:**

Previous Chats

a. Select a conversation to view the thread. Hover over any conversation to view the three-dot menu where you can rename, share or delete the required conversation.

Rename, share, or delete a conversation

b. Click on the **Previous chats** icon to view the history of conversations. Search, sort, or apply filter to view all the chats, your chats, or the ones shared with you. 8. **New chat:** Click on **New chat** to create a new conversation. 9. Once a query is executed and the results are displayed, you can find details of the analysis (columns, Business View, and the number of rows analyzed along with the time taken to execute the query) under **Search Inspector**. You can also **thumbs up/thumbs down** the analysis as preferred.

Search Inspector

10. **Business View:** The list of all available Business Views are displayed here. # Working with Kaiya ### Non auto-BV mode 1. Under **Settings → Advanced → Kaiya → Kaiya Conversation**, make sure the toggle **"Auto-select Business View"** is disabled for non auto-BV mode. 2. Choose the required Business View from the dropdown and start typing your query. Alternatively, you can choose from the initial set of queries provided below the search box. 3. Kaiya will work its magic. Depending on the input question, you will find the step-by-step process getting loaded. Most often, you can find these four steps: 1. Identifying the intent and relevant data 2. Enhancing context for deeper understanding 3. Interpreting with AI 4. Processing data to deliver analytical results 4. After the process gets completed, the results will be displayed. 5. The analysis of the resulting chart can be found in the **Search Inspector**. If you have multiple charts in a conversation, select the required chart to view the respective analysis. 6. Under **Business View**, you can find all the columns in the selected BV. {% hint style="danger" %} In the non auto-BV mode, the Business View selected at the start of a conversation remains locked for the entire session. Every follow-up question is answered against that same BV. {% endhint %} ### Auto-BV mode (dynamic) If you're unsure which Business View (BV) to select, Kaiya can automatically identify and select the most relevant one for you. Simply start typing your query, and Kaiya will ensure the appropriate BV is applied. To enable the auto-Business View mode, 1. Under **Settings → Advanced → Kaiya → Kaiya Conversation**, enable the toggle **"Auto-select Business View".** 2. Navigate back to **Kaiya** tab and start typing your query without having to select the Business View first. 3. The following step will be displayed as one of the execution steps.

Kaiya auto-selecting the BV

4. Kaiya will go through your query and auto-select the relevant Business View for you. 5. The results will be displayed. You can find **"Business View was auto-picked by Tellius Kaiya"** near the selected BV.

Auto-select BV by Kaiya

#### Dynamic selection of Business View In the fully dynamic auto BV mode, Kaiya evaluates the most relevant Business View for each question independently, at query time. If you start by asking about promotional lift (which routes to a *Promotions BV*) and then ask about inventory availability (which lives in a *Supply Chain BV*), Kaiya switches automatically. You do not need to start a new conversation or manually reselect.
**How BV selection works at query time** * When you submit a question, Kaiya's Planner agent reads a structured summary of all available Business Views across the instance, including their domains, key metrics, and example questions. * It narrows the candidates and selects the optimal one to generate the analysis plan. * Kaiya is aware whenever a BV or workspace is created or updated, so newly published Business Views become available for auto-selection immediately. **Context carryover across BV switches** When you switch to a different Business View mid-conversation, the following context elements carry forward from prior turns: * Active dimension filters (for example, region = Southeast, product = Laundry) * Time period selections * Metric references established in earlier questions * Entity clarifications (for example, how "market" was defined earlier in the conversation) Kaiya maps these elements to the schema of the new BV. Where a dimension or metric has a direct equivalent in the new BV, it is applied automatically. Where there is no match, Kaiya surfaces the gap and asks for clarification. {% hint style="warning" %} When two or three Business Views are equally strong candidates for a given question, Kaiya presents a multiple-choice question listing the matching BVs and asks which one you want to use. You select your preferred BV from the options, and Kaiya proceeds with that selection. This only occurs when there is genuine ambiguity between contenders; if one BV is clearly the strongest match, Kaiya picks it on its own. {% endhint %}
### Ask Kaiya about your Business View Kaiya answers natural language questions about metadata—such as measures, dimensions, calculated columns, and date fields—so that you can quickly uncover key details about your Business View (BV) without technical expertise. Whether you're a business user trying to understand data relevance before diving into analysis or an analyst seeking granular technical details, Kaiya bridges the gap between technical metadata and business context. Metadata queries accelerate data discovery, empowers non-technical users, and reduces the back-and-forth between teams. You can ask questions about the structure and content of your dataset (BV) to: * Discover available columns (measures, dimensions, date fields, and calculated columns). * Understand calculated column formulas and their purpose. * Identify fields related to a specific concept or KPI. * Bridge the gap between technical metadata (e.g., field definitions) and business relevance. #### **What type of questions you can ask Kaiya about your Business View** Navigate to the Kaiya conversational search bar in the Tellius interface. Select or activate the Business View (BV) you want to explore. Use natural language to ask Kaiya questions about the metadata. **1. Different types of available columns** ***"What are the measures and dimensions available in this BV?"*** Kaiya provides a structured table listing the columns in the BV, categorized as measures and dimensions.

Displaying columns in the BV

***"What date fields are available in this BV?"*** Kaiya displays a table listing all calculated columns along with their descriptions.

Displaying date fields

***"What are the calculated columns available in this BV?"*** Kaiya displays a table listing all calculated columns along with their descriptions and types (e.g., Measure or Dimension).

Displaying calculated columns

**2. Columns related to a specific concept or KPI** ***"Show me the columns related to sales in this BV".***

Displaying columns related to sales

For Kaiya responses, check out [this](/kaiya/kaiya-conversational-ai/kaiya-responses) page. # Kaiya responses All about working with the responses generated by Kaiya ### Resulting chart

Example of a resulting chart

1. Click on the **View Data** toggle button to view the underlying table data of the chart. Alternatively, you can click on the three-dot submenu of a chart and select **Detailed view**. 2. Click on **Add to Vizpad** to add the chart to an existing or a new Vizpad. You can select from the list of available Vizpads displayed. 3. Click on **Switch Chart** to switch the chart to a different type. The list of applicable chart types will be displayed and you can select the required chart type. For more details, check out [this section](/search/know-your-charts-in-tellius/switching-to-another-chart). 4. Click on **Filter** to apply filters to the chart.

Applying filters to a chart

5. Click on **Download** and select the required format in which you want the chart to be downloaded.

Download format

6. If you’re satisfied with the result, click on the **thumbs-up** button. It will be saved and your preferences will be saved for future queries. 7. If you’re not satisfied, click on the **thumbs-down** button. To remediate the results, click on **Fix it**. If you don’t want to resolve the issue, but only want to provide feedback, click on **Give feedback**. {% hint style="warning" %} The thumbs up/thumbs down feedback is available only in a live conversation and not in history. If the thumbs up or thumbs down is once clicked for a chart, it cannot be changed. {% endhint %} ### Copy and Export Kaiya results In addition to the existing download option, Kaiya provides flexible copy and export actions across all response types (text, charts, and tables) so you can reuse and share results without rework or screenshots.
**Copy to clipboard (per element):** You can copy individual elements from any Kaiya response directly to your clipboard. Text responses are copied as plain text, ready to paste into documents, emails, or chat messages. Charts and tables are copied as PNG images. This lets you grab exactly the piece of the response you need without exporting the entire result. **Export (per element):** Individual charts can be exported as .png, .jpg, .pdf, or .csv files. Individual tables can be exported as .csv or Excel files. This lets you move data directly into spreadsheets or reporting tools. **Export Result as Doc:** For complete sharing, Kaiya supports exporting the full result of a conversation response as a single editable Word document (.docx). The exported document contains all text, charts, and tables from the result, formatted with a clean, consistent layout. This is designed for turning Kaiya's analytical output into stakeholder-ready artifacts (reports, decks, and briefs) without manually stitching together multiple screenshots or exports. ### Reflection-based auto verification Kaiya is designed to get you to a usable answer as quickly as possible. When you ask a question, Kaiya begins executing the analysis and renders the first usable output (typically a data table) as soon as it is ready, even while it continues working on the remaining steps in the background (such as chart generation, formatting, and reflection-based validation). As soon as the initial table appears, you can begin validating the direction of the answer, checking whether the right columns and filters were applied, or deciding on your next follow-up question.
* After Kaiya generates its initial results, a Reflection agent automatically reviews whether the output actually matches what you asked for. * The Reflection agent checks for issues such as incorrect grain (the level of detail in the results does not match what was asked), missing constraints or filters that should have been applied based on your question, and partial coverage where only part of a multi-part question was addressed. * If the Reflection agent identifies a mismatch, Kaiya adjusts the execution plan and re-runs the query or the specific step that produced the incorrect output. The final result you see reflects the corrected analysis. For straightforward queries, reflection typically confirms the result is correct without any delay. For more nuanced questions (such as those involving multiple metrics, time comparisons, or conditional logic) reflection acts as a safety net that significantly improves first-attempt accuracy. ### Ask Kaiya to summarize conversations Kaiya can generate a summary of the entire conversation thread on demand. This is designed to consolidate context across a long, multi-step exploration into a single, clean narrative that you can share or use as a reference. **How to ask Kaiya to summarize?** At any point during a conversation, type a prompt like "Summarize the entire conversation" or "Summarize what we learned and list the top drivers." Kaiya will process the full thread and generate a consolidated summary. **What does the summary include?** The summary incorporates relevant context from across the entire conversation, including results from **Deep Insights**, direct analytical queries, earlier summaries generated within the thread, and metadata queries. Kaiya synthesizes these into a single coherent narrative. {% hint style="info" %} This capability is most valuable at the end of a long investigative session where you have explored multiple angles, drilled into different segments, and generated several charts and tables. {% endhint %} The resulting summary can be copied or exported (using the copy/export capabilities described in [this](#copy-and-export-kaiya-results) section) and shared directly with stakeholders. ### Preamble Kaiya includes a **Preamble,** a short, insightful explanation that appears before each response. This section breaks down exactly how your question was understood and how the answer was derived. It helps you build trust, learn the logic behind the response, and verify that Kaiya correctly interpreted your intent.

Preamble

It walks you through how Kaiya: * Interprets your query * Identifies key metrics, dimensions, and filters * Selects the most relevant dataset * Analyses and applies logic * Validation & finalization See exactly how data fields, filters, and groupings were mapped to your question. If you notice a mismatch in what was interpreted, adjust or rephrase your question. With this preamble-first approach, Kaiya doesn’t just give you an answer—it helps you understand the reasoning behind it. This makes your analysis more reliable, traceable, and smarter with every question. ### Clarification questions Kaiya is designed to get you the most accurate answers by making sure it understands your question correctly. Sometimes, the way you phrase a question might include words that could mean different things depending on context. In those cases, Kaiya will pause and ask you a clarification question before proceeding with the analysis.

Kaiya asking a clarification question

A clarification question is a smart prompt that Kaiya shows when your original question could be interpreted in multiple ways. For example, if you say: *“Show me sales by product and cost”* Cost could mean *“average cost”, “total cost”* etc. Kaiya might ask: *“Just to clarify, did you mean to see ‘sales’ by ‘product id’ and ‘average cost’?”* This ensures that Kaiya understands exactly what you’re looking for, before it selects columns, generates charts, or calculates results. #### When Kaiya asks * **Filters or dimensions are unclear.** *"Compare performance"* without specifying by-region, by-product, or by-period. * **Aggregations or metrics are ambiguous.** *"Show me growth"* could mean period-over-period, a trend, or a rate. * **Column names or values need confirmation.** When multiple columns could match what you asked for. #### How to respond When Kaiya asks a clarifying question, you have three options: * **Pick from the options shown**, or supply the missing detail directly (for example, *"compare by region,"* *"use the revenue column"*). * **Refine your question** to add context. * **Ask a new question** to change direction entirely; Kaiya starts fresh. After you respond, Kaiya runs the analysis with the disambiguated parameters and returns the result the same way as a direct question. {% hint style="info" %} Saved memories reduce future clarifications. When you respond to a clarification, Kaiya can offer to remember your choice as a Preference memory. The next time the same ambiguity comes up, Kaiya applies your saved preference automatically without asking. {% endhint %} Once you respond to the clarification prompt, Kaiya updates your request using the confirmed terms. This promotes transparency, improves trust, and helps you get more meaningful results from your data conversations. # Triggering Insights with "Why" questions Kaiya converts natural-language “why” questions into automated Insights—configuring comparisons, selecting metrics, and surfacing key change drivers instantly. Kaiya supports automated insight generation via natural language "why" questions (e.g., “Why has revenue changed?”). When such a question is asked, Kaiya internally triggers the **Insights Agent**, configures a comparative analysis, and populates insight settings automatically—without requiring manual setup or pre-configuration in Composer. This feature eliminates the need to navigate menus, select filters, or define calculations manually, while still allowing full control for advanced overrides. ### 1. Ask a "Why" question After selecting the required Business View, ask a natural question starting with "Why". They are auto-routed to the Insights Agent. Below are a few examples: * *“Why has the revenue dropped?”* - Identifies top declining segments between two time periods * *“What’s driving the increase in costs between this quarter and last quarter?”* - Compares cost increments and finds driving categories * *“Why did market share shift for Product X?”* - Surfaces contributors (e.g., region, size, channel) to share change ### 2. Kaiya requests key Insight parameters If required inputs (like time ranges or target metrics) are missing, Kaiya will prompt you to provide: * Previous time range * Current time range * Target measure (e.g., Sales, Revenue, Profit)

Kaiya prompting for key parameters

### 3. Automatic Insight Configuration Once relevant input is received, Kaiya auto-configures the analysis: * **Measure**: The target measure mapped from your question (e.g., `Sales → SUM(Sales)`) * **Date Column**: Auto-identified based on your question/additional input * **Time Periods to Compare**: Selects the time period explicitly mentioned in your query (e.g., “this month vs last month”) * **Features (Dimensions)**: A broad set of dimensions (e.g., Region, SubCategory, Segment, Manufacturer, etc.) is pre-selected for analysis. Kaiya uses internal heuristics and metadata tags to select appropriate columns automatically. All the above configurations are visible before execution. You can change the measure, adjust the time ranges, include/exclude specific columns, or even change the Business View if needed. ### 4. Click on “Generate Insight” Once the setup is confirmed, click on the **“Generate Insight”** button. The Insights Agent runs a comparative analysis across the selected features. The output will highlight: * Key contributors to the change * Root cause drivers (e.g., which regions or segments changed most) * Summaries and structured explanations

Insights auto-configured

{% hint style="warning" %} Make sure to use column names and time period (if required) in your query. If prompted for details, provide comma-separated inputs like: *last month, this month, profit* {% endhint %} ### 5. Insight Results Once you've reviewed the pre-filled configuration and clicked **Generate Insight**, Kaiya will begin computing the analysis in the background using the **Insights Agent**. Kaiya offloads the analytical workload and starts processing the Insight asynchronously, which can be tracked in the **Notifications** page. A small banner appears in the top-right corner of the screen confirming that the insight is being generated. Once the insight is ready, the following banner updates to inform you that Insights have been generated.

After the Insights are generated

Once generated, the insights are automatically displayed inline—right in your current conversation thread. The results include key contributors broken down by relevant dimensions (e.g., Region, Product, Segment) and narrative summary.

Insights results generated in Kaiya

### 6. Navigation to the Insights page Alongside the result, you can find the **“Open Insight”** button which navigates you to the dedicated Insight page, where you can: * Interact with the breakdown * Apply additional filters * Export or share the results * Compare across more granular segments

Dedicated Insights results

This ensures actionable, automated analytics with minimal configuration effort—but retain full control to explore deeper if needed. # Mastering Kaiya conversational AI Master Kaiya’s conversational AI—supporting natural-language queries, context retention, comparisons, filters, trends, and automated Insights for advanced analytics. Kaiya AI Agents are a fully orchestrated analytics engine, where you can use natural language to automate everything from simple metrics to advanced diagnostics. With Kaiya AI agents, you can: * Move from simple metrics to root cause insights in a single flow. * Leverage AI orchestration to avoid manual report building, SQL writing, or dashboard tweaking. * Handle complex logic—filters, groupings, comparisons—without needing technical expertise. * Trust Kaiya to guide you, even when queries aren’t perfect. {% hint style="success" %} Under the hood, Kaiya parses questions into roles—**Measure**, **Filters**, **Grouping**, **Time**, **Limit/Sort**—and supports common aggregations (sum, avg, min, max, count/uniqueCount, median, market share) and time grains (yearly, quarterly, monthly, weekly, daily, hourly). {% endhint %} ## 1. **Live data access vs. Optimized historical queries** Kaiya dynamically selects data sources based on your query's time context. * **Live data queries**\ When you ask for recent periods (*"Show me TRx for this month"*), the Data Prep Agent pulls from live, constantly updated datasets. This ensures you're making decisions on the most current information. * **Historical queries**\ If you're analyzing past periods (*"Show TRx for 2022"*), Kaiya automatically optimizes performance by querying cached datasets or archives, reducing load times without compromising accuracy. * **Smart de-duplication**\ For domains like pharma sales where duplicate transactions exist, queries like *"Show TRx for Ioxalin in April 2024"* trigger deduplication logic within the Data Prep Agent—no manual cleaning required. ## 2. **Conversational context: Follow-up intelligence** Unlike static BI tools, Kaiya retains session context across your queries and adapts query structure without requiring you to restate parameters. If you ask, *"Show TRx for March 2024",* and follow up with *"How about last month?",* Kaiya understands that "*last month*" refers to **February 2024**, applies previous filters (e.g., product, region), and re-runs the query. Other follow-up capabilities: * *"What about by product?"*\ Kaiya understands that you now want to see the previous metric broken down by product. It automatically restructures the query to group the results by the "Product" dimension. * *"Show it weekly instead"*\ Kaiya switches your data view to show weekly trends, keeping your previous selections (like product, region, or date range) intact. ## 3. **Advanced time handling** Kaiya’s date/time parsing engine allows you to express time filters naturally: * *"Show TRx after November 2023"*\ Kaiya understands that you're asking for all TRx (Total Prescriptions) and applies a date filter to include only records starting from December 1, 2023, onward. * *"Monthly TRx for PillABC"*\ Kaiya organizes the TRx numbers for PillABC into a month-by-month breakdown, so you can easily see how prescriptions change over time. * *"For 'March 2024'"*\ When you use quotes like "March 2024", Kaiya treats it as a specific, fixed time period. Kaiya also intuitively understands relative timeframes: *"Last quarter"*, *"Past 6 months"*, *"Year-to-date"* ## 4. **Dynamic filtering across values, lists, and substrings** Kaiya automatically applies the right filters based on how you describe them—whether it's a single value, multiple options, or partial matches. * **Single filters**:\ *"Show TRx for Virginia"* → Applies exact match filters. * **Multi-value filters**:\ *"Show TRx for Virginia and California"* → Builds compound filters with proper logical operators. * **Substring matching**:\ *"Indication contains OTH"* → Translates to LIKE/CONTAINS logic in the backend. * **Logical combinations**:\ *"TRx for dermatology in NY OR NJ"* → Correctly applies AND/OR logic, respecting precedence. ## 5. **Group by and Aggregation** You can organize and analyze complex datasets by simply describing how you want to break down your data. Kaiya supports SUM, AVG, MIN, MAX, Top N / Bottom N, and nested groupings without explicit instructions. * *"Show TRx by region and product"*\ Kaiya automatically applies multi-level grouping, summarizing Total Prescriptions first by region, then by product within each region—exactly like you'd build a nested pivot table, but without manual setup. * *"TRx by all ecosystems"*\ Kaiya interprets the word **"all"** intelligently, expanding your request to group data across every relevant dimension (e.g., region, segment, product category), without needing you to list them explicitly. * *"Top 5 HCPs by Units"*\ This triggers both an aggregation (summing Units) and a ranking function, returning the highest performers. ## 6. **Comparisons made effortless** Kaiya handles aligning datasets, managing time frames, visualizing side-by-side comparisons. With simple phrasing, you trigger complex comparative analysis: * *"Compare NRx between Decile 7-8 vs 9-10"*\ Kaiya understands you're asking for a side-by-side comparison of two HCP segments (Deciles 7-8 vs. 9-10), and it automatically filters, groups to calculate the differences between these segments * *"TRx in Q1 2024 vs Q1 2023"*\ This triggers a period-over-period comparison, where Kaiya calculates both the absolute change and the percentage change in Total Prescriptions between the two quarters. * *"Marketshare of ProductK vs ProductL in CA"*\ Here, Kaiya recognizes you're asking for a product vs. product comparison within a specific region. It retrieves the market share data for both products and presents them in a comparative format. {% hint style="info" %} When asking about **trends**, explicitly mention the resolution (e.g., monthly, quarterly). For **market share** questions, mention the comparison scope (for example, “Market share of Brand A vs Brand B in California”). {% endhint %} ## 7. **Growth and trend calculations** You don’t need to specify formulas for growth. Kaiya can distinguish between point-in-time comparisons, continuous growth trends, event-based deltas (*"before and after campaign in Oct 2023"*). * *"Show TRx growth over 6 months"*\ Kaiya understands you're asking for how Total Prescriptions have changed over the past 6 months. and automatically calculates the percentage growth (or decline) month-over-month. * *"NRx growth in West vs East"*\ Kaiya detects that you're looking for a regional comparison of growth. It gives side-by-side growth metrics by segment (in this case, West and East regions), highlighting which region is growing faster or declining. * *"Monthly trend of TRx for Product X"*\ Recognizing the time-based trend analysis, Kaiya plots Total Prescriptions for Product X across each month, showing how Product X's prescriptions have moved month by month—perfect for spotting peaks, drops, or seasonal patterns. ## **8. Insight-driven questions ("Why" and "Compare")** When you ask: * *"Why did TRx drop in Q2 2024?"* * *"Compare TRx between Q1 2023 and Q1 2024"* Kaiya triggers the **Insights Agent** to do more than just show numbers. It identifies key drivers, breaks down variances, highlights top contributing factors, and presents both visuals and clear explanations—automating what would normally be manual analysis. You get immediate diagnostic insights without extra effort. ## 9. **Handling complex filtering logic** Kaiya translates your natural language into precise backend logic, without requiring you to use parentheses or Boolean operators. * *"TRx for Product N in NY where HCP Decile is 9"*\ Kaiya applies nested filtering, combining multiple conditions—filtering by product, location, and a specific HCP segment—all in one query. * *"TRx for dermatology in NY OR NJ"*\ Kaiya correctly interprets and handles the logical operators (in this case, "OR"). {% hint style="warning" %} Kaiya handles errors gracefully by providing clear, actionable feedback—whether it's an invalid dimension, unknown filter value, missing metric, or backend issue—so you’re guided to fix the input without confusion or dead ends. It never fails silently, ensuring smooth, transparent interactions. {% endhint %} ## 10. Single-BV, Auto-BV, and Multi-BV Kaiya supports three distinct BV-selection modes. They look similar from the chat surface but behave differently underneath. * **Single-BV (manual).** You pick one BV from the dropdown. Every question in the conversation runs against that BV. Use this when you know exactly which BV holds the data and you don't want Kaiya to second-guess. * **Auto-BV (dynamic).** Kaiya picks the most relevant BV for each question independently, and the chosen BV can change between turns as the topic shifts. Filters, time windows, and entity context carry forward when Kaiya switches. Each individual question still resolves against a single BV. * **Multi-BV.** You select up to three BVs at once for the session, and Kaiya joins across them using soft links authored at the BV level. Use this when answering questions that genuinely require combining data from multiple BVs — for example, joining call activity from one BV with prescription volume from another. Multi-BV and Auto-BV can both be active in the same conversation: a single session can have multiple BVs in play, and the topic can shift between turns. For the full behavior on multi-BV, check out [Multi-Business Views in Kaiya](/kaiya/kaiya-conversational-ai/multi-business-view-conversations). ## 11. Chart types Kaiya produces When you ask Kaiya a Text-to-SQL question, it visualizes the result as a chart or table. You can ask for a specific chart by name, or let Kaiya pick based on the question and the shape of the result. ### Supported chart types You can ask for any of these by name: * **Line:** trends over time (days, weeks, months, years). Example: *"Show revenue by month."* * **Column:** compare categories or discrete periods. Example: *"Sales by product."* * **Pie:** part-to-whole across a small number of categories. Example: *"Share of sales by region."* * **Donut:** same as pie, with a center label; good for a small number of slices. * **Detail table:** exact values in a tabular view; good for many categories or deep inspection. If you'd rather let Kaiya decide, just say *"show the chart"* or *"visualize this data"* and it picks based on the result shape. {% hint style="warning" %} If you ask for any unsupported chart, Kaiya falls back to the closest supported chart or to a detail table. {% endhint %} {% hint style="info" %} This page covers Kaiya's Text-to-SQL chart output only. The full Tellius chart library (used in Vizpads and Search) supports many more chart types. Check out [Know your charts](/search/know-your-charts-in-tellius). {% endhint %} ## 12. Ask Kaiya about itself You can ask Kaiya about its own features and capabilities at any time, in plain language; no special syntax required. This is useful when you want a quick orientation before diving in, or when you're checking whether a specific feature is supported in your deployment. Examples: * *"What can you do?"* * *"What chart types do you support?"* * *"What workflows are available?"* * *"How do I use memory?"* * *"What are your limitations?"* Kaiya answers in plain language, grounded in the features actually available in your deployment. If something isn't supported, Kaiya says so directly instead of guessing. {% hint style="warning" %} Capability questions are about **Kaiya's features**, not your data. To explore your dataset (columns, metrics, values), ask the question directly — *"what columns are in my dataset?"* or *"show me sales by region"* — and Kaiya routes it to the analytics workflow. {% endhint %} # Multi-Business View conversations Some business questions cannot be answered from a single Business View. A field force performance question may need call activity from one BV, prescription volume from another, and target attainment from a third. Kaiya supports answering these questions in a single turn by selecting multiple BVs and joining them through soft links. This page is the technical reference for how multi-BV behaves and what to expect across different configurations. {% hint style="success" %} Auto-BV and Multi-BV work together. If you are asking questions in auto-BV mode, then Kaiya will be able to select more than 1 Business View, if required. As the course of the conversation shifts, Kaiya can auto-select the underlying Business View accordingly. {% endhint %} ### What is a soft link? A soft link is a way of telling Kaiya "this column in BV 1 and this column in BV 2 mean the same thing in the real world." Two columns with the same name in different BVs could mean totally different things. So an admin tells Kaiya explicitly: "the `account_id` column in the *Sales BV* is the same thing as the `account_id` column in the *Field Activity BV.*" This declaration is called a soft link. Once the soft link exists, Kaiya can answer questions that need data from both BVs at the same time such as "show me prescription volume next to call activity for each account." Kaiya uses the soft link to match rows across the two BVs, the same way you'd use a shared column to do a VLOOKUP in Excel. Check out [this page](/data/preparing-your-business-views/soft-linking-a-business-view) for more details. The word "soft" is there to distinguish it from a regular database join, which is enforced at a deeper level. Soft links live at the Tellius BV layer; they don't change the underlying database. {% hint style="info" icon="megaphone" %} There can be a **maximum of 3 BVs per question**. The first BV is the **primary BV** (the first one Kaiya picks in Auto-BV, or the first one you select manually). It governs the SQL dialect, fiscal calendar, and date column for the conversation. BVs are joined via soft links. All BVs in a single question must come from the same data source**.** {% endhint %} {% hint style="danger" %} Multi-BV works when all BVs in a question are sourced from the same Tellius data source (for example, all sourced from the same Snowflake connection, or all from the same Redshift cluster). {% endhint %} If the soft links are present, and the BVs are from the same datasource, then Kaiya runs a single joined query across the selected BVs and answers from the combined result. {% hint style="info" icon="circle-chevron-right" %} Kaiya Apps and Kaiya Missions reuse the same logic. If you generate an App or set up a Mission from a multi-BV conversation, the resulting App or Mission inherits the BV selection and behaves the same way each time it runs. {% endhint %} # Exporting Kaiya conversations Learn about Exporting Kaiya Conversations in Tellius and discover how AI-powered analytics and conversational intelligence improve enterprise decision-making. Kaiya can export conversations as professionally formatted PowerPoint (PPTX) or PDF presentations. Rather than simply dumping charts and tables into slides, Kaiya generates a storyline (a narrative arc that organizes insights into a logical sequence) and builds the presentation around it. You can review the storyline, refine it in natural language, and preview each slide before exporting. #### How to export the Kaiya conversation There are two entry points for triggering an export. **From the download icon in a conversation:** After a completed Kaiya response, click the download icon that appears alongside the thumbs up/down feedback icons at the bottom. The following dropdown appears:
* **Download the entire conversation as a .doc file:** Exports the conversation as a .doc file immediately * **Export as PDF or PPT:** Select this option to begin the export flow. **From within a conversation:** You can also express presentation intent directly in Kaiya. For example, type "build me a deck on Q3 territory performance," and Kaiya generates the storyline and builds the deck within the conversation. #### Setting up the export The export opens in a split-pane interface. The left panel walks you through the configuration steps as a guided conversation. The right panel displays the export preview. **Step 1: Choose a format** Kaiya presents two format buttons: **PDF** and **PPTX**. Click your preferred format.
**Step 2: Select a visual template** Kaiya asks you to select a visual template. If your admin has uploaded a corporate PowerPoint template, it appears in the available list. Select a template to apply your organization's branding. The visual template controls the slide design, color palette, typography, logo placement, and chart styling. **Step 3: Select storyline structure** Kaiya asks you to select a storyline structure from the available list. Storyline structures define the narrative arc of the presentation: how findings are organized and sequenced across slides. **Step 4: Kaiya generates the storyline** After you confirm both selections, Kaiya generates the storyline which you can r**eview and refine as needed.** #### Review and refine the files Once the storyline is generated, the right panel displays the **Export Report** with two tabs: **Storyline** and **Preview**. **Storyline tab** * The Storyline tab shows the raw content for each slide in markdown format. * At the top, two dropdowns labeled **Story** and **Visual** allow you to switch the storyline structure or visual template after generation without starting over.
* Below the dropdowns, a **Slide/Sections Content** area displays the text content of each slide/section. * Navigation arrows and a slide/section counter (for example, "Slide 2 of 7") let you move between slides/sections. * Each slide/section includes title, headline text, bullet points with data findings, KPI callouts, and speaker notes. **Preview tab**
* The Preview tab shows a rendered visual preview of each slide/section as it will appear in the final export. * Numbered slide/section buttons at the top let you jump to any slide/section. * The preview displays the formatted output with headings, styled text, bullet points, and layout as they will appear in the downloaded file. #### Refining the storyline with Kaiya Below the storyline generation confirmation, a **"Refine with Kaiya"** section appears, where you can type natural language modifications. For example, you can type "make it shorter," "focus more on the executive summary," "reorder the findings to lead with the churn analysis," or "add a recommendations slide." Submit the instruction, and Kaiya regenerates the modified slides/sections while preserving the rest of the storyline. #### Exporting the final file Once you are satisfied with the storyline and preview, click the **"Export as PowerPoint"** button to download the PPTX file. If you selected PDF as the format, the button reads **"Export as PDF"** instead. #### Template support for admins Under **Settings → Application Settings → Styles → PPT Templates**, admins can upload a corporate PowerPoint template (PPTX file) per environment. * Kaiya extracts a brand style specification from the template, including color palette, typography, slide layouts, logo placement, chart styling, and visual elements. * All subsequent exports by any user in that environment are rendered on-brand, matching the uploaded template's visual language. * When no template is uploaded, Kaiya's default template is used automatically. #### What gets exported The exported presentation includes all findings from the Kaiya analysis, organized by the storyline structure. Charts from the analysis are embedded as high-resolution images to guarantee visual fidelity. Where possible, native PowerPoint charts are used so that recipients can edit them after export. Tables are rendered with template-consistent formatting. All numeric values in the exported deck match the source data exactly. # Kaiya Learnings Kaiya Learnings let you define aliases, standardize query patterns, and set user or system-level rules so Kaiya interprets words and questions consistently. You can teach Kaiya Search how to interpret specific words or phrases in your search queries, so you get consistent, correct answers without re-phrasing. This enhances the search experience by ensuring that Kaiya understands and processes queries according to your specific business context. * **Phrase Learnings →** fix the meaning of a word/short phrase (alias to a measure/dimension/filter). * **Query Learnings →** lock down the entire question pattern (aggregation, grouping, filters, time windows, ranking) using a required Intent so Kaiya handles a pattern the same way every time. ### **When to use Phrase vs Query Learnings?** #### **Phrase Learnings** * Ideal for aliases/synonyms and simple flags—map a single token to a measure/dimension/filter (e.g., `supplier` → *Commercial Vendor Name)* * Suitable for personal shortcuts scoped to a user/BV (e.g., `my region` → *Region IN {NE, Mid-Atlantic}*), where meanings shouldn’t affect others. * Ideal for cases where fixing one word/short phrase resolves ambiguity. #### **Query Learnings** * Ideal for multi-clause patterns that must behave identically across phrasings: time comparisons (MoM, Q3 vs Q2), per-group Top-N, vs plan/forecast, or thresholds + grouping. * Suitable for org-standard questions where you require Intent to fix aggregation, grouping, filters, time logic, and ranking. * Avoids repeated back-and-forth clarifications—capture the full pattern once (e.g., “top 3 customers per region by revenue”). * Controls the output shape (ranked lists, variance tables, contributor breakdowns) when ambiguity spans beyond a single token. With continuous learning: * Users (or admins) can save corrections from a Kaiya session as new Learnings. * When a new Learning overlaps an existing one, Kaiya warns and lets you merge or override. ### Levels of Learnings There are two levels of Kaiya Learnings: * Business View-level Learning * System-level Learning **Business View-level Learning** These are specific to the current Business View and do not affect other parts of the system. They are ideal for context-specific mappings, like associating "core customer reach" with the average profit within that particular Business View. **System-level Learning** These learnings are applied globally, affecting all users and queries on the platform, regardless of the Business View. They are suitable for establishing general rules and definitions, such as mapping abbreviations to their full meanings (e.g., PLV meaning Pluvicto). ### Scope of Learnings You can scope a Learning by owner and Business View (BV). The following takes the precedence of highest → lowest. #### **User-specific** * User + Business View — visible only to that user, only in the selected BV. * User + All BVs — visible only to that user, across all BVs. #### **System-specific (admin only)** * System + BV — visible to all users, only in the selected BV. * System + All BVs — visible to all users, across all BVs. {% hint style="info" %} A Learning has two axes: Owner and Business View (BV) scope. If two Learnings cover the same phrase/query, the higher-precedence one is used. {% endhint %} Example: * User creates Phrase Learning: “my region” → Region IN {NE, Mid-Atlantic} in Revenue\_BV. * Admin already has “my region” → Region IN {All East} (System + All BVs). * In Revenue\_BV for that user, the User + BV definition wins. # Phrase Learning Create Phrase Learnings in Kaiya to map words or phrases to measures, dimensions, or filters, improving query accuracy and understanding across Business Views. Create a **Phrase Learning** to tell Kaiya what a single word or short phrase should mean (map it to a measure, dimension, or filter condition) in a specific Business View (BV) or across All Business Views. 1. Navigate **Kaiya → Open Side Bar → Manage Learnings**. The following page will be displayed. It will be default to Phrase Learnings.
2. You can sort and order the Learnings as follows.
* Select whether you need to view Learnings from all Business Views or from a specific Business View. * Select which scope of Learnings should be displayed: User-level or Business View level.
3. The following will be displayed for each Learning: * **Phrase:** literal phrase/alias for which the Learning has been created * **Intent/mapping:** the resolved meaning for the phrase * **Level:** User level or Business View level Learning * **Business View:** The Business View for which the Learning has been created * Creator name and created time * Click on the three-do kebab menu to edit or delete a Learning. 4. Click on **Create Learning** button and the following window will be displayed.
5. Select the relevant Business View which is applicable for the new Learning. You can also select **All Business Views** if you want to this Learning to be applicable for all BVs. 6. **Learning level:** Choose if you want the Learning should be visible only for the specific user or available across all Business Views. * **User** — visible only to the creating user. * **BV-level** — visible to all users. Admin role required. 7. **Phrase:** Provide the actual phrase you want to teach Kaiya. Use separate learnings for meaningfully different phrases. 8. In the **Instruction type**, you can choose to provide textual instructions in natural language or map keywords. * **Keyword Mappings:** Creates a deterministic binding from the phrase to one or more concrete BV targets (measure/dimension/filter). Kaiya applies these exactly whenever the phrase occurs (within the selected scope). Ideal for repeatable, exact behavior. The phrase maps cleanly to a field, aggregation, or filter. * Click on **Add Mapping** and select from the sub menu as required. * **Aggregation:** Picks the metric and how to roll it up. Use when the word should always resolve to a specific metric/aggregation.\ **Dimension:** Sets the *“group by”* field to break down results.\ **Resolution:** Sets the time grain used for grouping without adding a date filter. Use for phrases like *“weekly revenue”.*\ **Filter:** Applies a non-time condition on a column\ **Time filter:** Constrains the time window or comparison periods
* For each type, you can select the required column and the corresponding value. * **Textual instructions:** Lets you write a short directive that guides Kaiya’s language understanding when a phrase appears. Ideal for human-readable rule and no single field/value cleanly represents it (early modeling, cross-BV wording, policy phrasing). In the textbox, write a concise, explicit directive in natural language.
9. After providing all the required details, click on **Save Changes** to create the Learning. Or click on **Cancel** to dismiss. 10. If you want to delete a Learning, click on **Delete Learning** button. All the above fields are applicable when editing a Learning.
# Query Learning Create Query Learnings in Kaiya to define how full questions are interpreted. Set intents, mappings, and query logic for consistent, org-wide understanding. A **Query Learning** fixes how Kaiya should interpret a full question pattern (aggregation, grouping, filters, time windows, ranking). It must include an **Intent** so Kaiya can reuse the learning for similar phrasings. 1. Navigate **Kaiya → Open Side Bar → Manage Learnings → Query Learnings**. The following page will be displayed.
2. You can sort and order the Learnings as follows.
3. The following will be displayed for each Learning: * **Query:** literal phrase/alias for which the Learning has been created * **Intent/mapping:** the resolved meaning for the phrase * Creator name, created time. and the timestamp of last update. * Click on the three-do kebab menu to edit or delete a Learning. {% hint style="warning" %} Query Learnings are org-wide patterns. You’ll notice there’s no **Learning Level** or **Selected Business View** field in the Query Learning dialog; only admins can create them and they apply across the org. BV is resolved at run time from the user’s active context. If you need per-user or per-BV semantics, use Phrase Learnings. {% endhint %} 4. Click on **Create Learning** button and the following window will be displayed.
5. **Query:** Enter a representative natural-language question users actually ask. Avoid single-word aliases like supplier → use **Phrase Learning** for that. 6. **Query Type:** Choose whether you want to add an analytical query or a compound query. * **Analytical Query -** Use for a single analysis pattern (one result set) with clear aggregation/grouping/time/filter/ranking. Examples: Top-N per group; threshold + grouping; single MoM/YTD compare. * **Compound Query -** Use for questions that combine multiple analytical operations into one Learning (multi-step or multi-output logic you want treated as a unit). Examples: *“Show MoM revenue by channel and highlight segments where TRx > 150.”, “Compare actual vs plan vs forecast by region with a ranked variance list.”* 7. **Intent:** Briefly describe in natural language what the query is intended to achieve. This helps Kaiya understand and apply the Learning accurately. Include: * **Aggregation(s):** sum/avg/count/calculation names * **Grouping:** the exact “group by” fields * **Filters/thresholds:** value conditions, segments * **Time logic:** window and/or Period A vs Period B * **Ranking/limits:** order by, Top-N, partitions {% hint style="warning" %} **Why Intent is mandatory?** Different phrasings (“top three per region”, “best 3 by region”) map to the same structured action because the **Intent** is the anchor. With **Intent**, Kaiya doesn’t rely on exact tokens; it “knows” what to build even if synonyms or order change, reducing follow-up questions. {% endhint %} 8. **Custom Mappings:** Turn on to bind tokens from the query to exact Business View fields, eliminating column ambiguity. Ideal for situations when multiple synonyms or overlapping names exist. Click on **Add Mapping** and the following window appears.
9. **Mapped Phrase:** The exact token from the query you’re pinning. Kaiya will resolve this token using the mapping you define. 10. **Type:** What kind of thing the phrase represents. * **Aggregation:** Picks the metric and how to roll it up. Use when the word should always resolve to a specific metric/aggregation. * **Dimension:** Sets the *“group by”* field to break down results. * **Resolution:** Sets the time grain used for grouping without adding a date filter. Use for phrases like *“weekly revenue”.* * **Filter:** Applies a non-time condition on a column * **Time filter:** Constrains the time window or comparison periods 11. **Business View:** The specific BV that contains the column you want to bind to. 12. **Column:** The exact field in that BV to map to (pick the modeled measure with its aggregation, or the precise dimension/flag). 13. Click on **Apply** to save the Learning, or click on **Cancel** to dismiss. 14. Finally, click on **Save Changes** to create the Learning. Or click on **Cancel** to dismiss. 15. If you want to delete a Learning, click on **Delete Learning** button. All the above fields are applicable when editing a Learning. # Kaiya Terms of Service Read the Tellius Kaiya Terms of Service outlining beta use, data processing with OpenAI, user responsibilities, limitations, and legal agreements for participation. {% hint style="info" %} Effective as of: **May 2, 2024** {% endhint %} YOUR PARTICIPATION IN THE **TELLIUS KAIYA** (“TELLIUS KAIYA”) IS GOVERNED BY THESE KAIYA PROGRAM TERMS OF SERVICE (**"KAIYA TERMS"**). THESE KAIYA TERMS ARE ENTERED INTO BETWEEN TELLIUS, INC. (**“TELLIUS”**) AND THE ENTITY PARTICIPATING IN THIS TELLIUS KAIYA (**“CUSTOMER”** OR **“YOU(R)”**). IF YOU ARE ENTERING INTO THESE KAIYA TERMS ON BEHALF OF AN ENTITY, YOU REPRESENT AND WARRANT THAT YOU ARE AUTHORIZED TO BIND SUCH ENTITY TO THESE KAIYA TERMS. These terms govern your access and use of the Tellius Kaiya services or features that Tellius offers on a beta basis (the **“Beta Services”**). Beta Services are offered “AS-IS” for testing and evaluation purposes, and Beta Services have different privacy, security and compliance commitments. Notwithstanding anything to the contrary in any agreement you have with Tellius, Tellius makes no warranties or representations and has no indemnity or support obligations with respect to Beta Services. **Please consider the following when deciding if you would like to participate in the Tellius Kaiya and use the Beta Services.** ### **Sensitive Personal Information** Customer’s use of the Tellius Kaiya is not covered by any existing business associate agreement with OpenAI, L.L.C. or its affiliates (collectively, **“OpenAI”**). Customer specifically agrees not to use the Kaiya to collect, store, process or transmit any sensitive personal information, and Customer shall be solely responsible for any sensitive personal information that is inadvertently submitted to the Kaiya. Tellius and its third party technology providers (including OpenAI) are not subject to any additional obligations that apply to sensitive personal information under these Kaiya Terms, regardless of whether you and Tellius have previously entered into a business associate agreement that applies to Tellius services to which you subscribe. ### **Processing by OpenAI** Customer acknowledges that by using Tellius Kaiya Services, you agree to OpenAI processing your data submitted to Tellius Kaiya Services in accordance with their data processing terms and security policy. If your use of the Tellius Kaiya Services will involve the processing of personal data, you must provide legally adequate privacy notices and obtain necessary consent for the processing of such data in accordance with applicable laws. ### **No Regional Data Hosting** The Beta Services involve integration with OpenAI, whose services are currently hosted in the U.S. Given such, no regional data hosting is offered by Tellius in connection with the use of the Beta Services, regardless of whether you and Tellius have previously agreed to regional data hosting terms that apply to Tellius services to which you subscribe. Please read these Kaiya Terms carefully to make sure you understand the applicable terms, conditions and restrictions on Beta Services. **By clicking “I Agree,” you represent and warrant that you have read, understand, and agree to be bound by these Kaiya Terms (including the acknowledgements and disclaimers set forth above and RESOLUTION OF DISPUTES THROUGH BINDING ARBITRATION RATHER THAN IN COURT set forth below) and that you are so authorized to accept these Kaiya Terms on behalf of your Company. If you do not agree, or are not so authorized, do not click “I Agree” or proceed with using the Beta Services.** ### **1. Beta Period and Usage** Customers may access and use the Beta Services on a non-exclusive basis in accordance with these Kaiya Terms for the specific period of time granted by Tellius (the **“Beta Usage Period”**). You agree to abide by any rate limits or other limitations directed by Tellius. Tellius may modify and/or discontinue any or all of the Beta Services at any time, in its sole discretion (with or without notice), and any or all of the Beta Services may not become generally available. The Beta Services are offered to Customers on a no-charge basis, but Tellius reserves the right to modify pricing for the Beta Services at any time during and after the duration of the Tellius Kaiya Beta. Applicable pricing will be made available to you. ### **2. Customer Requirements** (a) Compliance with Laws and Policies. You agree to comply with all applicable laws, rules, and regulations in connection with your access to, and use of, the Beta Services. In addition, you agree to comply with OpenAI’s policies when using the Beta Services: (i) Usage Policy (located at: [https://platform.openai.com/docs/usage-policies](https://openai.com/policies/usage-policies)), and (ii) Sharing and Publication Policy (located at: [https://openai.com/api/policies/sharing-publication/](https://openai.com/policies/sharing-publication-policy)). (b) Input and Output. You may provide input to the Beta Services (**“Input”**) and receive output generated and returned by the Beta Services based on the Input (**“Output”**). As between the parties and to the extent permitted by applicable law, you are responsible for Input and Output, including for ensuring that it does not violate any applicable laws, policies, or these Kaiya Terms. You agree that Tellius and OpenAI may use Input and Output as necessary to provide and maintain the Beta Services, comply with applicable law, and enforce their respective policies. Tellius may analyze and research Input and Output in connection with assessing the performance of and enhancements to the Beta Services. Due to the nature of machine learning, Output may not be unique across users, and the Beta Services may generate the same or similar output. Responses that are requested by and generated for other users are not considered your Output. ### **3. Restrictions on Use** You may not (i) use the Beta Services in a way that infringes, misappropriates or violates any person’s rights (including, without limitation, copyright, trademark, service mark, trade secret, contract, privacy or publicity rights); (ii) reverse assemble, reverse compile, decompile, translate or otherwise attempt to discover the source code or underlying components of models, algorithms, and systems of the Beta Services, or any portion thereof (except to the extent such restrictions are contrary to applicable law); (iii) use the Beta Services to develop foundation models or other large scale models that compete with Tellius or OpenAI; (iv) use any method to extract data from the Beta Services, including web scraping, web harvesting, or web data extraction methods; (v) represent that Output was human-generated when it is not; or (vii) attempt to bypass or circumvent any limitations on access or use of the Beta Services (e.g., rate limits, keys) or share your passwords or other login credentials. ### **4. Intellectual Property** Tellius and its third-party technology providers (including OpenAI), as applicable, own all legal rights, title, and interest in and to the Beta Services, including all intellectual property rights. Except for the rights expressly granted to you under these Kaiya Terms, no other rights or permissions to access or use any of the Beta Services is granted. ### **5. Feedback** By participating in the Tellius Kaiya Beta, you will have the ability to provide comments, feedback, ideas, suggestions, and/or other information regarding your use of the Beta Services (**“Feedback”**). By providing Feedback, you acknowledge that Tellius owns any Feedback, and Tellius may use all or part of your Feedback or any derivative thereof for any purpose, without any further remuneration, compensation, or credit to you. You hereby grant to Tellius, if for any reason it is further needed, a perpetual, non-revocable, royalty-free, worldwide license to use and exploit such Feedback. Tellius will not publish Feedback in a way that is attributable to you without your consent. ### **6. Termination** You may, in your sole discretion, discontinue your use of the Beta Services at any time. Tellius may terminate these Kaiya Terms and/or discontinue your participation in the Tellius Kaiya and access to the Beta Services at any time and for any reason, with or without notice and without liability to you, including, without limitation, if you breach these Kaiya Terms, if you are no longer a customer in good standing with Tellius or if there are changes in relationships with third party technology providers. Upon termination of these Kaiya Terms and/or your participation in the Tellius Kaiya Beta, you will stop using the Beta Services, and you will promptly return or, if instructed by Tellius, destroy all Confidential Information in your possession or control. The sections of these Terms, which by their nature should survive termination or expiration, will survive, including but not limited to Sections 5-10 and 12. ### **7. Disclaimer of Warranties** You acknowledge and agree that the beta services are provided on an “as is” and as available basis. To the extent permitted by applicable law, Tellius, its affiliates, subsidiaries, and licensors expressly disclaim any and all warranties of any kind, express or implied, including, but not limited to, merchantability, satisfactory quality, title, fitness for a particular purpose, non-infringement, quiet enjoyment and any warranties arising out of any course of dealing or usage of trade. Tellius makes no warranty that any of the Beta Services will meet your requirements or that the Beta Services will be uninterrupted, timely, or error-free, nor does Tellius make any warranty as to the results (including, without, limitation, any outputs) that may be obtained from the use of the Beta Services or the accuracy of any other information generated or obtained through the Beta Services. No information or advice, whether oral or written, obtained from tellius or through the use of the Beta Services shall create any warranty. Some jurisdictions do not allow the exclusion of certain warranties and conditions, so some of the above exclusions may not apply to you. ### **8. Limitation on Liability** In no event will Tellius, its affiliates, subsidiaries, or licensors be liable to you or any other third party for any indirect, special, incidental, exemplary, punitive, or consequential damages or for lost revenue, lost profits, lost data, loss of technology or goodwill or interruption to or loss of use of service arising out of or in connection with these Kaiya terms or company’s or any other third party’s use of the Beta Services (including, without limitation, use or reliance on any outputs), regardless of theory of liability, including contract, warranty, tort (including negligence), strict liability, or otherwise, and whether or not Tellius has been advised of the possibility of such loss or damages. The parties agree that the limitations on liability set forth herein are agreed allocations of risk and will apply notwithstanding the failure of essential purpose of any limited remedy. In any case, Tellius’s aggregate liability under these Kaiya terms will not exceed U.S. one hundred dollars (U.S. $100). ### **9. Indemnification** You agree to hold harmless and indemnify Tellius, its affiliates and subsidiaries, officers, directors, agents, and employees (collectively **"Tellius Indemnified Parties"**) from and against any third-party claim arising from or related to relating to your use of the Beta Services (including Input and Output) and your breach of these Kaiya Terms or violation of applicable laws, rules and regulations, including any liability arising from or relating to such claims, losses, damages, judgments, settlements, costs and expenses (including attorneys' fees). In such a case, Tellius will provide you with written notice of such claim, suit or action. ### **10. Confidential Information** During and after your participation in the Tellius Kaiya, you shall not disclose any proprietary and/or non-public information of Tellius or third parties provided to you or to which you have access in connection with the Tellius Kaiya (**“Confidential Information”**), except as authorized in writing by Tellius or as required by law or court order, provided: (a) you will promptly notify Tellius in writing of the requirement for disclosure, and (b) disclose only that portion of the Confidential Information legally required. You shall promptly notify Tellius of any actual or suspected misuse or unauthorized disclosure of Confidential Information. Confidential Information includes, without limitation, these Kaiya Terms and any documents, designs, techniques, specifications, unreleased and experimental product features, product plans, existing or prospective business plans, existing or prospective research or test objectives and/or results, comments and discussions related to any such information provided by yourself or other applicable Tellius Kaiya program members. You agree to (i) use Confidential Information only for the purpose of participating in the Tellius Kaiya; (ii) not disclose Confidential Information to any third parties; (iii) not copy or download any Confidential Information unless instructed to do so by Tellius; and (iv) use the same degree of care, but no less than a reasonable degree of care, to prevent the unauthorized use, dissemination or publication of Confidential Information as you would use to protect your own confidential information of like nature. ### **11. Changes to Kaiya Terms** We reserve the right to modify these Kaiya Terms from time to time. We will notify you of material revisions, for example, via an in-product notification or an email to the email associated with your account. Your continued participation in the Tellius Kaiya Beta after changes have become effective will be deemed as your acceptance of such changes. If any changes are not acceptable to you, you may discontinue your use of the Beta Services in accordance with Section 6 above. ### **12. Miscellaneous** **(a) Assignment.** These Kaiya Terms will bind and inure to the benefit of each party's permitted successors and assigns. Neither party may assign these Kaiya Terms without the advance written consent of the other party, except that either party may assign these Kaiya Terms in connection with a merger, reorganization, acquisition, or other transfer of all or substantially all of such party's assets or voting securities. Any attempt to transfer or assign these Kaiya Terms in derogation of the foregoing will be null and void. **(b) Severability.** If any provision of these Kaiya Terms will be adjudged by any court of competent jurisdiction to be unenforceable or invalid, that provision will be limited to the minimum extent necessary so that these Kaiya Terms will otherwise remain in effect. **(c) Independent Contractors.** These Kaiya Terms do not create a partnership, joint venture or agency relationship between you and Tellius. Tellius and you are independent contractors, and neither party will have the power to bind the other or to incur obligations on the other’s behalf without the other party’s prior written consent. **(d) Government End-Users.** Elements of the Beta Services are commercial computer software. If the user or licensee of the Beta Services is an agency, department, or other entity of the United States Government, the use, duplication, reproduction, release, modification, disclosure, or transfer of the Beta Services, or any related documentation of any kind, including technical data and manuals, is restricted by a license agreement or by the terms of these Kaiya Terms in accordance with Federal Acquisition Regulation 12.212 for civilian purposes and Defense Federal Acquisition Regulation Supplement 227.7202 for military purposes. All Beta Services were developed fully at private expense. All other use is prohibited. **(e) Notices.** Any notices to Tellius must be sent to: Tellius Inc, 12700 Sunrise Valley Dr, #305 Reston, VA 20191, Attn: Legal Department, via first class or air mail or overnight courier, with a copy via email to and are deemed given upon receipt. Notice to you may be provided by sending email to the email address associated with your account or by posting an in-app message to your account, and is deemed received when sent (for email) or posted. **(f) Amendment; Waiver.** Except as provided under “Changes to Kaiya Terms,” no amendment to these Kaiya Terms will be binding unless executed in writing by a duly authorized representative of Tellius and Customer. No waiver will be implied from conduct or failure to enforce or exercise rights under these Kaiya Terms, nor will any waiver be effective unless in a writing signed by a duly authorized representative on behalf of the party claimed to have waived. **(g) Export Control.** In its use of the Beta Services, Customer agrees to comply with all export and import laws and regulations of the United States and other applicable jurisdictions. Without limiting the foregoing, (i) Customer represents and warrants that it is not listed on any U.S. government list of prohibited or restricted parties or located in (or a national of) a country that is subject to a U.S. government embargo or that has been designated by the U.S. government as a “terrorist supporting” country, (ii) Customer will not (and will not permit any of its users to) access or use the Beta Services in violation of any U.S. export embargo, prohibition or restriction, and (iii) Customer will not submit to the Beta Services any information that is controlled under the U.S. International Traffic in Arms Regulations. **(h) Injunctive Relief.** You agree that any breach of these Kaiya Terms by you may result in irreparable harm to Tellius or its affiliates or subsidiaries, for which damages would be an inadequate remedy and therefore, in addition to its rights and remedies otherwise available at law, Tellius shall be entitled to seek equitable relief, including injunction, in the event of such breach. **(i) Entire Agreement.** These Kaiya Terms and any policies incorporated in these Kaiya Terms contain the entire agreement between you and Tellius regarding the Tellius Kaiya and your access and use of the Beta Services and supersedes any prior or contemporaneous agreements, communications, or understandings between you and Tellius on the subject thereof. For the avoidance of doubt, as it relates to the Beta Services, these Kaiya Terms will control to the extent there is a conflict with any other agreement entered into between you and Tellius that apply to Tellius services to which you subscribe (i.e., the Tellius Subscription Terms of Service or Master Services Subscription Agreement). **(j) Governing Law; Dispute Resolution.** i) Direct Dispute Resolution. In the event of any dispute, claim, question, or disagreement arising from or relating to these Kaiya Terms, whether arising in contract, tort, or otherwise (“Dispute”), the parties shall first use their best efforts to resolve the Dispute. If a Dispute arises, the complaining party shall provide written notice to the other party in a document specifically entitled “Initial Notice of Dispute,” specifically setting forth the precise nature of the dispute (“Initial Notice of Dispute”). If an Initial Notice of Dispute is being sent to Tellius, it must be emailed to and sent via mail to: Tellius Inc, 205 Van Buren Street, Suite 120 #1012, Herndon, Virginia 20170, US Following receipt of the Initial Notice of Dispute, the parties shall consult and negotiate with each other in good faith and, recognizing their mutual interest, attempt to reach a just and equitable solution of the Dispute that is satisfactory to both parties (“Direct Dispute Resolution”). If the parties are unable to reach a resolution of the Dispute through Direct Dispute Resolution within thirty (30) days of the receipt of the Initial Notice of Dispute, then the Dispute shall subsequently be resolved by arbitration. ii) Arbitration. IN THE EVENT THAT A DISPUTE BETWEEN THE PARTIES CANNOT BE SETTLED THROUGH DIRECT DISPUTE RESOLUTION, AS DESCRIBED ABOVE, THE PARTIES AGREE TO SUBMIT THE DISPUTE TO BINDING ARBITRATION. BY AGREEING TO ARBITRATE, THE PARTIES AGREE TO WAIVE THEIR RIGHT TO A JURY TRIAL. All aspects of the arbitration shall be treated as confidential, and neither the parties nor the arbitrators may disclose the content or results of the arbitration, except as necessary to comply with legal or regulatory requirements. The result of the arbitration shall be binding on the parties and judgment on the arbitrator’s award may be entered in any court having jurisdiction. The arbitrator shall award to the prevailing party, if any, the costs and attorneys’ fees reasonably incurred by the prevailing party in connection with the arbitration. iii) FOR ANY CLAIM WHICH IS NOT SUBJECT TO THIS DISPUTE RESOLUTION PROVISION, CUSTOMER AGREES TO SUBMIT AND CONSENT TO THE PERSONAL AND EXCLUSIVE JURISDICTION IN, AND THE EXCLUSIVE VENUE OF, THE STATE AND FEDERAL COURTS LOCATED WITHIN STATE OF VIRGINIA. This Agreement is governed by the laws of the State of Virginia, without regard to its conflicts of law rules. Any legal proceeding arising out of or relating to this Agreement will be brought in the state and federal courts of Virginia. Each Party consents to the exclusive jurisdiction and venue of such courts iv) THESE KAIYA TERMS MUST BE CONSTRUED AS IF IT WAS JOINTLY WRITTEN BY BOTH PARTIES. BOTH CUSTOMER AND TELLIUS AGREE THAT EACH MAY BRING OR PARTICIPATE IN CLAIMS AGAINST THE OTHER ONLY IN THEIR RESPECTIVE INDIVIDUAL CAPACITIES, AND NOT AS A PLAINTIFF OR CLASS MEMBER IN ANY PURPORTED CLASS. NO ARBITRATION OR CLAIM UNDER THESE KAIYA TERMS SHALL BE JOINED TO ANY OTHER ARBITRATION OR CLAIM, INCLUDING ANY ARBITRATION OR CLAIM INVOLVING ANY OTHER CURRENT OR FORMER USER OF SERVICES PROVIDED BY TELLIUS, AND NO CLASS ARBITRATION PROCEEDINGS SHALL BE PERMITTED. IN THE EVENT OF ANY DISPUTE CONCERNING THE VALIDITY OR ENFORCEABILITY OF THIS PROVISION, SUCH CLAIM MUST BE ADJUDICATED BY A COURT AND NOT BY AN ARBITRATOR # Best practices Get the most from Kaiya conversational AI with best practices for clean, well-structured data. Learn how to prep datasets and ask smarter, clearer questions. ### General data preparation To get the most accurate and useful answers from Kaiya, it's important to prepare your data correctly. This means keeping your datasets clean, naming things clearly, and using the right types of fields. * Try to keep datasets under **50 columns**. Kaiya works better with fewer, more relevant columns. Remove columns that are rarely used or not helpful for analysis. * Avoid confusing names. If you have both **“Product Line”** and **“Product Type”,** Kaiya might not know which one to use if you use **"Product"** in your search query. * If metrics like **Profit Margin**, **Conversion Rate**, or **Churn Rate** are part of regular analysis, create them as calculated columns in the dataset upfront. * Make sure your data joins neatly. Dimensions and facts should match in granularity to prevent duplicate rows or wrong totals. * Use full, readable names like `Policy Creation Date` instead of `plc_date`. * Use **underscores** or **spaces** — not symbols like brackets, slashes, or emojis. * Avoid using vague words like “growth” or “total” as column names. {% hint style="info" %} **Why?** Kaiya tries to interpret the *meaning* behind words. If your column is named “Sales Growth” and you ask “What is sales growth?”, Kaiya may prioritize the column match over calculating growth dynamically. To avoid this, consider using clearer naming like “Annual Sales Growth” or rephrasing the question to specify the desired calculation. {% endhint %} * You can teach Kaiya your business language. Use **Synonyms** to map your company’s terms to the actual columns in your dataset. * Avoid overlapping synonyms. If two fields share similar terms (like “**Expenses**” for both “**Costs**” and “**Material Expenses**”), Kaiya might get confused. * Use only essential date columns. Name them clearly and ensure they're in **Date** format, not **Text**. Kaiya uses these fields to answer questions like “last month’s revenue” or “YoY growth.” * When selecting dimensions during Feed creation, if a Date column appears with the wrong icon, check its data type in the metadata section (under **Data → Prepare**) and ensure it’s correctly set as a **Date**. * Index these: * Common filter fields like **Region**, **Product**, **Drug Name**, **Channel** * Fields with few values (low-cardinality) like **Segment** or **Product Category** * Don’t index: * Long text or free-text fields like **Comments** or **Descriptions** * Columns that overlap in meaning (e.g., “**Washington**” in both City and State) {% hint style="info" %} Kaiya uses indexed fields for auto-suggestions when filtering and selecting values. Indexing free-text columns clutters value suggestions and increases the chance of incorrect matches. Stick to structured fields for indexing (like Region, Product Category, or Segment). {% endhint %} {% hint style="success" %} When a query is ambiguous, Kaiya may ask **clarification questions** like “*Which date field did you mean?*” or “*Do you want to filter by Region or Country?*” These prompts help refine results quickly—just reply naturally, without needing to repeat the full question. Use **Learnings** to teach Kaiya your specific data language over time. * Use **Phrase Learning** to map business terms to fields, and **Query Learning** to pin complex questions to the right analytical intent. * Use thumbs-up on accurate answers. Use thumbs-down to correct intent and create a **Learning**. * For recurring complex multi-step questions, use **Query Learning** templates to standardize and reuse the flow. {% endhint %} ### How to ask better questions By following these best practices, you’ll help Kaiya understand your questions more accurately and return better answers. * Be specific. Include filters or timeframes. Instead of *“How are things going in the East?”,* use *“Sales trend in East region over last 6 months”.* * Break big questions into smaller parts to avoid overloading. Retry with different phrasing to be simpler or more specific. * Instead of a casual question*“Did people like our service?” → use “Customer satisfaction score in 2024”.* * To ask about change or trends, use this format: * *“% change in Sales from Jan 2024 to Feb 2024”* * *“What is the change in Revenue this quarter vs last quarter?”* * To start a new topic in the same chat, say *“Ignore previous context”* or click on the **"Clear context"** *icon* to clear conversation history. * There’s no context preserved across conversations. Start a new chat when you switch Business Views (BVs). Don’t switch BVs mid-conversation. {% hint style="warning" %} Kaiya is currently tuned for descriptive and comparative analysis (aggregations, trends, drivers). For forecasting/correlation or complex boolean logic, pair it with Vizpads, Insights, Feed, or agentic workflows. {% endhint %} # Ask across your documents (Unstructured) Ask questions across unstructured documents in Tellius to extract insights from text, PDFs, and files using AI-powered search, semantic understanding, and contextual answers. The **Unstructured** tab within the **Data → Connect** module is where you create, manage, and monitor connections to non-tabular data sources. While the **Structured** tab handles traditional database and warehouse connections, the Unstructured tab is purpose-built for file-based and document-based sources. These connections feed documents, PDFs, call transcripts, presentations, and other file-based content into Kaiya's unstructured analysis engine. Once connected and synced, the files from these sources are indexed and made available to Kaiya for retrieval, search, and reasoning within Workspaces. This enables use cases such as analyzing sales call transcripts alongside CRM data, extracting insights from regulatory filings, or grounding Kaiya's answers in internal documentation and reports. ### Managing unstructured files
The search bar in the top-right corner allows you to filter the list of unstructured connections by name. The sorting control below the search bar lets you sort the connections list by **Creation Date** and **Name** in either newest-first or oldest-first order.
The **Author** filter lets you narrow the list to connections created by a specific user. This is particularly useful in multi-user environments where multiple team members are setting up connections, and you need to find connections owned by a particular person. The **Reset** button clears all active sorting and filter selections, returning the connections list to its default view. **All/Created by Me:** These two sub-tabs filter the connections list by ownership. * **"All"** shows every unstructured connection in the environment regardless of who created it. * **"Created by me"** filters the list to show only connections that the currently logged-in user created. ### Connections Table The main area displays a table listing all configured unstructured data connections. Each row represents a single connection and displays the following columns:
**Name:** The display name assigned to the connection when it was created. **Type:** The connector type, indicating which external storage service this connection links to. Supported types include * Google Drive * Amazon S3 * Gong * Azure Blob Storage * Google Cloud Storage * PDFs **Schedule:** Displays the configured sync schedule for the connection. If no automatic sync schedule has been set, the connection syncs only when manually triggered. If a schedule is configured, it shows the recurrence pattern (for example, daily or weekly). **Connection status:** Shows whether Tellius can currently reach the external data source. * **"Connected"** shows that the credentials are valid and the source is reachable. * **"Error"** indicates the connection has failed, typically due to expired credentials, revoked permissions, a misconfigured path, or the source being unreachable. * **"Connecting..."** will be displayed when Tellius is trying to connect to the source. **Data sync status:** Shows the status of the most recent data synchronization. **"Completed"** indicates all files from the source have been successfully pulled and indexed. **Creation date:** The date and time when the connection was originally created, displayed in your local timezone. ### Row Actions (Three-Dot Menu) Each row in the connections table has a three-dot menu (⋮) on the far right. Clicking this menu reveals three actions that you can perform on that specific connection.
**Edit:** Opens the connection configuration for editing and update credentials. **Synchronize:** Triggers an immediate, on-demand synchronization of the connection. When you click **Synchronize**, Tellius reaches out to the external data source, pulls any new or updated files, and indexes them for use in **Kaiya Workspaces**. Use this action when you have recently added new files to the source and want Kaiya to have access to them immediately without waiting for a scheduled sync. The **Data sync status** column will update to reflect the progress and completion of the sync operation. **Delete:** Permanently removes the connection. Deleting a connection removes the link to the external data source and removes the indexed content from Kaiya's knowledge base. This action cannot be undone. Any **Workspaces** that were using files from this connection will no longer have access to that content. ### Re-index data Re-indexing rebuilds the entire search index for all unstructured data across all connections. Specifically, it re-indexes all unstructured data that has been synced from your connections, regenerates automatic entities that Kaiya has extracted from the documents (such as people, organizations, dates, products, and other named entities), and deletes any manual entities that were previously created by users. When you click on **Re-index data**, a confirmation dialog appears. Click on **Confirm** to continue. #### When to re-index data? Use **Re-index** after large-scale changes to your connected data sources, after modifying Workspace configurations, or if the index has become fragmented over time. Re-indexing is also appropriate after resolving connection errors that may have caused partial or failed syncs. {% hint style="warning" %} Re-indexing is a resource-intensive operation that processes all unstructured data in your environment. The time required depends on the total volume of documents across all connections. This operation cannot be undone. Any manual entities that your team has created will be permanently deleted and will need to be recreated after the re-index completes. {% endhint %} The **"Create new connection"** button in the top-right corner launches the workflow for adding a new unstructured data source. Check out [this](/kaiya/ask-across-your-documents-unstructured/how-to-connect-to-unstructured-data) page for more details. # Workspace Configuration Configure your Tellius workspace by managing settings, permissions, and preferences to ensure secure access, optimize performance, and support scalable analytics. Clicking the **"Workspace configuration"** button opens the **Workspaces management** page. Workspaces are the organizational layer that sits between your unstructured data connections and Kaiya's conversational interface.
#### What is a Workspace? A **Workspace** is a curated collection of files and documents that Kaiya searches to answer user questions. Each Workspace groups related unstructured content around a specific use case, project, or domain. It keeps Kaiya's retrieval scope focused and accurate. Instead of searching across every unstructured file in your environment, Kaiya searches within the relevant Workspace, which improves answer quality and reduces noise from unrelated documents. #### When to create a Workspace? Create one Workspace per distinct analytical use case or domain. For example, you might create separate Workspaces for sales call analysis, competitive intelligence documents, regulatory filings, or customer meeting notes. Please do not mix unrelated document types into a single Workspace. #### Workspaces Table The Workspaces page displays a table with the following columns: **Name:** The display name of the Workspace. This is a clickable link that opens the Workspace for viewing and editing its contents and configuration. **Use case description:** A text description of what the Workspace is used for. This describes the analytical purpose of the grouped documents. **Created by:** The user who created the Workspace. **Status:** The current operational status of the Workspace. **"Active"** indicates the Workspace is live and Kaiya can search its contents when answering questions. **Creation date:** The date when the Workspace was originally created. **Sorting and Search:** The **Workspaces** page includes the same sorting controls available on the main **Unstructured** connections page, allowing you to sort by **Creation Date** and **Name** in newest-first or oldest-first order. A **Search** bar is available to filter Workspaces by name. #### Workspace Row Actions Each Workspace row has a three-dot menu (⋮) on the far right with the following options: **Open:** Opens the Workspace detail view, which provides full visibility into the Workspace's configuration, the files it contains, and the entities Kaiya has extracted from those files. **(Details, Files, and Entities)** **Edit:** Opens the Workspace configuration for inline editing. ### Workspace Detail View When you click **Open** on a Workspace, you are taken to the Workspace detail view. It is organized into three tabs: **Details**, **Files**, and **Entities**. #### Details Tab The Details tab provides the descriptive metadata for the Workspace. This is where you understand what the Workspace is for and how Kaiya interprets its purpose. An **Edit** button in the top-right corner lets you modify these fields directly.
**Workspace description:** A detailed description of the Workspace's purpose and scope. This tells administrators and users what the Workspace contains and what kinds of questions it is designed to answer. **Use case description:** A description of the analytical use case the Workspace supports. When you ask Kaiya a question, Kaiya uses these descriptions to decide which Workspace (and therefore which set of documents) to search. A well-written use case description helps improve retrieval accuracy. **Sample questions:** A set of example questions that this Workspace is designed to answer. Writing specific, representative sample questions improves Kaiya's ability to match incoming user queries to the right Workspace. These serve two purposes. * They guide you on what kinds of questions you can ask against this Workspace's content. * They help Kaiya calibrate the types of queries this Workspace is relevant for. #### Files Tab The Files tab shows every file that has been ingested into this Workspace from your connected unstructured data sources. This is where you see exactly what content Kaiya has access to when answering questions scoped to this Workspace.
If you need to temporarily stop a source from feeding into this Workspace without deleting the connection entirely, you can turn off the connection, and files from that source will stop updating and will not be used by Kaiya during analysis. The Files table displays the following columns: **Source type:** Identifies the nature of the file. **Connection name:** The name of the unstructured data connection that this file was synced from. This maps back to the connections listed on the main **Unstructured** tab. **Source name:** The original name or title of the file as it exists in the source system. **Added by:** The user who added or synced this file into the Workspace. **Addition date:** The date when the file was added to this Workspace. #### Entities Tab The Entities tab displays the tracked entities that Kaiya has extracted from the files in this Workspace. Entities are structured pieces of information (for example: people, organizations, technologies, and other named concepts) that Kaiya identifies and catalogs from unstructured content to improve its ability to answer questions accurately.
The entity system works on a one-entity-per-type principle. Each entity should represent a single, distinct person, organization, technology, or concept. This ensures that Kaiya extracts and tracks information about each entity cleanly without conflating it with other entities. {% hint style="info" %} The entity type helps Kaiya understand the role each entity plays when answering questions. For example, knowing that "Oracle" is a Technology rather than an Organization helps how Kaiya interprets references to it in context. {% endhint %} The Entities table displays the following columns: **Entity name:** The name of the extracted entity. This is the specific person, organization, technology, or concept that Kaiya has identified across the Workspace's files. **Type:** The category of the entity (whether it's a person, organization, product etc.) **Added by:** Indicates who created or identified the entity. **"Tellius"** means the entity was automatically extracted by Tellius during indexing. Entities can also be manually created by users, in which case the user's name would appear here. **Sources:** Shows which connected source the entity was extracted from. For example, "Gong" indicates the entity was identified from Gong call transcripts. **Description:** A contextual description of the entity that explains its role or relevance within the Workspace. These descriptions are generated by Kaiya based on the content of the files and give you visibility into how Kaiya understands each entity's role. # How to connect to unstructured data? Learn how Tellius connects to unstructured data sources for AI-powered search, document analysis, and conversational insights across enterprise content. To add a new unstructured data source, click the **"Create new connection"** button on the **Unstructured** tab of the **Data → Connect** page. This takes you to the **Add new connectors** page. A **Search** bar in the top-right corner lets you filter the available connector types by name if needed. ### Available Content Repositories Under the **Content Repositories** section, the following six unstructured connector types are available. Clicking on any connector type opens the **"Add a connection"** dialog with fields specific to that connector.
**Google Drive:** Connects to files and folders stored in Google Drive. **Amazon S3:** Connects to objects stored in Amazon S3 buckets. **Gong:** Connects to call recordings and transcripts stored in Gong. **Azure Blob Storage:** Connects to blobs stored in Azure Blob Storage containers. **Google Cloud Storage:** Connects to objects stored in Google Cloud Storage buckets. **File Upload:** Allows you to upload PDF files directly from your local. Once your unstructured sources are connected and indexed, the documents and folders within them become available to scope individual Kaiya questions using @ mentions in the conversation input, so you can target a specific report or library instead of searching the full workspace every time. ## Add @ mentions in conversations Scope a Kaiya question to specific documents or folders by typing `@` directly in the chat input. Kaiya then searches only the sources you select, returning answers grounded in exactly those files instead of your full workspace. ### Why use @ mentions In unstructured mode, when you ask Kaiya a question without an @ mention, it searches the full workspace corpus. This works well when you want broad coverage. It works less well when you already know the answer lives in a specific quarterly report, a single payer policy, or one folder of summaries. Without scope, the relevant document competes with hundreds of others for retrieval attention, and your answer can come back diluted. @ mentions solve this by letting you state the scope inline, while you type. You do not open a separate filter panel. You do not navigate to a document picker. You do not restate which files you mean across follow-up questions. The mention pills sit in the message itself, and your chat history preserves them so you (and anyone the chat is shared with) can see what was scoped at every turn. The result: precise answers from exactly the sources you care about, without leaving the chat input.esult: precise answers from exactly the sources you care about, without leaving the chat input.
#### How to use @ mentions **1.** Type `@` anywhere in your message. A dropdown opens, listing: * Recent documents in your workspace * Folders derived from your document paths **2.** Use the arrow keys to move through the list, then press **Enter** to select. **3.** Each selection appears as an inline pill in your message, showing with an **×** button to remove that mention {% hint style="info" %} You can add more mentions to the same message. The total cap is 10 selections per message (documents and folders combined). {% endhint %} **4.** Finish typing the rest of your question and send. Kaiya searches only within the sources you selected. **Example:** *@Q3 Financial Report.pdf What were the key revenue drivers?* #### What you can mention You can mention: * **Documents** you have access to in the current workspace. * **Folders** derived from your document locations. When you mention a folder, the scope expands to every document inside that folder path. This is useful when you want Kaiya to search a whole library, for example all payer policies in a `/policies/payers/` folder, without selecting each file one by one. #### How scope is enforced Two behaviors define how Kaiya handles the scope you set: * **Explicit scope is respected.** Kaiya informs if you @ mention sources that do not contain information relevant to your question. It does not silently widen the search to other documents in your workspace. Your selection is the authoritative scope. * **Mentions are preserved.** Your chat history shows the mention pills exactly as you sent them. Anyone with the chat shared can see which sources each answer was based on. This matters for trust and auditability. When someone asks "where did this number come from," the chat itself shows the scoped sources alongside the citations in the response. #### Access and visibility @ mentions follow the permissions you already have in Tellius: * Admins see all workspace documents in the autocomplete. * You only see documents and folders you have permission to access. Items you do not have access to never appear in the dropdown. # Connect to Google Drive Clicking **Google Drive** opens the **"Add a connection"** dialog with the following fields.
**Connection Name:** A user-defined display name for this connection. **Description:** A brief text description of the purpose of this connection. **Folder URL:** The full URL of the Google Drive folder you want Tellius to connect to. This must be a direct link to a Google Drive folder in the format `https://drive.google.com/drive/folders/...`. Tellius will ingest all supported files within this folder. **Authentication Method:** A dropdown that specifies how Tellius authenticates with Google Drive.
* **Service Account -** Tellius uses a Google Cloud service account to access the folder. The service account must have read access to the specified folder. * **Account Key File Info:** A dropdown that specifies how the service account credentials are provided (not applicable if OAuth is selected). * **Paste JSON:** Opens a text area where you paste the full contents of the service account JSON key file directly into the form. * **Upload File:** You can drag and drop or browse to select the service account JSON key file. The upload accepts up to 1 file with a maximum total size of 40.00 MB. * **JSON File:** A text area where you paste the full contents of the Google Cloud service account JSON key file. This is the credential file you download from the Google Cloud Console when you create a service account key. The JSON contains the project ID, private key, client email, and other authentication details that Tellius needs to connect to Google Drive on behalf of the service account. * **OAuth -** OAuth authentication connects Tellius to Google Drive using an individual user's Google account authorization. When configured, Tellius initiates an OAuth consent flow where a user grants Tellius permission to access their Google Drive files. For deployments with long-term stability requirements, **Service Account** authentication is recommended over OAuth. **Scheduled Sync:** Configures how frequently Tellius automatically syncs files from this Google Drive folder. * **Manual** - Tellius will only sync when you explicitly trigger it using the **Synchronize** action from the three-dot menu on the connections table. * **Schedule -** Set automatic recurring syncs so that new files added to the Google Drive folder are automatically pulled into Tellius without manual intervention. A second dropdown appears: **Cron Schedule (UTC)**. The **Cron Schedule** dropdown lets you define how frequently Tellius automatically syncs files from the connected source. All schedule times operate in UTC, so factor in your local timezone when choosing a schedule. The available options are: * Hourly * Every 6 hours * Daily at midnight * Daily at 2 AM * Every 12 hours {% hint style="info" %} Choose a schedule frequency that matches how often new content arrives in your source. Over-frequent syncing on a source that rarely changes adds unnecessary processing load, while under-frequent syncing on an active source means Kaiya may not have access to the latest files. {% endhint %} Click **Continue** to proceed with creating the connection, or **Cancel** to discard the configuration. # Connect to Amazon S3 Learn how Tellius connects to Amazon S3 for AI-powered search, document analysis, and conversational insights across enterprise content. Clicking **Amazon S3** opens the "Add a connection" dialog with the following fields.
**Connection Name:** A user-defined display name for this connection. **Description:** A brief text description of what this connection is used for. **Bucket:** The name of the Amazon S3 bucket you want Tellius to connect to. Enter only the bucket name (for example, "my-analytics-bucket"), not the full ARN or URL. The IAM credentials you provide must have read access to this bucket. **Region Name:** The AWS region where the S3 bucket is located. Enter the region code in standard AWS format (for example: "us-east-1", "eu-west-2"). The region must match the bucket's actual region. **AWS Access Key ID:** The access key ID for the IAM user or role that Tellius will use to authenticate with AWS. This is part of the AWS programmatic access credentials. The IAM entity associated with this key must have at minimum `s3:GetObject` and `s3:ListBucket` permissions on the specified bucket. This field is masked after entry. **AWS Secret Access Key:** The secret access key that corresponds to the AWS Access Key ID above. Together, these two values form the complete IAM credential pair. This field is masked after entry. **Scheduled Sync:** Configures how frequently Tellius automatically syncs files from this S3 bucket. * **Manual** - Tellius will only sync when you explicitly trigger it using the **Synchronize** action from the three-dot menu on the connections table. * **Schedule -** Set automatic recurring syncs so that new files added to the S3 bucket are automatically pulled into Tellius without manual intervention. A second dropdown appears: **Cron Schedule (UTC)**. The **Cron Schedule** dropdown lets you define how frequently Tellius automatically syncs files from the connected source. All schedule times operate in UTC, so factor in your local timezone when choosing a schedule. The available options are: * Hourly * Every 6 hours * Daily at midnight * Daily at 2 AM * Every 12 hours {% hint style="info" %} Choose a schedule frequency that matches how often new content arrives in your source. Over-frequent syncing on a source that rarely changes adds unnecessary processing load, while under-frequent syncing on an active source means Kaiya may not have access to the latest files. {% endhint %} Click **Continue** to proceed with creating the connection, or **Cancel** to discard the configuration. # Connect to Gong Clicking **Gong** opens the "Add a connection" dialog with the following fields.
**Connection Name:** A user-defined display name for this connection. **Description:** A brief text description of what this connection is used for. **Gong Access Key:** The API access key from your Gong account. You can generate this from the Gong admin settings under API integrations. This key identifies your Gong workspace and authorizes Tellius to pull call data. This field is masked after entry. **Gong Access Key Secret:** The secret that corresponds to your Gong Access Key. Together, these two values authenticate Tellius with the Gong API. This field is masked after entry. **Start Date:** An optional date picker that specifies the earliest date from which Tellius should pull Gong calls. Only calls recorded on or after this date will be synced. For example, setting the start date to January 1, 2026, would pull only calls from 2026 and later. If left empty, Tellius will sync all available calls from the Gong account. **Scheduled Sync:** Configures how frequently Tellius automatically syncs new calls from Gong. * **Manual** - Tellius will only sync when you explicitly trigger it using the **Synchronize** action from the three-dot menu on the connections table. * **Schedule -** Set automatic recurring syncs so that new files added to Gong are automatically pulled into Tellius without manual intervention. A second dropdown appears: **Cron Schedule (UTC)**. The **Cron Schedule** dropdown lets you define how frequently Tellius automatically syncs files from the connected source. All schedule times operate in UTC, so factor in your local timezone when choosing a schedule. The available options are: * Hourly * Every 6 hours * Daily at midnight * Daily at 2 AM * Every 12 hours {% hint style="info" %} Choose a schedule frequency that matches how often new content arrives in your source. Over-frequent syncing on a source that rarely changes adds unnecessary processing load, while under-frequent syncing on an active source means Kaiya may not have access to the latest files. {% endhint %} Click **Continue** to proceed with creating the connection, or **Cancel** to discard the configuration. # Connect to Azure Blob Storage Clicking **Azure Blob Storage** opens the "Add a connection" dialog with the following fields.
**Connection Name:** A user-defined display name for this connection. **Description:** A brief text description of what this connection is used for. **Authentication Type:** A dropdown that specifies how Tellius authenticates with Azure.
1. **Client Credentials -** uses an Azure Active Directory (Entra ID) app registration to authenticate via OAuth 2.0 client credentials flow. This is the recommended approach for server-to-server authentication. * **Client ID -** The Application (client) ID of the Azure AD app registration that Tellius will use to authenticate. You can find this in the Azure portal. This field is masked after entry. * **Client Secret** - The client secret generated for the Azure AD app registration. This acts as the password for the app registration and is used together with the Client ID and Tenant ID to obtain an access token. Client secrets have expiration dates, so ensure the secret is current. * **Tenant ID -** The Directory (tenant) ID of your Azure Active Directory tenant. This identifies which Azure AD instance Tellius should authenticate against. You can find this in the Azure portal under Azure Active Directory > Overview. 2. **Storage Account Key -** The access key for your Azure Storage account. You can find this in the Azure portal under your Storage Account > Access Keys. Azure provides two access keys (key1 and key2) for rotation purposes; either one will work. This key grants full read (and write) access to the storage account. This field is masked after entry. **Start Date:** An optional date picker that specifies the earliest date from which Tellius should pull files. Only blobs created or modified on or after this date will be synced. If left empty, Tellius syncs all files in the container. **Azure Blob Storage Account Name:** The name of the Azure Storage account that contains the container you want to connect to. This is the storage account name as it appears in the Azure portal (for example, "mystorageaccount"). **Azure Blob Storage Container (Bucket) Name:** The name of the specific container within the storage account that Tellius should connect to. For example, "yourcontainer". Tellius will ingest all supported files within this container. **Scheduled Sync:** Configures how frequently Tellius automatically syncs files from this Azure container. * **Manual** - Tellius will only sync when you explicitly trigger it using the **Synchronize** action from the three-dot menu on the connections table. * **Schedule -** Set automatic recurring syncs so that new files added to Azure Blob are automatically pulled into Tellius without manual intervention. A second dropdown appears: **Cron Schedule (UTC)**. The **Cron Schedule** dropdown lets you define how frequently Tellius automatically syncs files from the connected source. All schedule times operate in UTC, so factor in your local timezone when choosing a schedule. The available options are: * Hourly * Every 6 hours * Daily at midnight * Daily at 2 AM * Every 12 hours {% hint style="info" %} Choose a schedule frequency that matches how often new content arrives in your source. Over-frequent syncing on a source that rarely changes adds unnecessary processing load, while under-frequent syncing on an active source means Kaiya may not have access to the latest files. {% endhint %} Click **Continue** to proceed with creating the connection, or **Cancel** to discard the configuration. # Connect to Google Cloud Storage Learn how to connect Tellius to Google Cloud Storage to access, ingest, and analyze data from cloud buckets for faster insights and scalable analytics. Clicking Google Cloud Storage opens the **"Add a connection"** dialog with the following fields.
**Connection Name:** A user-defined display name for this connection. **Description:** A brief text description of what this connection is used for. **Bucket:** The name of the Google Cloud Storage bucket you want Tellius to connect to. Enter only the bucket name (for example, "your-gcs-bucket"), not the full `gs://` URI or HTTPS URL. The service account credentials you provide must have read access to this bucket, specifically the `storage.objects.list` and `storage.objects.get` permissions. **Start Date:** An optional date picker that specifies the earliest date from which Tellius should pull files. Only objects created or modified on or after this date will be synced. **Account Key File Info:** A dropdown that specifies how the Google Cloud service account credentials are provided. Two options are available: * **Paste JSON:** Opens a text area (the JSON File field below) where you paste the full contents of the service account JSON key file directly into the form. * **Upload File:** Displays a file upload area where you can drag and drop or browse to select the service account JSON key file from your local machine. The upload zone accepts up to 1 file with a maximum total size of 40.00 MB. **JSON File:** This field appears when **Paste JSON** is selected in Account Key File Info. Paste the full contents of the Google Cloud service account JSON key file here. This is the credential file you download from the Google Cloud Console when you create a service account key (IAM & Admin > Service Accounts > Keys > Add Key > Create new key > JSON). The JSON contains the project ID, private key, client email, and other authentication details that Tellius needs to access the GCS bucket on behalf of the service account. **Scheduled Sync:** Configures how frequently Tellius automatically syncs files from this GCS bucket. * **Manual** - Tellius will only sync when you explicitly trigger it using the **Synchronize** action from the three-dot menu on the connections table. * **Schedule -** Set automatic recurring syncs so that new files added to GCS are automatically pulled into Tellius without manual intervention. A second dropdown appears: **Cron Schedule (UTC)**. The **Cron Schedule** dropdown lets you define how frequently Tellius automatically syncs files from the connected source. All schedule times operate in UTC, so factor in your local timezone when choosing a schedule. The available options are: * Hourly * Every 6 hours * Daily at midnight * Daily at 2 AM * Every 12 hours {% hint style="info" %} Choose a schedule frequency that matches how often new content arrives in your source. Over-frequent syncing on a source that rarely changes adds unnecessary processing load, while under-frequent syncing on an active source means Kaiya may not have access to the latest files. {% endhint %} Click **Continue** to proceed with creating the connection, or **Cancel** to discard the configuration. # Kaiya Apps Build interactive data applications from a conversation Kaiya Apps lets you generate fully interactive, persona-scoped data applications directly inside Tellius, using only natural language. You describe what you need in a conversation with Kaiya, it generates a complete application: layout, data bindings, filter logic, navigation tabs, KPI cards, charts, tables, and written insights. The resulting app is a live, multi-section application tied to a Business View. Data can be refreshed on demand, the app can be shared with other users, and modifications are made conversationally rather than through a configuration panel.
#### How Kaiya Apps differ from Vizpad Vizpad is a general-purpose analytics canvas where users manually select chart types, configure axes, drag in dimensions, and arrange layouts. Kaiya Apps operates differently. You provide a business question or describe a persona and their recurring analytical needs. Kaiya then generates the entire application structure, chooses the appropriate chart types, selects relevant metrics and dimensions from the Business View, writes contextual insights, and produces a finished multi-tab application. The key architectural distinction: Vizpad is designed for open-ended exploration. Kaiya Apps is designed for recurring, role-specific analytical needs where the same set of questions is asked repeatedly, potentially by multiple people across the organization. #### Data behavior Apps query the underlying Business View at creation time and store a data snapshot. This snapshot powers the app immediately, so there is no delay from live queries each time the app loads. When data needs to be updated, admins and app owners can trigger a manual refresh. The refresh runs asynchronously in the background. While a refresh is in progress, the app remains fully usable, displaying data from the most recently completed refresh. ### How to access Kaiya Apps The **Apps** section is available as a dedicated item in the left navigation pane. It appears below the **Data** section in the sidebar.
Click **Apps** in the left navigation to open the Apps library. ### The Apps library The Apps library is the central hub for managing all applications. When you open the Apps page, you see a grid view of all published apps. Each app card displays the app name, a brief description, its publication status, the Business View it is connected to, the author, and the date it was last modified.
At the top of the Apps library, you have the following controls: * **Search** bar: Filter apps by name using the search field at the top left. * **Status filter**: A dropdown at the top right lets you toggle between **Published** and **Archived** apps. By default, the library displays **Published** apps. * **View** toggle: Switch between a grid layout (card view) and a list layout using the toggle icons next to the status filter. * **Create New App**: This button at the top right opens the app creation interface. * **App Conversations**: Opens a side panel showing your previous app creation conversations. Each entry displays the conversation and its status of creation. Clicking an entry reopens that conversation so you can continue where you left off.
# How to create a Kaiya App Learn how to create a Kaiya App in Tellius using natural language—build interactive apps from insights or from scratch with automated KPIs, layouts, and analysis. There are two ways to create a Kaiya App. The method you choose depends on whether you are starting from an existing analysis or building a new app from scratch. #### From a Kaiya Deep Insights Conversation After Kaiya completes an agentic **Deep Insights** analysis, three action buttons appear at the bottom of the response: * Create App * Subscribe to existing schedule * Create new schedule for workflow
Click **Create App** to convert the analysis into an interactive application. The generated app inherits the analytical approach from the **Deep Insight**, including the analysis logic, metric relationships, and findings. It carries forward the specific analytical framework that produced the insight. Once created, the source conversation and the resulting app are bidirectionally linked. A **Go to App** link appears in the original conversation, and a **Go to Source** link appears within the app. This lets you trace any app back to the analysis that produced it.
#### From the Apps page Directly This path is for building a new app from scratch without an existing analysis. 1. Navigate to the **Apps** page using the left navigation sidebar and click the **Create New App** button. 2. The app creation interface opens in a split-pane layout. The left panel contains the Kaiya conversation. The right panel displays the app and plan created.
3. At the top of the conversation panel, select the Business View that contains the data your app should use. 4. Type your app request in the chat input. Describe the persona who will use the app, the business questions it should answer, and the metrics or dimensions that matter. For example: "Build an app for Field Sales & Dealer Performance: B2B / National Retail Channel Intelligence." 5. Press Enter or click the send button to submit. 6. Kaiya interacts with you and asks clarification questions when required. 7. Kaiya then processes your request and generates an App Blueprint (the plan) for your review. ### What is an App Blueprint (Plan)? Before Kaiya creates the app, it generates a detailed blueprint and presents it for your review. The blueprint is displayed in the right panel while the conversation continues on the left. You can verify the proposed structure and request changes before any app is built. The plan is a structured document titled **App Blueprint** and contains the following sections: | Analysis Goal | The core business question the app is designed to answer. This anchors the entire app structure. | | :-------------------------------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Key Performance Indicators (KPIs) | The primary metrics displayed in the app. These are the quantitative measures that the app will track and visualize. | | Data Sources | The specific tables from the selected Business View that will feed data into the app. | | Analysis Dimensions | The categorical fields available for grouping, filtering, and slicing data within the app. | | Key Insights | Pre-identified analytical findings that Kaiya plans to surface in the app, based on the data and the stated analysis goal. | | App Sections | The individual tabs or pages of the app. Each section lists its purpose, the specific metrics and dimensions it uses, and the visualization types it will contain (KPI cards, bar charts, line charts, tables, filter controls, markdown summaries). | | Interactive Controls | The user-adjustable filters that will be available in the app, enabling users to slice data by dimensions such as region, time period, segment, or product. | #### Reviewing and approving the blueprint After Kaiya presents the blueprint, it summarizes the plan in the chat panel and asks for confirmation. The message includes a count of the proposed sections, data views, and metrics, followed by options: Describe any changes you want. For example: "Add a section for monthly activation trends" or "Remove the Rankings tab and use a dark theme." You can also request design changes at this stage, such as "use dark theme", "add a bar chart", or "card-based layout". Once you approve, Kaiya creates the app. A confirmation message appears in the chat: "Insight app created successfully using a structured plan", followed by the App ID. The completed app renders in the right panel immediately. {% hint style="info" %} After creating the app, you can navigate to the plan by clicking on the **"Show Plan".** The plan will be displayed in the place of the app. You can go back to the app by clicking again on **"Hide Plan"**. {% endhint %}
### What types of analysis are supported? Kaiya Apps can generate applications built around several analysis types. All analytical capabilities available in the Kaiya Deep Insights are supported here. The analysis type determines the structure of the insights, the chart types used, and the nature of the findings presented in the app. Some of the types are as follows:
Analysis TypeWhat It DoesExample Use Case
ForecastingProjects future values of a metric based on historical patternsWeekly store revenue forecast by region for the next 8 weeks
Variance / Driver AnalysisIdentifies the factors driving differences between actual results and a comparison baselineGross margin variance by product category compared to the prior quarter
Root CauseTraces underperformance or anomalies back to their underlying driversIdentifying why a specific store location is underperforming its sales target
Segmentation / CohortGroups entities into meaningful clusters based on shared characteristicsCustomer segments organized by annual spend decile
Anomaly DetectionFlags data points or entities that fall outside expected thresholdsStore locations where foot traffic dropped below the trailing 12-week average
What-If / ScenarioModels outcomes under hypothetical conditionsProjected revenue lift under different promotional discount levels
Correlation / DependencyMeasures the strength and direction of relationships between two variablesAverage transaction value versus repeat purchase rate, analyzed by store manager
{% hint style="success" icon="lightbulb-exclamation-on" %} You do not need to specify analysis types manually. When you describe what you want the app to do, Kaiya automatically selects the appropriate analysis types based on your description. For example, asking for "performance vs target" will trigger variance analysis, while asking for "forecast next quarter" will trigger forecasting.
{% endhint %} # How to customize a Kaiya App Learn how to customize a Kaiya App in Tellius using natural language—modify charts, KPIs, filters, and layouts with version control and real-time updates. Kaiya Apps are not static once created. You modify them the same way you built them: through conversation. There is no drag-and-drop editor or configuration panel. All changes are made through natural language instructions in the Kaiya conversation. 1. Open the app you want to modify. 2. Click the **Customize** icon (Kaiya icon) in the top-right toolbar. This opens the Kaiya conversation panel in a split-pane view alongside the app. 3. Type your modification request in natural language at the bottom of the conversation panel. 4. Kaiya processes the instruction, and updates the app in the right panel. #### What you can change * Remove or add KPI cards * Swap chart types (for example, change a bar chart to a line chart) * Add or remove dimension filters * Change time ranges or date filters * Add, remove, or reorder sections (tabs) * Change the theme or visual styling of the app * Modify the insights or summaries {% hint style="info" %} Every modification is saved as a new version. Changes remain in draft until you explicitly publish. Version history is accessible from within the app, so you can review previous versions and roll back if needed.
{% endhint %} ### How versioning works in Kaiya Apps Kaiya Apps use a versioning system to track changes and control what other users see. * **Draft versions:** When you customize an app, each save creates a new draft version. Draft changes are only visible to the person making the edits until the app is published. * **Publishing**: Once you are satisfied with your changes, publishing the app makes the current version visible to all users who have access. * **Published vs. Archived:** The Apps library supports two states. Published apps are actively available to users. ### Permissions and Sharing Kaiya Apps use the same explicit user and group permission model as Vizpads. When you create an app, you are its owner. You can share it with specific users or groups, granting them view/edit access. Modifications made affect all users who have access to that app once the changes are published. There is no per-user customization layer; the published version is the same for everyone with access. ### Refreshing data on a schedule In addition to triggering refresh manually from the toolbar (**Refresh app data**), you can configure automatic refresh on a schedule. Schedules are set in natural language inside the app conversation. Examples: * *"Refresh this app every day at 6 a.m."* * *"Update the data every Monday morning."* * *"Refresh hourly."* * *"Stop the scheduled refresh."* **When the Business View changes** A Kaiya App is bound to the Business View it was built from. When the Business View is updated with new data or refreshed aggregations, those changes appear in the app on the next refresh (manual or scheduled). If the schema of the Business View changes after the app was built (columns added, removed, renamed, or retyped), the existing app's refresh is rejected because the app's data bindings no longer match. In that case, recreate the app to pick up the new schema. # Live data in Apps An App can be **precomputed**, **live**, or **mixed**. * **Precomputed:** every number comes from data captured at the last refresh. * **Live:** every cell queries the source when you use it, so the numbers are always current. * **Mixed:** some cells query live, the rest use data from the last refresh. Because a live App queries the source when you filter, you can slice the data without regenerating the app. ### **How live querying works** When someone changes a filter in a live App, the App does not run the query itself. It sends the name of the query and the filter values you chose (never the SQL) to Tellius. Tellius fills in the values, applies your data permissions, and runs a read-only query against the source. The rows come back and the cell redraws. Two things follow from this design, and both matter: * The App in your browser never holds the SQL and never connects to the data platform directly. Every live interaction is a checked call through Tellius. * Your data permissions are applied at the moment the query runs, for whoever is viewing — never for whoever built the app. ### **What you see in a live App** When you open a live App, the difference from a precomputed one shows up in three places: the filter bar, how cells load, and how quickly they respond. **The filter bar:** A live App has a filter bar with dropdowns for values (Region, Brand, Payer) and a picker for date ranges. The dropdown options are loaded from the source rather than saved into the App, so the lists are always current and show only the values your permissions allow. **Loading:** Cells fetch their data as soon as the App opens, so you see numbers immediately and don't have to choose a filter first. Date filters start on a wide default range, and value filters start unset, resolving to everything you're permitted to see. **Responding to filters:** When you change a filter, only the cells that depend on that filter re-query; the rest stay as they are. Data and dropdown lists load independently, so a cell never sits waiting on a dropdown to finish. And, if you go back to a filter combination you've already used in the same session, it renders instantly, because the App reuses the results it already has. ### **What live filters can and cannot do** Only the values in the filter are interactive. What a cell measures and how it groups were decided when the app was built. **Supported** * Value filters, such as *Region*, *Brand*, or *Payer* (one value or a list) * Time and date-range filters * Filters that drive several cells at once * Whole-App live, or a mix of live and precomputed cells * Live cells inside older versions of an App * Remixing a live App **Not supported** * Drill-down - a live cell cannot regroup by a different column * Changing which measures or dimensions a cell shows * Re-running calculation or summary steps when you interact * Typing free text to filter on values that aren't listed {% hint style="info" %} *"Show me this by region instead"* is an edit to the App, not a filter. Ask Kaiya to change it. {% endhint %} ### **App types and badges** Every App, and every version of an App, is one of three types, shown so nobody has to guess whether a number is current. | Type | Meaning | How it's shown | | --------------- | ------------------------------------------------------------- | ------------------------------------------------ | | **Live** | Every cell queries the source. | One badge in the App header. No per-cell badges. | | **Mixed** | Some cells are live; the rest use data from the last refresh. | A Live pill on each live cell only. | | **Precomputed** | All data comes from the last refresh. | No badge of any kind. | {% hint style="info" %} The App's plan card carries the same signal before the App is built. Because the type is stored per version, opening an older version shows that version's behaviour, not the current one's. {% endhint %} ### **Making an existing App live** A precomputed app can be converted in conversation, with no rebuild: * **"Make this app live"** converts the whole app. Its existing queries are reused and pointed back at the source, and interactive filters come from the key dimensions already in the plan. * **"Make just the *****support-impact***** panel live"** converts one section, producing a mixed app. {% hint style="warning" %} Sections whose data comes from calculation steps rather than a query cannot be converted and stay precomputed. On Apps built without section-level structure, a request for a single section converts the whole App instead. {% endhint %} ### **Editing a live App** Presentation changes are cheap; new data is not. * Restyling, relabelling, rearranging, or building a new cell from data the App already fetches leaves the existing queries untouched. * Asking for a metric, dimension, grouping, or filter column the App doesn't already fetch creates new queries. Existing cells keep working, and the new cell gets its own live query. ### **Refreshing a live App** * Refresh re-captures data for precomputed cells. * A fully live App has nothing to re-capture, because every cell already queries the source when you use it. Refreshing one records a successful refresh and updates the timestamp without re-running anything. * A mixed App refreshes its precomputed half normally. * If you refresh a live App and nothing appears to change. It's because the App was already current. ### **Data permissions in live Apps** Data permissions in a live app work differently from a shared file, and the difference is deliberate. * Permissions are resolved for the person viewing the App, at the moment the query runs; not for the person who built it. * The same live App therefore shows different totals to people with different permissions. This is the intended design. * Filter dropdowns are filtered the same way, so you are never offered a value you cannot query. * If permissions cannot be resolved, the cell shows an error rather than unrestricted data. * If you have no permitted values for a filter, that cell shows an error instead of someone else's data. # AI summaries in Apps An App can generate a written summary of what you're looking at (a call plan for the selected physician, a verdict on the selected invoice etc.) at the moment you ask for it. ### **How AI summaries work** An AI summary is written when you ask for it. Press **Generate summary** and the App sends its instructions plus the data currently on screen to Tellius, which calls the model configured for Apps and returns formatted text rendered in place, alongside the data it describes. The App never holds model credentials. Every call routes through Tellius, the same boundary as live data. ### **The three controls** | Control | What it does | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Generate summary** | Writes the summary. Nothing is written until you press it. | | **Clear cache & regenerate** | Discards the stored answer and writes a new one. Use this when the underlying data changed but the text didn't. | | **Edit instructions** | Shows the guidance given to the model in a text box you can change, so you can retune tone, focus, or house rules without editing the App. Editing produces a fresh answer. | ### **What a summary can and cannot do** A summary describes what's on screen. If a number isn't in the view it was given, it isn't available to the summary. #### **Supported** * Summaries, briefings, recommendations, and verdicts * Summaries scoped to the current selection or filter state * Instructions you edit yourself * Several independent summary blocks in one App * Summaries over live-queried data #### **Not supported** * Querying the data platform - a summary only sees what was sent to it * Reasoning over the full dataset behind a chart * Generating automatically when the App opens, or on every selection change * Word-by-word streaming - the answer arrives complete * Very large selections, which are rejected #### **Caching** * An answer is stored against the exact combination of instructions and data sent, for about 15 days. * Reopening the same record weeks later returns the stored answer instantly. * Change the data, the selection, or the instructions, and a new answer is written. * If the source updated but the numbers on screen didn't change, the text won't change either. Use **Clear cache & regenerate**. #### **Adding a summary to an App** Summaries are opt-in. An app that only shows charts and tables won't have one. Ask for it explicitly. For example, type in "add an AI summary of the selected account", and Kaiya adds the block. An administrator can adjust how summaries behave across future apps. #### **Combining summaries with live data** An App can do both. Narrow the filter bar, the live cells re-query the source, and a summary block summarises those freshly returned rows. Nothing special is needed to combine them. The summary always describes whatever the cell is currently showing. ### Troubleshooting | Symptom | What's happening | What to do | | --------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | A cell shows an error as soon as the app opens | Your data permissions couldn't be resolved, or you have no permitted values for that filter | Ask an administrator to check data access for this dataset. The app refuses to show rows rather than show the wrong ones. | | Refresh succeeds but nothing changed | The app is fully live, so there's no captured data to refresh | Expected. A live app is always current. | | *"Show this by a different dimension"* doesn't work | Only filter values are interactive | Ask Kaiya to edit the app. Grouping is part of the app's design. | | A section stayed precomputed after *"make it live"* | Its data comes from calculation steps, so it can't be re-queried | That section keeps refresh-based data; the rest of the App is live. | | The summary text is stale after a data change | An identical earlier answer is cached for about 15 days | Use **Clear cache & regenerate**. | | **"Regenerate"** returns identical text | The stored answer is being returned for an unchanged request | Use **Clear cache & regenerate**, or edit the instructions. | | Nothing happens on open where a summary is expected | Summaries are generated on request by design | Press **Generate summary**. | | The App has no summary block at all | The request that built the App didn't ask for one | Ask for it explicitly and Kaiya will add the block. | # Anatomy of a completed app Explore the anatomy of a completed app in Tellius—understand its structure, components, and configuration to build, review, and optimize analytics workflows. Once generated, a Kaiya App is a fully rendered, multi-section interactive application. The following elements are present in a completed app:
#### Header banner Each app opens with a styled header banner that displays the app title, a description of what the app covers, and optionally, category or channel tags (for example, "B2B Channel" and "Retail Channel"). The banner provides immediate context about the scope of the application. #### Navigation tabs Apps are organized into multiple tabs, each corresponding to a section defined in the blueprint. Tabs appear below the header and allow users to navigate between different views of the data. For example, an app might have tabs labeled Overview, Drivers, Segments, Rankings, and Recommendations. #### Section-level guidance Each section within a tab can include a guidance callout at the top. This callout has a title and a brief explanation of what the section displays and how to use it. It orients the user before they engage with the metrics and charts below. #### Insights and summaries Kaiya generates contextual text within each section. It is analytical narrative that references the specific metrics and dimensions in the app, explains what the data shows, and highlights what the user should pay attention to. These summaries are generated based on the data at the time of creation and updates when the app data is refreshed. #### KPI cards Key metrics are displayed as prominent KPI cards at the top of relevant sections. Each card shows the metric name (for example, Total ACV, Quota Attainment, Accounts at Risk, Renewal Pipeline), the current value, and a contextual subtitle explaining the metric (such as "Active B2B Contracts ($M)" or "YTD Team Performance"). #### Charts and tables Depending on the analysis types specified in the blueprint, each section contains a combination of visualizations: bar charts, line charts, tables etc. Chart types are selected by Kaiya based on what is most appropriate for the data and the analytical intent of the section. #### Interactive filters The app includes user-adjustable filters based on the dimensions defined in the blueprint. These filters let viewers slice the data by region, time period, segment, product, or any other available dimension without modifying the app itself. ### Actions on the App When viewing a completed app, a toolbar appears in the top-right corner of the screen. The toolbar contains the following controls:
* **Business View indicator:** Displays the name of the Business View the app is connected to. * **Version dropdown (Latest):** A dropdown labeled “Latest” that lets you switch between different versions of the app. Clicking the dropdown reveals a list of all saved versions, each displayed with a version badge (v1, v2, etc.), the version name (the most recent version is always labeled “Latest”, while earlier versions use a timestamped identifier), and the date and time the version was saved. Selecting an earlier version loads that version of the app in the main panel, allowing you to review previous states. This is how you access version history and roll back to an earlier version if needed.
* **Show Plan:** Opens the **App Blueprint** that was used to generate the app. This lets you review the original plan, including the analysis goal, sections, KPIs, and data sources at any time after creation. * **Delete:** Removes the app. Available to admins and app owners only. * **Refresh app data:** Triggers a manual data refresh against the underlying Business View. The app continues to display the most recently loaded data while the refresh runs in the background. Available to admins and app owners. * **Customize:** Opens the Kaiya conversation panel for the app, allowing you to [modify the app](/kaiya/kaiya-apps/how-to-customize-a-kaiya-app) conversationally. # Mastering prompts for Kaiya Apps ### How to write an effective prompt The quality of your prompt directly affects how close the first generated app is to what you need. A well-structured prompt usually means the blueprint is right on the first pass and only minor adjustments are needed. A strong prompt typically includes: 1. **The primary question or goal.** One sentence is enough — *"Analyze sales performance across regions"* or *"Investigate why churn increased in Q3."* 2. **The key metrics that matter.** Naming 3–6 specific KPIs ensures they are treated as priority. Kaiya can infer metrics from the Business View, but explicit naming prevents surprises. 3. **The dimensions you want to slice by.** *"By region, by product category, by sales rep"* drives the filter options and breakdown sections. 4. **The audience.** *"For the executive team"* produces KPI-heavy, scannable layouts. *"For the operations team"* produces denser layouts with more tables and detail. 5. **Design preferences (optional).** Theme (dark or light), accent colors, spacing density. If you do not specify, Kaiya auto-designs based on the data domain. **Weak prompts vs strong prompts** | Weak | Strong | | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | "Create a dashboard for my data" | "Analyze sales performance by region and product. Show revenue, margin %, and MoM trends. For the sales leadership team." | | "Show me sales" | "Show total orders, average order value, and top 10 SKUs by revenue. Quick overview, no deep analysis." | | "Something that shows revenue" | "Deep dive into customer churn. Investigate why churn increased in Q3, focusing on cohort patterns, product correlations, and risk signals." | **What to specify and what to let Kaiya decide** | You should specify | Kaiya will decide | | ------------------------------------------ | -------------------------------------- | | The core metrics that matter to you | The exact chart types for each section | | The primary dimensions to slice by | Tab names and section ordering | | The audience (executive, analyst, ops) | Color palette unless you specify | | The depth you want (overview vs deep dive) | The number of tabs | | Specific time periods or filter values | Layout details | ### Prompt examples by use case Use these prompts as starting points for your own Kaiya Apps. Adapt the metrics, dimensions, and depth to the specific Business View you are building from. **Sales and revenue** * *"Analyze Q4 sales performance across regions and product lines. Key metrics: total revenue, units sold, average deal size, quota attainment %, and win rate. Show MoM trends and top and bottom performers by rep. For the sales leadership team."* * *"Deep dive into why revenue dropped in the enterprise segment last quarter. Investigate deal size trends, win/loss patterns, stage-level drop-off, and competitive displacement signals. Include actionable recommendations."* **Marketing and campaigns** * *"Campaign performance analysis. Show ROAS, CPA, click-through rate, and conversion rate by channel and campaign type. Compare this quarter to last quarter. Highlight underperforming campaigns with improvement actions."* * *"Analyze email campaign engagement: open rate, click rate, unsubscribe rate by list segment and send time. Show trends over the past six months and surface the top five segments by engagement lift."* **Operations and supply chain** * *"Supply chain health check. On-time delivery rate, inventory turnover, backlog volume, and supplier lead times by region and product category. Flag any metrics below threshold with severity indicators. Operations team, compact layout."* * *"Investigate order fulfillment delays over the past 90 days. Break down by warehouse, carrier, and SKU category. Show root cause distribution and a prioritized bottleneck list."* **Customer and churn** * *"Comprehensive churn analysis. Overall churn rate, churn by customer segment, product plan, and tenure cohort. Show MoM trend, top churn drivers, and a risk-ranked list of at-risk accounts with recommended retention actions."* * *"Customer health scorecard. Show NPS, support ticket volume, product usage frequency, and renewal likelihood by account tier. Flag accounts below health threshold. For the customer success team."* **Finance** * *"P\&L overview. Revenue, COGS, gross margin, operating expenses, and EBITDA. Compare actuals to budget by department and month. Highlight variances above 5%. Executive audience, spacious layout."* * *"Analyze billing and collections health. ARR, MRR, net revenue retention, invoice aging, and days sales outstanding. Show trend over 12 months and segment by customer tier."* **Pharma commercial** * *"Build an app for regional directors showing TRx and NBRx performance vs target, call frequency trends, and territory coverage gaps."* * *"HCP targeting. Rank HCPs by decile and segment, flag high-potential drop-offs, and surface recent call history. Built for the weekly cycle plan."* **Healthcare and clinical** * *"Patient outcomes summary. Show readmission rate, average length of stay, discharge disposition breakdown, and complication rate by care unit and diagnosis group. Clinical team, light theme."* **People and HR** * *"Workforce analytics. Headcount by department and level, attrition rate, time-to-fill, and engagement score. Show trends over the past year and surface departments with elevated attrition risk. For HR leadership."* ### **Phrasing edit requests effectively** Specific edits route directly. Kaiya applies the change without needing follow-up questions: * *"Add a KPI card for gross margin % to the Overview tab."* * *"Remove the Trends tab and replace it with a Segment Breakdown tab."* * *"Add a filter dropdown for product category that drives both the chart and the table."* * *"Switch the bar chart on the Sales tab to a horizontal bar sorted descending by revenue."* Vague edits trigger clarifying questions before any change is made: * *"Improve the charts"* — which charts, and what improvement? * *"Add more analysis"* — what kind? Trends, comparisons, breakdowns, new metrics? * *"Make it look better"* — colors, chart types, layout, typography? **Batching multiple edits** You can combine small edits into one request: *"Change the title to 'Q4 Sales Review', switch the bar chart to a line chart, and add a date range filter."* Kaiya applies them together. {% hint style="info" %} To refresh the visual style without changing data or structure, ask Kaiya to *"redesign the app"*. Kaiya will offer a small set of theme options. Picking one regenerates the visual layer only. All data and tabs are preserved exactly as they were. {% endhint %} # Kaiya Browser Extension The Kaiya browser extension brings Kaiya into your Chrome browser as a side panel, so you can ask questions about your data without leaving the page you are working on. You type a question in natural language, optionally capture what is on screen, and Kaiya answers against your Business Views. The same conversational experience you get inside Tellius, available in a panel on top of any tab. ### What you can do with Tellius browser extension The side panel supports Kaiya's standard conversational analytics: * **Ask Kaiya in natural language.** Type a question and get an answer against your data, the same way Kaiya behaves inside Tellius. * **Scope to a Business View.** Choose **All Business Views** or pick a specific Business View for the conversation. * **Auto-select a Business View from a screenshot.** When you capture the screen and send it, Kaiya selects the most relevant Business View based on the image you send. * **Capture screen.** Send a screenshot of the current page as visual context. You can capture a particular area, or send the entire page. * **Dictation and Voice mode.** Provide your input by voice instead of typing. You can dictate your responses, and Kaiya will respond in audio if **Voice mode** is enabled. * **Clear context.** Reset the current conversation context. * **Chat history.** Browse and reopen your earlier extension conversations. {% hint style="warning" %} The extension's conversations are stored separately from your main Tellius/Kaiya conversations. Conversations you have inside the Tellius do not appear in the extension, and extension conversations do not appear in the product. The extension's history is tied to the signed-in user in the extension. {% endhint %} ### Install and run the extension The extension named "Tellius Browser Extension" is available on the Chrome Web Store. Once loaded, the extension is available in your browser. Open the side panel from the Chrome toolbar (via the extensions menu / puzzle-piece icon, where you can also pin it for quick access). ### A tour of the side panel When the panel opens with no conversation yet, it shows an empty state in the middle of the conversation area.
The dark bar at the very top of the panel contains: * **Pin icon:** pins the panel so it stays in place while you work. * **Close (✕):** closes the side panel. Below the header is the purple toolbar: * **New chat (＋)** starts a new conversation. * **Chat history toggle:** the panel icon next to **New chat** opens the history of Kaiya conversations made in the extension. {% hint style="warning" %} This history holds only the conversations you have had **in the extension**, for the signed-in user. It does not show conversations from the main Tellius product. {% endhint %} #### Conversation area The box at the bottom of the panel is where you type. Its placeholder reads **"Ask Kaiya Anything…"** The input box has three controls: * **＋ (menu button)** opens the actions menu: **Capture screen**, **Clear context**, **Dictation**, and **Voice mode** (see **The ＋ menu**, below). * **Business View selector** shows the current scope, **All Business Views** by default, with a chevron to open the selector (see **Choosing a Business View**, below). * **Send (↑)** sends your question. You can also press **Enter** to send. {% hint style="danger" %} The extension reads the page (screenshot + DOM) and answers using your governed Tellius data. It works when Tellius has access to the data behind what's on screen (for example, a Tellius Vizpad, or a third-party dashboard whose underlying data is also modeled in Tellius). If Tellius doesn't have that data, the extension will tell you and ask you to pick a Business View, {% endhint %} ### Asking Kaiya a question 1. Click into the **Ask Kaiya Anything…** box. 2. Type your question in natural language (for example, *"Show me revenue for New York"*). 3. Select the **Business View** scope using the selector, or let Kaiya auto-pick the Business View for you. 4. Press **Enter**, or click the **Send (↑)** button. 5. Kaiya answers in the conversation area, and the exchange becomes part of your extension chat history. ### The ＋ menu Click the **＋** button inside the **Ask Kaiya Anything…** box to open the actions menu. The menu has four options:
* **Capture screen:** captures what is on the current page and passes it into the conversation as visual context. You can capture a particular visualization on the page, or, if you do not narrow the capture, the entire page is sent. Kaiya can then reason about what is on screen and can also auto-select the relevant Business View from the captured image. * **Clear context:** clears the current conversation context, so your next question starts fresh. * **Dictation:** lets you speak your question instead of typing it (speech-to-text into the input box). * **Voice mode:** lets you interact with Kaiya by voice. # Tellius MCP server Tellius exposes its analytics engine through an MCP (Model Context Protocol) server. Any MCP-compatible client (Claude Desktop, Claude Code, or an application you build yourself) can connect to it and work with your Business Views, ask questions in plain English, run agentic Missions, and set up scheduled delivery. The MCP server holds no data of its own. It passes your requests to Kaiya, which interprets the question, generates the SQL, runs the analysis, and returns the result. Metric definitions, joins, hierarchies, and row-level security stay inside your Business Views, so an answer retrieved through MCP follows the same governed logic as the same question asked inside Tellius. ### **What you can build with it** **Connect your own AI client:** Point Claude Code, Claude Desktop, Cursor, or any other MCP client at Tellius and ask questions about your governed data from the tool you already work in. **Retrieve metrics into your own application:** Your app owns the interface (KPI cards, filters, dropdowns) and calls Tellius for the numbers. Users never sign in to Tellius directly. **Add contextual follow-ups:** A user looking at a metric asks why it moved. Your app sends the question with the same filters that produced the metric, so the answer describes the slice on screen. **Automate recurring analysis:** Run a saved Mission on a schedule and deliver the output by email, Slack, or Teams. ### **How to connect an MCP client** No need to install or run anything locally. The Tellius MCP server is hosted on your Tellius deployment. You configure an MCP client to point at its URL, sign in once, and the tools appear. Ask your Tellius administrator for your MCP endpoint URL. The host varies by deployment and ends in `/mcp`: ``` https:///mcp ``` The server speaks standard MCP over streamable HTTP, so any MCP-compatible client can connect. No custom protocol, plugin, or Tellius SDK is required. A server-sent events transport is also available for older clients that need it, though HTTP is preferred where a client supports both. ### **Two ways to sign in** * **Browser sign-in:** Available to all users. Configure the MCP URL in a client that supports OAuth. The first time you connect, your browser opens a Tellius confirmation page. Approve it, and the client stores its credentials and connects without asking again. * **Client ID and secret:** For clients that run without a browser. An administrator creates MCP OAuth credentials in Tellius under **Admin Settings**, and those go into the client's configuration. Only administrators can create these credentials. Use browser sign-in wherever the client supports it. It needs no administrator involvement, and each user's own permissions apply. #### **Claude Code** Add the server from a terminal, then authenticate inside a session: ```bash claude mcp add --transport http tellius https:///mcp ``` Add `--scope user` to make it available across all your projects rather than only the current one. Then start Claude Code and run `/mcp` to complete the browser sign-in and check the connection status. `claude mcp list` shows whether the server is registered. #### **Claude Desktop and other clients with a connector UI** Open the client's settings, find the section for adding a custom connector or MCP server, and paste the URL. The client opens a browser window for sign-in the first time you use it. #### **Headless clients** Clients that cannot open a browser, such as Cursor, use the client ID and secret instead. Ask an administrator to create MCP OAuth credentials in **Admin Settings**, then enter them in the client's configuration alongside the MCP URL. #### **Confirming it worked** * List the available tools in your client. * A working connection shows the Tellius tools, including `tellius_ask`. * If the tool list is empty or the server shows as disconnected, the sign-in has probably not completed. Trigger it again from the client. {% hint style="warning" %} **Certificate errors.** If your client reports a TLS error when connecting, the host may be serving an incomplete certificate chain. Add the missing intermediate CA to your client's trust store or CA bundle. This is a host configuration issue rather than a problem with your client. {% endhint %} #### **Permissions** Every request runs as a specific Tellius user. Business View permissions and row-level security are applied to that user, so an answer retrieved through MCP reflects the same access the user has inside the product. ### **How to start asking a question: `tellius_ask`** `tellius_ask` is the tool behind most integrations. It takes a question in plain English plus the Business View to answer it from, and returns the answer along with the data and the query that produced it. | Parameter | What to send | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `question` | The request in plain English, with filters written into the sentence. | | `business_view_ids` | A list containing the Business View id. | | `include_raw` | Set to `true` to receive the data table and the generated SQL alongside the written answer. Required if you plan to read an exact value or validate the result. | Always send the `business_view_id` rather than the Business View name. Names can be edited; ids are stable. #### **Finding the Business View id** * Use `tellius_list_business_views` to search and page through the Business Views you have access to. * Each result carries its `business_view_id`. * To check that a Business View holds the metric and dimensions you need, call `tellius_get_business_view_details` for its full column schema, data types, and sample values. * Clients that support MCP resources can read the same information directly from `tellius://business-views` and `tellius://business-views/{id}/schema`. #### **Writing filters into the question** * Filters are not passed as separate structured fields. They go into the question text, and only the Business View id travels separately. * Each filter you selected becomes a short phrase in the question. * Filters set to "All" are simply left out. You do not need to write "for all products". Asking without naming a product already covers all of them. | Control | Selected value | Phrase to include | | ------- | -------------------- | --------------------------- | | Metric | Revenue | `Revenue` | | Product | All products | omit | | Product | *a specific product* | `for ` | | Region | National | omit | | Region | *a specific region* | `in the region` | | Period | *a quarter* | `for ` | | Period | *a date range* | `for through ` | Assembled, a question follows this shape: ``` [for ] [in the region] [for ] ``` {% hint style="success" %} Keep the wording identical for a given card. Use the same phrasing every time for the same metric, changing only the filter values. Consistent wording produces consistent SQL, which is what keeps a displayed number stable between refreshes. {% endhint %} #### **Reading the response** With `include_raw` set to `true`, the response carries three parts: * **A written summary:** A sentence answering the question, suited to a chat or drill-down view. * **A data table:** Columns and rows holding the actual values. * **The SQL:** The query Tellius generated and ran. The response is shaped roughly like this: ```json { "summary": "Revenue in the region for was ...", "data": { "columns": ["Region", "Quarter", "Revenue"], "rows": [["", "", 0.0]] }, "sql": "SELECT SUM(Revenue) ... WHERE ..." } ``` Read the exact field names from the `tellius_ask` output schema shown in your MCP client. A chart definition may also be returned. #### **Validating before you display** Check the response before rendering it as a number. **1. Confirm you received data, not a follow-up.** The response may come back asking a clarifying question, or asking the user to sign in. Treat either as "no value yet" rather than rendering it. **2. Check the SQL against your intent.** The returned SQL shows the filters and the aggregation that were used. Confirm they match what your interface asked for. This is the strongest guard against a misread question, and it is the reason to send `include_raw: true` even when you only need a single number. **3. Sanity-check the value.** Confirm it is numeric and within a plausible range. Where your data has a natural hierarchy, a rollup check works well: the parts should sum to the whole for the same metric and period. #### Questions appear in Tellius Each question asked through `tellius_ask` is saved as a conversation turn in Tellius. The exchange is visible in the Kaiya interface even when the user never opens Tellius directly, which keeps external activity auditable alongside in-product usage. ### Investigating "why": `tellius_deep_insight` `tellius_deep_insight` runs a multi-step agentic investigation rather than a single query. Use it for questions about causes and drivers, where a single aggregation would not answer the question. It takes the same shape of request as `tellius_ask` and returns the same shape of response. A deep insight plans, runs several steps, and validates its own findings, so a call can run for a few minutes on a large Business View. * **Set a generous client timeout.** A timeout tuned for a simple query will cut off a deep insight before it finishes. * **Avoid firing many deep insights at once.** Long-running calls hold resources for their whole duration. Queue them rather than launching a large batch in parallel, or fast queries issued at the same time may be left waiting. ### Running Kaiya Missions and workflows Saved Missions and workflows can be executed headlessly through `tellius_run_workflow`, passing the workflow id and any inputs it needs. A Mission can pause for input at two different points, and the tool you call to continue depends on which one paused it. **A question asked before the run starts** comes from the Mission's own defined inputs. Answer it by calling `tellius_run_workflow` again with the input filled in. **A question asked while the Mission is already running** comes from a step that requests input mid-execution. This kind of pause carries a `conversation_id`. When you see one, call `tellius_resume_workflow` with that same `conversation_id`. {% hint style="warning" %} Calling `tellius_run_workflow` again to answer a mid-run question starts a brand-new run instead of continuing the paused one, so the same question comes back and the Mission never completes. The presence of a `conversation_id` in the clarification is the signal to switch to `tellius_resume_workflow`. {% endhint %} ### **Scheduling delivery** `tellius_create_schedule` sets up recurring delivery of either a saved workflow or a stored ad-hoc question. You supply the name, the cadence, what to run, and where to send it. Creating the schedule records it. Tellius runs it on its cadence from then on and delivers the result to the channels you configured, through email, Slack, or Teams. To send to Slack or Teams, look up the channel ids first with `tellius_list_slack_channels` or `tellius_list_teams_channels`. Schedules listed through `tellius_list_schedules` are scoped to the calling user. ### **How your data is handled** **Where the MCP server runs.** The Tellius MCP server runs inside your Tellius deployment. The server holds no data of its own. It provides an MCP interface over existing Tellius capabilities and forwards each request to Kaiya, which does the work. **When a language model is involved.** The MCP server itself does not use a language model. Whether one is involved depends on the request. A question sent through `tellius_ask` uses a model to interpret it and generate the query. A request like `tellius_list_business_views` does not — it returns the list directly. Your administrator configures which model Kaiya uses under **Settings → Application Settings.** **What the model receives.** Business View schema is sent so the model can write the query, and query results are sent so it can summarize them or build a report. Underlying row-level data does not leave your environment. **Conversation history.** Questions asked through MCP are saved as conversation turns in Tellius and remain available in the Kaiya interface. # What Tellius can do through MCP Once your client is connected, these are the tools it can call. In addition to `tellius_ask` for questions, and the discovery tools to find the right Business View, there are additional tools to build workflows, schedule delivery, or manage saved memories. Some tools create, change, or permanently delete workflows and schedules. The access column marks which. #### **Discovery** | Tool | Access | What it does | | ----------------------------------- | --------- | ------------------------------------------------------------------------- | | `tellius_list_business_views` | Read-only | Search and page through Business Views. The starting point for most work. | | `tellius_get_business_view_details` | Read-only | Full column schema, data types, and sample values for one Business View. | | `tellius_list_datasets` | Read-only | Raw imported datasets, before they are modeled into a Business View. | | `tellius_list_connections` | Read-only | Configured data source connections. | #### **Ask and analyze** | Tool | Access | What it does | | ------------------------------- | ---------- | -------------------------------------------------------------------------------- | | `tellius_ask` | Read/write | Natural-language question answered as SQL and results. | | `tellius_deep_insight` | Read/write | Multi-step agentic investigation for "why" questions. | | `tellius_get_starter_questions` | Read-only | Suggested questions for a Business View, for users who are not sure what to ask. | | `tellius_send_feedback` | Read/write | Record a thumbs up or down on a previous Kaiya response. | #### **Workflows and Missions** | Tool | Access | What it does | | -------------------------- | ----------- | -------------------------------------------------------- | | `tellius_list_workflows` | Read-only | Paginated list of workflows and Kaiya Missions. | | `tellius_search_workflows` | Read-only | Search by name or description. | | `tellius_get_workflow` | Read-only | Full step detail for one workflow or Mission. | | `tellius_create_workflow` | Read/write | Author a new reusable multi-step workflow. | | `tellius_update_workflow` | Read/write | Change the name, steps, state, or Business Views. | | `tellius_delete_workflow` | Destructive | Permanent delete. | | `tellius_run_workflow` | Read/write | Execute headlessly. May pause for input before starting. | | `tellius_resume_workflow` | Read/write | Continue a run that paused mid-execution. | #### **Schedules** | Tool | Access | What it does | | ------------------------- | ----------- | ------------------------------------------------------------- | | `tellius_create_schedule` | Read/write | Recurring delivery of a saved workflow or an ad-hoc question. | | `tellius_list_schedules` | Read-only | Schedules belonging to the calling user. | | `tellius_get_schedule` | Read-only | Full delivery configuration for one schedule. | | `tellius_update_schedule` | Read/write | Pause, resume, or change cadence and delivery channels. | | `tellius_delete_schedule` | Destructive | Permanent delete. | #### **Channels, memory, and reference content** | Tool | Access | What it does | | ---------------------------------- | ---------- | ------------------------------------------------------------------------------------- | | `tellius_list_slack_channels` | Read-only | Channel ids for Slack delivery on a schedule. | | `tellius_list_teams_channels` | Read-only | Channel and team ids for Teams delivery on a schedule. | | `tellius_remember_user_preference` | Read/write | Save a memory (a rule, a definition, or an instruction) that later turns will recall. | | `tellius_list_user_memories` | Read-only | Review saved memories. | ### **Resources** Resources are addressable pieces of context a client can read directly, without calling a tool. | Resource | Contents | | ----------------------------------------- | ------------------------------------------- | | `tellius://business-views` | Live list of Business Views. | | `tellius://business-views/{id}/schema` | Column schema for one Business View. | | `tellius://datasets/{id}/schema` | Column schema for one dataset. | | `tellius://guides/tellius-capabilities` | What Kaiya can and cannot do. | | `tellius://guides/business-view-modeling` | Joins, column types, and modeling guidance. | | `tellius://guides/workflow-design` | How to write effective workflow steps. | ### **Prompts** A prompt is a starting point your client can offer, rather than something you type. Where tools are single actions your client calls one at a time, a prompt is a prepared sequence. It sets out the steps for a longer task and walks the client through them in order. This helps most when you know the outcome you want but not which tools get you there. | Prompt | What it walks through | | ------------------------ | --------------------------------------------------------------------- | | `tellius_setup_data` | Connection, then dataset, then Business View, then a first query. | | `tellius_analyze` | Discover data, explore the schema, then analyze. | | `tellius_build_workflow` | Clarify the goal, draft the steps, create the workflow, then test it. | ### **Quick reference** | Item | Value | | --------------------- | ------------------------------------------------------------------------------------- | | Protocol | MCP over streamable HTTP | | Endpoint | A URL ending in `/mcp` — get the full address from your administrator | | Setup | Point an MCP client at the URL and sign in. Nothing to install. | | Main tool for metrics | `tellius_ask` | | Request | `question` with filters in the text, plus `business_view_ids` and `include_raw: true` | | Authentication | Browser sign-in, once; token refreshed automatically | | Permissions | Runs as a Tellius user; row-level security applies | | Read the value from | The returned data table | | Validate with | The returned SQL, plus a rollup or range check | | Tools available | 25 tools, 6 resources, 3 prompts | # Kaiya Skills With Skills, you teach Kaiya how to reason about *your* business. Kaiya answers from your domain by combining pre-built domain ontologies and investigation approaches with what you teach it, what your data means, what it has learned over time, and what it remembers about how you work. Skills are the layer you author and control directly: domain ontologies, investigation approaches, and business logic that shape how Kaiya generates SQL, builds charts, writes summaries, and frames analysis. {% hint style="info" %} Skills are applied automatically. You do not invoke a skill manually. Like **Memory** and **Learnings**, the relevant skills are applied naturally during a Kaiya conversation, and you can review which ones were applied under the response's **thought process** dropdown. {% endhint %} ### How skills fit in: the Domain Reasoning Layer Skills are one part of Kaiya's **Domain Reasoning Layer.** The set of context layers that sit behind every briefing and every chat.
A tab bar lets you move between layers: **All layers**, **Skills**, **Phrase learning**, **Query learning**, and **Memory**. The **All Layers** view shows the full context graph with elements across all four layers, joined and continuously refining together. Below it, four cards summarize each layer, each with a **Manage** link: * **Skills** *(Taught)* Domain ontologies, investigation approaches, and business logic; pre-built with Kaiya, extended by what you teach it about your domain. * **Phrase learning** (*Defined)* Phrase-level patterns Kaiya learns from your team's vocabulary — business terms, synonyms, and shorthand mapped to the data model. * **Query learning** (*Confirmed)* Query patterns Kaiya has confirmed from your feedback. This includes preferred queries, business rules of thumb, what "good" looks like. * **Memory** (*Compounding)* Compounding context Kaiya carries across sessions. This is the longest-tail layer, which gets richer the more your team uses the system. {% hint style="success" %} When skills overlap, the precedence order is: **Custom skills > Domain skills > Behavioural Layer > Implementation Layer.** User-level customizations always win over broader defaults; the Implementation Layer (which defines core tool calls and platform functionality) sits at the foundation and is not overridden through user or domain skills. {% endhint %} ### **Inside the Skills layer: four context layers** When you open the **Skills** tab, the left **Context Layers** panel shows the four layers that feed Kaiya's reasoning for a request, from the foundational platform instructions through to your tenant's own skills: * **System Prompt.** The base instructions Kaiya uses when planning and summarizing. It is read-only reference, and it is split into two sub-layers: the **Implementation Layer** (the core tool calls and platform functionality that make Kaiya operate correctly across the platform) and the **Behavioural Layer** (Kaiya's default behaviour, which super users can tune when platform-wide behaviour needs adjusting). * **Business View Context.** The schema, grain, and vocabulary passed to Kaiya with the active Business View. It is set by the workspace and is read-only here. * **Domain Skill.** Industry-specific rules and defaults, curated by Tellius and shipped with the platform (described below). * **Custom Skill.** Your tenant's own skills, authored from the specific requirements of your deployment (described below). ### **Domain Skills vs Custom Skills** The difference is who owns them, who can edit them, and how they are structured. **Domain Skills** are curated by Tellius and ship with the platform. They hold industry-specific rules and sensible defaults for a vertical. A Domain Skill is organized into one or more **sections**, where each section has its own description and detail and teaches Kaiya one distinct thing. For example, one section for how to run a particular analysis and another for how to summarize the result. Domain Skills are editable by **super users only**; every other role sees them as read-only. **Custom Skills** are created by your own organization, based on the specific requirements of your deployment (your vocabulary, preferences, and business rules). A Custom Skill is authored directly in the tenant and, once published, applies to **every user in that tenant** rather than to a single person. A Custom Skill carries a description, a detail body, and one or more routing labels (described below). {% hint style="warning" %} A skill's layer (Domain or Custom) is chosen when it is created and cannot be changed afterward. Each skill also has a **Status** control, so it can be enabled or disabled without being deleted. {% endhint %} ### **Anatomy of a Custom Skill** * **Skill name.** A name for the skill. * **Description.** A short, human-readable summary of when and why the skill applies. The description is what routes the skill to the relevant Kaiya engine paths. * **Detail.** The skill definition itself — the instructions the engine executes. Accepts markdown. * **Labels.** One or more technical routing tags that determine which Kaiya engine path the skill applies to. * **Status.** A toggle to enable or disable the skill without deleting it. ### **What each Label controls:** | Label | What it shapes | | --------------------- | ------------------------------------------------------------------------------------------------------------------- | | Default | General behaviour where no more specific routing applies. | | SQL | SQL generation for standard textual queries. Also the routing label for Deep Insights analytical framing. | | SQL Editor | Semantic-cache queries — the fast path that returns within 3–5 seconds once the original query has been configured. | | SQL Reflection | Reflection logic applied to textual SQL queries. | | SQL Editor Reflection | Reflection logic applied to semantic-cache queries. | | Highcharts | Chart selection and formatting via the Highcharts rendering library. | | Chart Config | Legacy chart configuration (being phased out). | | Narration | How chart titles, summaries, and result narratives are written. | ### **How skills are layered and prioritized** A single request can match more than one layer at once. The layers resolve from the foundational platform instructions through to your tenant's own skills: **What each Label controls:** | **Layer** | **What it does** | | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | Layer 1a: System Prompt - Implementation | Defines core tool calls and platform functionality. The foundational layer that ensures Kaiya operates correctly across the platform. | | Layer 1b: System Prompt - Behavioural | Defines default Kaiya behavior across the platform. Can be tuned by super users when platform-wide behavior needs adjustment. | | Layer 2: Domain skills | Encodes vertical or Business-View-specific behavior. Scoped to a Business View. | | Layer 3: User skills | Per-user customizations. Overrides domain and behavioural layers at runtime when both apply. | When more than one applies, a loaded **Custom Skill overrides the Behavioural Layer**, and a Custom Skill takes precedence over a Domain Skill where both apply. The Implementation Layer sits at the foundation and is never overridden by a skill. ### **Who can manage skills** Skill management is role-based. **Super users** see and manage all four context layers, including Domain Skills. **Admin users** can manage Custom Skills. **Power users** and other roles can see the skills applied to their conversations but cannot add or edit them. # How to create a new Skill The **Skills & Context** area is where you see and manage everything Kaiya uses to reason about your business. You reach it from the tab bar at the top of the page: **All layers**, **Skills**, **Phrase learning**, **Query learning**, and **Memory**. ### The four context layers The left-hand **Context Layers** panel lists the four layers that feed Kaiya's reasoning for a request, ordered from the foundational platform instructions through to your own tenant's skills. ### System Prompt (read-only) The **System Prompt** layer holds the base instructions Kaiya uses when planning and summarizing. It is read-only reference and is divided into two sub-layers: * **Implementation Layer:** the core entries that make Kaiya operate correctly, such as *Agentic Insights – Planner*, *Agentic Insights – Workflow Planner*, *Agentic Insights – Summary*, *Agentic Insights – WebSearch*, and *CMS – Anchor Decision*.
* **Behavioural Layer:** Kaiya's default behaviour across the platform.
Selecting any entry opens a read-only view with a short description and the full instruction text shown as a numbered, scrollable block with a line count and a **Copy** button. You cannot edit anything in this layer from this page. ### Business View Context (read-only) The **Business View Context** layer holds the schema, grain, and vocabulary passed to Kaiya with each active Business View. Selecting a Business View opens a read-only view. The content block shows that Business View's tables, measures, dimensions, and any model-specific notes (including warnings such as the data engine in use. Like the System Prompt, this layer is reference only) it is set by the workspace and cannot be edited here.
#### Domain Skill (curated by Tellius) A **Domain Skill** holds industry-specific rules and sensible defaults for a vertical. Only super users can change it; everyone else sees it as read-only. A Domain Skill is made up of a **Description** and one or more **Sections** (covered in detail below). Its lifecycle is shown with a **Live** badge and a **Revert to draft** button. #### Anatomy of a domain skill A domain skill has: * **Name:** the name of the domain skill. * **Description:** a single line describing what the skill does. * **Sections:** one or more sections, each with its own name, description, and detail. #### What a section is A **section** breaks a domain skill into the distinct things it teaches Kaiya. When you click **Add section**, a **New section** is created in place with its own editable **Name**, its own **Description**, and its own **Detail** body (markdown). You author this content directly inside the domain skill. #### Create a domain skill
1. Click on **New skill**. 2. Under **Layer**, choose **Domain Skill** (*Curated by Tellius · super only*). 3. Enter a **Name** for the skill. 4. Write the **Description** one line on what the skill does (placeholder: *"Describe what this skill does…"*). 5. Click **Add section**, give the section a name, and fill in its **Description** and **Detail**. Click **Done** to collapse it. Repeat for each distinct thing the skill should teach. Before you add any, the area reads *"No sections yet — add the sections that hold this skill's rules and vocabulary."* 6. Click **Create Skill** to save, or **Cancel** to discard. {% hint style="warning" %} Domain skills are **editable by super users only**. Other roles can read them but cannot create or change them. {% endhint %} #### Custom Skill (your tenant's own) A **Custom Skill** captures your organization's own vocabulary, preferences, and business rules. The detail header shows the skill's lifecycle state, when it was last updated, and the context it is associated with — for example, *Live · updated 5h ago · Chest*. A Custom Skill is made up of a **Description**, a **Detail** body, and one or more **Labels** (covered below).
#### Anatomy of a custom skill Each custom skill has the following parts: * **Name:** a short name for the skill * **Description:** a single line stating when and why the skill applies * **Detail:** the actual instructions Kaiya follows when the skill applies. It accepts markdown and is shown as a numbered block with a line count and a **Copy** button. * **Labels:** one or more routing tags that control which parts of Kaiya receive this skill (auto-generated by Kaiya after you publish a Skill). #### Labels Labels control routing. They determine which Kaiya pipeline steps receive a skill's detail when they run. Labels are auto-generated: when you write a skill's details and description, Kaiya reads them and assigns the labels it judges relevant. You can then **override** the result with the checkboxes: adding or removing labels yourself. For example, a skill described as applying to PDF exports is auto-tagged **PDF Export**, which you can confirm or change.
Open the dropdown to see the options: * **Simple Analysis:** routes the skill to the standard, single-step analysis path. * **Chart Generation:** routes the skill to the chart-building step. * **Summary Generation:** routes the skill to the result-summary step. * **PPT Export:** routes the skill to the PowerPoint export step. * **PDF Export:** routes the skill to the PDF export step. * **DOCX Export:** routes the skill to the Word export step. * **Deep Analysis:** routes the skill to the multi-step Deep Insights analysis path. * **Deep Summary:** routes the skill to the Deep Insights narrative-summary step. * **Default:** applies the skill to all prompts in the engine, rather than to one specific step. This is the broad, always-on routing; every other label targets a single capability. Select one or more options using the checkboxes. Each selected label appears as a removable chip, and you remove one by clicking the × on its chip. #### Create a custom skill
1. Click on **New skill**. 2. Under **Layer**, choose **Custom Skill** (*Your tenant's own*). 3. Enter a **Name** for the skill. 4. Write a one line description on what the skill does and when it applies 5. Fill in the **Detail:** the rules, vocabulary, and routing the skill should follow. It accepts markdown with YAML front-matter 6. Click **Create Skill** to save, or **Cancel** to discard. While you are creating it, the skill appears in the left list as **Untitled skill** with a **NEW** tag. {% hint style="success" %} Skills move through two states: Draft and Live. A live, published, active skill, shown with a green dot in the left list and a **Live** badge in the detail view. Use **Revert to draft** to pull a Live skill back into draft state for editing. {% endhint %} {% hint style="info" %} Enabled skills are matched and **applied automatically** during a Kaiya conversation, based on each skill's description and label routing, in the same way Phrase learning, Query learning, and Memory are applied. To see which skills and other context were used in a given answer, open the **thought process** dropdown on that Kaiya response. {% endhint %} When more than one layer applies to the same request, they resolve in this order: **Custom Skill › Domain Skill › Behavioural Layer**, with the **Implementation Layer** as the foundation that is never overridden by a skill. {% hint style="info" %} Skills are selected by matching their description to the query intent, then routed by their auto-generated label to the relevant engine path. For **Deep Insights**, skills are scoped to the planner only. The SQL executor and summary generator run with skills disabled, so any downstream change results from the changed plan rather than those steps reading a skill. {% endhint %} ### How Domain Skills and Custom Skills relate The difference between custom and domain skills are how they are organized and who owns them: * A **Custom Skill** is a skill at the **custom level:** your tenant's own, authored directly in the Custom Skill layer. * A **Domain Skill** is a namespace (an organizing container) at the domain level, curated by Tellius. The **sections** inside a domain skill are themselves skills at the domain level. The same underlying object type as a custom skill, grouped under the domain skill's name. Each skill stays self-contained. Grouping sections under a domain skill organizes them. # Kaiya's persistent memory Learn how Kaiya Persistent Memory personalizes AI-driven analytics with reusable context, semantic understanding, and smarter workflows. When you're analysing data, you often establish context that is specific to your organization, your data, or your analytical preferences. Which metric to use when someone says "sales." How to define "longer delivery times." Whether a particular query should route to a direct SQL answer or a Deep Insight workflow. Without persistent memory, this context is lost at the end of every conversation, and you re-explain the same things each time. Kaiya has a persistent memory layer that survives across conversations. You define a business rule, a metric preference, an entity definition, or a routing instruction once, and Kaiya applies it automatically in every future session within the scope you choose. Memories are managed through the **Memory Management** tab, located within the **Kaiya → Manage Learnings** page. They can be created manually, extracted from uploaded documents, or saved automatically from conversational interactions such as clarifications and workflow corrections. ### Accessing Memory Management The Learnings page has three tabs: **Phrase Learnings, Query Learnings**, and **Memory Management**. Click the **Memory Management** tab to view and manage all stored memories.
The Memory Management tab displays all memories in a table with the following columns: * **Type**: The classification of the memory (for example, **Preference, Constraint, Instructional, Fact, Ontological, Procedural**, or **Insight**). Each type is displayed as a colored label. * **Content**: This is the actual instruction, definition, or preference that Kaiya will use. * **Scope**: Where the memory applies. Displayed as a colored label: System (global across all users), Business View (tied to a specific BV), or User (applies only to the individual who created it). * **Status**: A toggle switch indicating whether the memory is active. When toggled on, the memory is live and Kaiya uses it. When toggled off, the memory is stored but inactive. * **Updated**: The date and time the memory was last modified. The table includes filtering and sorting controls at the top: * **Sorting**: Sort by Creation Date (Newest First or Oldest First). * **Type filter:** Filter by specific memory types (All Types, or select individual types). * **Scope filter:** Filter by scope (All Scopes, System, Business View, or User). * **Status filter:** Filter by active/inactive status (All Status, Active, or Inactive). * **Search:** A search bar to find memories by keyword. * **Reset:** Clears all applied filters. Each memory row has a three-dot menu on the right that opens options to edit or delete the memory. ### Memory Types Each memory is classified into a type that tells Kaiya how to use it. The type determines whether the memory is treated as a hard rule, a soft preference, a factual definition, or a routing instruction. The following types are available: **Preference:** A default behavior that Kaiya applies automatically but that can be overridden by the user in a specific conversation. Preferences are the most common memory type and are created automatically when you respond to clarification questions. For example, "For analyzing cancellation ratios, use planned delivery lead time (Product spec) instead of actual delivery lead time in days (Fulfillment)." **Constraint:** A rule that Kaiya must always follow without exception. Constraints are stronger than preferences and cannot be overridden conversationally. Use constraints for business logic that should never vary. For example, "Always break down cancellation analysis by program type and income bracket." **Fact:** A factual statement about your data or business that Kaiya should treat as ground truth. Facts are used to resolve ambiguity when Kaiya encounters terms or entities that could have multiple interpretations. For example, "In the EV dataset, Model Y refers to the Tesla Model Y Long Range variant only." **Instructional:** A routing or workflow instruction that tells Kaiya how to handle specific types of queries. Instructional memories are created automatically when you approve or correct Kaiya's workflow routing decisions (for example, when Kaiya proposes a Deep Insight but you redirect it to a direct SQL query). For example, "For questions like 'show me national Sales', route to text-to-SQL, not Deep Insight." **Ontological:** An entity definition or synonym mapping. Ontological memories prevent Kaiya from applying incorrect default definitions to business terms that have specific meanings in your organization. For example, "NBRx market share means new-to-brand prescriptions as a share of total prescriptions within the therapeutic area, not overall portfolio." **Procedural:** A step-by-step instruction for how Kaiya should approach a specific type of analysis or task. For example, "When calculating market share by territory, first filter to the active formulary, then aggregate by territory name, not territory ID." **Insight:** A saved analytical observation from a previous conversation. Insight memories are available for Kaiya to reference or cite in future conversations when the topic is relevant. For example, "Q3 territory underperformance was driven primarily by HCPs in Decile 4-6 who reduced call frequency after the formulary change." ### Memory Scope Every memory has a scope that determines who it affects and what data it applies to. Scope is set when a memory is created and can be changed later by editing the memory. | **Scope** | **Who It Affects** | **When to Use** | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | User | Only the individual user who created the memory. Other users on the same Tellius instance are not affected. | Personal analytical preferences. For example, a specific user who always wants to see revenue in EUR rather than USD. | | Business View | All users who query the specified Business View. The memory is tied to a specific BV selected from a dropdown when the memory is created or edited. | Business logic that is specific to a dataset. For example, a definition of "market share" that is calculated differently in the Commercial BV versus the Clinical BV. | | System | All users across the entire Tellius instance, regardless of which Business View they are querying. System-scope memories are global. | Organization-wide rules and definitions. For example, a company-wide standard that "revenue" always means net revenue after returns. | {% hint style="info" %} When a memory is scoped to Business View, a BV selector dropdown appears in the memory creation or editing dialog, allowing you to choose which BV the memory applies to. Memories scoped to a BV are only active when Kaiya is working with that specific Business View. {% endhint %} {% hint style="warning" %} When memories at different scopes conflict, more specific scopes take precedence. A User-scope memory overrides a System-scope memory for that individual. A Business View-scope memory overrides a System-scope memory when that BV is active. {% endhint %} ### How Kaiya uses memories at query time Memories are consumed at two points in Kaiya's query processing pipeline: #### Query routing When a question is submitted, Kaiya determines what type of workflow to use. Instructional-type memories are checked at this stage. If a matching Instructional memory exists, Kaiya applies it automatically instead of using its default routing logic. #### Query execution and context resolution During the analysis planning phase, Kaiya retrieves all active memories that are relevant to the current query and BV context. Preference and Fact memories are applied here. This means that over time, as you build up a library of preferences and facts, Kaiya asks fewer clarification questions because the ambiguities that would normally trigger them have already been resolved by stored memories. ### Frequently Asked Questions #### Can I deactivate a memory without deleting it? Yes. Toggle the **Status** of the required memory. The memory is retained in **Memory Management** but is no longer used by Kaiya. You can reactivate it at any time by toggling it back on. #### Can I see which memories Kaiya used for a specific query? Memories that influenced a query's execution are reflected in Kaiya's **Thought Process** and step-by-step execution log. If a memory was used to skip a clarification or route a query, the relevant step in the execution log references the stored preference. #### Do memories from one Business View affect queries on other Business Views? Only if the memory is scoped to **System** (global) or **User**. Memories scoped to a specific Business View are only active when Kaiya is working with that BV. A preference defined for the Commercial BV does not apply when you query the Clinical BV. #### Can I use memories to teach Kaiya custom terminology? Yes. This is exactly what Ontological-type memories are for. If your organization uses a term that differs from the column name in the BV (for example, "market" means something specific in your context), you can create an **Ontological** memory defining it. Kaiya uses this definition to resolve the term correctly in future queries. # How to create a new memory Learn how to add memories to Kaiya. There are five ways to add memories to Kaiya. Two are manual (you create them directly) and the rest are conversational (Kaiya proposes them during interactions and you approve). Under **Kaiya**, click to open the side panel and select **Manage Learnings** in the bottom. The following window will be displayed.
Click on **Add Memory** button. The following two options will be displayed.
### Import document This method lets you upload a file containing business rules, data dictionaries, glossaries, or any reference material, and Kaiya extracts individual memory items from it automatically. 1. The following window will be opened.
2. Optionally, select a Business View from the dropdown at the top. This scopes the extracted memories to that BV. If left blank, the scope defaults based on the content. 3. Drag and drop a file into the upload area, or click to browse. The upload limit is 1 file up to 10 MB. Supported file types: PDF, DOCX, XLSX, CSV, MD, PPTX, HTML. 4. Kaiya parses the document and extracts individual knowledge items. Each item is displayed in a preview table with columns for **Include** (checkbox), **Type** (auto-classified), **Content** (the extracted text), and an **Edit** button.
5. Review the extracted items and edit individual items if needed. 6. Click **Add to Knowledge Base** to save all selected items. ### Describe Memory This method lets you type a memory directly in natural language, and Kaiya extracts structured knowledge items from your description. 1. A dialog opens with a Business View dropdown (optional) and a rich text editor labeled **"Your Text"** with formatting options. For example: "When analyzing revenue, always include YoY comparison and breakdown by region".
2. Type or paste your memory content into the editor. You can enter a single instruction or a longer block of text containing multiple rules. 3. Click **Extract Memories**. Kaiya parses your text and presents the extracted knowledge items in the same preview table as the Import Document flow (with **Include**, **Type**, **Content**, and **Edit** columns). 4. Review, edit if needed, and click **Add to Knowledge Base** to save. ### Clarification-based memories This is the most common way memories are created. When Kaiya encounters ambiguity in your question, it asks a clarification question with numbered options. Your response becomes a memory that Kaiya applies automatically in future conversations. When your question references a term that maps to multiple columns or definitions in the Business View, Kaiya pauses and asks for clarification before proceeding. The clarification appears with "I need some clarification before proceeding" followed by numbered options. You select your choice by typing out your option.
#### **Kaiya asks whether to remember the clarifications** After Kaiya completes an analysis that involved one or more clarifications, a **"Should I remember this?"** button appears at the bottom of the analysis results, next to the thumbs up/down feedback icons.
Clicking this button triggers the **"Worth Remembering"** prompt as follow, allowing you to save relevant clarifications and preferences from the current conversation.
* The prompt lists each clarification you made during the conversation as a checkbox item. * You select which clarifications you want Kaiya to remember and deselect any you do not. * There is also an **"Add another preferences"** section with a text input where you can type additional preferences beyond the ones Kaiya suggested. Click **Remember** to save the selected items. Kaiya confirms with a *"Locked into Memory!"* banner. The memories are saved under **"Preference"** type. ### Workflow-based routing When Kaiya routes a query to a specific workflow (for example, Deep Insight or text-to-SQL), and you correct that routing, Kaiya can persist the correction as a memory. For instance, if Kaiya proposes sending your query to **Deep Insight** but you indicate it should be a direct SQL query, Kaiya asks whether you want to remember this routing preference. If you confirm, the correction is saved as an Instructional-type memory and applied automatically to similar queries in future sessions. ### Explicitly command Kaiya to "Memorize it" You can also create memories directly within a Kaiya conversation by using the "memorize it:" prefix in the chat input. Type "Memorize it:" followed by the statement you want Kaiya to remember. For example:
Kaiya saves the statement as a memory. Kaiya automatically classifies it as **Instructional** based on the content. ### Editing a Memory To edit an existing memory, click the three-dot menu on the memory row in the **Memory Management** table and select **Edit**. The following dialog opens:
* **Content:** A text area containing the memory text. You can modify the text directly. * **Type:** A dropdown to change the memory type. Available options: Constraint, Preference, Fact, Instructional, Ontological, Procedural, Insight. * **Scope:** Radio buttons to select User, Business View, or System. * **Business View:** A BV selector dropdown that appears when the scope is set to Business View. Select the specific BV this memory applies to. * **Status:** Toggle on to keep the memory active; toggle off to deactivate it without deleting. Click **Save Changes** to apply your edits, or **Cancel** to discard. {% hint style="info" icon="square-dashed-circle-plus" %} When a new memory is being saved, whether from a conversation, manual entry, or document import, Kaiya runs a semantic similarity check against all existing memories. This prevents duplicate or near-duplicate entries from accumulating over time. {% endhint %} # Automatic semantic cache Learn how Automatic Semantic Cache speeds up Kaiya's response time for questions that are structurally similar to ones already answered. Semantic Cache is an automatic caching layer that speeds up Kaiya's response time for questions that are structurally similar to ones already answered. When Kaiya resolves a question for the first time, the generated SQL is stored alongside the natural language query. When a similar question is asked later (by the same user or any other user on the same Business View), Kaiya reuses the cached SQL as a starting point instead of generating it from scratch. #### How it works * When a question is submitted, Kaiya checks whether a semantically similar question has already been resolved on the active Business View. * If the similarity crosses an internal threshold, the cached SQL becomes a reference point. * Instead of running the full query resolution pipeline, Kaiya routes the question through a faster, lighter model that starts from the cached SQL and adapts it to the current question, adjusting for different date ranges, dimension values, or filter combinations. The query structure is reused; the specifics are recalculated. This means filter variations return correct, current results rather than stale cached output. A cached query for **`"TRx values for Product A in Q1 2023, broken down by month and region"`** can be adapted to answer **`"TRx values for Product B, broken down by month and region"`** without re-running the full resolution pipeline. {% hint style="info" %} When Semantic Cache is used, Kaiya indicates this in the **Thought Process** section. The **Thought Process** section displays a note highlighting **Semantic Cache,** followed by the original cached question text. {% endhint %}
#### Scope of the cache The cache is **shared per Business View, not per user**. When one user resolves a question, every other user querying the same BV benefits from the cached result going forward. Each user does not pay the full resolution cost independently. This is where the performance benefit compounds; the questions that slow down individual users tend to be the same questions the rest of the team is also asking. #### When semantic cache helps most Semantic Cache delivers the largest benefit on high-frequency questions where the analytical intent is the same across sessions even if the filter values change. Examples: * "What were last week's TRx by territory?" — asked every Monday by multiple regional directors * "Show top 10 products by revenue this quarter" — asked across sales and commercial ops * "What is call coverage vs target for this week?" — pulled by field force managers daily {% hint style="warning" %} Whenever the underlying Business View is modified, the affected cache entries are automatically invalidated. The next question resolves fresh against the updated schema. Kaiya will never return a result built on SQL that references columns or relationships that no longer exist. {% endhint %} # Kaiya Voice Mode Use Kaiya Voice Mode in Tellius to ask questions with natural speech, get real-time voice responses, and explore data through hands-free, conversational analytics. Kaiya supports a voice-first conversational experience that lets you ask your questions naturally instead of typing them. Voice Mode goes beyond basic dictation: it handles natural speech patterns including pauses, mid-sentence corrections, filler words, and changes in direction, and it supports multi-turn voice conversations where you can ask follow-up questions without restarting. Kaiya will respond back in voice, making it a true two-way conversation. ### **How to use Voice Mode** 1. Under **Settings**, Voice Mode can be enabled in your environment (check out [this](/settings/advanced/kaiya#voice-assistant) page) by your admins. 2. Once done, you will see a voice input option in the Kaiya interface. 3. Click or tap the voice button and speak your question naturally. You do not need to use precise, structured language; Kaiya is designed to interpret conversational speech and extract the analytical intent.
You can change direction mid-question, and Kaiya will follow. For example, you might say *"How is TRx trending in the Northeast?"*, then follow with *"Actually ignore that... Show the top districts this month"*, and Kaiya will discard the first question and process the second without requiring you to start a new conversation. ### **Actions in Voice Mode** When conversing with Kaiya in voice mode, a purple overlay window appears over the Kaiya interface. The window displays the Kaiya logo with a "Listening..." indicator that confirms Kaiya is actively listening for your voice input. At the bottom of this window, three control buttons are available, along with an additional option to minimize the window.
**Mute:** The microphone button on the left lets you mute and unmute your microphone during the voice conversation. Your conversation context is preserved while muted. **Open Transcription:** The chat bubble button in the center opens the live transcription view within the voice mode window. When activated, the window expands to display a running transcript of the entire voice conversation, showing both your spoken questions and Kaiya's spoken responses as text bubbles. The transcript updates in real time as the conversation progresses.
**Exit Voice Mode:** The X button on the right ends the voice mode session and closes the voice overlay window entirely. You are returned to the default Kaiya text-based interface. Your conversation history from the voice session remain visible in the conversation thread. **Minimize:** The minimize button (located in the top-right corner of the voice mode window) collapses the voice overlay into a smaller floating element so that you can continue exploring. Voice mode continues to run in the background; Kaiya is still listening and responding to your voice input even while minimized. Click the button again to restore the full voice mode window.
### **Supported Voice Providers** Kaiya supports two voice processing options: * **GPT Realtime** is the preferred voice option, providing real-time voice-to-voice interaction. * **Deepgram** is an alternate option that supports multiple voice profiles. When Deepgram is configured, admins can define domain-specific key terms (such as drug names or product names) in the Deepgram Configuration to improve transcription accuracy for industry-specific vocabulary. {% hint style="warning" %} The voice provider will be configured by your admins. {% endhint %} ### **When you should use Voice Mode** Anytime! Voice Mode reduces friction for on-the-go workflows where typing is inconvenient. It is particularly valuable for: * Field teams who need quick answers before a meeting * Mobile users who are reviewing data while multitasking * Faster "brain dump" style exploration where you want to rapidly ask multiple related questions without pausing to type. # Kaiya Web Search Kaiya can augment its analytical responses with information retrieved from the web when a question depends on external, time-sensitive context.
{% hint style="warning" %} This capability is designed to ground and parameterize your analytics; not to act as a general-purpose internet search assistant. {% endhint %} ### **How web search works** When Kaiya detects that your question requires fresh or external context to answer accurately, it automatically triggers a web search to fetch important "anchor" details. These anchors include information such as * Event date ranges (for example, when a specific hurricane made landfall) * Policy effective dates (for example, when a regulatory change went into effect) * Geography or scope details (for example, which states were affected by a policy) * Timing windows (for example, the exact dates of a holiday week or promotional period). Kaiya then uses these anchors to run the correct structured analysis against your internal data. For example, it might use the anchored dates to set the right pre/post comparison windows, filter results to the impacted regions, or align your analysis to a policy start date. ### **What it means for you** You can ask questions the way you naturally would, without needing to look up dates or manually apply filters. For example: * If you ask *"Did Thanksgiving impact TRx for Product X?"*, Kaiya can look up the exact Thanksgiving dates and apply a properly anchored comparison window in your internal TRx analysis. * If you ask *"What happened to sales after the hurricane?"*, Kaiya can find the hurricane's date range and affected regions, then filter and compare your sales data accordingly. * If you ask *"Show me the trend since the policy change"*, Kaiya can look up when the policy took effect and use that as the starting point for the trend analysis. ### **How Kaiya remembers the web anchors** When Kaiya retrieves anchor details from the web, it stores them with a freshness-based Time-To-Live (TTL) that determines how long the anchor remains valid within the conversation. The TTL is assigned based on how time-sensitive the information is: * **High-freshness anchors** are data points that change rapidly, such as stock prices, exchange rates, or live event scores. These refresh quickly and have a short TTL because the information may become stale within hours or even minutes. * **Medium-freshness anchors** are data points that change infrequently but are not permanent, such as policy effective dates, regulatory thresholds, or quarterly earnings dates. These persist longer within the conversation because the underlying information is unlikely to change during a single analytical session. * **Low-freshness anchors** are historical facts that do not change, such as the date a hurricane made landfall, when a specific law was enacted, or when a company was acquired. These persist for the full duration of the conversation because the information is permanent. This TTL-based approach ensures that follow-up questions within the same conversation thread use the same dates, scope, and context as the original question. You do not need to re-state or re-look up the anchor; Kaiya reuses it automatically until the TTL expires or the conversation ends. {% hint style="warning" %} Web search can be enabled by admins from the **Settings →** **Advanced →** **Kaiya**. It is only triggered when Kaiya determines that external context is needed; it does not fire on every question. {% endhint %} Web search anchors are one type of context that Kaiya retains during a conversation. But Kaiya's memory extends well beyond web search results. Check out [this](/kaiya/how-kaiya-remembers-your-context) page for the full scope of how Kaiya tracks and reuses context across your conversation. # How Kaiya remembers your context Learn how Kaiya remembers your context in Tellius—using past interactions, preferences, and data history to deliver personalized, consistent, and relevant insights. Kaiya maintains a short-term memory system that tracks context across every turn in your conversation. This means follow-up questions work naturally; you do not need to repeat setup, re-state filters, or re-specify the scope of your analysis when asking the next question. Kaiya remembers what you have already established and builds on it. ### **What Kaiya remembers?** Kaiya's memory tracks four categories of context across your conversation: 1. **Conversation context.** Kaiya tracks the metrics, dimensions, filters, and entities from earlier in the conversation. If you asked about **TRx for Product X** in the **Northeast**, and then ask *"How about the Southeast?"*, Kaiya knows you mean **TRx for Product X**. The metric and product are carried forward; only the geographic filter changes. You do not need to re-specify everything from scratch. 2. **Web search anchors.** When Kaiya retrieves an anchor from the web (as described in the [Web Search section](/kaiya/kaiya-web-search)), it stores that anchor in short-term memory with a freshness-based TTL. High-freshness anchors like stock prices refresh quickly. Medium-freshness anchors like policy effective dates persist longer. Historical events persist for the full conversation. This ensures follow-up questions use the same dates and scope as the original question without Kaiya needing to re-search or re-estimate them. 3. **Cross-capability context.** Kaiya retains context when you switch between different Kaiya capabilities within the same conversation. If you run a **Deep Insight** and then ask **"Now break that down by district"**, Kaiya carries the analytical context forward from the **Deep Insight** into the follow-up query. If you run an analytics query and then ask for a summary, Kaiya includes the results from that query in the summary. Context flows seamlessly across **Deep Insights**, direct analytics queries, metadata questions, and summaries within the same thread. 4. **Implicit definitions.** Kaiya also tracks the implicit analytical frame you have established through your questions. This includes the scope you are working in (such as a specific region, payer segment, or store cluster), the comparison frame (such as pre versus post, forecast versus actuals, or year-over-year), and the business logic for how metrics are being calculated or interpreted. ### **How is this different from basic follow-up features?** Basic follow-up features in most analytics tools carry forward simple input parameters: the product you selected, the time range you specified. They work for narrow, predictable queries. Kaiya carries forward computed context, not just input parameters. This distinction is important because it enables three types of follow-ups that basic tools cannot handle: * **References to prior results.** If Kaiya showed you a chart, it remembers the specific output. You can ask "Which region had the biggest drop?" and Kaiya references the data from the prior result to answer the question. You do not need to re-run the analysis or re-describe the chart. * **Anchors from external lookups.** If Kaiya searched the web for a policy date or an announcement date, it remembers that date for follow-ups. You do not need to re-trigger the lookup or manually specify the date in your next question. * **Multi-step reasoning chains.** If Kaiya ran a multi-step analysis (for example, an SQL query, then Python processing, then a visualization), it remembers the intermediate steps. Follow-up questions can reference any part of that chain. You can ask about the raw data, the computed output, or the visualization, and Kaiya knows which part of the chain you are referring to. ### **Structured memory scaffolding** Under the hood, Kaiya's memory system is built on three core memory types that provide structure to how context is stored and retrieved: * **Ontological memory** stores definitions, relationships, synonyms, and formulas related to your data. This helps Kaiya understand that "revenue" and "sales" might mean the same thing in your organization, that a specific calculated column uses a particular formula, or that two fields have a parent-child relationship. Ontological memory ensures Kaiya interprets your terminology consistently throughout the conversation. * **Instructional memory** stores user preferences, administrator-defined constraints, and business rules. For example, a rule like "always exclude internal test accounts from patient counts" or a formatting preference like "show currency values in thousands" can be stored in instructional memory and applied automatically whenever relevant. These act as persistent guardrails that keep Kaiya's outputs aligned with your organizational standards. * **Reference memory** stores results from external lookups (including web search anchors) and prior analytical outputs. This enables Kaiya to reuse a date it looked up from the web earlier in the conversation. ### **How Kaiya retrieves relevant memory?** Kaiya retrieves the right context from memory in two ways: **Always-on rules (deterministic overlays).** Some saved context is automatically included every time Kaiya runs in a specific situation. For example, when you are working with a particular Business View, Kaiya may always apply certain filters, definitions, or business rules that have been configured for that Business View. **Smart lookup (semantic retrieval).** For context that is not always relevant, Kaiya searches its saved memory and retrieves only what is relevant to your current question. This works semantically, meaning Kaiya can find relevant context even if the words in your question do not exactly match the words used when the context was originally stored. For example, if you previously established that "growth" means percentage change year-over-year, and you later ask about "the increase rate", Kaiya can match those concepts and apply the same definition. {% hint style="success" %} ### **What this means for you?** You can ask multi-step, multi-turn questions without re-stating context. Each question builds on what came before. Kaiya handles follow-ups without repetition, maintains continuity when you switch between different analysis types within the same thread, and delivers more coherent answers across longer, complex exploratory workflows. {% endhint %} # Get familiar with our Search interface Explore the Tellius Search interface—learn how to use the search bar, voice queries, Business Views, and guides to run natural language data searches.

Tellius Search interface

1. **Business View dropdown** The required Business View that is associated with the search queries can be chosen from the dropdown list. If you choose a specific Business View, then the results for all your subsequent queries will be searched from that particular Business View. 2. **Search bar** The search bar is the place where you type in your search query in natural language. 3. **Voice-based query** Clicking on the mic icon will allow you to provide voice-based search queries. Tellius will comprehend your voice query and convert it into text. 4. **Search guide** The search guide serves as a beginner's reference for possible search queries that could be executed from the selected Business View. 5. **How-to Search** How-to Search is a collapsible section that breaks down how you can structure and phrase your search queries. 6. **Business Views** - List of all the existing Business Views. 7. **Search guide -** To view and customize Search Guide 8. **Search history** - List of recently executed search queries. # Understanding Tellius Search Discover the power of natural search with Tellius. ## What is natural search? Natural search refers to user interactions with a system using everyday spoken language, akin to executing a Google search. This contrasts with traditional query languages that employ a restricted vocabulary. Understanding and processing natural search queries, which encompass a broad vocabulary, is a complex task. Tellius has addressed this challenge by developing a sophisticated search engine capable of interpreting natural language. ## How Tellius handles natural search? Our Search module integrates the following advanced aspects and empowers users with a highly intuitive, efficient, and responsive search experience. ### Interactive search bar * In Tellius, the Search bar is designed to be highly interactive. Each word you type is automatically transformed into a color-highlighted token. * Each word in your query is recognized as an individual token. These tokens are interactive elements * By treating each word as a separate entity, the system can more accurately identify and present results that are most relevant to your specific query. * Click on any token to explore and select alternative suggestions, effectively refining or altering your query for a more targeted analysis. ### Deploying NLU and NLP * Natural Language Understanding (NLU) streamlines your search by understanding and classifying your query's purpose, ensuring that the most relevant results are displayed. * Natural Language Processing (NLP) converts your natural language questions into a format the database can understand, using advanced technology to recognize and fix any errors in your query. ### Auto-correcting queries * The search bar is equipped to understand queries written in natural, conversational language. * Tellius smartly interprets your queries, automatically adjusting them into a format it can process. * The search engine identifies and suggests the next possible keyword to offer an intuitive and efficient search experience. * There’s no fixed format - even if your query isn't phrased perfectly or fully formed, Tellius is designed to grasp your intent. This flexibility means you can phrase your questions as you would in a conversation, and still expect precise, accurate results. ### Auto inference * In addition to displaying the relevant charts for each query, Tellius goes a step further. It actively runs insights for certain types of queries, making your analysis richer and more meaningful. * Automatically infers the intent of your question, choosing the most suitable format for displaying results—charts, tables, or insights. * Identifies and provides the most appropriate visual representation (like pie charts, bar charts, line charts, maps) for your query, accommodating various ways of question formulation. ### Active Speech Recognition (ASR) integration * Tellius incorporates ASR technology that allows users to vocalize their queries instead of typing them, facilitating a more natural and accessible search process. * If you pause, break, or your query is incomplete, Tellius patiently waits. Once you resume and finish your query, it seamlessly interprets the entire question and generates the analysis you need. ### Efficiency with Fast Query Engine (FQE) Built into Tellius architecture, the FQE is designed for rapid search and visualization. It utilizes caching, indexing, and partitioning to ensure efficient data access patterns and low latency. # Search Guide Explore the Tellius Search Guide—use curated query templates to learn patterns, improve natural language search, and generate faster, more accurate insights. The Search Guide serves as the initial reference point for users, offering a curated selection of ready-to-use search queries from the selected Business View. It significantly simplifies and accelerates user onboarding by presenting tailored queries, effectively addressing the 'blank-slate' challenge. ### **Categorizing queries in the Search Guide** Upon selecting the Search tab in Tellius, users are greeted with a set of nine distinct cards, each representing a category of ready-to-implement search queries. The structured categorization of queries not only enables users to select the most relevant search queries but also helps users quickly overcome the initial uncertainty of query generation.

Categories in Search Guide

1. **Top/Bottom Analysis:** These queries utilize "top n" and "bottom n" keywords, ideal for identifying highest and lowest performers.\ *Example: "Show me the top 5 best performing items of Q4 2023."* 2. **Comparisons and Filters:** This category involves "compared to" and "vs" keywords for direct comparisons.\ *Example: "Show me profit in California vs Texas."* 3. **Understanding Trends:** Focused on revealing trends over time, this category is essential for longitudinal analysis.\ *Example: "Show me the sales trend for product X over the past year."* 4. **Changes over Time:** Queries in this category highlight growth or decline over specified periods of time.\ *Example: "What has been the growth in customer base since 2020?"* 5. **Clusters and Segments:** These queries help in generating the analysis for a specific segment or cluster of the data for a specific period of time. Often includes the keywords "*Segments between*".\ *Example: "Show segments between Q1 and Q3 for sales in the North region*.*"* 6. **Basic Analysis:** This category includes fundamental queries involving a measure and a dimension.\ *Example: "Display the total revenue by each sales region."* 7. **Resolution:** Focuses on time-specific resolutions like "weekly", "monthly", and "yearly".\ *Example: "Show me monthly revenue trends for the past year."* 8. **Time-based Analysis:** These queries are time-oriented, analyzing changes over specific time periods.\ *Example: "What were the sales in the last 3 weeks compared to the same period last year?"* . 9. **Insights:** A non-editable category providing insight-driven search queries for deeper analysis. {% hint style="warning" %} Understanding Trends, Changes over Time, Resolution, and Time-based Analysis categories will be available only if date-related columns exist in the Business View. {% endhint %} ### Customizing Search Guide To help users make the most of the search functionality, admins can customize the Search Guide. The search queries can be edited and removed to make sure they align with the requirements specific to each Business View. 1. Log in as **Admin** and go to **Search**. 2. In the **Search Guide,** click on any query to execute and visualize the results in real-time.

Search Guide

3. Click on the **Don’t open search guide automatically next time** checkbox if you don't want the Search Guide to be displayed next time you use Search.

Show/hide Search Guide

4. Click on the Expand icon 🔽 next to **How-to Search** to view the syntax/format to be followed for a search query.

How-to Search

4. Click on **Refresh** to refresh the entire Search Guide with regenerated queries. ### Editing queries and categories 1. Click on **Edit Search Guide** to edit the queries and categories.

Refresh/Edit Search Guide

2. From the dropdown in the top left corner, choose the required Business View from the list. The Business Views can be sorted and searched.

Choosing the required Business View

3. According to the Business View selected, the associated columns will be displayed in the right pane. 4. To edit the category name, click on the pencil icon next to each category, and provide the required name. 5. Click on the ✔️ icon to save the query or click on ❌ to discard the query. Click on **Apply to each BV** to update the specific category name for all the Business Views. {% hint style="info" %} If you change the first category's title in a Business View and click on **Apply to each BV**, then the title of the first category in other Business Views will also be changed. {% endhint %} 6. The icon next to each query indicates whether the query is edited by admins. 7. To edit the query, click on the pencil icon next to each query. The suggestion for next word in the query will be provided. 8. The results for the query will be displayed in the bottom section as you edit. Click on the ✔️ icon to save the query or click on ❌ to discard the query.

Comparison category of Search Guide

9. To regenerate the query, click on the cycle icon next to the pencil icon and a relevant query will be auto-generated. 10. To hide a particular query, click on the eye icon situated near each query. 11. Once all the edits have been made, click on **Save changes** to save the search guide or click on **Cancel** to discard the changes. # Executing a search query Master search queries with aggregations, filters, time ranges, and advanced logic to extract precise, meaningful insights from your data effectively. Efficiently executing a search query in Tellius involves the following steps: 1. Selecting the Business View 2. Construct the required query 3. Analyze the search results 4. Save to a Vizpad (to save the results) Start by choosing the appropriate Business View. This sets the context for your query, ensuring that the search is tailored to the specific dataset you want to analyze. Next, type in or input a voice-based query in natural language as per your requirements. Go through different sections of the search results to analyze them. Save the results to a Vizpad (if you want them to be saved for future use). {% hint style="info" %} Please note that the results of a search query will be stored only if they are saved to a Vizpad or Insight. {% endhint %} # Selecting a Business View Learn how to select and explore Business Views in Tellius, view columns, use SmartView Search, and streamline queries with intelligent, automated insights. 1. From **Search** tab, click on **All Business Views** dropdown to choose the required Business View.

Business View dropdown

2. The available Business Views for your account will be displayed in the dropdown. Select the required Business View. 3. When a Business View is selected, the columns present in the corresponding Business View will be displayed in the right pane, organized under *Group View* and *Table View*. It helps you to be informed of the columns in a Business View and create search queries accordingly.
List of columns in a business view

Columns of the selected Business View

4. The columns could be searched using the **Search** bar below the Business View name. 5. The green-colored columns are **Measures,** whereas the black-colored ones are **Dimensions**. The date columns are represented in yellow color. 6. Once a query is successfully executed, the same details will be pinned next to the Search Inspector.
Display of columns in a business view

Pinned Business View panel

6. Click on the arrow next to the Business View name to hide the panel. Click on the Business View icon in the right pane to view the columns.
Ability to show/hide business views

Show/hide Business View panel

{% hint style="info" %} Tellius Search supports up to 10,000 unique filter values per column. To update the limits, please reach out to your Customer Success team. {% endhint %} ### **Auto-selection of Business View (SmartView Search)** From 4.3.1, users need not select the relevant Business View as a first step to execute a query. SmartView Search eliminates the need to select a Business View before querying. It intuitively identifies the best-fit Business View based on your query's context, streamlining the search process. SmartView Search in Tellius revolutionizes the way you interact with data, offering a seamless and intuitive search experience. Here's an in-depth look at its features: 1. **Entity extraction:** It identifies crucial elements like column names and values in your query, ensuring focused and relevant search results. 2. **Intent classification:** Tellius determines whether you're looking for a chart or an insight, customizing the results to fit your query's purpose. 3. **Business View shortlisting:** SmartView Search scans all accessible Business Views to find the most relevant ones for your query, removing the need for manual selection. 4. **Intelligent scoring algorithm:** It evaluates every potential Business View and ranks them based on their relevance to your query, ensuring the most suitable Business View is used for your search. 5. **Auto correction:** Automatically corrects typos in your query, ensuring accuracy in the search results. 6. **Smart chart logic:** Recommends the most appropriate chart type based on your data. 7. **TQL generation:** Translates your query into Tellius Query Language for efficient processing. 8. **Chart rendering:** Visualizes your search results for easy interpretation. # Typing a search query Type natural language queries to explore data, get real-time visual results, and refine insights with interactive tokens, auto-suggestions, and voice input. Once you select the Business View, the columns of the chosen Business View are displayed in the right pane. This visibility is crucial for formulating queries that are specific and relevant to your data.

Selected Business View

After selecting the Business View, type your query in natural language. Use keywords that closely match the columns and values in the selected Business View for accurate results. {% hint style="success" %} If you're finding it challenging to begin with a query, check out our [Search Guide](/search/search-guide). It offers a curated collection of ready-to-use queries, designed to get you started. {% endhint %} ### What is a query? In Tellius, a search query is a string of keywords in natural language, accompanied by interactive elements, which you can type or input via voice into the search bar to visualize real-time results. Tellius translates this query into an SQL command to retrieve the results from your dataset. {% hint style="info" %} Don’t worry about making typos; Tellius is designed to auto-correct and recognize the closest-resembling column or value. For added convenience, you can provide your query through voice input. Tellius efficiently handles any pauses or breaks in your speech, adjusting the query as needed. {% endhint %} ### Understanding query composition Consider the query: "*Show me monthly profit by market*".

Highlighting tokens in query

* The keywords "monthly", "profit", and "market" are identified as tokens and highlighted in different colors for easy identification. * "Profit" and "market" are columns within your Business View, as can be verified in the Business View panel. * The "monthly" resolution is derived from the "Order\_date" column, indicating the time frame for your query.

The tokens identified in the Business View

### Interacting with tokens and query modifications * When you hover over these highlighted tokens, you'll notice they are clickable, unlike other parts of the query (e.g., "S*how me*") which only display a text cursor. * Each token has a small 'x' in its top right corner and clicking on this 'x' removes the token from your query. * As you type the search query, get suggestions for the next word or phrase. * Clicking on a token reveals a list of suggested alternatives. Selecting an alternative will immediately transform your query and update the results accordingly.

Suggested alternatives for keyword "market"

### **Get dynamic results and suggestions** As you type, watch the results dynamically update on the canvas. For example, start with "*Show me total profit*" and then extend to "*Show me total profit* *by city in 2022*" to see how results evolve with each word. Once you have your results, you can easily clear the current search query by clicking the "x" icon near the microphone in the search bar. This allows you to start a new query.

Clearing a search query

# Constructing effective search queries Search techniques to craft queries that yield the most relevant and comprehensive results. From basic to complex queries, Tellius' powerful search engine is designed to interpret and analyze a vast array of questions, paving the way for informed decision-making. This guide explores the skillful and strategic use of search techniques to leverage the full potential of Tellius Search. ### Example Query To demonstrate the query structure, consider the example below: total revenue by product for New York monthly #### Components of the query 1. **Aggregation**: Specifies the mathematical operation to be performed on the data. * **Keyword**: `total` * **Measure**: `revenue` 2. **Grouping**: Defines how data should be grouped. * **Keyword**: `by` * **Dimension**: `product` 3. **Filtering**: Applies conditions to narrow down the data. * **Keyword**: `for` * **Value**: `New York` 4. **Time Resolution**: Determines the time frame for the data. * **Value**: `monthly` #### Query keywords and values * **Groupby Keyword**: `by`\ Used to group data based on a specific dimension. * **Combined Groupby**: `and`\ Allows for grouping by multiple dimensions. * **Filter Keyword**: `for`, `in`\ Applies a filter to narrow down the data. * **Time Resolution**: `monthly`, `yearly`, `quarterly`, `daily`, `weekly`\ Specifies the temporal granularity of the data. * **Comparison between Values**: `compared to`, `vs`\ Used to set up a comparison between different data sets. * **Time-based Filters**: Examples include `last year`, `March 2020`, `this week`, `Q4 2019`\ Filters the data based on specific time periods. * **Additional Logical Functions**: `contains`, `=`\ Provides additional logical operations to refine the data. #### Constructing a query When constructing a query, it is essential to combine these components logically to ensure accurate data retrieval. Here's the structure to follow: 1. Start with an aggregation keyword and the measure you want to analyze. 2. Use the groupby keyword to define how to break down the measure. 3. Apply filters using filter keywords and values to specify the subset of data you need. 4. Define the time resolution to determine the period over which the data should be aggregated. ### **Starting with Basic Queries** Basic queries that involve direct data retrieval serve as the foundation for any search. Try these straightforward questions, which are excellent starting points for deeper analysis. #### **Simple data requests** * *"Show total profit"* * *"Show average profit in 2023"*

"Show total profit"

**Combining multiple parameters** * *"Show revenue and quantity\_sold"* * *"Show sales and profit by category"*

"Show sales and profit by category"

#### **Regional or category-specific queries** * *"Show count profit for California"* * *"Show total profit by category by region"*

"Show total profit by category by region"

{% hint style="info" %} Keywords such as "*from*", "*before*", and "*after*" can be used for time-period-related queries. Example: *Show me profit after January 2023 and before September 2023.* {% endhint %} ### **Moving to Intermediate Queries** These queries incorporate multiple elements like time frames, filters, or comparison metrics, offering more refined results. #### Filters Queries that extract data based on specific conditions or criteria. * *"Show average profit by country for furniture"* * *"Show total sales by ProductName for Texas"* * *"Show total hours worked by Department"*

"Show total sales by ProductName for Texas"

#### **Dates and time ranges** Queries focusing on data within a specified date or time period. * *"Show minimum users for the last 2 months"* * *"Show top 3 performers by sales region this year"* * *"Show bottom 5 Profit by Country for the last quarter"*

"Show bottom 5 Profit by Country for the last quarter."

#### **Resolution** Queries that break down data into specific time intervals. * *"Show total training hours completed by employees monthly"* * *"Show yearly progression of employee satisfaction scores across all departments"* * *"Show average sales and average profit quarterly"*

"Show average sales and average profit quarterly."

#### Percentages Queries that calculate and compare data in percentage terms. * *"What's the percentage profit for technology compared to furniture?"* * *"What is the percentage of employees meeting performance targets by department?"* * *"Give me the percentage profit for electronics compared to apparel for all categories"*

"What's the percentage profit for technology compared to furniture?"

#### **Absolute change and Percentage change** 1. **Absolute change:** This refers to the direct difference in a metric's value between two time periods, not considering the size of the initial value. It is useful for understanding the exact increase or decrease in a metric. 2. **Percentage change:** In contrast, percentage change provides the proportional change in a metric, relative to its original value. It's expressed as a percentage, offering a sense of the scale or significance of the change, especially in relation to the starting point. * *"What is the percentage change in annual employee satisfaction scores from 2020 to 2023?"* * *"Show the percentage change in the number of new hires in the Sales department in 2019 vs 2023"* * *"Absolute change in customer support tickets resolved in 24 hours"*

"Percentage change in profit for 2013 vs 2014"

#### Time-Based Queries focusing on data related to specific time frames. * *"Show me the total Profit for 2022"* * *"Show the total helpdesk tickets resolved in January 2022"* * *"Show total cybersecurity incidents reported in Q2 2022 compared to Q2 2023"*

"Show the total Profit for Jan 2013 compared to Feb 2013"

#### **Contains** Queries that filter data based on the presence of specific terms or phrases. * *"Show total discount by region for suppliers containing Global"* * *"Show total sales by region where product\_name contains Panasonic"* * *"List employees whose job title contains 'Manager'"*

"Show total sales by region where Product_Name contains Panasonic Inkjet, Red"

#### **"Since" or "From"** The terms "**Since**" and "**From**" are equivalent to the "greater than or equal to" (>=) operator, which will be applied to the subsequent date/time value. The data following "since" or "from" can specify a year, a month, or a specific date. * *"List all transactions for product\_abc since April 1, 2021"* * *"Show sales growth in New York since January 2020."* * *"Show employee turnover rates since 1/11/2021."*

"Show me monthly profit for Panasonic since 2013"

#### Compared to Queries that perform comparative analysis between different data sets or values. * *"Show sum profit by country for technology compared to furniture"* * *"Show average sales in Q1 compared to Q2"* * *"Show total sales by category for Ohio compared to Texas"*

"Show sum profit by country for technology compared to furniture"

#### **Top N and Bottom N** Queries to identify the highest or lowest-performing data points. * *"Show bottom 5 employee turnover rates by department for the last 3 years."* * *"Show top 10 employee performance ratings by role and location."* * *"Show top 3 revenues by region this quarter."*

"Show top 3 revenues by region this quarter."

### **Exploring Complex Queries** Complex queries combine multiple conditionals and elements such as filter, resolution, time range, and compared to, for in-depth analysis. * *"Show sum Profit by Country for Technology compared to Furniture monthly for the last 4 years."* * *"Show daily number of customer support calls for Software A in 2020 compared to 2021."* * *"Show quarterly data breach incidents for North American operations compared to European operations for the last 2 years."*

Show avg profit by segment for technology compared to furniture monthly for the last 3 quarters

#### Combining trends, growth, and segments Queries aimed at analyzing trends, growth patterns, and segmenting data. * *"Show segments of average sales and average revenue by category."* * *"Show trend of average employee retention rates monthly for this year."* * *"Show trend of average customer ticket resolution time monthly for this year."*

"Show segments of average sales and average profit by category"

#### Top N and Bottom N comparison with GroupBy Advanced queries that rank Top N or Bottom N dimensions based on specified segments or trends. * *"What are the top 5 Product Categories by Subscription rate in the region?"* * *"Show top 3 customers with the most returns yearly."* * *"List the bottom 10 vendors by revenue in the last 6 months."*

"Show top 3 customers with the most returns monthly"

#### **Query for the immediate preceding time period** Users can compare a chosen period against its immediate predecessor to gain insights into short-term performance, identify emerging trends, and monitor current growth against recent historical data. The query can be used for days, weeks, months, years, and quarters.

"Show me sales of last 2 months vs the prior 2 months"

**Other variations:** * Show me sales of last n \[days/weeks/months] this year \[vs/compared to] prior n \[days/weeks/months] last year * Show me sales of last n \[days/weeks/months] \[vs/compared to] the preceding period * Show me sales of last n \[weeks/months] \[vs/compared to] the prior n \[weeks/months] #### **Query for YoY time period comparison** Users can assess the performance against the same time period from the previous year to understand seasonal trends, benchmark against the previous year's performance, and measure yearly growth/decline in a more granular manner. The query can be used for days, weeks, months, years, and quarters.

"Show me sales by segment for the last 4 weeks this year vs 4 weeks last year"

**Other variations:** * Show me sales for the last x \[days/weeks/months/quarters] this year \[vs/compared to] last year * Show me sales for the last x \[days/weeks/months/quarters] this year \[vs/compared to] x days last year  * Show me sales by segment for the last x \[days/weeks/months/quarters] this year \[vs/compared to] x \[days/weeks/months/quarters] last year #### Post-aggregation filtering (HAVING clause) The HAVING clause allows you to filter data after aggregation calculations are performed, rather than before. This is essential when you need to filter based on calculated values like totals, averages, or counts. Fro example, "Find products where total revenue exceeds $1M" - filters based on summed revenue per product {% hint style="success" %} **When to use HAVING vs WHERE:**
* **WHERE** operates on individual rows before grouping: *"Show accounts where individual sales > $100K".* Use **WHERE** when filtering on existing column values before any calculations * **HAVING** operates on grouped results after calculation: *"Show accounts where total sales > $100K".* Use **HAVING** when filtering on calculated values (sums, averages, counts, percentages) * Combining both: WHERE filters raw data first (reducing dataset size), then HAVING filters calculated results {% endhint %} Tellius processes these queries by first grouping your data, performing the aggregation (sum, average, count), then applying the filter condition to those calculated results. {% hint style="info" %} Tellius automatically pushes aggregations and filters to your data source when possible. HAVING conditions are processed at the database level, not in Tellius memory. This maintains fast performance even with large datasets and complex calculations {% endhint %} **Example queries for threshold-based filtering:** * "Customers where lifetime value > $10K" (HAVING with sum) * "Products where monthly sales variance > 20%" (HAVING with statistical functions) #### Per-group rankings ("For each") The "for each" pattern calculates rankings within specific groups rather than across the entire dataset. This addresses situations where you need to identify top or bottom performers within categories, regions, time periods, or other dimensions. **For example,** * **Standard query:** "Top 5 products" → 5 highest-performing products ranked globally * **Per-group query:** "Top 5 products for each region" → 5 products ranked within each region
{% hint style="info" %} * **In Search/Kaiya:** Use natural language like "Top 5 customers for each month" * **In Vizpads:** Enable the "within group" option in Top N/Bottom N filters * **For charts:** The primary dimension determines the grouping * **For tables:** The first dimension in your query determines the grouping {% endhint %} **Optimal group sizes** * Ideal range: 10-1000 members per group for best performance * Avoid high-cardinality grouping (>10,000 groups) without additional filters * Use date ranges or filters to reduce group count when working with time-based grouping **Example queries for comparative analysis across segments** * "Top performers for each region compared to regional average" * "Bottom 3 reps for each territory and product category" # Marketshare queries Learn how to build accurate market share queries with clear syntax, examples, and guidance to analyze performance, compare trends, and refine insights. Marketshare is a performance metric used to measure a company's sales or market share relative to the total sales or performance of a specific market or industry. The following documentation includes syntax and examples that will help you understand how to accurately calculate marketshare and get valuable insights into your company's performance. ### **Syntax** Marketshare **KPI** for **target variable** for/by **filters/dimensions** * **Green-colored text** represents the KPI (key performance indicator) that you want to measure, such as *TRx* or *NRx*. It is always the word that follows “Marketshare”. * **Red-colored text** is the target variable or marketshare filter (i.e., filter in numerator which will not be present in the denominator). This is the text that follows the KPI; unless there is a "vs" or "compared to" keyword, in which case it would be the first two words. * **Blue-colored text** is the list of global filters (the parameters you want to apply in your marketshare analysis). There could be multiple filters after a "for" or "in”. {% hint style="info" %} For refined search query results, please make sure to add a time period. Example: *for last 4 weeks, in 2023* {% endhint %} ### **Examples** #### Marketshare **dollar sales** for **Brand A** in **2019**
#### Marketshare **dollar sales** for **Brand A** vs **Brand B** for **New York** for **Derm** is the same as #### Marketshare **dollar sales** for **Brand A** compared to **Brand B** for **Derm** for **New York**
#### **Marketshare ****dollar sales**** for ****brand**** by ****state** This shows the multiple values for each brand for a particular state, where the different brands would sum upto 100%
#### **Marketshare ****dollar sales**** for ****state**** by ****brand** This shows the multiple values for each brand with the shares of state among other tiers (where the different brands would not sum upto 100%)
**Marketshare ****dollar sales**** for ****Brand X**** by ****segment** This shows the share of sales Brand X has within each segment (which does not add up to 100%)
#### **Marketshare ****dollar sales**** for/by ****segment**** for ****Brand X** This shows the share of each segment's sales for Brand X (same as the percentage of dollar sales in XYZ, and adds up to 100%)
#### **Marketshare ****dollar sales**** for ****Brand X**** in 2021 compared to 2022**
### **Change in marketshare** "Change in market share" refers to the variation in the percentage of a company's sales (or another relevant measure) within a specific market or industry over a given time period. This change can be due to factors such as new product launches, pricing strategies, marketing efforts, or changes in consumer behavior. Understanding the "change in market share" helps businesses evaluate the effectiveness of their strategies, monitor competition, and identify market trends. Now, from 4.2 version, users can now include "**change in market share"** keyword for marketshare-related queries. With this out-of-the-box support for "change in market share" keyword, users can now better analyze changes in market share over time or across different conditions, empowering their decision-making process.
It's important to understand that the placement of the target variable in the query can significantly affect the resulting data. For instance, the two queries below provide different outputs due to the change in position of 'Advil', the target variable: * `market share of dollar sales for Advil by segment` * `market share of dollar sales by segment for Advil` When adding a filter for the target variable and breaking it down by another filter, a new type of query arises. For example, `market share of dollar sales for Advil for adult internals for retailers` . To compare these results over different time periods, such as the "last 4 weeks vs the same period a year ago", we've introduced support for "**change in market share**" keyword queries. #### **Syntax for change in market share** To utilize this feature, ensure you provide the following values in the query where the target variable appears after the measure column. The syntaxes are, * **Standard Syntax**: Show me \[change/percentage change/percent change] in market share **\** for **\** for **\** \[vs/ compared to] **\** * **Syntax with Global Filters**: Show me \[change/percentage change/percent change] in market share **\** for **\** for **\** \[vs/ compared to] **\** for X1 for X2 Here, * **M1** represents the measure * **V1** represents the target variables * **F1** and **F2** represent a list of filters for the target population, with multiple filters following "for" or "in" * **X1** and **X2** represent a list of global filters, including dimension or date columns Users can now execute queries such as: * Show me \[change/percentage change/percent change] in market share **Sales** for **Nike** for **New York** vs **California** * Show me \[change/percentage change/percent change] in market share **Sales** for **GoPro** for **North America** vs **South America** for 2022 * Show me \[change/percentage change/percent change] in market share **Sales** for **Nike** for **New York** vs **California** for 2022 for First-class shipping {% hint style="info" %} From v4.3, users can assess the percentage change in market share without specifying a target filter. {% endhint %} ### **Syntax and examples of queries that can be executed** Here \ and \ represent dimensions or time periods **Syntax 1:** Show me change/percentage change in marketshare \ by \ for/in \ compared to/vs. \ **Example 1:** Show me change/percentage change in marketshare sales by category for/in California compared to/vs. Washington **Syntax 2:** Show me change/percentage change in marketshare \ by \ for/in \ compared to/vs. \ **Example 2:** Show me change/percentage change in marketshare sales by category for/in 2013 compared to 2014 **Syntax 3:** Show me change/percentage change in marketshare \ for/in \ compared to/vs. \ **Example 3:** Show me change/percentage change in marketshare sales for/in California compared to/vs. Washington
# Analyzing search results Learn how to analyze Tellius' search results, explore charts, use the Search Inspector, and interpret query execution times effectively. # Understanding search results Explore Tellius Search results with guided insights, smart visualizations, query inspectors, formatting tools, and advanced analytics to refine and analyze your data. As you enter a query in Tellius, the system immediately begins displaying relevant results. The results screen is composed of several interactive elements, each designed to enhance your search experience and data visualization.

Search results interface

1. **Search Guide** Click on this option to access the Search Guide. It's a helpful resource to refer back to while executing search queries. 2. **Add to Search Guide** If you find a query particularly useful, you can add it to the Search Guide for future reference. Click on this button and you will be redirected to the Search Guide. Select the appropriate category for your query, and save your changes. Alternatively, cancel if you decide not to add it.

Select the catgory to add query

3. **Search results canvas** This area displays your search results. Tellius intelligently selects the most suitable chart type for visualizing your data and provides actionable buttons at the top right corner for further analyses. 4. **Search Inspector** Here, you can view the details of your executed query, including the columns analyzed, the Business View used, the time taken to execute a query, and the SQL code generated from the query. 5. **Help us Learn** If the search results don’t align with your expectations, use this feature to guide Tellius in better understanding how to segment your query. 6. **Business View Panel** The panel displays the columns in the Business View for easy identification for constructing/analyzing the query elements. 7. **Settings** The configuration details of the chart will be displayed here, comprising multiple fields. You can add columns from the Business View panel to these fields, allowing you to tailor the visualization according to your needs. 8. **Formatting** Enhance your chart with various formatting options, such as number formatting, conditional formatting, and customizing data labels, color palettes, chart titles, legends, and background colors. 9. **Advanced Analytics** Explore advanced analysis options like benchmarking and setting Y-axis target lines to deepen your data exploration. 10. **Search Query Inspector** Same as Search Inspector (#4). Click here to display the Search Query Inspector. This panel will be displayed by default next to the Business View panel once the query is executed. 11. **Search Guide** Click here to quickly refer to the guide and execute queries from the curated list. The list of categories will be displayed. Click on each category to show/hide the associated queries. Click on any required query to execute it.

Search Guide opened from the right pane

{% hint style="warning" %} Please note that clicking on the Search Guide option in the right pane will display the Search Guide queries in the adjacent panel while keeping the search results intact. However, clicking on the Search Guide (listed #1) will remove the results and move back to the Search Guide. {% endhint %} 12. **Search History** Displays the list of search queries executed for a specific date range. Customize the date range and Business View to suit your requirements. # Search Inspector Dive into how Tellius breaks down your search queries The Search Query Inspector panel provides detailed insights into how your search queries are processed and analyzed. Also, it displays the number of rows parsed by Tellius in the selected Business View and the time taken to execute the query. This panel enhances transparency and understanding of the query execution process. ### We Analyzed (Tokens analyzed) Tellius breaks down the elements of a search query, including the dimensions, measures, date range, and the specific Business View used for analysis. Each keyword that has been input will be analyzed individually. Tellius interprets these tokens to understand your query better. For example, in the below screenshot, Tellius processed the following:

"We Analyzed" section

* Identified the keyword “trend” and understood the pattern the data needs to be presented. * Matched the keyword “shipping cost” with the measure column “*Shipping\_Cost*” with median aggregation. * From the keyword “monthly”, analyzed the "*Order\_Date*" column with “monthly” resolution. * All these analyses have taken place in the Business View “*bv\_Order\_2809*”. ### **Time Taken**

"Time Taken" section

This section not only shows the time taken to execute the query but also distinguishes between the time consumed by Tellius’s own engine and other external engines. * By clicking the arrow next to the time displayed, you can view the breakdown of the execution times. * Click on **Show Details** to view the time taken to execute each individual query. * For further details, check out [this dedicated page](https://app.gitbook.com/o/S3VKMrzMgXbC36NqGRj8/s/JHwf1QFuv1BRPzfSnL2Z/~/changes/35/search/analyzing-search-results/time-taken-to-execute-a-query). ### **Rows Analyzed**

"Rows Analyzed" section

For example, if it reads "*We Analyzed 18K Rows and returned 96 Rows result*". * The query scanned 18,000 rows of data from the dataset. This indicates the scope or size of the data that Tellius processed to get the relevant results. * Out of the 18,000 rows analyzed, Tellius identified 96 rows that matched the criteria or conditions specified in the search query. ### **SQL Code** * Users can view the SQL code generated for the search by clicking on the "*View SQL code generated for this search"* option. * In the "*SQL generated by Search*" window, the complete SQL code is displayed which can be copied for further analysis. # Time taken to execute a query Understand the time taken to execute a query with detailed breakdowns of Tellius and external engine processing to spot bottlenecks and improve performance. It's common for users to encounter query execution time that is slower than expected. This lag can often be attributed to external resources rather than being a problem with Tellius. However, it's crucial to identify and understand the sources of such delays in order to effectively address them. As a step to enhance transparency, we track and display the time spent by Tellius and other external data engines (such as Snowflake) to execute every query. With this, we provide a clear picture of performance metrics, which in turn assists users in identifying bottlenecks and aids in streamlining the troubleshooting process.

TIme taken to execute a query

Following the execution of a query in **Search** and **Vizpads**, we provide a breakdown of the time taken by Tellius and any external resources to execute the query and load the corresponding chart. This detailed breakdown includes all stages of the process, including caching and execution. * For live resources, we display both the total time taken to execute a query and the breakdown of time spent by individual resources. * For non-live resources, we display the total time taken by Tellius to execute a query. ### Exploring the components of Time Taken tab 1. Upon executing a search query and visualizing the results, the time taken to execute the query will be displayed in the **Search Inspector** pane under **Time Taken**. 2. Click on the expand icon next to **Time Taken** to view the breakdown of the time taken.

Expanding the Time Taken tab

2. Click on **Show Details** to view the time taken by individual query (such as request, rendering, pre-processing etc.) in the **Query time breakdown** window. Each query's comprehensive details, including the ID, description, and the resource in which it was executed, will be displayed.

Time taken breakdown

#### **Understanding the breakdown details** In Tellius, multiple types of queries are utilized to extract, manipulate, and visualize your data. Each query has a specific purpose and contributes to a different aspect of the data analysis process. In the Query time breakdown window, a table will be displayed with three columns: Query ID, Query action and the time taken to execute the query in Tellius or other external resources. For a detailed understanding, the description of every **Query action** is listed below: **Total count query** This query is executed to determine the total row count, which is essential in generating statistical insights. It helps you understand the overall volume of data within your dataset. **Max date query** This query is used to retrieve the most recent date within your dataset. It's critical for calculating relative time filters, allowing you to observe and analyze trends over specific periods. **Percentage calculation** This query calculates the denominator value for percentage or market share calculations. It's useful when you need to understand proportions or market dynamics in your data. **Top/bottom query** This query is used to identify the top or bottom 'N' values of a dimension in your dataset, typically in situations involving filters or sorting. **Cohort query** This query is used to calculate Cohort Totals or SubTotals, aiding in cohort analysis—which is a powerful tool for understanding customer behavior over time. **Internal pre/post-processing** This process involves preprocessing user inputs, generating queries for the data source, and post-processing query results—thereby ensuring accurate data analysis. **Rendering on browser** This process involves rendering the charts on the browser and managing the network bandwidth between the browser and the server, ensuring prompt display of your visualizations.
# Interacting with the resulting chart Explore all chart interaction options in Tellius—switch views, apply filters, download results, or build Vizpads and Insights directly from any generated chart. A suite of icons located at the top right corner of every chart helps you dive deeper into the chart and interact with the results. Users can directly build Vizpads or Insights from the charts with the help of these actionable icons.

Icons in the top right corner of every chart

### **View Chart/View Data** * Click on this icon to switch between the visual chart representation and its underlying table data. * Alternatively, click on the three-dot menu and select **"Detailed View"**. This will present the chart data in a tabular format.

Data table view and the chart view of a line chart

### **Add to Vizpad** * The resulting chart can be incorporated into a Vizpad. * You can either select an existing Vizpad or opt to create a new one.

Adding the chart to an existing Vizpad or to a new Vizpad

* Once a new Vizpad is created and the chart is added, a prompt window will be displayed asking if you want to go to the new Vizpad. Choose **"Yes"** to proceed immediately, or **"No"** if you wish to stay on the current page.

Go to the newly created Vizpad

### **Switch Chart** * Click on this icon and the available chart types will be displayed. The charts that are incompatible will be greyed out automatically.

Switching to other charts

* The existing chart will be converted to the selected chart type, where all current values and filters will remain applied. {% hint style="info" %} Please note that any changes made to a chart type will remain temporary unless they are saved. {% endhint %} ### **Filter** * To apply filters, click on the **funnel icon**. For more details on applying filters, check out [this section](/search/know-your-charts-in-tellius/adding-columns-to-fields-in-configuration-pane#filter). * The option "**Use aggregated column from object**" allows you to filter using data aggregated at a higher level. This is beneficial when analyzing broader trends or patterns.

Applying filter to a chart

### **Download** * Click on the **download icon** to download the current chart. * Select the preferred format (JPG, PNG, PDF, CSV or PPT) in which the chart needs to be downloaded.

Different formats to download

### **Insight** * Click on **Insight** to generate Insights directly from the chart. * Various Insight types (Trend, Driver, Comparison, Discovery) with a relevant example for each will be displayed. * Select a sample Insight to get started or choose **"Configure your Insight"** to start a new one. * In the Insight configuration window, follow the prompts to tailor your Insight as needed.

Insight types with sample Insight

# Know your charts in Tellius Explore every chart type in Tellius and learn how to visualize data effectively. See how Tellius auto-selects the best chart and switch views anytime. Tellius offers a variety of charts at your disposal to visualize the results. When you input a query, Tellius automatically identifies and presents the most suitable chart on the results canvas, aligning with your search query. However, you can also switch to a different chart type as required. --- [Next Page](https://help.tellius.com/llms-full.txt/1)