Skip to content

Commit 862a2eb

Browse files
setohe0909setohe0909
authored
FQE-1719- Validate HubSpot Handler (#11831)
1 parent 46bc61a commit 862a2eb

8 files changed

Lines changed: 1984 additions & 267 deletions

File tree

‎mindsdb/integrations/handlers/hubspot_handler/README.md‎

Lines changed: 203 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -7,167 +7,227 @@ HubSpot handler for MindsDB provides interfaces to connect to HubSpot via APIs a
77
## Table of Contents
88

99
- [HubSpot Handler](#hubspot-handler)
10-
- [Table of Contents](#table-of-contents)
1110
- [About HubSpot](#about-hubspot)
12-
- [HubSpot Handler Implementation](#hubspot-handler-implementation)
13-
- [HubSpot Handler Initialization](#hubspot-handler-initialization)
14-
- [Implemented Features](#implemented-features)
11+
- [Installation](#installation)
12+
- [Authentication](#authentication)
13+
- [Access Token Authentication](#access-token-authentication)
14+
- [OAuth Authentication](#oauth-authentication)
15+
- [Data Catalog Support](#data-catalog-support)
16+
- [Available Tables](#available-tables)
1517
- [Example Usage](#example-usage)
18+
- [Basic Connection](#basic-connection)
19+
- [Data Catalog Operations](#data-catalog-operations)
20+
- [Querying Data](#querying-data)
21+
- [Data Manipulation](#data-manipulation)
1622

1723
---
1824

1925
## About HubSpot
2026

21-
HubSpot is a CRM platform with all the software, integrations, and resources you need to connect your marketing, sales, content management, and customer service.
22-
<br>
23-
https://www.hubspot.com/products?hubs_content=www.hubspot.com%2F&hubs_content-cta=All%20Products%20and%20Features
24-
25-
## HubSpot Handler Implementation
26-
27-
This handler was implemented using [hubspot-api-client
28-
](https://github.com/HubSpot/hubspot-api-python), the Python library for the HubSpot API.
29-
30-
## HubSpot Handler Initialization
31-
32-
The HubSpot handler is initialized with the following parameters:
33-
34-
- `access_token`: a HubSpot access token. You can find your access token in the HubSpot Private Apps Page. [Read more](https://developers.hubspot.com/docs/api/private-apps).
35-
36-
## Implemented Features
37-
38-
- [x] HubSpot Companies Table for a given account
39-
- [x] Support SELECT
40-
- [x] Support LIMIT
41-
- [x] Support WHERE
42-
- [x] Support ORDER BY
43-
- [x] Support column selection
44-
- [x] Support INSERT
45-
- [x] Support UPDATE
46-
- [x] Support DELETE
47-
- [x] HubSpot Contacts Table for a given account
48-
- [x] Support SELECT
49-
- [x] Support LIMIT
50-
- [x] Support WHERE
51-
- [x] Support ORDER BY
52-
- [x] Support column selection
53-
- [x] Support INSERT
54-
- [x] Support UPDATE
55-
- [x] Support DELETE
56-
- [x] HubSpot Deals Intents Table for a given account
57-
- [x] Support SELECT
58-
- [x] Support LIMIT
59-
- [x] Support WHERE
60-
- [x] Support ORDER BY
61-
- [x] Support column selection
62-
- [x] Support INSERT
63-
- [x] Support UPDATE
64-
- [x] Support DELETE
65-
66-
## TODO
67-
68-
- [ ] HubSpot Leads table
69-
- [ ] HubSpot Products table
70-
- [ ] Many more
27+
HubSpot is a comprehensive CRM platform providing marketing, sales, content management, and customer service tools. This integration provides secure, enterprise-ready access to HubSpot's CRM data through MindsDB's unified interface.
7128

72-
## Example Usage
29+
**Official Website:** https://www.hubspot.com/products
30+
**API Documentation:** https://developers.hubspot.com/docs/api/overview
7331

74-
The first step is to create a database with the new `hubspot` engine by passing in the required `access_token` parameter:
32+
## Installation
7533

76-
~~~~sql
77-
CREATE DATABASE hubspot_datasource
78-
WITH ENGINE = 'hubspot',
79-
PARAMETERS = {
80-
"access_token": "..."
81-
};
82-
~~~~
34+
Install the handler dependencies using pip:
8335

84-
Use the established connection to query your database:
36+
```bash
37+
pip install -r requirements.txt
38+
```
8539

86-
### Querying the Companies Data
87-
~~~~sql
88-
SELECT * FROM hubspot_datasource.companies
89-
~~~~
40+
**Required Dependencies:**
41+
- `hubspot-api-client==12.0.0` - Official HubSpot Python client
42+
43+
## Authentication
9044

91-
or, for the `contacts` table
92-
~~~~sql
93-
SELECT * FROM hubspot_datasource.contacts
94-
~~~~
45+
The handler supports two authentication methods with enterprise-grade security:
9546

96-
or, for the `deals` table
97-
~~~~sql
98-
SELECT * FROM hubspot_datasource.deals
99-
~~~~
47+
### Access Token Authentication
10048

101-
Run more advanced queries:
49+
Recommended for server-to-server integrations and production environments.
50+
51+
**Steps to obtain access token:**
52+
1. Navigate to your HubSpot account settings
53+
2. Go to Integrations → Private Apps
54+
3. Create a new private app or select existing one
55+
4. Configure required scopes (contacts, companies, deals)
56+
5. Copy the generated access token
57+
58+
**Security Note:** Access tokens provide full API access. Store securely and rotate regularly.
59+
60+
### OAuth Authentication
61+
62+
Recommended for applications requiring user consent and dynamic scope management.
63+
64+
**Required OAuth Parameters:**
65+
- `client_id`: Your app's client identifier
66+
- `client_secret`: Your app's client secret (store securely)
67+
- OAuth flow implementation (handled externally)
68+
69+
**Security Note:** Never expose client secrets in client-side code. Use server-side token exchange.
70+
71+
72+
## Data Catalog Support
73+
74+
The handler provides comprehensive data catalog capabilities:
75+
76+
**Table Metadata:**
77+
- `TABLE_NAME`: Name of the table (companies, contacts, deals)
78+
- `TABLE_TYPE`: Always "BASE TABLE" for HubSpot entities
79+
- `TABLE_SCHEMA`: Schema identifier ("hubspot")
80+
- `TABLE_DESCRIPTION`: Human-readable description of table contents
81+
- `ROW_COUNT`: Estimated number of records (when available)
82+
83+
**Column Metadata:**
84+
- `COLUMN_NAME`: Column identifier
85+
- `DATA_TYPE`: SQL data type (VARCHAR, INTEGER, TIMESTAMP, etc.)
86+
- `IS_NULLABLE`: Whether column accepts NULL values
87+
- `COLUMN_DEFAULT`: Default value (if any)
88+
- `COLUMN_DESCRIPTION`: Column purpose and HubSpot property mapping
10289

103-
~~~~sql
104-
SELECT name, industry
105-
FROM hubspot_datasource.companies
106-
WHERE city = 'bangalore'
107-
ORDER BY name
108-
LIMIT 5
109-
~~~~
110-
111-
~~~~sql
112-
INSERT INTO hubspot_datasource.companies(name)
113-
VALUES('company_name')
114-
~~~~
115-
116-
~~~~sql
117-
UPDATE hubspot_datasource.companies
118-
SET name = 'company_name_updated'
119-
WHERE name = 'company_name'
120-
~~~~
121-
122-
~~~~sql
123-
DELETE FROM hubspot_datasource.companies
124-
WHERE name = 'company_name_updated'
125-
~~~~
126-
127-
~~~~sql
128-
SELECT email, company
129-
FROM hubspot_datasource.contacts
130-
WHERE company = 'company_name'
131-
ORDER BY email
132-
LIMIT 5
133-
~~~~
13490

135-
~~~~sql
136-
INSERT INTO hubspot_datasource.contacts(email)
137-
VALUES('contact_email')
138-
~~~~
91+
## Available Tables
13992

140-
~~~~sql
93+
| Table Name | Description | Key Columns | Primary Operations |
94+
|------------|-------------|-------------|-------------------|
95+
| `companies` | Organization records from HubSpot CRM | id, name, domain, industry | SELECT, INSERT, UPDATE, DELETE |
96+
| `contacts` | Individual contact records | id, email, firstname, lastname | SELECT, INSERT, UPDATE, DELETE |
97+
| `deals` | Sales opportunity records | id, dealname, amount, stage | SELECT, INSERT, UPDATE, DELETE |
98+
99+
## Example Usage
100+
101+
### Basic Connection
102+
103+
**Using Access Token:**
104+
```sql
105+
CREATE DATABASE hubspot_datasource
106+
WITH ENGINE = 'hubspot',
107+
PARAMETERS = {
108+
"access_token": "pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
109+
};
110+
```
111+
112+
**Using OAuth (Advanced):**
113+
```sql
114+
CREATE DATABASE hubspot_datasource
115+
WITH ENGINE = 'hubspot',
116+
PARAMETERS = {
117+
"client_id": "your-client-id",
118+
"client_secret": "your-client-secret"
119+
};
120+
```
121+
122+
### Data Catalog Operations
123+
124+
**List Available Tables:**
125+
```sql
126+
SHOW TABLES FROM hubspot_datasource;
127+
```
128+
129+
**Get Table Schema:**
130+
```sql
131+
DESCRIBE hubspot_datasource.companies;
132+
DESCRIBE hubspot_datasource.contacts;
133+
DESCRIBE hubspot_datasource.deals;
134+
```
135+
136+
**Get Detailed Column Information:**
137+
```sql
138+
SELECT * FROM information_schema.columns
139+
WHERE table_schema = 'hubspot_datasource'
140+
AND table_name = 'companies';
141+
```
142+
143+
### Querying Data
144+
145+
**Basic Data Retrieval:**
146+
```sql
147+
-- Get all companies
148+
SELECT * FROM hubspot_datasource.companies LIMIT 10;
149+
150+
-- Get all contacts
151+
SELECT * FROM hubspot_datasource.contacts LIMIT 10;
152+
153+
-- Get all deals
154+
SELECT * FROM hubspot_datasource.deals LIMIT 10;
155+
```
156+
157+
**Advanced Filtering and Analytics:**
158+
```sql
159+
-- Companies by industry and location
160+
SELECT name, industry, city, state
161+
FROM hubspot_datasource.companies
162+
WHERE industry IN ('Technology', 'Healthcare')
163+
AND city = 'San Francisco'
164+
ORDER BY name;
165+
166+
-- Contact engagement analysis
167+
SELECT
168+
company,
169+
COUNT(*) as contact_count,
170+
STRING_AGG(email, ', ') as emails
171+
FROM hubspot_datasource.contacts
172+
WHERE company IS NOT NULL
173+
GROUP BY company
174+
ORDER BY contact_count DESC;
175+
176+
-- Sales pipeline analysis
177+
SELECT
178+
dealstage,
179+
COUNT(*) as deal_count,
180+
SUM(CAST(amount AS DECIMAL)) as total_value,
181+
AVG(CAST(amount AS DECIMAL)) as avg_deal_size
182+
FROM hubspot_datasource.deals
183+
WHERE amount IS NOT NULL
184+
GROUP BY dealstage
185+
ORDER BY total_value DESC;
186+
```
187+
188+
### Data Manipulation
189+
190+
**Creating Records:**
191+
```sql
192+
-- Create new company
193+
INSERT INTO hubspot_datasource.companies (name, domain, industry, city, state)
194+
VALUES ('Acme Corp', 'acme.com', 'Technology', 'New York', 'NY');
195+
196+
-- Create new contact
197+
INSERT INTO hubspot_datasource.contacts (email, firstname, lastname, company, phone)
198+
VALUES ('john.doe@acme.com', 'John', 'Doe', 'Acme Corp', '+1-555-0123');
199+
200+
-- Create new deal
201+
INSERT INTO hubspot_datasource.deals (dealname, amount, pipeline, dealstage)
202+
VALUES ('Acme Software License', '50000', 'sales', 'qualified-to-buy');
203+
```
204+
205+
**Updating Records:**
206+
```sql
207+
-- Update company information
208+
UPDATE hubspot_datasource.companies
209+
SET industry = 'SaaS', city = 'Austin'
210+
WHERE name = 'Acme Corp';
211+
212+
-- Update contact details
141213
UPDATE hubspot_datasource.contacts
142-
SET email = 'contact_email_updated'
143-
WHERE email = 'contact_email'
144-
~~~~
214+
SET phone = '+1-555-9999', company = 'Acme Corporation'
215+
WHERE email = 'john.doe@acme.com';
145216

146-
~~~~sql
147-
DELETE FROM hubspot_datasource.contacts
148-
WHERE email = 'contact_email_updated'
149-
~~~~
150-
151-
~~~~sql
152-
SELECT dealname, amount
153-
FROM hubspot_datasource.deals
154-
WHERE dealstage = 'deal_stage_name'
155-
ORDER BY dealname
156-
LIMIT 5
157-
~~~~
158-
159-
~~~~sql
160-
INSERT INTO hubspot_datasource.deals(dealname)
161-
VALUES('deal_name')
162-
~~~~
163-
164-
~~~~sql
217+
-- Move deal through pipeline
165218
UPDATE hubspot_datasource.deals
166-
SET dealname = 'deal_name_updated'
167-
WHERE dealname = 'deal_name'
168-
~~~~
169-
170-
~~~~sql
171-
DELETE FROM hubspot_datasource.deals
172-
WHERE dealname = 'deal_name_updated'
173-
~~~~
219+
SET dealstage = 'proposal-made', amount = '75000'
220+
WHERE dealname = 'Acme Software License';
221+
```
222+
223+
**Deleting Records:**
224+
```sql
225+
-- Archive old deals
226+
DELETE FROM hubspot_datasource.deals
227+
WHERE dealstage = 'closed-lost'
228+
AND createdate < '2023-01-01';
229+
230+
-- Remove test contacts
231+
DELETE FROM hubspot_datasource.contacts
232+
WHERE email LIKE '%test%' OR email LIKE '%example%';
233+
```

‎mindsdb/integrations/handlers/hubspot_handler/__about__.py‎

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
__title__ = 'MindsDB Hubspot handler'
2-
__package_name__ = 'mindsdb_hubspot_handler'
3-
__version__ = '0.0.1'
1+
__title__ = "MindsDB Hubspot handler"
2+
__package_name__ = "mindsdb_hubspot_handler"
3+
__version__ = "0.0.1"
44
__description__ = "MindsDB handler for the Hubspot API"
5-
__author__ = 'Shivam Dhaka'
6-
__github__ = 'https://github.com/mindsdb/mindsdb'
7-
__pypi__ = 'https://pypi.org/project/mindsdb/'
8-
__license__ = 'MIT'
9-
__copyright__ = 'Copyright 2023 - mindsdb'
5+
__author__ = "Shivam Dhaka"
6+
__github__ = "https://github.com/mindsdb/mindsdb"
7+
__pypi__ = "https://pypi.org/project/mindsdb/"
8+
__license__ = "MIT"
9+
__copyright__ = "Copyright 2025 - mindsdb"

0 commit comments

Comments
 (0)