@askdb/client API reference

Reference · @askdb/client

@askdb/client is a config-driven facade over @askdb/core. createAskDb() resolves the schema, model, and dialect from askdb.config.* once; call sites pass only a question. Use it when you want the shortest path from config to SQL. Use @askdb/core directly when you construct the model yourself, serve multiple schemas, or want zero dependency on @askdb/config.

createAskDb(options)

Builds a client bound to a config snapshot and AI provider registry. The schema, model, and dialect are resolved lazily on the first ask() call and cached for the process lifetime. Call reload() to clear the cache.

import { createAskDb } from "@askdb/client";
import { bootstrapAskDbEnv, getAskDbRuntimeConfig } from "@askdb/config";
import { openaiProvider } from "@askdb/ai-openai";

bootstrapAskDbEnv({ cwd: process.cwd() });

const askdb = createAskDb({
  config: getAskDbRuntimeConfig(),
  providers: [openaiProvider],
  schema: { path: "./my-app.schema" },
});

Options — CreateAskDbOptions

Field	Type	Required	Description
config	AskDbRuntimeConfig	yes	Runtime config snapshot from getAskDbRuntimeConfig(). Call bootstrapAskDbEnv() at startup first.
providers	AiProviderAdapters	one of	Provider adapters, e.g. [openaiProvider] from @askdb/ai-openai. The client builds the registry internally — the common path.
registry	AiRegistry	one of	Prebuilt registry from createAiRegistry(...) — advanced alternative to providers (e.g. to share one registry across clients). Pass exactly one of the two.
schema	SchemaSource	no	Default schema source. Falls back to host.schemaJson, then host.schemaPath, from askdb.config.ts.
dialect	BuiltInDialectId	no	Default dialect override. Falls back to config.nlToSql.dialect → schema.provider → "postgres".
unknownDialect	"throw" | "fallback-postgres"	no	What to do when schema.provider is not a recognized built-in dialect id. Default "throw".
onResolve	(info: ResolveInfo) => void	no	Hook fired on every ask() call once resolution completes. Useful for logging which dialect and model were chosen. ResolveInfo has dialect and modelSource.

SchemaSource

Accepted forms for the schema option and per-call overrides:

{ path: string }               // directory, bundle file, or schema.json path
{ json: string }               // raw JSON string
{ schema: AnyNormalizedSchema} // pre-loaded schema object

---

client.ask(question, overrides?)

const { sql, usage, unboundSql, params, preparedQuery } = await askdb.ask(
  "How many orders shipped last month?",
);

Runs the same pipeline as @askdb/core’s ask(). Returns AskPipelineResult — see @askdb/core API → Result. The facade forwards options and returns the core result verbatim, including optional unboundSql / params / parameters / preparedQuery when parameterize is on (default). Rebind locally with bindPreparedQuery from @askdb/core — it does not authorize tenant IDs.

Overrides — AskOverrides

All AskPipelineOptions fields can be overridden per call. In addition, schema, model, and dialect can be swapped for a single request:

Field	Type	Description
schema	SchemaSource | AnyNormalizedSchema	Override the default schema for this call only.
model	AskDbLanguageModel	Override the default model for this call only.
dialect	AskDialectInput	Override the dialect for this call only.
explain	boolean	Include guardrail metadata in the result.
omitSensitiveIdentifiersFromNlToSqlPrompt	boolean	Strip sensitive identifiers from the DDL prompt.
mode	AskDbModeV1	Trust boundary override.
tenantScope	TenantScope	Required when the schema has a tenant policy.
tenantSqlMode	TenantSqlOutputMode	"sql-only" or "sql-params".
parameterize	boolean	Default true. Set false to skip unbound SQL / parameter manifest output tokens.
retriever	Retriever	RAG retriever.
retrievalK	number	Top-k for the retriever.
retrievalThresholdChunks	number	Chunk count threshold for triggering retrieval.
totalSchemaChunkCount	number	Total indexed chunk count; from buildSchemaIndex result stats.
logger	AskDbLogger	Per-call structured logger.
deps	AskGenerateDeps	{ generateText? } for testing.

---

client.reload()

askdb.reload();

Drops the cached schema and model. The next ask() call re-resolves them from config. Useful in tests or in processes that hot-reload their config without restarting.

---

Read next

@askdb/core APIask() options and result types in full.Configuration referenceAll askdb.config.* fields and environment variables.Embed in a Node appEnd-to-end walkthrough using both the direct and client paths.