@dx-do/cli 5.2.49 → 5.2.50

package/dist-node/13-filter-layer.tas-r1ff5anv.md

@@ -0,0 +1,29 @@
+# 13-filter-layer (TAS)
+
+## Purpose
+
+Demonstrate the `LAYER` filter, which selects vertices belonging to a specific topology layer.
+
+## Query Construction
+
+Uses `LAYER` with `value: "ATC"` (Application Transaction Context layer). Layers are a top-level organizational concept in the topology — each vertex belongs to exactly one layer, conventionally identified by the first segment of its `externalId`.
+
+## API Surface Exercised
+
+- **Filter**: `LAYER` with `value` (single string)
+- The schema also supports `values` (array) for matching multiple layers
+
+## Expected Output
+
+Returns up to 50 vertices in the ATC layer. Typically this includes `BUSINESSTRANSACTION` vertices (web-app endpoints reported by APM) and `INFERRED_DATABASE` vertices (databases discovered behind those transactions).
+
+## What the Results Tell You
+
+Common DXO2 topology layers (discovered from externalId prefixes — the exact set on a given tenant depends on which connectors and agents are reporting):
+- **ATC** — Application Transaction Context (business transactions, databases)
+- **APM_INFRASTRUCTURE** — Agents, agent connections, DXI services
+- **INFRASTRUCTURE** — Hosts, k8s entities (pods, containers, deployments, namespaces)
+- **CONNECTOR_METADATA** — Connectors and products (present when the tenant uses connectors that publish to this layer)
+- **ACN_CONFIGURATION** — Agent configuration entities (present when ACN-style configuration is in use)
+
+By convention, the layer name appears as the first segment of each vertex's `externalId` (e.g., `ATC:BUSINESSTRANSACTION:...`), though this is a convention, not a rule.

package/dist-node/13-filter-layer.tas.data-store-5mneyz77.json5

@@ -0,0 +1,30 @@
+/*
+ * `LAYER` filter — restrict to vertices in a single topology layer.
+ * Layers are the top-level organizational concept (every vertex
+ * belongs to exactly one); `entities/host` and `entities/agent`
+ * cover which types live where.
+ *
+ * Note `value` (singular string) for one layer; the filter also
+ * supports `values` (array of strings) for OR-matching multiple
+ * layers — useful when scoping across related layers (e.g. ATC +
+ * APM_INFRASTRUCTURE for an APM-side question).
+ *
+ * Use `discovery_layers` to enumerate valid layer names on the
+ * bound tenant before authoring. Common layers: ATC,
+ * APM_INFRASTRUCTURE, INFRASTRUCTURE, CONNECTOR_METADATA,
+ * ACN_CONFIGURATION, plus tenant-specific ones from connectors.
+ */
+{
+  /*
+   * Single-value LAYER filter — the cheapest way to scope. `ATC`
+   * (Application Transaction Context) is where business
+   * transactions and inferred databases live. To match multiple
+   * layers, use `values: [...]` (array form) instead.
+   */
+  "filter": {
+    "op": "LAYER",
+    "value": "ATC"
+  },
+  "limit": 50,
+  "projection": "DETAILED"
+}

package/dist-node/13-filter-layer.tas.data-store-tmd-9qmhyfzr.json

@@ -0,0 +1,4 @@
+{
+  "description": "LAYER filter: get all vertices in the ATC (Application Transaction Context) layer — business transactions and inferred databases",
+  "tags": ["tas", "filter", "layer"]
+}

package/dist-node/14-filter-traverse.tas-da9jene0.md

