Faz Docs

Connect faz to a MongoDB database. JSON queries with operation field, full CRUD support, schema discovery via document sampling.

MongoDB queries arrive as JSON with a top-level operation field. faz's connector covers the standard read and write operations and discovers schema by sampling 100 documents per collection.

Default port	Query language	Write support	Schema discovery	Driver
27017	MQL (JSON)	Yes (RBAC-gated)	Document sampling (100 docs)	`pymongo`

Quick example

faz.yaml

databases:
  - name: <database>          # used as --database <database> in queries
    type: mongodb
    host: localhost
    port: 27017
    database: <db-name>       # the actual MongoDB database on the host
    username: <username>
    password: <password>

permissions:
  - database: <database>      # must match `name:` above
    access: R
    # access codes:
    # R    read only           — find, findOne, aggregate, count, distinct
    # W    write only          — insertOne, updateOne, deleteOne (no reads)
    # RW   read + write
    # RA   read + append       — reads + insertOne / insertMany
    # RWA  read + write, no DELETE
    # A    admin (incl. DDL — createIndex, dropCollection, …)

See Permissions for the full model, per-table overrides, and the operation matrix.

faz query '{"operation":"find","filter":{},"limit":5}' --database <database> --table <collection> --language mql

uv run faz query '{"operation":"find","filter":{},"limit":5}' --database <database> --table <collection> --language mql

python -m faz query '{"operation":"find","filter":{},"limit":5}' --database <database> --table <collection> --language mql

Configuration

Field	Type	Default	Notes
`host`	string	`localhost`	MongoDB host or IP. For replica sets, use the primary or a `mongodb+srv` URI host.
`port`	integer	`27017`	MongoDB port.
`database`	string	`""`	Database name. Required.
`username`	string	`""`	MongoDB user (in the auth database, usually `admin`).
`password`	string	`""`	Password.
`ssl`	boolean	`false`	When `true`, enables TLS.
`extra`	mapping	`{}`	Reserved for replicaSet / authSource hints.

For replica sets and Atlas, the simple host:port pattern works for connecting to a primary; full mongodb+srv:// URIs aren't currently supported as the host field. Set host to the primary's hostname.

Capabilities

The query body must be a JSON object with an operation field. Supported operations:

Operation	Op class	Notes
`find`	SELECT	`filter`, `projection`, `limit`, `sort`.
`findOne`	SELECT	Same shape as `find`, returns one doc.
`aggregate`	SELECT	Pipeline of stages.
`count`	SELECT	`filter`.
`countDocuments`	SELECT	Synonym for `count`.
`distinct`	SELECT	`field`, `filter`.
`insertOne`	INSERT	`document`.
`insertMany`	INSERT	`documents` (list).
`updateOne`	UPDATE	`filter`, `update`.
`updateMany`	UPDATE	Same.
`replaceOne`	UPDATE	`filter`, `replacement`.
`deleteOne`	DELETE	`filter`.
`deleteMany`	DELETE	`filter`.

Schema discovery samples 100 documents per collection. Field types are inferred from the sample; sparse fields that don't appear in the first 100 documents won't show up.

Limitations

$out and $merge are blocked at the connector level. These pipeline stages write data even on what looks like a read pipeline. The Injection Analyser also catches them at the safety layer; the connector enforces a second time as defense-in-depth.
$where, $function, $accumulator are blocked. Server-side JavaScript is rejected by the Injection Analyser.
System databases are excluded from schema discovery: admin, local, config.
$lookup JOINs across databases are technically allowed by the connector, but each touched collection is independently checked by RBAC. If your $lookup reaches a collection your policy doesn't grant, the whole query blocks.

Troubleshooting

ServerSelectionTimeoutError — MongoDB isn't reachable, or the primary you're trying to reach has stepped down. For replica sets, point at the current primary.

Authentication failed. — username, password, or authSource is wrong. By default the connector authenticates against the database you connected to; if your user lives in admin, MongoDB may reject the auth. Workaround: connect to the admin database in faz.yaml and access other databases via $lookup-style queries.

Schema discovery returns empty fields list — the collection is empty, or the connecting user lacks find privileges. Verify with mongosh.

Query blocked at INJECTION_ANALYSER — your query body contains a $where, $function, $accumulator, $out, or $merge. Rewrite without server-side JavaScript or write stages.

For the broader troubleshooting flow, see Connection failed.

Databases overview — cross-connector basics.
Permissions — how access codes map to MongoDB operations.
CouchDB — sibling document database with similar JSON query shape.

MongoDB

Quick example

Configuration

Capabilities

Limitations

Troubleshooting

Related

On this page