Skip to content
Querion

Querion / Reference

Configuration reference

Every key in querion.yaml and .env.example, with defaults and behavior confirmed against the code that reads them.

On this page
  1. How the file is found
  2. Environment interpolation
  3. Strictness
  4. Top-level keys
  5. database
  6. sources
  7. limits
  8. trove
  9. Environment variables
  10. A complete example
  11. Fixed values

Querion reads one YAML file plus environment variables. Start from querion.example.yaml and .env.example. The loader is querion/config.py.

The split is deliberate. The file describes what Querion connects to and how far it may go: the database, the application programming interface (API) sources, the model and the limits. The environment holds the secrets. The file can then be reviewed, copied and kept in version control without exposing a password or a token.

How the file is found

The path is chosen in this order:

  1. The -c / --config PATH flag, placed before the subcommand.
  2. The QUERION_CONFIG environment variable.
  3. querion.yaml in the current directory.

If the file does not exist, Querion stops with a “Config not found” error. Relative paths inside the file (schema_doc, docs, layer_path) resolve against the directory that holds the config file, not the current directory.

Environment interpolation

Any ${VAR} in a string value is replaced from the environment, recursively through lists and maps. Details from the code:

  • Names may contain only uppercase letters, digits and underscores. A name with lowercase letters, such as ${my_key}, is not replaced and stays in the value as typed.
  • A variable that is not set becomes an empty string, with no warning. An unset QUERION_DATABASE_DSN therefore shows up later as “no database DSN configured”.
  • The result is always text. Write numbers and booleans literally. trove.enabled: ${TROVE_ON} with TROVE_ON=false becomes the text "false", which counts as true.

Strictness

Unknown keys at the top level are ignored. Unknown keys inside database, limits, trove or a source block raise an error, because those blocks are passed to typed constructors. Every source needs name and base_url.

Top-level keys

  • company (default "your organization"): the organization name inserted into the analyst prompt.
  • model (default opus): passed to the Claude Code command-line interface (CLI) as --model. Any alias the CLI accepts works. Opus is the recommended tier.
  • claude_bin (default empty): path to the claude binary. If empty, Querion uses the first claude on PATH.

database

  • dsn (default empty): the Postgres connection string, or data source name (DSN). Use a read-only role.
  • statement_timeout_ms (default 15000): sent as SET statement_timeout before each query.
  • row_cap (default 500): the most rows one query returns. Querion fetches row_cap + 1 to detect truncation and marks the result as capped.
  • schema_doc (default empty): path to a curated schema Markdown file. If it is unset, or the file is empty or unreadable, Querion introspects the live database instead: once at startup for querion serve, and on every run for querion ask.

Only the first 30 rows of a result, with cells cut at 40 characters, are shown to the model. row_cap limits what is fetched, not what the model sees.

sources

A list of Hypertext Transfer Protocol (HTTP) sources. Each entry has:

  • name (required): the identifier the model uses in a source:NAME directive. Use only lowercase letters, digits, _ and -. Querion lowercases the name it reads from a directive and accepts only those characters, so a name such as Stripe or my.api can never be reached.
  • base_url (required): prepended to every path.
  • auth_header (default empty): "Header-Name: value". The string is split at the first colon. The value may use ${VAR}. Without a colon, no header is sent.
  • safe_get (default empty list): regular expressions for allowed paths. See the safety model.
  • docs (default empty): path to a Markdown file describing the API. It is injected into the analyst context.
  • timeout (default 25): request timeout in seconds.

limits

  • daily_per_user (default 50): daily question cap per caller. 0 or less means unlimited. Only the web server enforces it; querion ask does not. The counter resets at 00:00 Coordinated Universal Time (UTC) and is stored in .querion_usage.json next to the config file.
  • max_steps (default 7): reasoning steps per question. When the limit is reached, Querion asks the model for a final answer without more directives.
  • max_directives_per_step (default 4): the most directives executed from one model reply. Extra directives are dropped. The prompt itself always tells the model that up to 4 are allowed, whatever you set here.

trove

  • enabled (default false): fold a Trove semantic layer into the knowledge.
  • layer_path (default .trove/semantic.md): the layer file. If the file is missing or empty, nothing is added.

Environment variables

From .env.example:

  • QUERION_DATABASE_DSN: referenced as ${QUERION_DATABASE_DSN} in the example config. Querion does not read this name directly; it matters only because the config uses it.
  • EXAMPLE_API_KEY: a placeholder secret for the example source. Rename it to match your platforms.
  • QUERION_CLAUDE_BIN: shown commented out in .env.example, but no code reads it. To use it, write claude_bin: ${QUERION_CLAUDE_BIN} in querion.yaml.

Read directly by the code:

  • QUERION_CONFIG: the config path, as described above.

The CLI calls load_dotenv() at startup when python-dotenv is installed, so a .env file is picked up. Without that package, export the variables yourself.

A complete example

All keys, with their defaults where the example does not set one:

company: "Acme Inc"
model: opus
# claude_bin: /usr/local/bin/claude

database:
  dsn: ${QUERION_DATABASE_DSN}
  statement_timeout_ms: 15000
  row_cap: 500
  # schema_doc: docs/schema.md

sources:
  - name: example
    base_url: https://api.example.com
    auth_header: "Authorization: Bearer ${EXAMPLE_API_KEY}"
    safe_get:
      - ^/v1/customers
      - ^/v1/orders
      - ^/v1/invoices
    docs: docs/sources/example.md
    timeout: 25

limits:
  daily_per_user: 50
  max_steps: 7
  max_directives_per_step: 4

trove:
  enabled: false
  layer_path: .trove/semantic.md

Fixed values

These are not configurable:

  • The Postgres connection timeout: 5 seconds.
  • The timeout for one claude call: 200 seconds.
  • The rows shown to the model: 30 per result, cells cut at 40 characters.
  • The HTTP response text fed back to the model: 6000 characters.
  • The age at which the web server drops a run: one hour, checked when it accepts a new question.