@@ -0,0 +1,38 @@
+# 14-filter-traverse (TAS)
+
+## Purpose
+
+Demonstrate the `TRAVERSE` filter, which starts from a seed set of vertices and follows edges to discover connected vertices up to a configurable depth.
+
+## Query Construction
+
+1. **Seed**: `ATTRIBUTE` filter selects `k8s_CLUSTER` vertices (whatever clusters happen to be reporting on the tenant)
+2. **Traverse**: Follows edges in `ANY` direction with `repeat: 2` (two hops)
+3. **includeInput**: `true` includes the seed cluster vertex in the result
+
+The `traverse` field is an **array** of `Traverse` objects. Each specifies:
+- `direction`: `FORWARD`, `BACKWARD`, or `ANY`
+- `repeat`: How many hops to take (equivalent to "depth")
+- Optional `vertexFilter`/`edgeFilter`: Can constrain which vertices or edges to follow
+
+## API Surface Exercised
+
+- **Filter**: `TRAVERSE` with `input`, `traverse`, `includeInput`
+- **Traverse spec**: `direction`, `repeat`
+- **Nesting**: ATTRIBUTE filter as input to TRAVERSE
+
+## Expected Output
+
+Returns up to 100 vertices: the k8s_CLUSTER vertex plus all vertices reachable within 2 hops. Typical results include:
+- The cluster itself
+- k8s_NAMESPACE vertices (e.g. `tixchange-v1`, `tixchange-v2`, `monitoring-system`, plus standard ones like `kube-system`)
+- k8s_DEPLOYMENT, k8s_DAEMONSET vertices
+- k8s_POD vertices
+- HOST vertices
+- AGENT vertices connected to those hosts
+
+## What the Results Tell You
+
+`TRAVERSE` is the primary way to explore graph relationships. The `repeat` parameter controls depth — `repeat: 1` gives immediate neighbors, `repeat: 2` gives two-hop neighbors. With `direction: "ANY"`, traversal follows edges regardless of direction (both parent→child and child→parent relationships).
+
+Note that the result includes only vertices by default. To see the edges, use `TAKE_EDGES` (see query 15).

package/dist-node/14-filter-traverse.tas.data-store-p0vxtfvj.json5

@@ -0,0 +1,63 @@
+/*
+ * `TRAVERSE` filter — start from a SEED set of vertices and follow
+ * edges to discover connected vertices up to a configurable depth.
+ * The primary tool for "find things related to X" investigative
+ * questions.
+ *
+ * Pattern: ATTRIBUTE filter selects the seed (here: k8s_CLUSTERs);
+ * TRAVERSE walks edges out from those seeds. `repeat: 2` means
+ * follow 2 hops; `direction: ANY` ignores edge directionality
+ * (FORWARD / BACKWARD restrict to one).
+ */
+{
+  /*
+   * TRAVERSE wraps a seed filter and extends with edge-walking
+   * configuration. The result is the union of seeds (when
+   * includeInput=true) AND everything reachable in N hops.
+   */
+  "filter": {
+    "op": "TRAVERSE",
+    /*
+     * The seed: k8s_CLUSTER vertices (the starting points).
+     * Picking a tight seed is critical — TRAVERSE from a too-broad
+     * seed (e.g. ALL hosts) will explode the result set across
+     * the whole topology.
+     */
+    "input": {
+      "op": "ATTRIBUTE",
+      "expressions": [
+        {
+          "name": "type",
+          "values": ["k8s_CLUSTER"],
+          "operator": "IN"
+        }
+      ]
+    },
+    /*
+     * `traverse` is an ARRAY of hop specs, applied sequentially.
+     * One element here = "one round of traversal." Each element:
+     *   direction: FORWARD | BACKWARD | ANY
+     *   repeat:    how many times to apply this hop spec
+     *   vertexFilter / edgeFilter (optional): constrain which
+     *     vertices/edges to follow on this round
+     *
+     * For multi-stage traversal (e.g. cluster → namespace →
+     * deployments only), use multiple array elements with
+     * vertex/edgeFilter on each.
+     */
+    "traverse": [
+      {
+        "direction": "ANY",
+        "repeat": 2
+      }
+    ],
+    /*
+     * includeInput=true returns the seed vertices alongside what
+     * was reached via traversal. Set false when you want only the
+     * neighborhood, not the seeds.
+     */
+    "includeInput": true
+  },
+  "limit": 100,
+  "projection": "DETAILED"
+}

package/dist-node/14-filter-traverse.tas.data-store-tmd-5hepg5wf.json

@@ -0,0 +1,4 @@
+{
+  "description": "TRAVERSE filter: start from k8s_CLUSTER vertices and traverse 2 levels deep to find connected namespaces and deployments",
+  "tags": ["tas", "filter", "traversal"]
+}

