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 r.type, count(*) as count FROM resources r GROUP BY r.type ORDER BY r.type"

Output (JSON):

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

Complex Queries

# Find all EC2 instances
stategraph mql query "SELECT i.address, i.attributes->>'instance_type' FROM instances i JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id WHERE r.type = 'aws_instance'"

# Count resources by workspace
stategraph mql query "SELECT s.workspace, count(*) FROM instances i JOIN states s ON i.state_id = s.id GROUP BY s.workspace ORDER BY s.workspace"

# Find untagged AWS resources
stategraph mql query "SELECT i.address, r.type FROM instances i JOIN resources r ON i.resource_address = r.address AND i.state_id = r.state_id WHERE r.type LIKE 'aws_%' AND (i.attributes->'tags' IS NULL OR i.attributes->>'tags' = '{}')"

stategraph mql schema

Get the MQL schema for understanding available tables and columns.

stategraph mql schema

Example

stategraph mql schema

Output (JSON):

{
  "tables": {
    "instances": {
      "columns": {
        "address": "string",
        "type": "string",
        "provider": "string",
        "module": "string",
        "attributes": "json",
        "dependencies": "array"
      }
    },
    "states": {
      "columns": {
        "id": "string",
        "name": "string",
        "group_id": "string",
        "workspace": "string"
      }
    }
  }
}

Scripting Examples

Export query results to CSV

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

Count resources and format output

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

Find resources matching a pattern

stategraph mql query "SELECT address FROM instances WHERE address LIKE '%database%'" | \
  jq -r '.[].address'

Generate report

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

Error Handling

Syntax Errors

stategraph mql query "SELEC * FROM instances"
# Exit code: 2
# Output: syntax-error
# Expected keyword SELECT

Unknown Columns

stategraph mql query "SELECT foo FROM instances"
# Exit code: 2
# Output: unknown-column
# Column 'foo' not found

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

Next Steps