Documentation & Help

Welcome to Kyomi! This page will help you get the most out of your AI-powered data analytics platform.

Quick Start

1. Connect Your Data

Connect your Google BigQuery projects through Settings → BigQuery. Kyomi will automatically index your datasets and tables to help the AI understand your data.

2. Start Chatting

Ask questions in natural language and the AI will query your data, create visualizations, and provide insights.

3. Build Dashboards

Save important charts and analyses to dashboards for quick access and sharing with your team.

Creating Charts

Kyomi uses ChartML - a simple, human-readable format for defining data visualizations. You can create charts in three ways:

1. Ask the AI

Simply describe what you want to see:

"Show me revenue by month as a line chart"
"Create a bar chart of sales by region"
"Make a table of top 10 customers"

The AI will write the ChartML for you.

2. Use the Chart Builder

Click the chart icon in the SQL editor or dashboard editor to open the visual chart builder with:

SQL Editor Tab: Write or paste your query
Chart Config Tab: Configure visualization with live preview
AI Copilot: Get help refining your chart

3. Write ChartML Directly

For full control, write ChartML directly in your dashboards or use the Chart Config tab.

ChartML Basics

ChartML uses simple YAML syntax to define visualizations:

yaml

```chartml
data:
  query: |
    SELECT month, revenue
    FROM `project.dataset.sales`

visualize:
  type: line
  columns: month
  rows: revenue
  style:
    title: "Monthly Revenue"
    height: 400
```

Key Concepts

data: - Where your data comes from

query: - BigQuery SQL query
inline: - Hardcoded data array

visualize: - How to display the data

type: - Chart type (bar, line, area, scatter, pie, donut, metric, table)
columns: - X-axis / categories (NOT x:)
rows: - Y-axis / values (NOT y:)
style: - Customization (title, colors, height, etc.)

aggregate: - Data transformations (optional)

Group, filter, and calculate metrics
Runs in DuckDB for fast client-side processing

Chart Types

Bar Chart

Best for comparing categories.

yaml

visualize:
  type: bar
  columns: category
  rows: value

Line Chart

Best for trends over time.

yaml

visualize:
  type: line
  columns: date
  rows: value
  style:
    showDots: true

Area Chart

Like line charts but with filled area underneath.

yaml

visualize:
  type: area
  columns: date
  rows: value

Scatter Plot

For showing relationships between two numeric variables.

yaml

visualize:
  type: scatter
  columns: x_value
  rows: y_value

Pie / Donut Chart

For showing proportions of a whole.

yaml

visualize:
  type: donut
  columns: category
  rows: value

Table Chart

Interactive data tables with sorting and pagination.

yaml

visualize:
  type: table
  columns:
    - { field: name, label: "Customer" }
    - { field: revenue, label: "Revenue" }
  style:
    pageSize: 25
    height: 600

Table Features:

Click column headers to sort (ascending/descending)
Ctrl+click for multi-column sorting
Pagination with customizable page size (10, 25, 50, 100 rows)
Scrollable with fixed headers

Metric Card

Single key numbers with optional comparison.

yaml

visualize:
  type: metric
  value: 1234
  label: "Total Revenue"
  comparison:
    value: 15
    label: "vs last month"

Data Sources

BigQuery Queries

Query your connected BigQuery projects:

yaml

data:
  query: |
    SELECT
      DATE_TRUNC(order_date, MONTH) as month,
      SUM(amount) as revenue
    FROM `my-project.sales.orders`
    WHERE order_date >= DATE_SUB(CURRENT_DATE(), INTERVAL 12 MONTH)
    GROUP BY month
    ORDER BY month

Kyomi Features:

Query caching: Results cached in DuckDB for instant re-rendering
Arrow streaming: 20-100x faster data transfer (Pro tier and above)
Cost estimation: See bytes processed before running
Query size limits: Protect against expensive queries

Inline Data

For static data or examples:

yaml

data:
  inline:
    - { month: "Jan", revenue: 1000 }
    - { month: "Feb", revenue: 1200 }
    - { month: "Mar", revenue: 1100 }

Client-Side Data Processing (DuckDB)

Kyomi includes a powerful DuckDB middleware that runs in your browser for fast data transformations:

