Aggregate
aggregateGroup, count, and rank records across any Boomerang entity. group_by and metrics use typed enums — only supported groupings are expressed, backend maps each to the right DB column. Supports OR/AND filter composition via FilterGroups, having clauses for threshold filtering ('accounts with 3+ paths'), anti-joins for NOT EXISTS queries ('accounts with no intro request'), and cursor pagination for large result sets. COUNTING RULE: for 'number of paths' questions always use AGG_OP_COUNT_DISTINCT on REL_METRIC_RELATIONSHIP_ID — never AGG_OP_COUNT on REL_METRIC_STAR, which inflates counts when rows join-duplicate across categories or path types. GROUP-BY HYGIENE: always include the _ID group field alongside _NAME for accounts/users/contacts (e.g. both REL_GROUP_TARGET_ACCOUNT_ID and REL_GROUP_TARGET_ACCOUNT_NAME) — this surfaces name-casing duplicates ('IBM' vs 'ibm') as distinct IDs rather than silently merging or confusingly splitting them. QUALITY vs VOLUME: raw path counts include weak/unlikely connections that inflate rankings. When ranking without a strength filter, proactively note that results include low-confidence paths and offer to re-run filtered to CONFIRMED/STRONG strength for a quality-adjusted ranking.
Use when: Use for counting, ranking, grouping, breakdowns, and threshold questions. TRIGGER PHRASES: 'top N', 'most', 'how many', 'group by', 'breakdown by', 'which has the most', 'accounts with 3+', 'leaderboard', 'rank the connectors/accounts', 'best path to X', 'strongest connections to X', 'who can introduce me to X', 'who knows someone at X', 'which connector/account has the most/strongest paths to X'. KEY PATTERN — ranked-by-source filtered-to-one-target: a question like 'top 5 connectors who can reach Salesforce' reads like a lookup but is really group ENTITY_RELATIONSHIP by source user, filtered to target account — always use Aggregate for this, never page through raw relationship rows. Set limit for top-N. Use having for post-aggregation thresholds (e.g. 'accounts with 3+ paths'). For OR filters (e.g. 'ICP match OR CONFIRMED strength') pass multiple FilterGroups. Use page_token + next_page_token to paginate large result sets.
Behavior: read_only
workspace_id / user_id are injected from request headers.
Returns rows[] with fields: fields
IMPORTANT: If the response contains more than one record, always present the options to the user and ask them to choose before taking any follow-up action. Do not act on all results automatically.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Sort order on aggregated results. Use metric_alias to sort by a computed metric (most common for top-N), or group_field to sort alphabetically by a group key. | |
| joins | No | Optional cross-entity joins. For ENTITY_RELATIONSHIP prefer REL_FILTER_HAS_INTRO_REQUEST instead. Use JoinClause with JOIN_TYPE_ANTI when querying ENTITY_ACCOUNT and need to exclude accounts with existing intro requests. | |
| limit | No | ||
| entity | No | ||
| having | No | Post-aggregation filters applied after GROUP BY. AND-combined. Use for threshold questions: 'accounts with 3+ paths' → having path_count GTE 3. | |
| metrics | No | One or more aggregation metrics per group. At least one required. | |
| group_by | No | ||
| page_token | No | ||
| filter_groups | No | Pre-aggregation filters applied before GROUP BY. Groups are OR-combined; filters within each group are AND-combined. For a pure AND query pass a single FilterGroup. For OR: pass multiple groups — e.g. [{strength=CONFIRMED}, {icp=MATCH}] matches rows where strength is CONFIRMED OR icp is MATCH. Omit for no filtering. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||