Querion / Guides
Connecting data sources
Set up a read-only Postgres role, give the model a schema, and add HTTP API sources with a per-source allowlist and a docs file.
On this page
Querion reads from two kinds of source: one Postgres database and any number of web application programming interfaces (APIs) reached over Hypertext Transfer Protocol (HTTP). Each source needs two things.
- A credential that can only read. It sets the outer limit of what Querion can do, whatever the model asks for.
- A description the model can read. The model has never seen your data. The schema and the API docs you give it decide whether it asks for the right thing.
Postgres
Set database.dsn to a standard Postgres connection string. Create a dedicated read-only role first. A recipe:
CREATE ROLE querion_ro LOGIN PASSWORD 'choose-a-strong-one';
GRANT CONNECT ON DATABASE yourdb TO querion_ro;
GRANT USAGE ON SCHEMA public TO querion_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO querion_ro;
ALTER ROLE querion_ro SET default_transaction_read_only = on;
ALTER ROLE querion_ro SET statement_timeout = '15s';
Then revoke SELECT on any table that holds secrets, such as sessions or raw tokens. Querion cannot know which tables are sensitive, and anything the role can read can end up in the model’s context.
Three details of the recipe:
GRANT SELECT ON ALL TABLEScovers the tables that exist now. Tables created later need their own grant, orALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO querion_ro, run as the role that creates them.- Querion runs
SET statement_timeoutwithdatabase.statement_timeout_mson every connection, which replaces the role’s default for that session. Set the value you want inquerion.yaml. - For schemas other than
public, grantUSAGEandSELECTon them too, and describe them in a curated schema file. Live introspection reads onlypublic.
Schema knowledge
By default Querion introspects information_schema for the public schema and lists each table with its columns, types and primary key. For large or subtle schemas, write a curated file instead and set database.schema_doc. Generate a starting point:
querion introspect -o docs/schema.md
The file uses the same format the model sees. For a database with an orders table, a line looks like this:
# Database schema
_Live snapshot: 1 tables in schema public._
- `orders` [PK id] :: id:integer, customer_id:integer, created_at:timestamp with time zone
Then edit it. Remove tables the model should ignore, and add what the column names do not say: units, status values, which timestamp marks a sale. A shorter schema keeps every model call smaller, and notes on meaning save the model from guessing.
querion serve reads the schema once at startup; querion ask reads it on every run. Restart the server after schema or doc changes.
HTTP APIs
Adding a platform is configuration, not code. Three steps.
1. Put the secret in the environment
STRIPE_KEY=sk_live_xxx
2. Describe the API in Markdown
Write the file as a briefing for a new analyst: what the API is, which read endpoints exist, and what each returns. List read endpoints only. You do not need to mention the key, because Querion sends auth_header for you.
The repository ships an example at docs/sources/example.md. A shorter file for a made-up billing API, in the same outline:
# Billing API
## What this API is
The live source of truth for invoice status. The Postgres mirror may lag.
## Read endpoints (GET only)
- `GET /v1/invoices?customer={id}`: invoices for a customer
- `GET /v1/invoices/{id}`: one invoice, with line items
## Notes and gotchas
- Amounts are in minor units (cents); divide by 100 for display.
- `status` values: `open`, `paid`, `void`.
- Pagination uses `?limit=` and `?starting_after=`; the maximum limit is 100.
Querion puts the file under a header that names the source, its base URL and the directive to use, so the model knows how to call it.
3. Add a source block
sources:
- name: stripe
base_url: https://api.stripe.com
auth_header: "Authorization: Bearer ${STRIPE_KEY}"
safe_get:
- ^/v1/charges
- ^/v1/customers
- ^/v1/invoices
docs: docs/sources/stripe.md
timeout: 25
The model reaches it with a source:stripe directive containing GET /path. Repeat the block for each platform. Keep name to lowercase letters, digits, _ and -: Querion lowercases the name in a directive before looking it up, so a source named Stripe cannot be reached.
Restart querion serve after adding a source, then run querion check to see it listed.
The per-source allowlist
A GET is not always free of side effects. Some APIs expose state-changing operations over GET. safe_get handles this with default-deny:
- If
safe_gethas one or more patterns, only paths matching one of them are requested. - If
safe_getis empty or missing, any GET path is allowed.
How matching works, from querion/safety.py:
- Patterns are combined into one case-insensitive regular expression and applied with
re.match, so they match from the start of the path. - The query string is removed before matching, so it is never checked.
- Patterns are not anchored at the end.
^/v1/customersalso allows/v1/customers-export. End a pattern with$or/boundaries when that matters. - A path without a leading
/gets one added before matching. - The raw path text is matched.
/v1/customers/../adminmatches^/v1/customers.
A tighter pattern closes the last two gaps. It refuses any path that contains .., and allows /v1/customers, /v1/customers/123 and /v1/customers?limit=5, but not /v1/customers-export:
safe_get:
- ^(?!.*\.\.)/v1/customers(?:/|$)
A refused path returns an error message to the model, which names the source and the refused path. See the safety model.
Use safe_get for every API that is not strictly RESTful, that is, any API where a GET can change something.
Response handling
Responses come back as HTTP <status> followed by the JavaScript Object Notation (JSON) body (or raw text), cut to 6000 characters. An error status is not raised as an error; the model sees it and can adjust. Large responses are truncated, so describe paginated endpoints and filters in your docs file.