package/dist-node/15-filter-take-vertices-edges.tas-m160qc7z.md

@@ -0,0 +1,35 @@
+# 15-filter-take-vertices-edges (TAS)
+
+## Purpose
+
+Demonstrate the `TAKE_EDGES` graph-shaping filter, which extracts edges from a graph result produced by traversal.
+
+## Query Construction
+
+Wraps the same TRAVERSE from query 14 (k8s_CLUSTER → 2 hops) inside `TAKE_EDGES`:
+
+```
+TAKE_EDGES
+└── TRAVERSE (from k8s_CLUSTER, depth=2, includeInput=true)
+    └── ATTRIBUTE(type IN [k8s_CLUSTER])
+```
+
+## API Surface Exercised
+
+- **Filter**: `TAKE_EDGES` — extracts only edges from the result, discarding vertices
+- **Composition**: TAKE_EDGES wrapping TRAVERSE wrapping ATTRIBUTE
+
+The companion filter `TAKE_VERTICES` does the opposite — extracts only vertices. Together they allow decomposing a graph result into its vertex and edge components.
+
+## Expected Output
+
+Returns 0 vertices and 100 edges. Each edge has:
+- `id` — numeric edge ID
+- `sourceId` / `targetId` — vertex IDs at each end
+- `attributes` — edge metadata (type, layer, etc.)
+
+## What the Results Tell You
+
+`TAKE_EDGES` is essential for understanding the relationships between topology entities. Without it, traversal results include only vertices. The edges reveal the actual graph structure: which namespaces belong to which cluster, which deployments are in which namespace, etc.
+
+Other graph-shaping filters in the same family: `TAKE_VERTICES`, `TAKE_FLOWS`, `ADD_FLOWS`, `ADD_WIRES`, `ADD_WIRE_CONTEXT`, `ADD_TRANSITIONING_EDGES`.

package/dist-node/15-filter-take-vertices-edges.tas.data-store-drmcme43.json5

@@ -0,0 +1,46 @@
+/*
+ * `TAKE_EDGES` — wrap a TRAVERSE-shaped filter to extract the EDGES
+ * walked, not (only) the vertices. Default TAS query results
+ * include only vertices unless you opt into edges via TAKE_EDGES
+ * (or TAKE_VERTICES for the symmetric op).
+ *
+ * Use TAKE_EDGES when you need the relationship metadata: edge
+ * type, attributes, source/target IDs. The edges become the
+ * primary result; the vertices appear as graph metadata
+ * referenced by the edges.
+ *
+ * Inner shape is identical to query #14 (k8s_CLUSTER traversal);
+ * the only difference is the TAKE_EDGES wrapper at the top.
+ */
+{
+  /*
+   * TAKE_EDGES wraps a TRAVERSE (or any vertex-shaped filter) and
+   * returns the edges encountered. The `input` is what produces
+   * the vertex set whose edges to take.
+   */
+  "filter": {
+    "op": "TAKE_EDGES",
+    "input": {
+      "op": "TRAVERSE",
+      "input": {
+        "op": "ATTRIBUTE",
+        "expressions": [
+          {
+            "name": "type",
+            "values": ["k8s_CLUSTER"],
+            "operator": "IN"
+          }
+        ]
+      },
+      "traverse": [
+        {
+          "direction": "ANY",
+          "repeat": 2
+        }
+      ],
+      "includeInput": true
+    }
+  },
+  "limit": 100,
+  "projection": "DETAILED"
+}

package/dist-node/15-filter-take-vertices-edges.tas.data-store-tmd-8fewsp5s.json

@@ -0,0 +1,4 @@
+{
+  "description": "TAKE_EDGES: traverse from k8s_CLUSTER 2 levels deep, then extract edges to see relationships between cluster/namespace/deployment",
+  "tags": ["tas", "filter", "graph-shaping"]
+}

package/dist-node/16-filter-projection.tas-dh39mcx8.md

