HubSQL i beta: SQL direkte mod dine HubSpot-data

Du vil vide, hvor meget der ligger i pipelinen fordelt på stage. I dag betyder det, at du henter dine deals ud gennem API'et, hundrede ad gangen, og lægger dem sammen selv i din egen kode.

HubSpot har netop åbnet en beta, der gør det til én linje SQL. Den hedder HubSQL. Herunder gennemgår vi, hvad den er, hvordan et kald ser ud, hvor grænserne går, og hvad den efter vores vurdering er bygget til.

Alt herunder bygger på HubSpots egen beta-dokumentation, senest opdateret 9. september 2026. Siden kræver, at du er logget ind med en HubSpot-udviklerkonto. Vi har læst specifikationen grundigt igennem, men har ikke kørt betaen i produktion endnu, så alt om faktisk ydeevne er dokumentationens ord, ikke vores målinger.

Hvad er HubSQL?

HubSQL er et query-lag oven på jeres CRM-data. I dag har hver objekttype sit eget endpoint: ét til deals, ét til kontakter, ét til virksomheder. Vil du kombinere dem, henter du fra flere endpoints og samler stumperne i din egen kode. HubSQL erstatter det med ét endpoint, hvor du sender dit spørgsmål som SQL i request-bodyen og får rækker tilbage.

Kort fortalt: SQL er det sprog, man i årtier har brugt til at stille spørgsmål til en database. Indtil nu har man skullet hente HubSpot-data ud i stumper og selv regne på dem bagefter. Med HubSQL kan man stille spørgsmålet direkte og få svaret.

Sådan ser et kald ud

Det er et POST-kald med to felter i bodyen. query er selve SQL-strengen og må ikke være tom. pageSize er valgfri og styrer, hvor mange rækker du får per side.

POST https://api.hubapi.com/analytics/hubsql/2027-03-beta/query

{
  "query": "SELECT dealname, amount FROM OBJECT.DEAL WHERE amount > 1000",
  "pageSize": 5
}

Sådan ser svaret ud

Du får en flad JSON-array af rækker, som var det et regneark. results er rækkerne, paging dukker kun op, hvis der er flere sider, og felter uden værdi kommer tilbage som null.

{
  "total": 14,
  "results": [
    { "amount": "15000", "dealname": "big deal" },
    { "amount": "4250",  "dealname": "Globex renewal" },
    { "amount": null,    "dealname": "Jorb K - New Deal" }
  ],
  "paging": {
    "next": { "after": "eyJjdXJzb3IiOiIyMDAifQ==" }
  }
}

En detalje der er værd at have med: dokumentationen beskriver total som antallet af returnerede rækker, men eksemplerne viser noget andet. I kodeblokken ovenfor står der 14 ved siden af tre rækker. total er antallet af rækker der matcher dit query, ikke antallet du fik i denne side. Byg jeres logik på det.

Hvad du kan spørge om

Datakilder skrives som SCHEMA.TABLE, hvor schema enten er OBJECT eller EVENT. Fyrre standardobjekter er med i denne fase af betaen: deals, kontakter, virksomheder, tickets, fakturaer, ordrer, line items, quotes, brugere, kampagner og en række flere. Dertil app-objekter og custom objects i HubSpot, som angives med deres objectTypeId.

Du kan hente data på tværs af objekter med LEFT JOIN:

SELECT dealname, amount, CONTACT.firstname, COMPANY.name
FROM OBJECT.DEAL
LEFT JOIN OBJECT.CONTACT
LEFT JOIN OBJECT.COMPANY
WHERE DEAL.amount > 1000

Udelader du ON-delen, bruger HubSpot den primære association mellem de to objekttyper. Vil du bruge en bestemt associationstype, angiver du dens navn som tekst. Højst tre joins per query.

Og så er der aggregeringerne, som er dét, der reelt er nyt her:

