Natural Language Queries
Ask questions about your infrastructure in plain English and get ParaQL queries generated by AI
The ParaQL natural language (NL) feature lets you describe what you want in plain English, and an LLM translates your request into a valid ParaQL query. This is useful when you know what you want to find but aren't sure of the exact syntax, column names, or CI types.
Using the NL Sidebar
Click the sparkle icon in the query console toolbar to open the NL chat sidebar. Type your question and the system will:
- Analyze your message to extract entity references (CI names, hostnames, types)
- Ground those references against your actual CMDB data using fuzzy matching
- Build a schema-aware context including CI types, columns, relationships, and matching CIs
- Generate a ParaQL query with an explanation and any assumptions made
The generated query is automatically loaded into the editor. You can run it immediately or refine it further.
Example Conversations
| You Say | ParaQL Generated |
|---|---|
| "How many pods are running?" | SELECT COUNT(*) AS running_pods FROM kubernetes.pod WHERE config.phase = 'Running' |
| "Show me all VMs on host-01" | SELECT name, config.status FROM proxmox.vm WHERE config.node = 'host-01' |
| "What changed in the last 24 hours?" | SELECT ci_name, change_type, changed_at FROM changes WHERE changed_at > NOW() - INTERVAL '24 hours' ORDER BY changed_at DESC |
| "Which pods use the most memory?" | SELECT name, namespace, config.memory_mb FROM kubernetes.pod ORDER BY config.memory_mb DESC LIMIT 20 |
| "What depends on the ceph storage pool?" | SELECT name, ci_type, depth, path, criticality FROM IMPACT(ceph.pool) ORDER BY depth |
How It Works
1. Identifier Extraction
The system scans your message for infrastructure references:
- Quoted strings:
"pod-xyz",'web-server-01' - FQDNs:
web-01.prod.example.com,api.prod.internal - Hyphenated tokens:
host-01,ceph-osd-3(4+ chars with at least one hyphen)
These are filtered against ParaQL keywords and CI type names to avoid false positives.
2. Pre-flight Resolution
Extracted identifiers are matched against your CMDB using fuzzy matching. This produces grounding data that tells the AI:
- The exact CI name as it appears in the database
- The CI type (so the LLM knows which table to query)
- A confidence score
For example, if you mention "host-01", the pre-flight might resolve it to host-01.prod.example.com of type proxmox.node with 92% confidence.
3. Query Generation
The AI receives your CMDB schema (CI types, columns, relationships, data sources) along with the grounding data and generates:
- query — The ParaQL query string
- explanation — A plain-English explanation of what the query does
- assumptions — Any assumptions made about ambiguous parts of your request
The generated query is validated for correct syntax before being returned.
Refinement
The NL sidebar maintains a conversation thread. You can refine results by asking follow-up questions:
- "Add a filter for the production namespace"
- "Group that by source instead"
- "Make it a time-series over the last month"
- "Only show critical ones"
When you have a query in the editor, the NL system includes it as context, so you can say "modify this to also include the node name" and the LLM knows what "this" refers to.
Status and Availability
The NL feature requires AI to be enabled for your Parascope instance. Check availability by looking at the sparkle icon in the toolbar:
- Visible and active — NL is enabled and healthy
- Grayed out or hidden — NL is not available on this instance
Tips for Better Results
- Be specific about what you want to see. "Show me pod names and namespaces" is better than "show me pods."
- Mention CI types when you know them. "How many kubernetes pods are running?" is clearer than "how many containers exist?"
- Use quotes for exact names.
"host-01"helps the pre-flight resolver find the exact CI. - Reference relationships explicitly. "What VMs run on proxmox node host-01?" guides the LLM toward traversal syntax.
- Start simple, then refine. Get a basic query working, then ask for modifications incrementally.
Limitations
- The NL system is as good as the LLM and the schema context it receives. Novel or highly complex queries may need manual adjustment.
- Computed virtual columns (
age(),stale_for(), etc.) and advanced features likeAS OFor variable-depth traversal may not always be suggested unless you mention them. - The system cannot execute queries — it only generates them. You always review and run the query yourself.
- Rate limits may apply depending on the configured LLM provider.