Every key a config file understands.

Go from nothing to a working query

Every language does the same three things: install the package, point it at a config file, and ask a question in plain English. Two things to have ready first:

export QF_API_KEY="your-real-key-here"

Go

No third-party dependencies — standard library only.

go get github.com/awsaman-ai/queryforge

package main

import (
	"context"
	"fmt"

	qf "github.com/awsaman-ai/queryforge"
)

func main() {
	cfg, err := qf.LoadConfig("orders.config.json")
	if err != nil {
		panic(err)
	}
	engine := qf.New(cfg)

	res, err := engine.Translate(context.Background(), "cancelled orders over 200 dollars", "sql", nil)
	if err != nil {
		panic(err)
	}

	fmt.Println(res.Query.SQL)   // SELECT ... WHERE (status = $1 AND amount > $2)
	fmt.Println(res.Query.Args)  // [CANCELLED 200]
	fmt.Println(res.Explain)     // plain-English readback of what it understood
}

Save this as main.go next to your config file and run go run main.go.

Python

The engine ships inside the wheel — no Go toolchain to install.

pip install queryforge-ai

Installs as queryforge-ai, imports as queryforge.

from queryforge import QueryForge

qf = QueryForge.postgres("orders.config.json")
pending = qf.query("cancelled orders over $200")

print(pending.to_sql())    # SELECT ... WHERE (status = $1 AND amount > $2)
print(pending.to_args())   # ('CANCELLED', 200)
print(pending.explain())   # plain-English readback of what it understood

Save this as app.py next to your config file and run python app.py.

Java

Two Maven dependencies: the classes, and the engine binary for the platform you run on (see the platform table for the classifier to use — e.g. darwin-arm64 for Apple Silicon, linux-amd64 for most servers). Why two?

<dependency>
  <groupId>io.github.awsaman-ai</groupId>
  <artifactId>queryforge</artifactId>
  <version>LATEST</version>
</dependency>
<dependency>
  <groupId>io.github.awsaman-ai</groupId>
  <artifactId>queryforge</artifactId>
  <version>LATEST</version>
  <classifier>darwin-arm64</classifier>
</dependency>

import io.queryforge.QueryForge;
import io.queryforge.PendingQuery;
import java.nio.file.Paths;

public class App {
    public static void main(String[] args) {
        QueryForge forge = QueryForge.postgres(Paths.get("orders.config.json"));
        PendingQuery pending = forge.query("cancelled orders over $200");

        System.out.println(pending.toSql());    // SELECT ... WHERE (status = $1 AND amount > $2)
        System.out.println(pending.toArgs());   // [CANCELLED, 200]
        System.out.println(pending.explain());  // plain-English readback of what it understood
    }
}

Requires Java 11 or later. Zero runtime dependencies — not even a JSON library.

Putting Python or Java behind a web server? Read Running in production for timeouts, logging, error codes and how to cap the number of queries running at once.

The shape of a config file

Every config is one JSON object with the same nine possible top-level keys. Only two are ever required: entity and fields. Everything else has a sensible default, so the smallest valid config is genuinely tiny.

{
  "entity": "Order",
  "fields": [
    { "name": "status", "type": "string" }
  ]
}

This loads. No model, no backend, no capability flags — everything not shown here falls back to a type-aware default, explained section by section below.

How it's loaded

In Go, the file is read once at startup:

cfg, err := qf.LoadConfig("orders.config.json")
engine := qf.New(cfg)

res, err := engine.Translate(ctx, "cancelled orders over 200 dollars", "sql", nil)
fmt.Println(res.Query.SQL)   // SELECT * FROM orders WHERE (status = $1 AND amount > $2)
fmt.Println(res.Query.Args)  // [CANCELLED 200]

entity & version

These boxes just name the file (and, optionally, set the timezone). They carry no query logic of their own. Each arrow below points at one box and says what it means, with an example.

"entity": "Order",
"version": 2,
"timezone": "Asia/Kolkata"

model & models[]

The model block tells QueryForge which AI service turns a typed sentence into a query plan. Skip it entirely if you'll only ever send ready-made queries through GenerateFrom — that path never calls a model.

1. Pick the service and the model

Start with the provider cards, then the model and the key. The lines below are what the builder writes into model.

Pasting the key instead

Choosing Paste my key swaps the variable name for a password box. Use it for local testing only.

2. Advanced settings: how it answers

Open Advanced settings to change the label, the address and how the model behaves. Every box here has a default, so leave one blank and its key stays out of the file.

3. More connection settings

Timeouts and retries. Open More connection settings inside Advanced settings. The grey numbers are the defaults, used when a box is left empty.

aws (region and credentials) is only used when the provider is Amazon Bedrock, and is ignored by every other provider. See Amazon Bedrock below.