SELECT dealstage, COUNT(*) AS antal, SUM(amount) AS total
FROM OBJECT.DEAL
GROUP BY dealstage
ORDER BY antal DESC

COUNT, SUM, AVG, MIN, MAX og MEDIAN er understøttet. Det er den slags spørgsmål, man i dag enten skal bygge en rapport til i grænsefladen eller regne sig frem til i egen kode.

Adgang, scopes og feltrettigheder

Både OAuth, static tokens og service keys virker. Din app skal have læse-scope for hver objekttype, queryet rører ved: spørger du om deals, kræver det crm.objects.deals.read. Events kræver business-intelligence.

Vigtigere er forskellen på, hvordan feltrettigheder håndhæves. Bruger du OAuth, gælder brugernes egne rettigheder, og forsøger du at læse en property, brugeren ikke må se, får du en 403 med besked om, hvilke properties der er spærret. Bruger du et static token eller en service key, håndhæves rettighederne ikke. Alt er læsbart. Den forskel bør I træffe en bevidst beslutning om, hvis I bygger noget kundevendt ovenpå.

Sådan henter du mere end de første rækker

Pagineringen er cursor-baseret. Sender du dit første kald uden after og får et paging.next.after tilbage, er der flere rækker. Du sender så samme query igen med after sat til den værdi og gentager, indtil feltet udebliver.

Tre tal er nemme at blande sammen. pageSize er rækker per side og er som standard 10, højst 100. LIMIT i selve queryet sætter loftet for hele resultatsættet: højst 10.000 rækker uden aggregeringsfunktion og 500 med. Er LIMIT lavere end pageSize, vinder LIMIT. Og aggregerede queries kan slet ikke pagineres, hvilket er værd at teste af, hvis I regner med at få mere end 100 grupper tilbage.

En SQL-parser oven på Search API

Læser man begrænsningerne i dokumentationen, tegner der sig et tydeligt billede af, hvad der ligger under motorhjelmen.

HubSQL tillader højst fem filtergrupper og 18 filtre i alt. Det er præcis de samme tal, som HubSpots eksisterende Search API har haft i årevis. Og kravet om, at et WHERE-udtryk skal skrives med OR på øverste niveau og AND indeni, svarer nøjagtigt til strukturen i filterGroups, bare skrevet ud i SQL-syntaks.

Når man først har set mønsteret, falder resten på plads:

• SELECT * returnerer kun hs_object_id, fordi søgemotoren under motorhjelmen leverer ID'er, og properties hentes ved at nævne dem.
• LIKE med wildcard forrest afvises. Det er prefix-matching i et søgeindeks.
• COUNT(DISTINCT) er udtrykkeligt approksimativ, hvilket peger på en cardinality-aggregering.
• Højst to GROUP BY-kolonner og intet HAVING, altså den faste dybde man kender fra nestede aggregeringer.
• ON accepterer kun tekststrenge som 'CONTACT_TO_DEAL', fordi det underliggende opslag er en traversering af associations mellem records og ikke et join i databaseforstand.

HubSQL er altså en SQL-parser, der oversætter ned til den søge- og rapporteringsmotor, HubSpot allerede havde. Funktionaliteten har med andre ord været der hele tiden. Sproget er nyt. Endepunktet ligger da også under /analytics/ og ikke under /crm/.

Kort fortalt: HubSpot har ikke bygget et nyt datalager. De har sat en ny dør på det, de allerede havde, og døren er lettere at gå igennem.

Fem begrænsninger du skal kende

1. Alt kommer tilbage som tekst. Tal, datoer, booleans. Beløbet 15000 kommer som "15000" i anførselstegn. Tomme felter bliver til null. Du skal konvertere selv i alle led bagefter.

2. WHERE skal skrives i en bestemt form. Det her afvises:

WHERE (dealstage = 'closedwon' OR dealstage = 'qualifiedtobuy')
  AND amount > 1000

Det skal skrives om med IN:

