MQL Commands

The stategraph mql command group provides access to MQL (Mapping Query Language) for querying your infrastructure from the command line.

Commands

Command Description
stategraph mql query Execute an MQL query
stategraph mql schema Get the MQL schema

stategraph mql query

Execute an MQL query against your infrastructure.

stategraph mql query <query>

Arguments

Argument Required Description
<query> Yes MQL query string

Example

stategraph mql query "SELECT type, count(*) FROM resources GROUP BY type"

Output (JSON):

[
  { "type": "aws_instance", "count": 20 },
  { "type": "aws_security_group", "count": 15 },
  { "type": "aws_subnet", "count": 6 }
]

More Queries

# Count total instances
stategraph mql query "SELECT count(*) FROM instances"

# List all resource types with counts
stategraph mql query "SELECT type, count(*) as count FROM resources GROUP BY type ORDER BY count DESC"

# Find resources by type
stategraph mql query "SELECT address FROM instances WHERE type = 'aws_instance'"

MQL Syntax Notes

MQL uses a SQL-like syntax with some differences from standard SQL:

  • No table aliases — Use full table names; FROM resources r then r.type does not work
  • No LIKE operator — Use exact matches with = instead
  • No JOINs — Query one table at a time
  • ORDER BY works — ORDER BY type ASC is supported
  • Column aliases work — count(*) as total is supported

stategraph mql schema

Get the MQL schema for understanding available tables and columns.

stategraph mql schema

Output (JSON) — shows all tables with column names and their PostgreSQL types:

{
  "tables": {
    "instances": {
      "columns": {
        "address": { "type": "text" },
        "attributes": { "type": "jsonb" },
        "dependencies": { "type": "text[]" },
        "provider": { "type": "text" },
        "resource_address": { "type": "text" },
        "state_id": { "type": "uuid" }
      }
    },
    "resources": {
      "columns": {
        "address": { "type": "text" },
        "module": { "type": "text" },
        "state_id": { "type": "uuid" },
        "type": { "type": "text" }
      }
    },
    "states": {
      "columns": {
        "id": { "type": "uuid" },
        "name": { "type": "text" },
        "group_id": { "type": "text" },
        "workspace": { "type": "text" }
      }
    }
  }
}

Run stategraph mql schema to see the full list of tables and columns — there are additional tables beyond what's shown here.

Scripting Examples

Export query results to CSV

stategraph mql query "SELECT address, type FROM resources" | \
  jq -r '.[] | [.address, .type] | @csv' > resources.csv

Count resources and format output

stategraph mql query "SELECT type, count(*) FROM resources GROUP BY type" | \
  jq -r '.[] | "\(.type): \(.count)"'

Generate report

#!/bin/bash
echo "Infrastructure Report"
echo "===================="
echo ""
echo "Total resources:"
stategraph mql query "SELECT count(*) FROM instances" | jq -r '.[0].count'
echo ""
echo "By type:"
stategraph mql query "SELECT type, count(*) FROM resources GROUP BY type" | \
  jq -r '.[] | "  \(.type): \(.count)"'

Error Handling

Syntax Errors

stategraph mql query "SELEC * FROM instances"
# Exit code: 2
# Output: QUERY_ERR
# Error ((None, "SELEC * FROM instances", "0"))

Unknown Columns

stategraph mql query "SELECT foo FROM instances"
# Exit code: 2
# Output: QUERY_ERR
# column "foo" does not exist

Tips

  1. Quote queries — Always wrap queries in quotes to prevent shell interpretation
  2. Use jq — Pipe output to jq for formatting and filtering
  3. Test incrementally — Build complex queries step by step
  4. Check schema — Use stategraph mql schema to see available columns
  5. Use full table names — No aliases; use resources.type not r.type

Next Steps