"model": {
  "provider": "gemini",
  "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai",
  "model": "gemini-3.5-flash",
  "apiKeyEnv": "QF_API_KEY",
  "temperature": 0,
  "maxTokens": 4096
}

Amazon Bedrock

"provider": "bedrock" talks to Bedrock's Converse API, one request shape for every model family it hosts (Claude, Nova, Llama, Mistral and more). The address is built from your AWS region, so there is no baseURL to set. There is no default model either: Bedrock ids differ by region and many need an inference-profile id (a us. or eu. prefix), so copy the exact id from the Bedrock console into model.

"model": {
  "provider": "bedrock",
  "model": "us.anthropic.claude-sonnet-4-6",
  "aws": { "region": "us-east-1", "bearerTokenEnv": "AWS_BEARER_TOKEN_BEDROCK" }
}

Everything in aws is optional. With no aws block at all, QueryForge reads the same variables the AWS CLI does: AWS_REGION, then AWS_BEARER_TOKEN_BEDROCK (a Bedrock API key) or AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN for temporary credentials).

Two ways to give each credential. The plain name (secretAccessKey) holds the value itself; the Env name (secretAccessKeyEnv) holds the name of an environment variable. Use one per credential, never both. A config picks one authentication mode, a bearer token or IAM keys, and half a key pair is rejected at load.

models[] — the fallback chain

An ordered list of backup models, same shape as model. QueryForge tries model first, then each entry here in order, and uses whichever answers first — so a rate limit, quota block or outage on one falls through to the next instead of failing the request. Entries may mix providers freely.

"models": [
  { "provider": "groq", "baseURL": "https://api.groq.com/openai/v1",
    "model": "llama-3.3-70b-versatile", "apiKeyEnv": "GROQ_API_KEY" },
  { "provider": "ollama", "baseURL": "http://localhost:11434/v1",
    "model": "qwen2.5" }
]

If Gemini is rate-limited today, Groq answers instead, and the response reports ProviderUsed: "groq" so you can see which one actually ran.

backends

Points your entity's name at the real table or collection in each database you use. Skip it and the entity name (Order) is used as-is. Every key here is a physical name, not a query rule — the actual compiling is done by the generator for that backend id.

"backends": {
  "sql":   { "table": "orders" },
  "mysql": { "table": "orders_tbl" },
  "mongo": { "collection": "orders_v2" }
}

With the mapping above: entity "Order" + collection "orders_v2" compiles Mongo calls to db.orders_v2.find(…), while the entity name in every question and every AST stays just "Order".

fields[] — the basics

This is the whole vocabulary the model is allowed to use. Anything listed here can be asked about; anything left out cannot be invented — the model is told to say so rather than guess. At least one field is required.

For a field of kind array, one more box appears: List holds (itemType).

{
  "name": "status",
  "type": "enum",
  "values": ["PLACED", "DELIVERED", "CANCELLED", "REFUNDED"],
  "synonyms": ["state", "order status", "delivery status"],
  "mapping": { "sql": "status", "mongo": "status" }
}

With synonyms set like this, "what's the state of my order" and "delivery status" both resolve to status just as well as the word "status" itself.

Importing fields from a schema

This is a config builder feature, not a config file key — a real schema has dozens of fields, and adding each one by hand is the slow part. Open the builder, go to Step 4 (Describe your fields), and expand Import fields from a schema. Pick your database, paste its own schema artifact, and the builder turns it into ordinary fields[] entries — the exact same shape "Add a field" produces, just filled in for you.

Pick the database you are importing from. Each tab shows what the builder asks you to paste, and how to get it.

Elasticsearch and SQL are read straight off the schema the database itself reports, so the type mapping is exact. Mongo has no fixed schema, so it's an educated guess from the sample's own value shapes — a date-looking string becomes date, a number becomes number, and so on; if two pasted documents disagree on a field's type, the row is flagged rather than silently picked for you.

A few config keys are detected automatically where the source schema states them outright:

• keywordMapping — from Elasticsearch's own "text field with a keyword sub-field" convention.
• nestedPath — from an Elasticsearch mapping type of "nested" (a plain "object" is flattened to a dot-path name instead, with no nestedPath).
• elemMatch — from a Mongo array whose sample elements are sub-documents, not scalars.
• indexed — from a SQL PRIMARY KEY or UNIQUE column.
• values — from a MySQL ENUM(...) column's literal list.

Before anything is added, a review table shows every discovered field with an editable type dropdown and a notes column explaining what was detected (or flagged) — an unrecognized column/mapping type is never silently guessed at; it's mapped to string with a note to check it by hand. A field whose name already exists in your config is unchecked by default rather than overwritten. Only the rows you leave checked are added, as real field cards you can keep editing exactly like a hand-added one.

