Aggregation_and_Leaderboard_Guide

Purpose

Use this guide to produce counts, percentages, top-N lists, and distribution views from supported search tools. Use it when:

• users ask for percentages, totals, rankings, or breakdowns by agency/vendor/category.

• users ask for dashboard-like rollups from filtered result sets.

• users need numerator/denominator logic for ratio calculations.

Construction Rules

• Aggregation-driven analysis should use the default keyword behavior. Do not send search_mode unless you need a non-default mode.

• Keep aggregation requests focused:

  • one question per call when possible.

  • include only filters needed to define the cohort.

• Apply filters before aggregation:

  • agency, vendor, NAICS/PSC, location, set-aside, and date ranges.

• For percentages, run two consistent cohorts:

  • denominator: full scoped population.

  • numerator: same scope plus the qualifying condition.

• Keep aggregation names explicit and stable for downstream reporting.

Examples

Top awardees by dollars obligated for a scoped window: Tool: Search_Federal_Contract_Awards

{
  "query": "",
  "award_date_range": {
    "from": "now-2y/d",
    "to": "now/d"
  },
  "naics_category_ids": ["541512"],
  "aggregations": ["top_awardees_by_dollars_obligated"]
}

Count-style breakdown by agency in one category: Tool: Search_Federal_Contract_Opportunities

{
  "query": "",
  "posted_date": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "naics_category_ids": ["541611"],
  "aggregations": ["top_federal_agencies_by_doc_count"]
}

Numerator cohort for percentage calculation: Tool: Search_Federal_Contract_Awards

{
  "query": "",
  "award_date_range": {
    "from": "now-12M/d",
    "to": "now/d"
  },
  "set_aside_types": ["Total Small Business"],
  "aggregations": ["top_awardees_by_dollars_obligated"]
}