Aggregations

Group and calculate metrics without requerying BigQuery:

yaml

aggregate:
  - { measure: revenue, operation: sum, as: total_revenue }
  - { measure: quantity, operation: avg, as: avg_quantity }
groupBy: [category, region]

Supported operations:

sum, avg, min, max, count, count_distinct

Filtering

Apply filters to your data:

yaml

aggregate:
  filters:
    - { field: revenue, operation: ">", value: 1000 }
    - { field: region, operation: "in", value: ["US", "CA"] }

Filter operations:

>, <, >=, <=, =, !=
in, not in
contains, starts_with, ends_with

Why DuckDB?

Fast: Aggregations run in milliseconds
No API calls: Transform cached data instantly
Free: Doesn't count against BigQuery quota
Interactive: Change filters/groupings without waiting

Dashboard Parameters

Make your dashboards interactive with parameters:

Define Parameters

yaml

params:
  - name: start_date
    type: date
    default: "2024-01-01"
  - name: region
    type: select
    options: [US, EU, APAC]
    default: US

Use in Queries

Reference parameters with $params:

yaml

data:
  query: |
    SELECT *
    FROM sales
    WHERE date >= '$params.start_date'
      AND region = '$params.region'

Parameter Types

date - Date picker
select - Dropdown menu
multiselect - Multi-select dropdown
text - Text input
number - Numeric input

Styling & Customization

Color Palettes

Kyomi includes beautiful color palettes:

yaml

style:
  colorPalette: spectrum_pro  # or autumn_forest, horizon_suite

Custom colors:

yaml

style:
  colors:
    - "#FF6B6B"
    - "#4ECDC4"
    - "#45B7D1"

Chart Dimensions

yaml

style:
  height: 400        # Chart height in pixels
  width: "100%"      # Full width (default)

Axes & Labels

yaml

style:
  title: "My Chart"
  xAxisLabel: "Date"
  yAxisLabel: "Revenue ($)"
  showLegend: true
  legendPosition: "right"  # or "top", "bottom", "left"

Number Formatting

yaml

style:
  format: "$,.2f"     # Currency: $1,234.56
  format: ",.0f"      # Thousands: 1,234
  format: ".1%"       # Percentage: 45.2%

Advanced Features

Multi-Series Charts

Multiple metrics on one chart:

yaml

visualize:
  type: line
  columns: month
  rows: [revenue, cost, profit]
  style:
    title: "Financial Overview"

Dual-Axis Charts

Different scales for different metrics:

yaml

visualize:
  type: line
  columns: month
  rows: revenue
  secondaryAxis:
    rows: conversion_rate
    format: ".1%"

Annotations

Add reference lines and markers:

yaml

style:
  annotations:
    - type: line
      value: 1000
      label: "Target"
      color: "#FF0000"

BigQuery Connection

Setting Up

Go to Settings → BigQuery
Click Connect Google Account
Authorize Kyomi to access BigQuery
Select which projects to index

Project Management

Add projects: Click "Add Projects" to index new data sources
Remove projects: Remove projects you no longer need
Public datasets: Toggle to include BigQuery public datasets
Refresh catalog: Manually refresh to pick up schema changes

Billing

Kyomi uses your BigQuery billing project for queries. You pay Google directly based on bytes processed. Kyomi charges only for AI usage, not BigQuery costs.

Cost optimization:

Use LIMIT clauses for exploration
Set query size limits in Settings
Enable query caching (automatic)
Use Arrow streaming on Pro+ tiers

AI Agent Features

Custom Knowledge

Train the AI on your business context:

Workspace Knowledge (Settings → Knowledge → Workspace)

Shared across all team members
Define metrics, terminology, business rules
Admin-only editing

User Knowledge (Settings → Knowledge → User)

Private to you
Personal preferences, common queries
Your own reference notes

Auto-Learnings (Settings → Knowledge → Learnings)

AI automatically learns from conversations
Discovered tables and schemas
Query patterns and preferences

Token Usage

Monitor AI usage in Settings → Usage:

See percentage of monthly budget used
Breakdown by feature (Chat, SQL Copilot, Chart Copilot)
Upgrade tier for more AI budget

