Run a server

The local quick start proves the query language. A server adds the important part: an application-owned catalog boundary.

RAQ currently includes Python/FastAPI and Rust/Axum implementations. This guide uses the Python implementation because it also hosts the browser playground.

Start the repository environment

From the repository root:

nix-shell

Then start the server:

cd backend
PYTHONPATH=src uvicorn raq.app:app --reload --port 8001

The first run initializes the local SQLite demo database. Open http://127.0.0.1:8001/ for the playground or request http://127.0.0.1:8001/schema to inspect the public catalog contract.

Send a bounded query

import { project, relation, runQuery, where } from "@raquery/query";

const query = project(
  where(relation("products"), "price > 100"),
  ["name", "price"]
);

const result = await runQuery(
  "http://127.0.0.1:8001/products",
  query,
  { store_id: 42 }
);

The request contains a serializable query tree. The server:

1. resolves products through the endpoint’s catalog
2. composes server-owned scope and authorization
3. validates the combined tree
4. compiles it to SQL with bound parameters
5. returns rows plus the inspectable SQL plan

What this does not expose

The client does not receive unrestricted table access. Physical joins, hidden columns, tenant rules, and source names remain owned by the application’s catalog definition.

For writes, the application keeps ownership of mutation logic and lets the catalog translate physical write lineage into public change notifications. Read Mutations and live updates for that flow, or continue to Query composition.