endor-route-estate-queries

name	endor-route-estate-queries
description	Use when routing estate-scale data pulls between Query graph joins and facade list/count/shard patterns after bounded topology discovery—choosing how to fetch counts, aggregates, or validated joins across many projects. Not for single-project RCA; hand off when full row export is needed without a validated Query join.

Route estate queries (Query vs facade)

Default path: classify the ask → pick grain (project vs namespace) → discover if needed → validate on a sample → scale.

Normative parity: query-vs-list-semantics contract. Guide: docs/guides/query-recipes.md.

Scope

In scope	Out of scope
Dashboard counts across many projects	Single-project finding RCA
Query graph joins vs count() / list_groups	Unvalidated custom joins at full tenant
Topology discovery (bounded Project.list)	endor-estate pull unless user asks
Namespace-scoped Query (non-Project roots)	Policy validation
Sample validation before estate-wide Query

Handoffs: endor-retrieve-scan-results (one repo rows) · endor-project-retrieval-bundle (single-project bundle) · endor-namespace-relationship-map (consumer graph).

Step 0 — Classify output and grain

Per-project grain (estate dashboard)

User wants	OutputShape	Primary path
PV / finding category counts per project	COUNT_BY_PROJECT / FINDING_CATEGORY_COUNTS	Query.Project.* after validation
DM count per importer project	(dashboard)	client.Query.Project.count_dm after recipe="dm" validation
Online estate dashboard tiles (no pull)	—	fetch_online_dashboard_counts → ir/online_dashboard_counts.json
Finding rows for one scan	FINDING_ROWS	Finding.list_by_project
Package usage by version	DM_VERSION_CARDINALITY	DependencyMetadata.list_groups

from endorlabs.query import OutputShape, discover_topology, recommend

topo = discover_topology(client, "<tenant>", traverse=True, max_pages=...)
plan = recommend(OutputShape.COUNT_BY_PROJECT, topology=topo)
shards = topo.project_shards()

Namespace grain (no Project root)

User wants	Primary path
Count/filter at one namespace (e.g. agent hook events)	client.Query.at_namespace(QuerySpec.root("<Kind>").count(...), namespace=…) or facade count()
Tenant-wide finding total (no per-project breakdown)	Probe Query.at_namespace with Finding root; compare to Finding.count
New vs resolved over time	FindingLog.list_groups (probe Query group_by_time)
OSS CVE/coordinate lookup	QueryVulnerability / QueryMalware

from endorlabs.query import QuerySpec

spec = QuerySpec.root("AgentHookEvent").list_parameters(count=True)
client.Query.at_namespace(spec, namespace="<leaf>", parse=..., merge=...)

Do not force Query.Project.discover when the ask has no project grain.

Step 1 — Discover topology (per-project grain only)

from endorlabs.query import discover_topology

topo = discover_topology(
    client,
    "<tenant>",
    traverse=True,
    max_pages=...,  # bound cost during discovery
)

Resolve Project rows first; pass resource objects into Query.Project recipes.

Step 2 — Correctness gate (before scale)

from endorlabs.query import validate_sample

sample = topo.projects[:10]
result = validate_sample(client, sample, recipe="pv", sample_size=5)
assert result.matched, result.to_dict()
counts = client.Query.Project.count_pv(topo.projects)
dm_counts = client.Query.Project.count_dm(topo.projects)

Canonical MQL: endorlabs.filters.

Step 3 — Execute

Archetype	Shard key	Query?
single_repo	project	Optional; recommend() may prefer facade_count
monorepo_hub	leaf namespace + pagination	Yes for validated count joins
managed_platform / estate_sprawl	leaf namespace batches	Yes if sample validated

Row materialization: topo.project_shards() → tools/list_sharding. Online-only dashboard: fetch_online_dashboard_counts.

Anti-patterns

• Treat Query.Project as the only Query API — use execute / at_namespace for other root kinds
• POST Query at tenant root when projects live in child namespaces
• Use Query.Project.count_dm when the ask needs DM version buckets (list_groups semantics differ)
• Skip sample validation because Query was faster on another customer
• traverse=True on findings after Project is already resolved

Related skills

Skill	When
endor-retrieve-scan-results	One project findings
endor-list-query-performance	List/count performance
endor-namespace-scoping	Namespace invariants