docs: document ktx mongo-query command

docs-site/content/docs/cli-reference/ktx-mongo-query.mdx

@@ -0,0 +1,103 @@
+---
+title: "ktx mongo-query"
+description: "Fetch rows from a MongoDB connection by running an aggregation pipeline."
+---
+
+Run a MongoDB aggregation pipeline against a `mongodb` connection in your
+**ktx** project. MongoDB is not a SQL source, so `ktx sql` refuses a mongodb
+connection — `ktx mongo-query` is the row-fetch path for MongoDB, and the
+`mongo_query` MCP tool is its agent-facing equivalent.
+
+## Command signature
+
+Use `ktx mongo-query` with a required connection id, a required collection
+name, and a positional aggregation pipeline given as a JSON array of stage
+objects.
+
+```bash
+ktx mongo-query '<pipeline-json>' --connection <id> --collection <name> [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-c`, `--connection <id>` | **ktx** database connection id. Required. | - |
+| `--collection <name>` | Collection to query. Required. | - |
+| `--database <name>` | Database name. | Connection's first configured database |
+| `--limit <n>` | Maximum documents to return. Must be between `1` and `10000`. | `1000` |
+| `--output <mode>` | Output mode: `pretty`, `plain` (TSV), or `json`. | `pretty` |
+| `--json` | Shortcut for `--output=json` (overrides `--output`). | `false` |
+
+## Examples
+
+Quote the pipeline JSON in shell scripts and when it contains spaces or
+punctuation.
+
+```bash
+# Match and project fields from the business collection
+ktx mongo-query '[{"$match":{"city":"Indianapolis"}},{"$project":{"business_id":1,"city":1}}]' \
+  --connection mongo --collection business --limit 500
+
+# Query a non-default database
+ktx mongo-query '[{"$match":{"status":"open"}}]' \
+  --connection mongo \
+  --collection orders \
+  --database analytics
+
+# Print JSON for agents or scripts
+ktx mongo-query '[{"$match":{"status":"open"}}]' \
+  --connection mongo \
+  --collection orders \
+  --json
+
+# Print TSV rows
+ktx mongo-query '[{"$limit":10}]' \
+  -c mongo \
+  --collection orders \
+  --output plain
+```
+
+## Output
+
+Pretty output prints aligned columns and a final row count.
+
+```text
+business_id  city
+-----------  ------------
+1001         Indianapolis
+1002         Indianapolis
+
+2 rows
+```
+
+Plain output prints a TSV header row followed by TSV data rows.
+
+```text
+business_id	city
+1001	Indianapolis
+1002	Indianapolis
+```
+
+JSON output preserves connection id, headers, rows, and row count.
+
+```json
+{
+  "connectionId": "mongo",
+  "headers": ["business_id", "city"],
+  "rows": [
+    [1001, "Indianapolis"],
+    [1002, "Indianapolis"]
+  ],
+  "rowCount": 2
+}
+```
+
+## Common errors
+
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| `must be a JSON aggregation pipeline array` | The pipeline argument is not valid JSON. | Pass a JSON array of pipeline-stage objects. |
+| `must be a JSON array of pipeline-stage objects` | The parsed JSON is not an array of objects. | Wrap each stage as an object inside a JSON array, e.g. `[{"$match":{...}}]`. |
+| `Connection "<id>" is not configured in ktx.yaml` | The connection id is wrong or missing from the project. | Run `ktx connection list` and retry with an exact id. |
+| `driver "<driver>" is not a MongoDB connection` | The connection id resolves to a non-mongodb driver. | Use a `mongodb` connection id, or use `ktx sql` for SQL-queryable drivers. |

docs-site/content/docs/cli-reference/meta.json

@@ -8,6 +8,7 @@
     "ktx-ingest",
     "ktx-sl",
     "ktx-sql",
+    "ktx-mongo-query",
     "ktx-wiki",
     "ktx-status",
     "ktx-mcp",

docs-site/content/docs/integrations/primary-sources.mdx

@@ -735,6 +735,7 @@ nullability from how often the field is present:
 | Table sampling | Yes | Reads the most recent documents |
 | Nested analysis | Yes | Sub-documents and arrays modeled as opaque `json` |
 | Read-only SQL (`ktx sql`) | No | MongoDB is not a SQL source |
+| Row queries (`ktx mongo-query`) | Yes | Runs a read-only aggregation pipeline against a collection |
 
 ### Dialect notes
 
@@ -746,6 +747,13 @@ nullability from how often the field is present:
 - `sample_size` trades inference coverage for speed; raise it for collections
   with highly variable documents
 
+### Querying rows
+
+MongoDB is not SQL-queryable, so `ktx sql` refuses a mongodb connection. Use
+[`ktx mongo-query`](/docs/cli-reference/ktx-mongo-query) to fetch rows by
+running a MongoDB aggregation pipeline, or the `mongo_query` MCP tool for the
+same capability from an agent client.
+
 ## Common errors
 
 | Error or symptom | Likely cause | Recovery |