diff --git a/docs-site/content/docs/cli-reference/ktx-mongo-query.mdx b/docs-site/content/docs/cli-reference/ktx-mongo-query.mdx new file mode 100644 index 00000000..86f2378d --- /dev/null +++ b/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 '' --connection --collection [options] +``` + +## Options + +| Flag | Description | Default | +|------|-------------|---------| +| `-c`, `--connection ` | **ktx** database connection id. Required. | - | +| `--collection ` | Collection to query. Required. | - | +| `--database ` | Database name. | Connection's first configured database | +| `--limit ` | Maximum documents to return. Must be between `1` and `10000`. | `1000` | +| `--output ` | 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 "" 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 "" 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. | diff --git a/docs-site/content/docs/cli-reference/meta.json b/docs-site/content/docs/cli-reference/meta.json index 2902f2c6..5165c539 100644 --- a/docs-site/content/docs/cli-reference/meta.json +++ b/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", diff --git a/docs-site/content/docs/integrations/primary-sources.mdx b/docs-site/content/docs/integrations/primary-sources.mdx index b553a3a7..4617a86c 100644 --- a/docs-site/content/docs/integrations/primary-sources.mdx +++ b/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 |