@@ -0,0 +1,31 @@
+# 16-filter-projection (TAS)
+
+## Purpose
+
+Demonstrate the `projectionFilter` query option, which limits which attributes are returned on each vertex — reducing response size and focusing on relevant data.
+
+## Query Construction
+
+Queries all `k8s_POD` vertices but uses `projectionFilter.attributes` to request only:
+- `name` — pod name
+- `type` — vertex type
+- `hostname` — host the pod runs on
+- `k8s_namespace` — Kubernetes namespace
+- `k8s_status` — pod status
+
+Without `projectionFilter`, vertices would include all 20+ attributes. With it, each vertex's `attributes` map contains only the requested fields (if they exist on that vertex).
+
+## API Surface Exercised
+
+- **projectionFilter**: `{ attributes: [...] }` — whitelist of attribute names to include
+- The schema also supports `attributeValueAsFields` for renaming attributes in the response
+
+## Expected Output
+
+Returns 30 k8s_POD vertices, each with a minimal attribute set. Attributes not in the projection list are omitted.
+
+## What the Results Tell You
+
+Projection filters are important for performance. A single vertex can have dozens of attributes. When building UIs or processing large result sets, requesting only the needed attributes reduces bandwidth and parsing overhead.
+
+Note: The `projection` field (`"DETAILED"`, `"DEFAULT"`, `"ID_ONLY"`) controls the overall detail level, while `projectionFilter` provides fine-grained attribute selection. When `projectionFilter` is used, the `projection` field is typically omitted.

package/dist-node/16-filter-projection.tas.data-store-tmd-3r8anggx.json

@@ -0,0 +1,4 @@
+{
+  "description": "projectionFilter: return only specific attributes (name, type, hostname, k8s_namespace, k8s_status) for k8s pods",
+  "tags": ["tas", "filter", "projection"]
+}

package/dist-node/16-filter-projection.tas.data-store-xjbdry1x.json5

@@ -0,0 +1,36 @@
+/*
+ * `projectionFilter` — a per-attribute selection list. Where
+ * `projection: DETAILED` returns ALL attributes per vertex,
+ * `projectionFilter: { attributes: [...] }` returns ONLY the
+ * named attributes. Use to reduce response size when you know
+ * exactly which attributes you care about — e.g. building a
+ * UI list / table / dropdown.
+ *
+ * Note: `projection` (singular, the breadth setting:
+ * DETAILED/BRIEF/NO_TYPE) and `projectionFilter` (the per-attribute
+ * whitelist) are independent. You can omit `projection` and use
+ * just `projectionFilter` for the tightest response shape.
+ */
+{
+  "filter": {
+    "op": "ATTRIBUTE",
+    "expressions": [
+      {
+        "name": "type",
+        "values": ["k8s_POD"],
+        "operator": "IN"
+      }
+    ]
+  },
+  "limit": 30,
+  /*
+   * Per-attribute whitelist. The named attributes are always
+   * returned; everything else is omitted. NO error if an
+   * attribute doesn't exist on a vertex — just absent. Useful
+   * for building tabular output where missing values become
+   * empty cells.
+   */
+  "projectionFilter": {
+    "attributes": ["name", "type", "hostname", "k8s_namespace", "k8s_status"]
+  }
+}

package/dist-node/17-filter-lucene.tas-gyvtzwaa.md

@@ -0,0 +1,29 @@
+# 17-filter-lucene (TAS)
+
+## Purpose
+
+Demonstrate the `LUCENE` filter, which provides full-text search using Lucene query syntax against indexed vertex attributes.
+
+## Query Construction
+
+Uses `LUCENE` with `query: "name:Kubernetes*"` — Lucene query syntax searching for vertices whose `name` attribute starts with "Kubernetes".
+
+## API Surface Exercised
+
+- **Filter**: `LUCENE` with `query` string (Lucene query syntax)
+
+## Expected Output
+
+**This query is marked as `expectedFailure: true`** because Lucene indexing is not enabled on all tenants — when it isn't, the server responds with HTTP 400.
+
+When Lucene is available, the query would return AGENT and AGENT_CONNECTION vertices with names like "Kubernetes Agent".
+
+## What the Results Tell You
+
+The `LUCENE` filter is a powerful full-text search capability but depends on tenant-level configuration. When available, it supports the full Lucene query syntax including:
+- Field-specific queries: `name:value`
+- Wildcards: `name:Kubernetes*`
+- Boolean: `name:Kubernetes* AND type:AGENT`
+- Range queries: `startTime:[2024-01-01 TO 2024-12-31]`
+
+If Lucene is not configured, fall back to `ATTRIBUTE` filters with `MATCHES` operator for regex-based searching.