SQL Editor

Features

Syntax highlighting: BigQuery SQL with autocomplete
Dry run validation: Check queries before running
Query history: Auto-saved queries with search
Star favorites: Prevent auto-deletion
Performance stats: Execution time and bytes processed
Pagination: Navigate large result sets
Create charts: Turn results into visualizations

Keyboard Shortcuts

Ctrl/Cmd + Enter: Run query
Ctrl/Cmd + S: Save to history
Ctrl/Cmd + /: Toggle comment

Tips & Tricks

Performance

Cache everything: Kyomi caches BigQuery results in DuckDB - refresh only when needed
Use aggregations: Transform data client-side instead of requerying
Limit large queries: Use LIMIT for exploration, refine before full run
Arrow streaming: Enable in Settings for 20-100x faster data transfer (Pro+)

Chart Design

Keep it simple: One insight per chart
Choose the right type: Line for trends, bar for comparisons, table for details
Add context: Use titles, labels, and annotations
Test interactivity: Verify sorting and pagination on tables

Working with AI

Be specific: "Line chart of daily revenue for last 30 days" beats "show sales"
Iterate: Refine charts by asking follow-up questions
Add context: Put important business rules in Workspace Knowledge
Use copilots: SQL and Chart copilots are faster for quick edits

ChartML Reference

For the complete ChartML specification with all options and examples, visit:

chartml.org →

The ChartML docs include:

Complete property reference
Advanced examples
JSON schema for validation
Language specification

Need More Help?

In-app AI: Ask questions in chat - the AI knows how to help
Community: Join our Discord community (coming soon)
Support: Email support@kyomi.ai
Updates: Follow @kyomi_analyst for product updates

Last updated: November 2025

Documentation & Help ​

Quick Start ​

1. Connect Your Data ​

2. Start Chatting ​

3. Build Dashboards ​

Creating Charts ​

1. Ask the AI ​

2. Use the Chart Builder ​

3. Write ChartML Directly ​

ChartML Basics ​

Key Concepts ​

Chart Types ​

Bar Chart ​

Line Chart ​

Area Chart ​

Scatter Plot ​

Pie / Donut Chart ​

Table Chart ​

Metric Card ​

Data Sources ​

BigQuery Queries ​

Inline Data ​

Client-Side Data Processing (DuckDB) ​

Aggregations ​

Filtering ​

Why DuckDB? ​

Dashboard Parameters ​

Define Parameters ​

Use in Queries ​

Parameter Types ​

Styling & Customization ​

Color Palettes ​

Chart Dimensions ​

Axes & Labels ​

Number Formatting ​

Advanced Features ​

Multi-Series Charts ​

Dual-Axis Charts ​

Annotations ​

BigQuery Connection ​

Setting Up ​

Project Management ​

Billing ​

AI Agent Features ​

Custom Knowledge ​

Token Usage ​

SQL Editor ​

Features ​

Keyboard Shortcuts ​

Tips & Tricks ​

Performance ​

Chart Design ​

Working with AI ​

ChartML Reference ​

Need More Help? ​

Documentation & Help

Quick Start

1. Connect Your Data

2. Start Chatting

3. Build Dashboards

Creating Charts

1. Ask the AI

2. Use the Chart Builder

3. Write ChartML Directly

ChartML Basics

Key Concepts

Chart Types

Bar Chart

Line Chart

Area Chart

Scatter Plot

Pie / Donut Chart

Table Chart

Metric Card

Data Sources

BigQuery Queries

Inline Data

Client-Side Data Processing (DuckDB)

Aggregations

Filtering

Why DuckDB?

Dashboard Parameters

Define Parameters

Use in Queries

Parameter Types

Styling & Customization

Color Palettes

Chart Dimensions

Axes & Labels

Number Formatting

Advanced Features

Multi-Series Charts

Dual-Axis Charts

Annotations

BigQuery Connection

Setting Up

Project Management

Billing

AI Agent Features

Custom Knowledge

Token Usage

SQL Editor

Features

Keyboard Shortcuts

Tips & Tricks

Performance

Chart Design

Working with AI

ChartML Reference

Need More Help?