OpenSearch

Opensearch Aggregate

Generic, allowlist-bounded GROUP BY over a whitelisted mashup index.

Translates group_by into nested OpenSearch terms aggregations with metric sub-aggs, then applies having / sort / limit to the flattened groups. This is the matrix-walk primitive for TAM design (e.g. count companies by NAICS x state x employee band in one call).

Guardrails: group_by depth is capped at 3, per-level bucket size tapers by depth (_AGG_TERMS_SIZE_BY_DEPTH), the agg list is capped at 10, and returned groups at limit (<=1000). Counts from terms / cardinality are APPROXIMATE on a sharded index. Since mashup_companies/mashup_contacts share one contact-grained index, use uniqExact on COMPANY_ID for true unique-company counts. Mashup aggregations automatically apply the organization's deliverability policy.

post/opensearch/aggregate

Request

  • Base URL: https://be.graph8.com/api/v1
  • URL: https://be.graph8.com/api/v1/opensearch/aggregate
  • Auth: HTTP bearer

Headers

Authorizationstring nullable
X-Target-Org-Idstring nullable

Request body

index'mashup_contacts' | 'mashup_companies' | 'hem2contact' | 'ip2company' required

Logical index to aggregate. Maps to a whitelisted physical alias.

filtersobject

Pre-aggregation equality filters, identical semantics to /opensearch/search. RAW UPPERCASE field names.

group_bystring[] required

1-3 RAW UPPERCASE keyword fields to group on (e.g. ["COMPANY_NAICS", "COMPANY_STATE"]). Must be keyword-type fields -- the canonical COMPANY_* firmographics are. Capped at 3 dimensions to bound cluster cost. ORDER HIGHEST-CARDINALITY FIRST: deeper dimensions get smaller per-level bucket caps (1000 / 100 / 20), so a low-cardinality field placed last keeps full fidelity while a high-cardinality field placed last may be truncated.

havingobject nullable

Post-aggregation group filter keyed by metric alias, e.g. {"count": {"gte": 50}}. Operators: eq, gte, lte, gt, lt.

sortobject[] nullable

Sort the returned groups by a metric alias, e.g. [{"count": "desc"}]. Applied after having.

limitinteger

Max number of groups returned (after having + sort). Hard-capped at 1000.

Response

Successful Response

Changes

No recorded changes to this operation across all 2 revisions of this API.