The six field types

Every field is exactly one of these. The type decides which operators can even be considered, and what a value has to look like to pass validation.

Click a type to see what it holds and which comparisons it accepts out of the box (the ticked boxes).

Capability flags

Five booleans that decide exactly what's allowed to happen to a field. Each one defaults sensibly by type, and only the flags you explicitly set are ever written to the file — an untouched field always inherits today's default rather than freezing it.

{ "name": "internalCost",  "type": "number", "queryable": false }
{ "name": "description",  "type": "string", "searchable": false }
{ "name": "salary",       "type": "number", "returnable": false }

"orders where internalCost is over 50" → refused, the model never even learns the field exists. "description mentions x" → refused, but description can still be shown and sorted. SELECT * on the salary table becomes SELECT id, name, dept … automatically.

Custom fields — when a name doesn't explain itself

Some databases have field names like txt01 or customField3 — leftovers from a generic or per-tenant schema. The model can't guess what these hold just by reading the name, the way it can guess that status is a status. Check customField on a field like this, and QueryForge makes you explain it: the config simply won't load until you do.

{
  "name": "txt01",
  "type": "string",
  "customField": true,
  "displayName": "Passport Country",
  "description": "ISO country of issuance for the passport",
  "valueHint": "Free-text notes — usually mentions visa type, renewal status, and issuing country."
}

Ask "passports issued in Germany" and the model now knows txt01 is the right field. The readback also reads better: "Passport Country is Germany" instead of "txt01 is Germany".

Advanced field keys

The rest of what a field can carry — mostly nesting rules for MongoDB and Elasticsearch, plus small correctness and ranking hints.

// items: [{sku:"ABC", price:20}, {sku:"XYZ", price:900}]
// "item ABC costing over 100"

// without elemMatch — WRONG, matches this order:
{"items.sku":"ABC", "items.price":{"$gt":100}}

// with elemMatch: "items" — correct, matches nothing:
{"items": {"$elemMatch": {"sku":"ABC", "price":{"$gt":100}}}}

"mapping":        { "elasticsearch": "customerName" }
"keywordMapping": { "elasticsearch": "customerName.keyword" }

// "customer name contains John"        -> match on customerName (text)
// "customer name equals John Smith"    -> term on customerName.keyword

Operators

Nineteen comparisons exist in total; this is the complete, fixed catalogue — the loader rejects anything not in it. A field's operators list narrows what's allowed on it; leaving it out means "use my type's defaults" from the table above.

Dates, periods & timezone

A time in a question is one of two quite different things, and QueryForge keeps them apart on purpose. Getting this wrong is the difference between "how many orders today" returning today's orders and returning most of today's orders.

"operator": "between",
"value": { "kind": "period",
           "unit": "day",
           "from": -1, "to": -1 }

"operator": "after",
"value": { "kind": "relative_date",
           "unit": "hour",
           "amount": -2 }

How a period is read

from and to count whole units away from the current one: 0 is the current day, week or month, -1 is the one before it. Both ends are inclusive, and weeks start on Monday. A period is only valid with between, on a date field — it is a range, so "after last month" has no single honest reading.

Every backend compiles a period to a half-open range — start included, end excluded — rather than an inclusive BETWEEN. That way a row stamped 23:59:59.999 on the last day is counted, and midnight of the next day is not, without depending on the column's precision:

SQL            (created_at >= $1 AND created_at < $2)
MongoDB        { "createdAt": { "$gte": ISODate(start), "$lt": ISODate(end) } }
Elasticsearch  { "range": { "createdAt": { "gte": "…", "lt": "…" } } }

On a date-partitioned Elasticsearch setup, a period selects exactly the indices it overlaps — no wider scan than the question asked for.

timezone

Set the top-level timezone to the IANA zone your users live in, and calendar periods are cut on their midnight instead of UTC's.

{
  "entity": "Order",
  "timezone": "Asia/Kolkata",
  "fields": [ … ]
}

Why it is worth setting: a user in Kolkata asks "how many orders today" at 08:30 their time. Left at UTC, "today" runs 05:30 IST to 05:30 IST tomorrow — so every order placed between midnight and 5:30am is missing from the answer. No error, no warning, just a number that is quietly too small. With the zone set, the same question covers their real midnight-to-midnight day.

• Daylight saving is handled: the day the clocks move is 23 or 25 hours long, and its boundaries still land on local midnight.
• relative_date values are unaffected — "3 hours ago" is the same instant in every zone.
• Absolute literals such as {"kind":"date","v":"2026-09-15"} are still read as UTC, zone or no zone.
• The explanation returned with a query names the zone, so a user can catch a wrong one before trusting the numbers: "createdAt falls in yesterday (Asia/Kolkata time)".

