Performance

Use parameterized queries

Always use params instead of string interpolation — this enables query plan caching and prevents injection.

// Good
{"sql": "SELECT * FROM users WHERE id = ?", "params": ["123"]}

// Avoid
{"sql": "SELECT * FROM users WHERE id = '123'"}

KV for hot data

Pair SQL/MQL queries with KV caching for frequently-read data:

const cached = await kv.get(`user:${id}`);
if (cached) return cached;

const user = await sql.query('SELECT * FROM users WHERE id = ?', [id]);
await kv.set(`user:${id}`, user, { ttl: 300 });
return user;

Batch writes

Use sql/batch or mql/insertMany for bulk operations — they run in a single network round trip.

Vector search filters

Pass metadata filters to vector/query to narrow the search space before similarity ranking:

{
  "query": "authentication guide",
  "topK": 5,
  "filter": {"type": "docs", "version": "v2"}
}