Context queries

A context query decides what Kumo.io draws around an environment's resources: what they connect to, what contains them, and how it all nests. Use one to ask "what does this depend on?" or "what network is this in?", preview the answer, and save it as a diagram.

Applies to: BothPlan: Allpreview before you savenever changes your cloudsame query language as the built-in diagrams

Targets, context and appearance Try it in the web app Simple mode: nesting Advanced mode: what does this reach?The query itself Use the API

Targets, context and appearance

Three things work together to produce a diagram:

Step	Decides	Example
Environment	The targets: which resources the diagram is about.	The instances in your production VPC.
Context query	What else is drawn around the targets, and how it nests.	Their subnets and VPC, and the security groups attached to them.
View template	How each thing is drawn.	Subnets as containers, instances as icons.

The context query only ever adds around the targets, and the targets are always included. A context query also reads the same revision as its environment: it can't reach into a different point in time.

Every built-in diagram carries a context query. When you write your own, you are using the same language. See Views and diagrams.

Try it in the web app

Open Environments and choose an environment.
Select Explore & Apply Context.
Shape the context in the panel beside the canvas, then select Apply to Canvas to redraw the canvas exactly as a saved diagram would draw it.
When you're happy, select Save as View. The result is saved under Diagrams.

Preview evaluates the current query without saving anything and shows what each part found. Nothing here changes your cloud: a context query only reads what Kumo.io has already recorded.

The panel has two modes: Simple and Advanced.

Simple mode: nesting

Simple mode is about one question: how should the diagram nest?

Nesting is a tree of resource types, outermost first, such as a VPC, then subnets inside it, then instances inside those. Add a starting type, then use each row's expander to see what Kumo.io observed inside that type and add it.
A container that's missing is fetched for you. If you nest instances inside subnets, each instance's subnet is pulled in even when the environment didn't include it.
Each row also lists, under Not in view yet, types that are one connection away from what's drawn, so you can pull more in.
Only these types drops everything whose type isn't in the tree, including environment targets. With it off, the whole environment is drawn and the tree only decides how it nests.
Unnested Resources decides what happens to a resource that should have a parent but didn't find one: Keep it, Drop it, or Drop chains so that nothing is left floating.
Nesting changes redraw the canvas automatically after a moment. Undo puts back the last change.
Saved shapes keeps a named copy of your nesting to try on another environment. Saved shapes are stored in your browser only, so they don't follow you to another computer and aren't shared.

Advanced mode: what does this reach?

Advanced mode starts with Choose a lens, a set of ready-made starting points. Every field stays editable afterwards.

Lens	What it does
Just my targets	Only the environment's resources and the connections between them, grouped under their cloud scopes.
Show enclosing infrastructure	Nests each target inside its subnet, VPC, account and region, fetching missing containers.
Show dependencies	Follows what the targets depend on, two hops outward.
Show security context	The enclosing nesting plus the security groups and rules around each target, with a per-diagram switch to turn it off.
Show data flow	Follows outbound data movement two hops and always pulls in storage buckets.
Custom	A blank, flat canvas to build from.

Below the lenses, Related Context cards ask the reach question directly. Each card reads as a sentence:

From my targets, or the context so far.
follow these connection types (or any connection), Outgoing, Incoming or In Any Direction,
within a number of hops,
keep only resources that match a filter, or everything reached,
with a role that tells the template how to draw what was found,
and an optional toggle that becomes a per-diagram on/off switch.

You can also always include every resource of a type, and set an overall cap on hops across every card. Load an Example loads a complete query, and the raw query is editable as text.

The query itself

Both modes build one JSON document. In Simple mode, Copy Query copies it; in Advanced mode, Edit as JSON lets you change it directly. This example is a minimal query that follows each target's dependencies up to two hops out and nests the result inside its network:

