Skip to main content

HG Data Query (SQL)

Coming soon

The v2 MCP API is in preview and not yet generally available. These pages document its tools and request/response shapes; live data access is limited to enrolled organizations until v2 is released.

Execute read-only SQL SELECT queries against the HG Insights data warehouse. hg_data_query EXECUTES SQL you already have and returns rows; the similarly-named hg_query only GENERATES SQL from a plain-English question and does NOT run it — use hg_query when you need the SQL written for you, then run it here. Call the hg_catalog tool first to discover available tables and columns before writing queries. Queries must be SELECT-only (no INSERT, UPDATE, DELETE, DROP, etc.). Returns rows, column names, row count, and credits consumed. Credit cost is SCAN-BASED not row-based — the cost depends on data scanned, not rows returned. A query returning 0 rows can still consume ~50 credits; add WHERE predicates to narrow scans.

PREFER search_companies for vendor/product/category lookups, company counts, and firmographic filters — no SQL needed. Use hg_data_query only for multi-table joins, time-series, or aggregations search_companies cannot express.

CONSTRAINTS: SELECT * rejected — list explicit columns. Call hg_catalog to discover valid tables.

KEY COLUMNS: company_locations(cl): name, country_name, country_code, employees_min, employees_max, company_id, url_id. install_global(ig): product_id, product_name, vendor_name, category_leaf_name, url_id — NO category_id. Join: USING (url_id).

TAM: call get_vendor_information for product IDs, then filter install_global by product_id. See query param for worked examples.

Parameters​

NameTypeRequiredDefaultDescription
querystring✅ Yes-A single read-only SQL statement to run against the HG data warehouse. Must start with SELECT or WITH; SELECT * and any write/DDL (INSERT/UPDATE/DELETE/DROP) are rejected. Use exact table/column names from hg_catalog. Examples — (1) "How many mid-market North American companies have installed Splunk?" → call get_vendor_information(vendorName: "Splunk") for product IDs, then: SELECT COUNT(DISTINCT cl.company_id) FROM install_global ig JOIN company_locations cl USING (url_id) WHERE ig.product_id IN (<splunk_product_ids>) AND cl.country_name IN ('United States', 'Canada') AND cl.employees_min >= 100 AND cl.employees_max <= 1000. (2) "Companies running a SIEM that's not Splunk" (competitive displacement) → same first call for Splunk product IDs, then: SELECT DISTINCT cl.company_id, cl.name FROM install_global ig JOIN company_locations cl USING (url_id) WHERE ig.category_leaf_name IN (SELECT DISTINCT category_leaf_name FROM install_global WHERE product_id IN (<splunk_product_ids>)) AND ig.product_id NOT IN (<splunk_product_ids>) LIMIT 1000. The category subquery derives Splunk's categories from install_global itself — get_vendor_information returns product_id/product_name only, not category_leaf_name.
max_rowsinteger❌ No1000Row cap for the result set (default: 1000, max: 10000). Credit cost is scan-based, not row-based, so prefer COUNT/aggregate queries and tight WHERE predicates over pulling raw rows.

Required Integrations​

  • hginsights_db_query

Use Cases​

  • Run a custom aggregation or cross-table join no purpose-built HG tool can express — call hg_catalog first for exact table/column names
  • Compute TAM: count distinct companies running a product within a geo/size band (COUNT(DISTINCT ...) over install_global joined to company_locations)
  • Competitive displacement: companies in a category that do NOT run a given vendor (category IN <subquery> AND product_id NOT IN <ids>)
  • Time-series or trend rollups across warehouse tables not exposed by a specific tool
  • Ad hoc warehouse exploration once you know the exact tables and columns from hg_catalog

Example Usage​

Count mid-market US/Canada companies running Splunk (product IDs from get_vendor_information)

{
  "tool": "hg_data_query",
  "arguments": {
    "query": "SELECT COUNT(DISTINCT cl.company_id) FROM install_global ig JOIN company_locations cl USING (url_id) WHERE ig.product_id IN (1234, 5678) AND cl.country_name IN ('United States', 'Canada') AND cl.employees_min >= 100 AND cl.employees_max <= 1000"
  }
}

Competitive displacement: SIEM installs that are not Splunk

{
  "tool": "hg_data_query",
  "arguments": {
    "query": "SELECT DISTINCT cl.company_id, cl.name FROM install_global ig JOIN company_locations cl USING (url_id) WHERE ig.category_leaf_name IN (SELECT DISTINCT category_leaf_name FROM install_global WHERE product_id IN (1234, 5678)) AND ig.product_id NOT IN (1234, 5678) LIMIT 500",
    "max_rows": 500
  }
}

hg_catalog, hg_query, search_companies, company_technographic, get_vendor_information, company_install_time_series