Quickstart

Go from zero to your first query in under 5 minutes. This guide uses the hati CLI with the embedded DuckDB engine -- no cloud account or Docker required.

60-Second MCP Setup

Already using Claude, Cursor, or another MCP-compatible agent? Add HatiData as a tool in one step:

{
  "mcpServers": {
    "hatidata": {
      "command": "hatidata-mcp-server",
      "args": ["--host", "localhost", "--port", "5439"]
    }
  }
}

Then install and start:

pip install hatidata-agent[mcp]
hati init

Your agent now has query, list_tables, describe_table, and get_context tools. For the full MCP reference, see MCP Tools.

---

Install

Choose your preferred installation method:

# Python (recommended for AI agent workflows)
pip install hatidata-agent

# Rust (for CLI power users)
cargo install hatidata-cli

# Node.js
npm install @hatidata/sdk

Python Requirements

Python 3.9 or later. The hatidata-agent package includes psycopg2-binary for Postgres wire protocol connectivity.

Step 1: Initialize a Local Warehouse

hati init

This creates a .hati/ directory in your project with an embedded DuckDB database. No cloud connection needed -- everything runs locally.

.hati/
  config.toml        # Connection and runtime settings
  warehouse.duckdb   # Your local DuckDB database
  cache/             # Query and transpilation cache

Step 2: Create a Table

hati query "CREATE TABLE users (id INT, name VARCHAR, email VARCHAR)"

You can use Snowflake-compatible SQL syntax. HatiData automatically transpiles it to DuckDB:

# Snowflake types work too -- they're auto-converted
hati query "CREATE TABLE events (id INT, payload VARIANT, created_at TIMESTAMP_NTZ)"
# VARIANT -> JSON, TIMESTAMP_NTZ -> TIMESTAMP

Step 3: Insert Data

hati query "INSERT INTO users VALUES (1, 'Alice', 'alice@example.com')"
hati query "INSERT INTO users VALUES (2, 'Bob', 'bob@example.com')"
hati query "INSERT INTO users VALUES (3, 'Carol', 'carol@example.com')"

Step 4: Query Your Data

hati query "SELECT * FROM users"

Output:

+----+-------+--------------------+
| id | name  | email              |
+----+-------+--------------------+
|  1 | Alice | alice@example.com  |
|  2 | Bob   | bob@example.com    |
|  3 | Carol | carol@example.com  |
+----+-------+--------------------+
3 rows returned in 0.8ms

Snowflake-compatible functions are transpiled automatically:

# NVL -> COALESCE
hati query "SELECT NVL(email, 'unknown') FROM users"

# IFF -> IF
hati query "SELECT IFF(id > 1, 'yes', 'no') FROM users"

Step 5: Connect from Python

Use the Python SDK to connect an AI agent to your local warehouse:

from hatidata_agent import HatiDataAgent

agent = HatiDataAgent(
    host="localhost",
    port=5439,
    agent_id="quickstart-agent",
    framework="custom",
)

# The MCP server handles connections, or use `hati query` for CLI access
rows = agent.query("SELECT * FROM users")
for row in rows:
    print(row["name"], row["email"])

Step 6: Push to Cloud

When you are ready to share your data or connect AI agents remotely, push to the cloud:

hati push --target cloud

This uploads your local warehouse to HatiData Cloud ($29/month). Once complete, you get a connection string:

Connection ready!
  Host: your-org.proxy.hatidata.com
  Port: 5439
  Database: hatidata

Connect with psql:
  psql -h your-org.proxy.hatidata.com -p 5439 -U analyst -d hatidata

What Happens Next

After pushing to cloud, your data is available via any Postgres-compatible client:

# psql
psql -h your-org.proxy.hatidata.com -p 5439 -U analyst -d hatidata

# Python
from hatidata_agent import HatiDataAgent
agent = HatiDataAgent(host="your-org.proxy.hatidata.com", port=5439)
rows = agent.query("SELECT * FROM users")

# Node.js
import { Client } from 'pg';
const client = new Client({ host: 'your-org.proxy.hatidata.com', port: 5439 });

Try Hybrid SQL

HatiData's hybrid SQL lets you combine structured queries with semantic search. Get a free API key at hatidata.com/signup to unlock 50 hybrid queries/day.

from hatidata_agent import HatiDataAgent

agent = HatiDataAgent(
    host="localhost",
    port=5439,
    cloud_key="hd_live_..."  # from hatidata.com/signup
)

# Semantic search — find tickets about billing
result = agent.query("""
    SELECT ticket_id, subject, body
    FROM support_tickets
    WHERE semantic_match(embedding, 'billing dispute refund')
    ORDER BY semantic_rank(embedding, 'billing dispute refund') DESC
    LIMIT 10
""")

# Hybrid join — enrich with knowledge base
result = agent.query("""
    SELECT t.ticket_id, t.subject, k.article_title, k.solution
    FROM support_tickets t
    JOIN_VECTOR knowledge_base k ON semantic_match(k.embedding, t.subject)
    WHERE t.status = 'open'
    LIMIT 5
""")

Standard SQL queries work without a cloud key — hybrid SQL features require a free account.

Next Steps

• Local Mode -- Deep dive into offline development
• Cloud Mode -- Dashboard, connection strings, and team access
• Core Concepts -- Architecture, query pipeline, and key components
• Python SDK -- Agent-aware database access for AI workflows
• SQL Compatibility -- Full list of supported functions and types