Elasticsearch / OpenSearch

Elasticsearch and OpenSearch share one compiler — the query DSL QueryForge emits is byte-identical either way. A config still names one product (backends.elasticsearch or backends.opensearch), because that's the id you pass to Translate. Elasticsearch/OpenSearch can't be mixed with SQL or Mongo backends in the same config — a config targets one search cluster, not several.

Which index(es) to search — four modes

The Type dropdown in the builder has four choices. Click one to see what it writes into the config and what request it resolves to.

Business-rule routing — four strategies

Routing never guesses: a routing field absent from the question, or a strategy that resolves nothing, falls back to a required default index list. QueryForge never searches an unrestricted wildcard.

"routing": {
  "strategy": "pattern",
  "field": "tenantId",
  "indexPattern": "tenant-{tenantId}-orders",
  "default": ["orders-shared"]
}
// tenantId = "acme" -> tenant-acme-orders

"routing": {
  "strategy": "date",
  "field": "createdAt",
  "indexPattern": "orders-{yyyy-MM}",
  "granularity": "MONTH",
  "default": ["orders-legacy"]
}
// 2025-11-15..2026-02-10 -> 4 monthly indexes

"routing": { "strategy": "rules", "rules": [
  { "when": {"field":"amount","operator":"gt","value":"1000"},
    "indexes": ["orders-big"], "priority": 1 },
  { "when": {"field":"amount","operator":"gt","value":"500"},
    "indexes": ["orders-medium"] }
], "default": ["orders-standard"] }

"routing": { "strategy": "ifElse", "branches": [
  { "if": {"field":"createdAt","operator":"gte","value":"2026-01-01"},
    "indexes": ["orders-2026"] },
  { "else": true, "indexes": ["orders-legacy"] }
], "default": ["orders-legacy"] }

How the compiler actually behaves

Everything above is the config. This is what the generator does with it once a question has already been validated — for anyone debugging a query that came back with unexpected results, or reviewing the compiled DSL for correctness. It reflects the actual Go implementation (gen_es.go, source_es.go, elastic_config.go), not just the config shape.

One compiler, read-only, no execution

Elasticsearch and OpenSearch are compiled by the same function. There's no dialect split today because the query-DSL surface QueryForge emits — bool/filter, term/terms/range/match/prefix/wildcard/regexp/exists/nested, sort, _source, size/from — hasn't diverged between the two products. Generate() is a pure function of the query and the config: no network call, nothing executed against a real cluster. Method is always "GET" — QueryForge only ever builds a search request, never anything that could write.

type ESQuery struct {
  Method     string   // always "GET"
  Index      []string // resolved physical index/alias name(s)
  Path       string   // "/<index0>,<index1>/_search", ready to use
  SourceType string   // DIRECT_INDEX | MULTIPLE_INDEX | ALIAS | BUSINESS_RULE_INDEX
  Query      map[string]any
  Sort       []map[string]any
  Source     any // projection — omitted means every field
  Size, From int
}

A caller can use Path directly as GET <Path> with Query/Sort/_source/size/from as the body, or read Index and SourceType in structured form — both describe exactly the same resolution.

Which physical field a predicate actually touches

Every operator except contains reads a field's exact path — its keywordMapping when one is set, otherwise its ordinary mapping. Only contains on a string reads the plain mapping as analyzed text. This is the concrete mechanics behind the rule stated earlier: a field indexed twice (analyzed text + unanalyzed keyword) is searched on the right twin automatically, per operator — you never choose it yourself in the question.

Case-insensitive comparisons

A field's caseInsensitive: true renders differently depending on the query type, because Elasticsearch's own case_insensitive parameter isn't available everywhere. term, prefix, wildcard and regexp all take it natively. terms (used for in/containsAny) does not — QueryForge renders that case as a bool/should of individually case-insensitive term queries instead, one per value, with minimum_should_match: 1.

Negation and SQL's NULL semantics — the fix behind notEquals/notIn/NOT

In SQL, status <> 'CANCELLED' evaluates to NULL — not true — for a row whose status column is NULL, so that row is excluded from the results. A bare Elasticsearch must_not doesn't have that three-valued logic: a document that's missing the field entirely still satisfies must_not, because there's nothing there to contradict it. Left alone, that mismatch means notEquals/notIn/a logical NOT would silently return more rows on Elasticsearch than the identical question returns on Postgres or Mongo — breaking the guarantee that the same question means the same rows on every backend.

QueryForge closes the gap by ANDing an exists filter alongside every such must_not, so a document missing the field is excluded from both the match and its negation — matching how SQL and Mongo already behave. The guard is skipped where it wouldn't mean anything: isNull/isNotNull (already about absence) and a NOT over a nested field (the nested object existing says nothing about the leaf value inside it). This exact gap was caught in review before the backend shipped and is pinned permanently by a dedicated test (TestESNegationRequiresExistence).