WHERE dealstage IN ('closedwon', 'qualifiedtobuy')
  AND amount > 1000

Reglen er, at OR ikke må ligge inde i en AND-gruppe. Det er den begrænsning, der kommer til at koste flest fejlede kald i starten, fordi det er præcis den slags query, både mennesker og sprogmodeller skriver helt automatisk.

3. Events kan kun tælles, ikke listes. Ethvert EVENT-query skal indeholde mindst én aggregeringsfunktion. Der findes ingen vej til rå eventdata her. Glemmer du at filtrere på dato, får du automatisk de seneste syv dage, og du kan højst hente 90 dage ad gangen.

4. Der er ingen HAVING. Betingelser på aggregerede værdier findes ikke. De skal flyttes op i WHERE, hvilket ikke altid er muligt at oversætte en til en.

5. Følsomme data er ikke med. Felter markeret som Sensitive Data kan ikke tilgås gennem endepunktet overhovedet.

Det vigtigste tal i hele lanceringen: ét kald i sekundet

HubSQL har en grænse på ét request i sekundet og 10.000 i døgnet. Grænsen gælder per konto, ikke per integration, så jeres eksisterende jobs og scripts trækker fra den samme pulje.

Med højst 100 rækker per side svarer det til omkring en million rækker i døgnet under absolut ideelle forhold, og ingen mulighed for at køre kald parallelt. Til sammenligning kører HubSpots almindelige CRM-endpoints med et helt andet råderum.

Den grænse forsvinder næppe, når betaen lukker op. Den ligner en bevidst designbeslutning, og den fortæller ret præcist, hvad HubSQL er tænkt til. Skal I flytte data til et datawarehouse, holde et eksternt system synkroniseret eller lave en natlig eksport, er svaret stadig batch-endpoints eller HubSpot Data Hub. HubSQL besvarer spørgsmål. Det flytter ikke data.

Kort fortalt: Tænk på det som en medarbejder, der gerne svarer på et spørgsmål om tallene, men ikke gider printe hele arkivet ud til dig.

Hvorfor har HubSpot bygget det, når API'et findes i forvejen?

Vores læsning er, at det først og fremmest er bygget til AI-agenter.

Skal du give en agent adgang til et CRM gennem det almindelige API, skal den vide, hvilket af fyrre endepunkter den skal ramme, hvordan associationer slås op, hvordan der pagineres, og den skal regne sammen bagefter. Det er mange værktøjsdefinitioner og meget, der kan gå galt. Med HubSQL er det ét værktøj med én parameter. SQL ind, rækker ud. Og SQL er det forespørgselssprog, sprogmodeller skriver bedst uden oplæring, fordi der findes enorme mængder af det i deres træningsdata.

Læg mærke til fejlbeskederne i dokumentationen. De er formuleret sådan her: "SUM does not support string properties ('dealname'). Supported property types: number, datetime." Og: "Remove or replace the listed properties and try again." Almindelige API-fejl fortæller dig sjældent, hvordan du retter fejlen. De her er skrevet, så noget kan læse dem og prøve igen. Grænsen på ét kald i sekundet passer i øvrigt fint til en samtale, hvor der stilles en håndfuld spørgsmål, og slet ikke til en integration.

Kort fortalt: Skal en AI-assistent kunne svare på "hvor meget har vi solgt i Jylland i år", skal den kunne spørge om det på en måde, den selv kan finde ud af at formulere. SQL er det sprog, den er bedst til.

Dertil kommer to mere jordnære motiver. Det ene er, at beregningen flyttes hen til dataene: totalen per stage koster ét kald i stedet for hundrede, hvilket sandsynligvis er en besparelse for HubSpot selv. Det andet er, at data bliver liggende. Rigtig mange virksomheder piper i dag HubSpot-data ud i et warehouse, udelukkende for at kunne stille den slags spørgsmål. Hver af de pipelines gør platformen en anelse mere udskiftelig.