package/dist-node/17-filter-lucene.tas.data-store-1knw6srt.json5

@@ -0,0 +1,39 @@
+/*
+ * `LUCENE` filter — full-text search using Lucene query syntax
+ * against indexed vertex attributes. Powerful (wildcards, fielded
+ * queries, range queries, boolean composition) but tenant-config-
+ * dependent: Lucene indexing is NOT enabled on every tenant.
+ *
+ * **TENANT-DEPENDENT**: this query is marked `expectedFailure: true`
+ * in its TMD because tenants without Lucene indexing return HTTP
+ * 400. Always verify capability first via `discovery_capabilities`
+ * (when M3.8 ships) before authoring a LUCENE-based query as the
+ * canonical answer; if Lucene's off, fall back to ATTRIBUTE +
+ * MATCHES.
+ *
+ * Lucene syntax cheatsheet:
+ *   field:value           — fielded match
+ *   field:value*          — wildcard (multi-char)
+ *   field:value?          — wildcard (single-char)
+ *   field:[a TO z]        — range
+ *   foo AND bar           — boolean
+ *   "phrase match"        — phrase
+ *   field:val OR field:other
+ */
+{
+  /*
+   * Single LUCENE filter at the root. The `query` is a Lucene
+   * query string — `name:Kubernetes*` matches vertices whose
+   * `name` attribute starts with "Kubernetes".
+   *
+   * Equivalent ATTRIBUTE+MATCHES fallback (if LUCENE is off):
+   *   ATTRIBUTE { name: "name", operator: MATCHES,
+   *               values: ["^Kubernetes.*"], caseInsensitive: false }
+   */
+  "filter": {
+    "op": "LUCENE",
+    "query": "name:Kubernetes*"
+  },
+  "limit": 20,
+  "projection": "DETAILED"
+}

package/dist-node/17-filter-lucene.tas.data-store-tmd-5cf3tygg.json

@@ -0,0 +1,5 @@
+{
+  "description": "LUCENE filter: full-text search for vertices whose name starts with 'Kubernetes'. May fail with 400 if Lucene indexing is not enabled on the tenant.",
+  "expectedFailure": true,
+  "tags": ["tas", "filter", "lucene"]
+}

package/dist-node/18-filter-variable-reuse.tas-89fq0y6x.md