// "status" not "CANCELLED" -> without the guard, a document with no
// status field at all would incorrectly match:

{ "term": { "status.keyword": "CANCELLED" } }  // naive must_not target

// what QueryForge actually compiles:
{ "bool": {
    "must_not": [ { "term": { "status.keyword": "CANCELLED" } } ],
    "filter":   [ { "exists": { "field": "status.keyword" } } ]
} }

Nested query folding

Two conditions that are direct AND siblings and share the same nestedPath are merged into one nested query wrapping a single bool/filter, instead of becoming two separate nested queries that could each match a different array element. This is the Elasticsearch analogue of Mongo's elemMatch folding, structurally simpler because an ES nested query addresses fields by their full path even from inside the wrapper — no relative-path rewriting is needed, unlike Mongo. A lone predicate on a nested path is still wrapped in nested, just not merged with anything. Folding only ever looks at direct AND children, for the identical reason routing only trusts AND-reachable predicates (below): a condition inside an OR or a NOT isn't guaranteed to hold for the same element.

{
  "bool": { "filter": [
    { "nested": { "path": "items", "query": { "bool": { "filter": [
      { "term":  { "items.sku": "ABC" } },
      { "range": { "items.price": { "gt": 100 } } }
    ] } } } },
    { "bool": {
        "must_not": [ { "term": { "status.keyword": "CANCELLED" } } ],
        "filter":   [ { "exists": { "field": "status.keyword" } } ]
    } }
  ] }
}

Business-rule routing: what's actually trusted

The routing strategies documented above rest on one rule: only a condition reachable from the filter root through AND alone is ever used to pick an index. A condition inside an OR branch, or inside a NOT, doesn't have to hold for every row the query returns, so it's never trusted for routing — even if it looks like the "obvious" value. Two AND-reachable conditions on the same routing field are just as unusable as none at all: which one would even apply? Both cases fall back to default, exactly like an absent field.

Load-time checks specific to Elasticsearch

On top of the general field/operator rules from earlier on this page, an Elasticsearch/OpenSearch config is checked against these before it loads:

defaults & policy

Two small blocks that bound what an otherwise-valid question can do — page sizes and how deep a filter tree may nest.

"defaults": { "limit": 50, "maxLimit": 500 },
// "give me the first 10000 orders" -> ... LIMIT 500
"policy": {
  "maxNestingDepth": 5,
  "denyRegexOn": ["customerName", "description"]
}

Field rules — "using this also needs that"

This is a small, optional rule. It says: if the question uses field A, it must also use field B — somewhere. If it doesn't, QueryForge stops and explains why, instead of running a question that would give a confusing or misleading answer.

Why would I need this?

Most of the time, one field is enough on its own. "Orders placed after January 1st" makes sense by itself — no other field is needed to understand it. But sometimes one field, by itself, is not enough to make the question mean something clear. The example that started this feature: a passport's expiry date only means something once you know which country's passport it is. "Passports that are expired" sounds like a real question, and every part of it is a real, working field — but the answer would be wrong or misleading without a country attached to it. A field rule catches that before a query ever runs.

The two words to know

Building one in the config builder

You never write JSON by hand for this. Open the config builder, go to Step 6 (Guardrails), and open the Field rules box. Each rule is one sentence made from two dropdowns — pick the trigger field, pick the companion field, optionally type your own message. That's it:

When passportExpiry is filtered, also require country

Both dropdowns only ever show fields you've already added to the config — you can't typo a field name into a rule, because there is nothing to type. Leave the box empty and nothing changes about your config; the rule only appears in the downloaded file once you've filled one in.

What it looks like in the JSON file

"policy": {
  "requires": [
    {
      "when": { "field": "passportExpiry" },
      "requireAlsoOneOf": ["country"],
      "message": "Passport expiry needs a country to be meaningful"
    }
  ]
}

Two worked examples

Example 1 — passports (the one above). Config has passportExpiry and country. The rule says: if passportExpiry is filtered, country must be filtered too.

• "Passports from India expiring this month" → runs normally. Both fields are present.
• "Passports that are expired" → blocked. Only passportExpiry is present. The app gets back: "Passport expiry needs a country to be meaningful."
• "Orders from India" → runs normally. passportExpiry was never used, so the rule never switches on at all.

Example 2 — refunds. Config has refundReason and orderNumber. The rule says: if refundReason is filtered, orderNumber must be filtered too — a refund reason on its own can span thousands of unrelated orders, which is rarely what someone actually wants.

• "Why was order 4471 refunded" → runs normally.
• "Refunds because the item was damaged" → blocked — no order number anywhere in the question.

How a blocked question is reported