Den kedelige forklaring skal også med: udviklere har bedt om SQL-adgang til HubSpot i mere end ti år. Det er en af de længstlevende ønsker i deres community. Måske er det simpelthen en gammel anmodning, der endelig blev prioriteret, fordi agent-behovet gjorde forretningscasen god nok.

Kan man bruge HubSQL på websider i HubSpot CMS?

Det spørgsmål har vi allerede fået et par gange: kan man hente CRM-data ind på sider og React-moduler i HubSpot CMS med HubSQL?

Teknisk ja, i praksis nej. React-moduler på HubSpot cacher som udgangspunkt i ti sekunder, og cache-nøglen tager højde for module props og injicerede afhængigheder. Bruger du kontaktafhængig personalisering, får du en cache-nøgle per besøgende. Med ét kald i sekundet for hele kontoen falder den side om ved to samtidige besøgende.

CMS'et har i forvejen sit eget query-lag til netop det formål. GraphQL for CMS henter HubDB, CRM-objekter, blog og vidensbase server-side, samler queryet med komponenten og klarer associationsdata i ét kald. Cache-adfærden og de øvrige datahentningsmetoder til React-moduler er dokumenteret samme sted. Da HubSpot skulle løse problemet "få CRM-data ind på en renderet side", byggede de GraphQL. HubSQL ligger under analytics. To produkter, to formål.

Der er én undtagelse, som faktisk er interessant. GraphQL for CMS kan hente og filtrere records, men den kan ikke lave SUM eller COUNT på tværs af CRM'et. Vil du vise "samlet værdi af lukkede aftaler i år" på en side, skal du i dag hente alle records og regne selv. Der ville HubSQL være det rigtige valg, men kun med hård caching i minutter eller timer, uden personalisering i cache-nøglen, og med den fulde bevidsthed om, at du bruger af en meget lille daglig pulje.

Hvem bør kigge på det nu?

Betaen er relevant for jer, hvis I genkender en af disse:

• I bygger eller overvejer AI-agenter, der tilgår HubSpot, og I er trætte af at vedligeholde en værktøjsdefinition per objekttype.
• I har rapporteringsbehov, der falder ved siden af dashboards i HubSpot, og som i dag løses med eksport til regneark.
• I har custom objects med sammensatte spørgsmål, hvor HubSpots datamodel kræver flere kald og en del kode for at besvare noget, der burde være enkelt.

Det er derimod ikke svaret, hvis I leder efter en vej til datasynkronisering, eksport, skrivning af data eller realtidsintegration. HubSQL er udelukkende læsning.

Én praktisk anbefaling, hvis I går i gang: byg et valideringslag, der fanger den ugyldige WHERE-form, før kaldet sendes af sted. Med ét kald i sekundet er det ærgerligt at bruge sit budget på at få en 400-fejl tilbage.

Spørgsmål vi typisk får

De fire her er besvaret uden teknisk sprog, så de kan sendes videre til en kollega, der ikke arbejder med API'er til daglig.

Vores vurdering

HubSQL giver ikke adgang til noget, HubSpot ikke allerede kunne. Det gør adgangen markant nemmere for den slags spørgsmål, hvor man i dag skriver tredive linjer kode for at få ét tal. Og aggregeringerne dækker et reelt hul, der har været der længe.

Men grænsen på ét kald i sekundet er hele historien. HubSpot har bygget en samtalegrænseflade til deres eget data, sandsynligvis med agenter for øje, og de har gjort den for langsom til alt andet. Det passer ind i den retning, HubSpot har bevæget sig siden Breeze: platformen skal kunne betjenes af noget, der spørger, og ikke kun af nogen, der klikker.

Betaen er under aktiv udvikling, og både syntaks og grænser kan nå at ændre sig inden en officiel lancering. Skal vi kigge på, om HubSQL kan løse et konkret rapporterings- eller agent-behov hos jer, så tag fat i os.