> For the complete documentation index, see [llms.txt](https://docs.keewano.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.keewano.com/getting-started/readme.md). # What is Keewano Learn what Keewano is, how its event-native database works, and how to ingest data, query it, and connect AI agents. Keewano is a database built for machine reasoning at scale. It is designed for a world where AI agents are becoming direct consumers of data: asking questions that were not defined in advance, investigating sequences of behavior, testing hypotheses, and reasoning over what happened and why. ## Why it exists Keewano was founded around a simple idea: **today's data systems were built for humans, but the next generation of users will be machines.** Traditional OLAP systems and data warehouses are very good at answering questions that were anticipated in advance. AI agents work differently: they can ask a new question at any moment, look for relationships that were never predefined, and examine enormous amounts of information on the way to a conclusion. To do that well, they need more context, higher-resolution data, and access to the full history of what happened — not just pre-built tables, aggregates, or a subset of events selected ahead of time. Keewano was built around that agentic workload from the ground up. Rather than first transforming raw activity into conventional tables and aggregates, Keewano stores event histories in a purpose-built format that preserves **sequence and context as part of the data itself**. Agents can investigate what actually happened, event by event and across long histories, without teams having to predict every future question in advance. Keewano changes how the underlying event history is stored and moves computation closer to the data, so agents can work across much more context without constantly moving large amounts of raw data back and forth. In internal benchmarks, Keewano can scan **a quarter-billion events in under half a second**. In production workloads, customers have also seen **up to 84% fewer LLM tokens** used by moving more processing into the data layer before results are sent to the model. *** ## The core mental model In Keewano, an **entity** is something whose history you want to understand. An entity might be: * a user * an account * a device * a transaction * a machine * an AI agent In most products the entity is a **user** or an **install**, and that is the term the rest of this documentation uses — you will see `user_id` in SQL and `process_user` in Lua. Events are attached to that entity in the order they occur. For example: ``` Entity: customer_123 signed_up searched viewed_product added_to_cart left returned purchased contacted_support cancelled ``` Keewano keeps that history together and in order, so an agent can reason over the sequence directly instead of reconstructing it later from separate tables or views. That history becomes the raw material for analytics and machine reasoning. *** ## What that means in practice You send your product's events once. Keewano stores the event history, enriches it with context and meaning, and serves it through whichever interface fits the question: natural language, Data Tables, SQL, Lua, or an AI agent of your own. For live event workloads, you don't need to build a separate analytical ETL pipeline before agents can work with the data. You also don't need to define every future funnel, segment, or relationship in advance. **A question nobody anticipated is just another question.** For example: > Which users today are following the same behavioral path as users who churned last month? With a traditional analytics stack, answering that may require deciding which events matter, reconstructing user histories, and preparing or optimizing the data for that analysis. In Keewano, those histories already exist as ordered event sequences, so the question can be investigated directly. *** ## How it fits together ``` your sources → Keewano → your answers ``` ### Getting your data in You send data into Keewano through one of three ingestion paths. Match the path to how your data is produced: | If your data is… | Use… | | --------------------------------------- | ---------------------------------------------------------------------------- | | Real-time from streaming infrastructure | Kafka, database CDC, or your own backend → **REST API** | | First-party applications | Your mobile or web apps → **SDK** | | Warehouses, lakes, and backfills | Snowflake, BigQuery, Parquet/Iceberg, database snapshots → **Import (bulk)** | All three land in the same underlying event model. See [**Connecting to Keewano**](/getting-started/connecting-to-keewano.md) for setup instructions and the event structure. ### Getting answers out Several interfaces read the same underlying event history. They differ in who's asking and how much control they need. | Interface | For | What it is | | -------------------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [**Keewano Ask**](/analytics/keewano-ask.md) | Anyone | Ask in natural language and get an answer, chart, and follow-up questions without building a dashboard or writing a query first. | | [**Data Tables**](/analytics/data-tables.md) | Analysts, PMs | Compose your own grid from metrics, breakdowns, and segments when you want a structured analytical view. | | [**SQL**](/sql-query-studio/guide.md) | Analysts, engineers, BI tools | Query Keewano through the PostgreSQL wire protocol, so tools such as Tableau, Metabase, Looker, and psql can connect directly. Keewano supports SQL for compatibility even though its underlying storage model is not relational. | | [**Lua**](/lua-scripting/guide.md) | Engineers, advanced analysts | Run custom logic inside the database for sequence-heavy or specialized analysis that may be awkward or inefficient to express in SQL. | And [**MCP for Agents**](/analytics/mcp-for-agents.md) exposes the same data to AI agents you build yourself over the open Model Context Protocol. {% hint style="info" %} These aren't separate copies of your data. Every interface reads the same underlying event history, so an answer in Keewano Ask, a Data Table, a SQL query, a Lua script, and your own AI agent all work from the same source. {% endhint %} *** ## Why in-database computation matters AI agents need two things that can seem contradictory: * access to the complete picture * compact context they can reason over effectively Keewano is designed around both. The complete event history remains available inside the database, while computation can run close to the data. Instead of sending a huge raw dataset to an agent, Keewano can perform the heavy processing where the data lives and return the relevant result and supporting context. {% hint style="success" %} Put simply: **agents need access to everything. They don't need everything sent to them.** {% endhint %} *** ## Where Keewano fits Use KeewanoDB on its own or alongside the stack you have today. Events arrive straight from your app via SDK, or from the systems you already run. It auto-scales to thousands of agents querying at once. ![Raw events in from your existing stack, through KeewanoDB, out as agent-ready answers](https://3698466984-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWQi6lbHOA8tyhBBRtvuQ%2Fuploads%2Fgit-blob-15ee813246a83cb9034fefdbca1debe21d5cc075%2Fkeewano-architecture.png?alt=media) Raw events land intact and stay that way. Inside the database they're tied to entities and timelines, mapped to concepts agents can query, and served through the interfaces you already use — with the heavy processing running where the data lives rather than on the way out. ### On its own Send your events to Keewano and query them there. There is no warehouse to stand up first and no pipeline to maintain between the two. ### Alongside what you already run Keep your warehouse and your dashboards exactly where they are. Keewano reads from the event infrastructure you already have, as another destination on the bus. ``` ┌─→ Data Warehouse → BI / Dashboards Events → Event Bus ─┤ └─→ KeewanoDB → AI Agents ``` Your existing analytics systems carry on serving dashboards and established workloads, while Keewano serves the workloads that need live event histories, sequence-aware analysis, and machine reasoning. *** ## Where to start | If you're… | Start here | | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | **Setting up Keewano for the first time** | [Connecting to Keewano](/getting-started/connecting-to-keewano.md) — choose an ingestion path and send your first events. | | **Exploring your data in natural language** | [Keewano Ask](/analytics/keewano-ask.md) | | **Building analytical views** | [Data Tables](/analytics/data-tables.md) or the [SQL Guide](/sql-query-studio/guide.md) | | **Connecting an application or BI tool** | [Connecting to Keewano](/getting-started/connecting-to-keewano.md) for the SDKs, or the [SQL Guide](/sql-query-studio/guide.md) | | **Working with sequence-heavy or custom logic** | [Lua Guide](/lua-scripting/guide.md) | | **Building an AI agent on your data** | [MCP for Agents](/analytics/mcp-for-agents.md) | --- # 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 If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.keewano.com/getting-started/readme.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. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.