This is not treated as a broken question and it is not treated as an ordinary error either — it gets its own kind of answer, called a policy error, so your app can show a different, more helpful message than "something went wrong". It carries three things: which field triggered the rule, which field(s) it needed, and the message to show the user.

{
  "success": false,
  "code": "POLICY_VIOLATION",
  "message": "Passport expiry needs a country to be meaningful",
  "policyError": {
    "field": "passportExpiry",
    "requireAlsoOneOf": ["country"],
    "message": "Passport expiry needs a country to be meaningful"
  }
}

In the Go library this arrives as its own error type, *qf.PolicyViolationError — different from an ordinary "this question can't be answered" error, and different again from a plain validation mistake like a misspelled field name. QueryForge does not try the question a second time when this happens: rephrasing alone would not add the missing information, so it reports the problem once and stops, the same way it already does for a question outside the config's vocabulary.

Tenancy / scope fields

A scope field is a value your application already knows — subscriptionId, userId, enterpriseId — and forces onto every query. Declare it queryable: false so the model never even learns the field exists; you pass the value yourself, at call time, not in the question.

{ "name": "subscriptionId", "type": "string", "queryable": false }

engine.Translate(ctx, "delivered orders over 500 dollars", "sql", qf.Scope{
  "subscriptionId": session.SubscriptionID,
})
// WHERE (subscriptionId = $1 AND status = $2 AND amount > $3)

Scope predicates are AND-ed onto the filter root after the model answers, and they're still fully parameterized — so a scope value can only narrow a query, never widen or replace one, and an injection payload in it stays a bound argument, not query text.

Making the tenant filter compulsory

Everything on this page so far makes a scope filter impossible to escape once you pass one. Nothing so far makes you pass it. policy.requiredScope is the missing half: it tells QueryForge to refuse any query that arrives without the tenant filter, instead of quietly running it against everybody's data.

The problem it solves

A scope filter is passed at the call site, in code — which means it can be left out at the call site, in code. Add a new endpoint, copy an existing call, forget the last argument, and you have a query that is valid, runs perfectly, returns rows, and is missing the one condition that kept each customer's data separate. Nothing errors. Nothing warns. The results look completely normal, because they are normal — just not filtered to one tenant.

There is a quieter version of the same bug. The filter is passed, but the value is empty — an environment variable that was never set, a claim missing from a token, a session field that was still null. An empty value becomes tenant_id = '', which matches no rows at all. The page comes back empty and looks exactly like a customer who has no data yet. QueryForge refuses a blank scope value for this reason, on every config, whether or not you turn the rule below on.

The three settings

In the config builder, in the Guardrails step, the box is called Always require a tenant / user filter. Pick one of three:

The difference between the last two is worth being clear about, because it is the whole point of naming keys. "Require any filter" is satisfied by {"region": "eu"} — something was passed, so the check is happy, and the query still is not confined to a tenant. "Require these names" with tenantId is not satisfied by that, and says so.

What it looks like in the JSON file

"policy": {
  "requiredScope": {
    "mode": "fields",
    "fields": ["tenantId"]
  }
}

Use { "mode": "any" } for the middle setting. Leave the key out entirely for "Off" — a config without it behaves exactly as it did before this setting existed.

The names are scope keys, not fields

This is the one part that surprises people. The names you list here are the keys you pass at call time — they are not checked against the field list, and they usually should not appear in it at all. The recommended setup for a tenant column is to keep it out of the config entirely, or declare it queryable: false, precisely so the model never learns it exists. If these names had to be registered fields, the safest configuration would be the one that refused to load.

The builder does warn you about the reverse mistake: naming a key that is a queryable field. That is legal, but it usually means you meant to hide the column and forgot, so the model can currently see it and write its own filter on it.

What a refused query looks like

{
  "success": false,
  "code": "INVALID_SCOPE",
  "message": "invalid scope: this config requires scope key(s) \"tenantId\",
              which the scope did not provide; pass a value for each"
}

Every missing key is listed at once, so wiring up a new call site does not turn into one error per name. In the Go library this is an errors.Is(err, qf.ErrScope) match; the Python SDK raises InvalidScopeError and the Java SDK the equivalent — the same error type you already get for a malformed scope value, because this is the same kind of problem: a bug in the calling code, not in the user's question.

The check runs before the model is called. A missing tenant filter cannot be fixed by asking the AI again, so it costs no API call and no waiting — it fails immediately, at the call site where the mistake actually is. It applies to every entry point equally: Translate, GenerateFrom and ApplyScope, so it cannot be sidestepped by compiling a hand-built AST instead of asking a question.

A complete, valid config

Every field type, mapping, synonym, capability flag and safety rule from this page, in one file that loads as-is — the same one the Config Builder starts from when you click "start with an example."