{
  "kind": "ContextQuery",
  "apiVersion": "cloudgraph.context/v1",
  "parameters": {
    "includeDependencies": { "type": "boolean", "default": true }
  },
  "steps": [
    { "id": "targets", "type": "resource.input", "from": "environment.targets" },
    {
      "id": "dependencies",
      "type": "expandConnections",
      "connectionTypes": ["depends_on", "references"],
      "direction": "out",
      "depth": 2,
      "when": "${includeDependencies}"
    },
    { "id": "edges", "type": "includeInducedConnections" }
  ],
  "result": {
    "resources": [
      { "from": "$steps.targets.resources", "role": "target" },
      { "from": "$steps.dependencies.resources", "role": "optional_context" }
    ]
  },
  "structure": {
    "scopes": "region",
    "tiers": [
      { "type": "network.vpc" },
      { "type": "network.subnet", "parent": { "type": "network.vpc", "via": "contains", "direction": "in" } }
    ]
  }
}

Steps

Steps run in order, each adding to what's in the context:

Step	What it does
`resource.input`	Names the environment's targets so later steps and `result` can refer to them.
`expandConnections`	Walks connections from the current context, or from `start` or `from` if given. Takes `connectionTypes` (empty means any), `direction` (`in`, `out` or `both`, the default), `depth` (a number of hops, or `min` and `max`), an optional terminal filter `resource.where`, `excludeSemanticTypes`, and per-step `limits`.
`constrainDepth`	Sets one hop ceiling for every walk, wherever it appears.
`includeRelatedByType`	Pulls in related resources of one `semanticType`.
`includeInducedConnections`	Adds every connection whose two ends are both in the context.
`includePatternMatches`	Links resources whose attributes match by pattern, such as a wildcard certificate and the hostnames it covers. Works over what's already in the context.

Any step can carry when: ${parameter} so it runs only when that parameter is true. Declare the parameter with a default under parameters: a parameter that is missing and has no default counts as false.

Roles

The result block assigns a role to each step's output, which the template can draw differently. When result is present, it has the final say: the context is exactly what it maps, and a step it doesn't map is dropped. The roles are target, required_context, optional_context, decorative_context, hidden_support and user_added_context (resources you pin by hand). Without a result block, targets are target and everything else reached is required_context.

Structure

The structure block is the nesting tree. scopes adds provider, account or region containers above everything (none, provider, account or region). Each entry in tiers names a type, and nested ones name their parent: the parent's type, the connection that links them (via), and its direction seen from the child (out for a child-to-parent connection, in for parent-to-child, which is how contains points). A parent must be an earlier tier. Add fill: true to a tier to pull in every resource of that type inside the containers already drawn. exclusive: true is Only these types, and orphans (keep, drop or dropChains) is Unnested Resources.

Rules worth knowing

Keep a step that produces connections. A query with no steps draws no connections at all, so include includeInducedConnections.
Limits never fail. limits (maxResources, maxConnections, maxFanoutPerResource, and maxDepth at the top level) truncate the result and say so in the diagnostics.
Diagnostics explain the result. After each Apply to Canvas, the panel lists what the evaluation did, with anything that dropped or truncated resources marked, and suggests a likely cause when nothing was drawn.

Use the API

Three endpoints evaluate a query against an environment without saving anything. Each takes the query in contextQuery, plus optional parameters and environmentRevisionId (the environment's latest revision by default):

POST /v1/accounts/{accountId}/workspaces/{workspaceId}/environments/{environmentId}/context-query/evaluate
POST /v1/accounts/{accountId}/workspaces/{workspaceId}/environments/{environmentId}/context-query/frontier
POST /v1/accounts/{accountId}/workspaces/{workspaceId}/environments/{environmentId}/source-model

context-query/evaluate returns the resources and connections in the context, with their roles, the evaluation trace and diagnostics.
context-query/frontier returns what lies one connection outside the context, which is what Not in view yet shows. It also takes a limit.
source-model returns the shaped model a diagram is drawn from, which is what Apply to Canvas loads.

A query that doesn't parse is rejected with an error that says why. See the API reference.