Quick Start

Setting Up the Schema

To generate queries, the system needs to understand your database schema. This includes:

A list of relevant tables (those you will query, and those needed for joins).
The relevant fields within each table.
Optionally, aliases for tables and fields to make legacy or unintuitive names more meaningful without changing the underlying database.

Relevant fields include those used in relations—such as foreign keys or join conditions—on both sides of the relationship.

Example Schema Definition

Schema JSON


{
  "tables": [
    {
      "name": "users",
      "fields": {
        "id": { "type": "uuid" },
        "name": { "type": "string" },
        "created_at": { "type": "datetime" }
      }
    }
  ]
}

Using Table and Field Aliases

Tables and fields can have aliases to provide more meaningful names for legacy or unintuitive database names without requiring changes to the underlying database structure.


{
  "tables": {
    "order_items": {
      "alias": "Product Orders",
      "fields": {
        "item_qty": {
          "alias": "quantity",
          "type": "integer"
        },
        "unit_prc": {
          "alias": "unit_price",
          "type": "float"
        }
      }
    }
  }
}

Aliases allow your users to ask regular questions without needing knowledge of the actual table names, which might be unintuitive.

Supported Data Types

To generate type-safe queries, you must specify the data types for each field. The system supports both primitive and composite types.

Primitive Types

The following primitive types are currently supported:

string - Text data
integer - Whole numbers
float - Decimal numbers
datetime - Date and time values
date - Date only values
time - Time only values
bool - Boolean true/false values
oid - Object identifiers
uuid - Universally unique identifiers

Composite Types

Enums - Predefined set of values
Objects - Nested object structures

⚠️

Array types will be supported in subsequent versions.

Example with Data Types


{
  "tables": [
    {
      "name": "products",
      "fields": {
        "id": { "type": "uuid" },
        "name": { "type": "string" },
        "price": { "type": "float" },
        "in_stock": { "type": "bool" },
        "category": { "type": "string" },
        "created_date": { "type": "date" },
        "last_updated": { "type": "datetime" }
      }
    }
  ]
}

Supported Database Engines

To generate accurate queries for your specific database, you need to specify which database engine you’re using. Currently supported engines include:

MongoDB
PostgreSQL
MySQL
Microsoft SQL Server
Oracle Database
SQLite
MariaDB

Complete Schema Example

Here’s a complete schema configuration example:

Basic Configuration


{
  "database_engine": "PostgreSQL",
  "tables": [
    {
      "name": "customers",
      "fields": {
        "id": { "type": "integer" },
        "name": { "type": "string" },
        "email": { "type": "string" },
        "registered_at": { "type": "datetime" },
        "active": { "type": "bool" }
      }
    },
    {
      "name": "orders",
      "fields": {
        "id": { "type": "uuid" },
        "customer_id": { "type": "integer" },
        "total": { "type": "float" },
        "status": { "type": "string" }
      }
    }
  ]
}

With your schema properly configured, you’re ready to start generating type-safe queries for your database!

Adding Your Schema

You can add your schema using one of the following methods:

Using our API (see documentation at api.kaiwadb.com/docs )
Via SDK available for python
Through the dashboard, which currently supports importing the JSON schema format shown above. Future releases will feature a comprehensive GUI for schema management.

Agent Setup

The primary methods to use KaiwaDB are through our REST API, SDKs, or admin dashboard. For impatient users, we offer agents intended primarily for demo purposes.

The agent can be installed using:


curl --proto '=https' --tlsv1.2 -LsSf https://github.com/kaiwadb/agent/releases/download/v0.2.1/kaiwadb-agent-installer.sh | sh

or for Windows users:


powershell -c "irm https://github.com/kaiwadb/agent/releases/download/v0.2.1/kaiwadb-agent-installer.ps1 | iex"

Once installed, the agent can be started under a VPN where it can reach the database. The admin can then add database connections in the admin dashboard and send queries directly from the web app without requiring any additional infrastructure setup.

You can create an agent token in the settings of the admin dashboard to authenticate the agent.

Basic CLI Usage

After installing the agent, you can use the CLI to interact with the KaiwaDB service:


kaiwadb-agent --token "<token>"

Replace <token> with your agent token generated from the admin dashboard.