{
  "entity": "Order",
  "version": 1,
  "model": {
    "provider": "gemini",
    "baseURL": "https://generativelanguage.googleapis.com/v1beta/openai",
    "model": "gemini-3.5-flash",
    "apiKeyEnv": "QF_API_KEY",
    "temperature": 0,
    "maxTokens": 4096
  },
  "backends": {
    "sql":   { "table": "orders" },
    "mongo": { "collection": "orders" }
  },
  "fields": [
    {
      "name": "status", "type": "enum",
      "values": ["PLACED", "DELIVERED", "CANCELLED", "REFUNDED"],
      "operators": ["equals", "notEquals", "in", "notIn"],
      "synonyms": ["state", "order status", "delivery status"],
      "indexed": true, "priority": 10,
      "mapping": { "sql": "status", "mongo": "status" }
    },
    {
      "name": "refunded", "type": "boolean",
      "synonyms": ["was refunded", "is refunded"],
      "mapping": { "sql": "refunded", "mongo": "refunded" }
    },
    {
      "name": "createdAt", "type": "date",
      "operators": ["before", "after", "between"],
      "synonyms": ["created", "order date", "placed on", "ordered"],
      "indexed": true, "priority": 8,
      "mapping": { "sql": "created_at", "mongo": "createdAt" }
    },
    {
      "name": "amount", "type": "number",
      "operators": ["gt", "lt", "gte", "lte", "between"],
      "synonyms": ["total", "order value", "price", "cost"],
      "validators": { "min": 0 },
      "mapping": { "sql": "amount", "mongo": "amount" }
    },
    {
      "name": "tags", "type": "array", "itemType": "string",
      "operators": ["contains", "containsAny", "containsAll"],
      "synonyms": ["labels"],
      "mapping": { "sql": "tags", "mongo": "tags" }
    },
    {
      "name": "customerName", "type": "string",
      "operators": ["contains", "startsWith", "endsWith", "equals"],
      "synonyms": ["customer", "buyer", "name"],
      "searchable": true,
      "mapping": { "sql": "customer_name", "mongo": "customerName" }
    },
    {
      "name": "internalNote", "type": "string",
      "queryable": false, "returnable": false
    }
  ],
  "defaults": { "limit": 50, "maxLimit": 500 },
  "policy": { "maxNestingDepth": 5, "denyRegexOn": ["customerName"] }
}

What it does with a real question

Given this config, the question "cancelled orders over 200 dollars" resolves status and amount — both registered, both permitting the operators used — and compiles like this:

SELECT * FROM orders
WHERE (status = $1 AND amount > $2)
-- args: ["CANCELLED", 200]

{ "status": "CANCELLED", "amount": { "$gt": 200 } }

Same question, same validated plan, two different compiled outputs — nothing about the fields or the question changes between backends.

Common mistakes

Pulled directly from the loader's own validation rules — these are the ones that trip people up most, roughly ordered from "won't load at all" to "loads fine but quietly does the wrong thing."

Settings you pass at run time

The config file describes your data. These settings describe how QueryForge runs on your machine. They are environment variables, so you can change them per deployment without touching code or the config file.

They apply to the Python and Java SDKs, which run the QueryForge engine as a small helper process for each call. The Go library runs inside your own program and reads none of them — in Go you set the same things in code: a context deadline for timeouts and qf.SlogObserver for logs.

Limiting how many queries run at once

Each Python or Java call starts one engine process, and that process stays alive for the whole call — including the seconds spent waiting for the AI model to answer. A burst of 200 web requests therefore means 200 engine processes running together, which is how a server runs out of memory, file handles or process slots. One setting puts a ceiling on it.

# Python or Java
export QUERYFORGE_MAX_CONCURRENT_PROCESSES=8

# Java, as a JVM flag instead
java -Dqueryforge.maxConcurrentProcesses=8 -jar app.jar

With a limit of 8, the first 8 calls start right away. Call number 9 waits in line and starts the moment one of the 8 finishes. Waiting uses no polling and no extra threads, and your code does not change — a call that had to wait simply returns a little later.

What happens in each situation

Waiting counts against the timeout

Time spent in line is taken out of the call's timeout, not added on top of it. Give a query a 5-second timeout, let it wait 2 seconds for a slot, and the engine gets the remaining 3 seconds. A caller who asked for 5 seconds never waits much longer than 5 seconds, however busy the server is.

The limit is per process

The count is shared by every thread inside one program. In Java that means the whole JVM — every QueryForge instance shares one limit. In Python it means one interpreter process.

The setting is read once, on the first call. Changing the variable while the program is running has no effect; restart to apply a new value.

Choosing a number

