Quick Start

This guide walks you through creating a table, inserting data, querying it, and running a vector search — all against your Zatabase cloud project.

Prerequisites: A Zatabase account and project. See Getting Started if you have not set those up yet.

Replace your-project in the examples below with your actual project name.

1. Authenticate

All requests require your API key in the Authorization header:

export ZATABASE_ENDPOINT="https://your-project.zatabase.io"
export ZATABASE_KEY="your-api-key"

If you are building an application with end-user authentication, use the login endpoint instead:

curl -s -X POST $ZATABASE_ENDPOINT/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "SecurePass123!"}' | jq

This returns an access token and refresh token for session-based authentication.

2. Create a Table

curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "CREATE TABLE users (name TEXT, email TEXT, age INTEGER)"}' | jq

Supported column types: TEXT, INTEGER, FLOAT, BOOL, and VECTOR(N) for embedding columns.

3. Insert Data

curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "INSERT INTO users (name, email, age) VALUES ('\''Alice'\'', '\''[email protected]'\'', 30)"}' | jq

curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "INSERT INTO users (name, email, age) VALUES ('\''Bob'\'', '\''[email protected]'\'', 25)"}'

curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "INSERT INTO users (name, email, age) VALUES ('\''Charlie'\'', '\''[email protected]'\'', 35)"}'

4. Query Data

curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM users WHERE age > 28"}' | jq

Response:

{
  "rows": [
    {"name": "Alice", "email": "[email protected]", "age": "30"},
    {"name": "Charlie", "email": "[email protected]", "age": "35"}
  ],
  "affected_rows": 0
}

5. Vector Search

Create a table with a vector column, insert embeddings, and run a KNN query:

# Create a table with a 4-dimensional embedding column
curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "CREATE TABLE documents (title TEXT, embedding VECTOR(4))"}' | jq

# Insert documents with embeddings
curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "INSERT INTO documents (title, embedding) VALUES ('\''Rust Guide'\'', ARRAY[0.1, 0.2, 0.3, 0.4])"}'

curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "INSERT INTO documents (title, embedding) VALUES ('\''Python Guide'\'', ARRAY[0.5, 0.6, 0.7, 0.8])"}'

# Build an HNSW index for fast approximate search
curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 200)"}' | jq

# Find the nearest document to a query vector
curl -s -X POST $ZATABASE_ENDPOINT/v1/sql \
  -H "Authorization: Bearer $ZATABASE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT title, embedding <-> ARRAY[0.1, 0.2, 0.3, 0.5] AS distance FROM documents ORDER BY embedding <-> ARRAY[0.1, 0.2, 0.3, 0.5] LIMIT 5"}' | jq

6. Connect via SDK

Once you have verified things work with cURL, switch to an SDK for a better development experience.

TypeScript

import { Zatabase } from '@zatabase/sdk';

const db = new Zatabase({
  endpoint: 'https://your-project.zatabase.io',
  apiKey: 'your-api-key',
});

// Create a table
await db.sql.execute('CREATE TABLE users (name TEXT, email TEXT, age INTEGER)');

// Insert data
await db.sql.execute("INSERT INTO users (name, email, age) VALUES ('Alice', '[email protected]', 30)");

// Query
const result = await db.sql.execute('SELECT * FROM users WHERE age > 28');
console.log(result.rows);

Python

from zatabase import Zatabase

db = Zatabase(
    endpoint="https://your-project.zatabase.io",
    api_key="your-api-key",
)

# Create a table
await db.sql.execute("CREATE TABLE users (name TEXT, email TEXT, age INTEGER)")

# Insert data
await db.sql.execute("INSERT INTO users (name, email, age) VALUES ('Alice', '[email protected]', 30)")

# Query
result = await db.sql.execute("SELECT * FROM users WHERE age > 28")
print(result.rows)

Rust

use zatabase::Zatabase;

let db = Zatabase::builder()
    .endpoint("https://your-project.zatabase.io")
    .api_key("your-api-key")
    .build()?;

// Create a table
db.sql().execute("CREATE TABLE users (name TEXT, email TEXT, age INTEGER)").await?;

// Insert data
db.sql().execute("INSERT INTO users (name, email, age) VALUES ('Alice', '[email protected]', 30)").await?;

// Query
let result = db.sql().execute("SELECT * FROM users WHERE age > 28").await?;
println!("{:?}", result.rows);

Next Steps

SQL Reference — Full SQL syntax supported by Zatabase
Vector Search — Embeddings, HNSW indexes, and similarity queries
Collections — Ingest JSON documents with NoSQL semantics
Authentication — JWT flows, API keys, and environment switching
SDKs — Full SDK reference for TypeScript, Python, and Rust