@@ -0,0 +1,46 @@
+# 18-filter-variable-reuse (TAS)
+
+## Purpose
+
+Demonstrate `VARIABLE` — TAS query variables that allow defining reusable sub-queries by name. This is useful when the same vertex set is needed in multiple places within a complex query.
+
+## Query Construction
+
+1. **Variable declaration**: The top-level `variables` array defines a variable named `"k8s_hosts"` with its `input` filter (ATTRIBUTE type IN HOST)
+2. **Variable reference**: The main `filter` uses `VARIABLE` with `name: "k8s_hosts"` to reference the pre-defined set
+3. **Traversal**: The variable result is fed into a TRAVERSE (1 hop, any direction)
+
+```json
+{
+  "variables": [
+    {
+      "name": "k8s_hosts",
+      "input": { "op": "ATTRIBUTE", "expressions": [...] }
+    }
+  ],
+  "filter": {
+    "op": "TRAVERSE",
+    "input": { "op": "VARIABLE", "name": "k8s_hosts" },
+    "traverse": [{ "direction": "ANY", "repeat": 1 }],
+    "includeInput": true
+  }
+}
+```
+
+## API Surface Exercised
+
+- **TasQuery.variables**: Array of `{ name, input }` variable definitions
+- **Filter**: `VARIABLE` with `name` reference
+- **Composition**: VARIABLE as input to TRAVERSE
+
+## Expected Output
+
+Returns ~50 vertices: the 3 HOST vertices plus all their 1-hop neighbors (agents, k8s pods/containers connected to those hosts).
+
+## What the Results Tell You
+
+Variables serve two purposes:
+1. **Code reuse**: Define a complex filter once, reference it multiple times (e.g., in a JOIN's left and right inputs)
+2. **Readability**: Named sub-queries make complex queries easier to understand
+
+Variables are evaluated once and their result is cached for the duration of the query.

package/dist-node/18-filter-variable-reuse.tas.data-store-by35113t.json5

@@ -0,0 +1,55 @@
+/*
+ * `variables` + `VARIABLE` op — name a sub-filter once, reference
+ * it multiple times in the same query. Useful when a complex seed
+ * filter needs to participate in multiple places (multi-hop
+ * traversal with the same seed at each hop, or comparing two
+ * filters that share a base).
+ *
+ * Pattern shown here is minimal: define `k8s_hosts` once, reference
+ * once via VARIABLE. The win is bigger when the variable is used
+ * 2+ times — server evaluates the named filter ONCE.
+ */
+{
+  /*
+   * `variables` is a top-level field (sibling of `filter`).
+   * Each entry has a `name` and an `input` (the filter to bind).
+   * The bound name is then referenced via `{op:'VARIABLE', name}`
+   * anywhere a filter is expected.
+   */
+  "variables": [
+    {
+      "name": "k8s_hosts",
+      "input": {
+        "op": "ATTRIBUTE",
+        "expressions": [
+          {
+            "name": "type",
+            "values": ["HOST"],
+            "operator": "IN"
+          }
+        ]
+      }
+    }
+  ],
+  "filter": {
+    "op": "TRAVERSE",
+    /*
+     * `VARIABLE` is a leaf op (no `input`, no children) — it
+     * just dereferences the named entry from `variables`. Server
+     * substitutes the bound filter at execution time.
+     */
+    "input": {
+      "op": "VARIABLE",
+      "name": "k8s_hosts"
+    },
+    "traverse": [
+      {
+        "direction": "ANY",
+        "repeat": 1
+      }
+    ],
+    "includeInput": true
+  },
+  "limit": 50,
+  "projection": "DETAILED"
+}

package/dist-node/18-filter-variable-reuse.tas.data-store-tmd-ak7aprgk.json

@@ -0,0 +1,4 @@
+{
+  "description": "VARIABLE filter: define a named sub-query 'k8s_hosts' and reference it via VARIABLE, then TRAVERSE from it",
+  "tags": ["tas", "filter", "variable"]
+}

package/dist-node/19-filter-order-statefilter.tas-hm3z71qj.md

@@ -0,0 +1,36 @@
+# 19-filter-order-statefilter (TAS)
+
+## Purpose
+
+Demonstrate the `order` and `includeStatus` query options, which control result sorting and include alert/monitoring status on each vertex.
+
+## Query Construction
+
+Queries all AGENT vertices with:
+- **order**: Sort by `name` ascending, case-insensitive
+- **includeStatus**: `true` — include the vertex's monitoring status (alert level, staleness, etc.)
+
+The `order` field is an array of sort specifications, each with:
+- `name` — attribute to sort by
+- `desc` — descending if true
+- `caseInsensitive` — ignore case in string comparisons
+
+## API Surface Exercised
+
+- **TasQuery.order**: Array of `{ name, desc, caseInsensitive }` sort specs
+- **TasQuery.includeStatus**: Boolean to include vertex monitoring state
+- **Filter**: `ATTRIBUTE` with `IN` operator
+
+## Expected Output
+
+Returns up to 20 AGENT vertices sorted alphabetically by name. Each vertex may include additional status-related attributes showing whether the agent is active, its alert level, and when it last reported data.
+
+Typical agents include:
+- Database-monitoring agents (MySQL / Postgres / etc. APM IAs)
+- Kubernetes / Prometheus agents in any reporting clusters
+- Infrastructure agents
+- Experience Collector agents
+
+## What the Results Tell You
+
+The `order` option is critical for paginated UIs — combined with `limit` and `offset`, it enables consistent pagination over large result sets. The `includeStatus` flag adds real-time monitoring context to topology queries, allowing UI dashboards to show not just what exists but what's healthy.

package/dist-node/19-filter-order-statefilter.tas.data-store-ra9hj1rz.json5

@@ -0,0 +1,51 @@
+/*
+ * Sort + status-include — two query-envelope features:
+ *
+ * - `order: [...]` sorts the result. Required for paginated UIs
+ *   that combine `limit` + `offset` — without `order`, the server
+ *   can return rows in any order and pagination becomes
+ *   nondeterministic.
+ * - `includeStatus: true` enriches each vertex with monitoring
+ *   state (alert level, staleness, last-reported timestamp, etc).
+ *   Adds bytes — only set when you need the health signal.
+ *
+ * Both are sibling fields of `filter` at the top of the query.
+ */
+{
+  "filter": {
+    "op": "ATTRIBUTE",
+    "expressions": [
+      {
+        "name": "type",
+        "values": ["AGENT"],
+        "operator": "IN"
+      }
+    ]
+  },
+  /*
+   * `order` is an ARRAY of sort specs (multi-column sort).
+   * Each spec:
+   *   name: attribute name
+   *   desc: descending? (default false = ascending)
+   *   caseInsensitive: ignore case for string sorts (default false)
+   *
+   * Bake `order` into any query you intend to paginate. Without it,
+   * `limit`+`offset` results vary across requests.
+   */
+  "order": [
+    {
+      "name": "name",
+      "desc": false,
+      "caseInsensitive": true
+    }
+  ],
+  /*
+   * `includeStatus` adds monitoring-state attributes to each
+   * returned vertex (alert level, staleness, etc). Cost: extra
+   * bytes per vertex. Off by default; set true when you need
+   * "is this entity healthy / fresh?".
+   */
+  "includeStatus": true,
+  "limit": 20,
+  "projection": "DETAILED"
+}

package/dist-node/19-filter-order-statefilter.tas.data-store-tmd-wqer9xy2.json

@@ -0,0 +1,4 @@
+{
+  "description": "Order + includeStatus: list agents sorted by name with their alert/status states",
+  "tags": ["tas", "filter", "order", "status"]
+}

package/dist-node/20-nassql-from-metadata-basic.nassql-szr2xax1.md

@@ -0,0 +1,28 @@
+# 20-nassql-from-metadata-basic (NASSQL)
+
+## Purpose
+
+Demonstrate the simplest NASSQL pipeline: `FROM_METADATA` with `ALL` specifier, aggregated with `COUNT`.
+
+## Query Construction
+
+Three-step pipeline:
+1. `FROM_METADATA` with `{ op: "ALL" }` specifier — loads all metric metadata rows
+2. `COUNT` with `as: "total"` — counts all rows into a single number
+3. `KEEP` with `["total"]` — retains only the count column
+
+## API Surface Exercised
+
+- **FROM_METADATA**: Source operation loading metric metadata (not data values)
+- **COUNT**: Aggregation operation
+- **KEEP**: Column selection (must be the last operation in the pipeline)
+
+## Expected Output
+
+A single data row: `[["total"], [N]]` where N is the total number of metrics on the tenant. The number depends on retention, data volume, and what's reporting — small lab tenants may show tens of thousands; busy production tenants can sit in the millions.
+
+## What the Results Tell You
+
+This is the NASSQL equivalent of `SELECT COUNT(*) FROM metric_metadata`. The `FROM_METADATA` operation returns one row per registered metric. The `COUNT` aggregation collapses all rows into a single count.
+
+Key pipeline rule: `KEEP` must always be the last operation (the API returns HTTP 400 if anything follows KEEP).

package/dist-node/20-nassql-from-metadata-basic.nassql.data-store-tmd-c7drxs1m.json

@@ -0,0 +1,4 @@
+{
+  "description": "FROM_METADATA + COUNT: count total metrics across all sources",
+  "tags": ["nassql", "from_metadata", "count"]
+}