Turn on logging at info and watch the wait_ms field (next section). If it is usually near zero, the limit is rarely reached. If it is often large, calls are queueing — raise the limit if the server has room, or add workers. If the server still runs short of memory during bursts, lower it. Your AI provider's rate limit is a sensible upper bound too: more simultaneous calls than it allows only turns waiting in line into rate-limit errors.

Timeouts, errors and logs

Every failure comes back as a specific error with a stable code. There is no path that returns an empty or partial query in place of an error.

Setting a timeout

# Python (seconds)
# for every query, or for one
qf = QueryForge.postgres("orders.config.json", timeout=10)
sql = qf.query("cancelled orders").timeout(5).to_sql()

// Java (milliseconds)
// for every query, or for one
QueryForge forge = QueryForge.postgres(Paths.get("orders.config.json")).withTimeout(10_000);
String sql = forge.query("cancelled orders").timeout(5_000).toSql();

// Go: a context deadline
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
res, err := engine.Translate(ctx, "cancelled orders", "sql", nil)

Error codes

The same codes appear everywhere: on the Python exception as e.code, on the Java exception as getCode(), and in Go from qf.Classify(err). Catch the base class (QueryForgeError / QueryForgeException) if you don't care why, or a specific one if you do.

TIMEOUT and SDK_BUSY share a class on purpose, so one except TimeoutError / catch (TimeoutException e) handles both. Check the code when you need to tell "the engine was slow" apart from "the server was too busy to start it".

Logs

Logging is off until you turn it on. Set QUERYFORGE_LOG_LEVEL=info and every call writes one line when it finishes:

engine request completed
  library=queryforge language=java operation=translate request_id=e63571548915
  backend=sql entity=Order outcome=ok duration_ms=2310 wait_ms=410

duration_ms is how long the call took in total. wait_ms appears only when QUERYFORGE_MAX_CONCURRENT_PROCESSES is set, and is the part of that time spent waiting for a slot. A failed call writes one error line instead, carrying error_code.

Quick reference

Every key on one page, for when you already know what you're looking for.

Top level

Every field key

How QueryForge works

QueryForge has one engine, written in Go. The engine does all the real work. The Python and Java packages are small helpers that pass your question to that same engine. The pictures below show how the pieces fit together.

The big picture

Your app sends a question and your config. The engine asks an AI model what the question means, and the AI answers with a plan. The engine checks that plan against your config — only the fields and values you allowed can pass. Then the engine writes the query. Your app runs it with the database driver you already use.

Three ways to use the same engine

In Go, the engine is a normal library inside your program. In Python and Java, the engine is a separate small program that comes inside the package. The Python or Java code starts it when you make a call. You never see this happen, and you don't need Go installed.

Because every language uses the same engine, the same question and config give the exact same query in Go, Python and Java.

What happens in one call (Python and Java)

1. You call to_sql() in Python or toSql() in Java.
2. The SDK finds the engine program made for your computer.
3. It starts the program and sends one JSON message with your question and config. Your API key is not in the message — the engine reads it from the environment.
4. The engine asks the AI model, checks the plan against your config, and builds the query.
5. The engine sends one JSON message back, then closes.
6. The SDK gives you the query and its values. If something went wrong, you get a clear error instead.

Nothing keeps running between calls. There is no server, no open port, and nothing to install besides the package. Starting the engine takes a few milliseconds; the AI model takes much longer. If your app makes many calls at the same time, read Limiting how many queries run at once.

Java: why two dependencies? (the classifier)

The engine is a real program, like any app on your computer. A program is built for one kind of computer: one operating system (Linux, Mac or Windows) and one type of chip (Intel/AMD or ARM). A program built for a Mac does not run on Linux.

Java code is different — the same jar runs everywhere. So the Java SDK comes in two parts:

• queryforge — the Java code. One small file for everyone.
• queryforge + a classifier — the engine program for one kind of computer. There are five, one for each computer type.

A classifier is just a label in Maven that picks one version of a file. You add the one that matches your computer. We don't put all five engines in one jar, because then everyone would download four engines they never use.

What happens on the first call. Java cannot run a program while it is still packed inside a jar. So the first time you make a call, the SDK copies the engine out to a temp folder and runs it from there. Every later call uses that same copy.

Each engine version gets its own copy, so two apps using different QueryForge versions never mix them up. If your temp folder does not allow running programs (it is mounted noexec), set QUERYFORGE_CACHE_DIR to a different folder.

Python: why only one install?

pip does the choosing for you. QueryForge publishes a separate package file (a "wheel") for each kind of computer, and pip install queryforge-ai downloads the one that matches your machine. The engine is already inside it, ready to run. There is nothing to copy and no label to pick.

Why we built it this way

The trade-off: each Python or Java call starts a small program (a few milliseconds), and in Java you have to pick the right classifier for your computer.