Search schema with natural language

Every agent run starts cold on an unfamiliar schema. Call db.search() with a plain-english goal like “abandoned carts” to receive ranked hits across tables, columns, and stored descriptions, then write precise SQL against the exact tables it found.

import { PerSQL } from "@persql/sdk";

const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
const db = persql.database("acme/orders");

const { hits } = await db.search("abandoned carts", { limit: 5 });
for (const h of hits) {
  console.log(h.kind, h.table, h.column ?? "-", h.score.toFixed(2));
}

const top = hits.map(h => `${h.table}${h.column ? `.${h.column}` : ""}`).join(", ");
console.log("Search context:", top);

The search index spans table names, column names, and any descriptions you have stored via setDescription. Hits include a relevance score so the agent can decide when the match is strong enough to trust.

Next step

Validate agent SQL before running