Google Sheets Extension

Overview

The Databar Google Sheets Extension brings the power of Databar's enrichment functionality directly into Google Sheets. Run enrichments and waterfalls using custom formulas or the interactive sidebar, with built-in caching, rate limiting, and batch processing capabilities.

Getting Started

Installation

Open your Google Sheet
Go to Extensions > Apps Script
Copy and paste the Databar extension code files
Save and refresh your sheet

Configuration

Setting Up Your API Key

Method 1: Via Menu

Click Databar.ai in the menu bar
Select Configure API Key
Enter your API key from databar.ai
Click OK

Method 2: Via Sidebar

Open Databar.ai > Open Sidebar
Click Configure API Key button
Enter your API key
The sidebar will update to show "Connected to Databar.ai"

Managing Your API Key

Edit Key: Click the Edit key button in the sidebar
Remove Key: In the edit dialog, choose Remove Key
Test Connection: Databar.ai menu > Test Connection

Using the Sidebar

The sidebar is your command center for generating formulas and managing enrichments.

Opening the Sidebar

Databar.ai menu > Open Sidebar

Main Interface

The sidebar features:

API Key Status - Shows connection status
Enrichment search - Browse and configure enrichments
Quick Actions - Jobs, Help, and Settings
Direct Link - Databar logo links to your tables

Enrichment search

Browsing Enrichments

Open the sidebar
Browse the list of available enrichments and waterfalls
Use the search bar to filter by name or description
Waterfalls appear first in the list

Enrichment Cards Show:

Name and description
ID or identifier
Price (single value or range for waterfalls)
Data source

Configuring an Enrichment

All enrichments work through formulas.

Click an enrichment card
Configure Inputs - Fill in required parameters
- Type cell references (e.g., A2) for dynamic data
- Type static values for fixed data
- Required fields marked with *
Select Output Format
- Single cell (JSON) - Returns JSON in one cell
- Multiple cells (expanded) - Headers + values in separate cells
Select Fields (for expanded format only)
- Choose which fields to include
- Use "Select All" to toggle all fields
Copy Formula - Click the button to copy to clipboard

Configuring a Waterfall

Waterfalls have an additional step:

Select Providers

Check which providers to use in the waterfall
Reorder providers using ▲ ▼ arrows
- First provider is tried first
- Order matters for cost optimization
Uncheck providers to exclude them
- Unchecked providers move to the bottom automatically

Enrichment functions

Use these functions directly in your spreadsheet cells.

DATABAR_ENRICH

Run a single enrichment and return JSON.

Syntax:

=DATABAR_ENRICH(enrichmentId, paramName1, paramValue1, [paramName2, paramValue2, ...], ["BYPASS_CACHE"])

Parameters:

enrichmentId - The enrichment ID (e.g., 10)
paramName - Parameter name (e.g., "email")
paramValue - Cell reference or value (e.g., A2 or "[email protected]")
BYPASS_CACHE - Optional: Force fresh API call, ignore cache

Examples:

Basic enrichment:

=DATABAR_ENRICH(10, "email", A2)

Multiple parameters:

=DATABAR_ENRICH(6, "email", A2, "domain", B2)

Bypass cache:

=DATABAR_ENRICH(10, "email", A2, "BYPASS_CACHE")

Returns: JSON object with enrichment results

Usage Tips:

Use DATABAR_JSON_EXTRACT to extract specific fields
Results are cached for 24 hours
Empty parameters show as {{param_REF}} placeholders

DATABAR_ENRICH_EXPAND

Run an enrichment and expand results into multiple cells.

Syntax:

=DATABAR_ENRICH_EXPAND(enrichmentId, paramName1, paramValue1, [...], ["field1,field2"], ["BYPASS_CACHE"])

Parameters:

Same as DATABAR_ENRICH
fields - Optional: Comma-separated list of fields to return (e.g., "status,score,domain")
If no fields specified, all fields are returned

Examples:

All fields:

=DATABAR_ENRICH_EXPAND(10, "email", A2)

Specific fields:

=DATABAR_ENRICH_EXPAND(10, "email", A2, "status,score,domain")

Returns:

Row 1: Field names (headers)
Row 2: Field values

Usage Tips:

Perfect for creating structured data tables
Automatically expands to fill multiple columns
Use field filtering to show only what you need

DATABAR_WATERFALL

Run a waterfall enrichment and return concatenated results.

Syntax:

=DATABAR_WATERFALL(waterfallId, paramName1, paramValue1, [...], "enrichmentIds", ["BYPASS_CACHE"])

Parameters:

waterfallId - Waterfall identifier (e.g., "email_getter")
paramName / paramValue - Parameters for the waterfall
enrichmentIds - Required: Comma-separated provider IDs (e.g., "87,380,612")
BYPASS_CACHE - Optional: Force fresh execution

Examples:

Email waterfall:

=DATABAR_WATERFALL("email_getter", "first_name", A2, "last_name", B2, "company", C2, "612,833,87")

With cache bypass:

=DATABAR_WATERFALL("email_getter", "first_name", A2, "last_name", B2, "company", C2, "612,833", "BYPASS_CACHE")

Returns:

Cell 1 (where formula is): Concatenated result values (e.g., "[email protected]")
Cell 2 (next cell right): Full JSON with enrichment_data, result, and steps

Usage Tips:

Order providers by cost (cheapest first) to minimize spending
First successful provider stops the waterfall
Use the full JSON to see which provider succeeded and the cost
Use DATABAR_JSON_EXTRACT on the second cell to extract details

Example with JSON Extract:

Get the email from the waterfall:

=DATABAR_JSON_EXTRACT(B2, "result.email")

See which provider succeeded:

=DATABAR_JSON_EXTRACT(B2, "steps[0].provider")

Check the cost:

=DATABAR_JSON_EXTRACT(B2, "steps[0].cost")

DATABAR_WATERFALL_EXPAND

Run a waterfall and expand results into multiple cells.

Syntax:

=DATABAR_WATERFALL_EXPAND(waterfallId, paramName1, paramValue1, [...], "enrichmentIds", ["fields"], ["BYPASS_CACHE"])

Parameters:

Same as DATABAR_WATERFALL
fields - Optional: Filter to specific output fields

Returns:

Row 1: Field names
Row 2: Field values
Includes all fields from the waterfall result

DATABAR_JSON_EXTRACT

Extract specific values from JSON results.

Syntax:

=DATABAR_JSON_EXTRACT(jsonCell, path)

Parameters:

jsonCell - Cell containing JSON (from DATABAR_ENRICH or DATABAR_WATERFALL)
path - Path to value using dot notation and array indices

Path Syntax:

Simple field: "status"
Nested field: "user.name"
Array index: "items[0]"
Complex: "data.users[0].email"

Examples:

Extract email:

=DATABAR_JSON_EXTRACT(A2, "result.email")

Get first step action:

=DATABAR_JSON_EXTRACT(A2, "steps[0].action")

Extract nested data:

=DATABAR_JSON_EXTRACT(A2, "enrichment_data.Hunter.io API.email")

Returns: The extracted value, or ERROR: Path not found if path doesn't exist

DATABAR_STATUS

Check the status of a long-running enrichment.

Syntax:

=DATABAR_STATUS(taskId)

Parameters:

taskId - The task ID from a PROCESSING message

Example:

=DATABAR_STATUS("abc123-def456-ghi789")

Returns: Current status and result if completed

Batch Enrichment Tool

For processing large datasets without formulas.

When to Use Batch Tool

Processing 100+ rows
One-time enrichments
Want static values (no recalculation)
Maximum credit safety

How to Use

Select Input Data
- Highlight a column (e.g., A2:A1000)
Open Batch Tool
- Databar.ai menu > Tools > Batch Enrich (Static Values)
Configure
- Step 1: Enter enrichment ID
- Step 2: Enter parameter name (e.g., "email")
- Step 3: Review estimated cost
Confirm & Run
- Wait for progress updates (every 10 rows)
- Results written to next column as static values
Review Results
- Success/error summary displayed
- Static values never recalculate

Batch Tool Benefits

✅ Static values (never re-run) ✅ Progress tracking ✅ Cost estimation ✅ Error handling per row ✅ No accidental credit burn

Understanding Results

Regular Enrichment Results

JSON Format:

{
  "status": "valid",
  "score": 95,
  "domain": "example.com",
  "mx_record": "mail.example.com"
}

Expanded Format:

status

score

domain

mx_record

valid

example.com

mail.example.com

Waterfall Results

Cell 1 (Concatenated):

[email protected]

Cell 2 (Full JSON):

{
  "enrichment_data": {
    "Hunter.io API": {
      "email": "[email protected]",
      "score": 95,
      "verification_status": "valid"
    }
  },
  "result": {
    "email": "[email protected]"
  },
  "steps": [
    {
      "action": "Tried Hunter.io API",
      "provider": "Hunter.io API",
      "result": "completed",
      "cost": "6.00",
      "provider_logo": "/media/external_source_logo/Hunter.io.png"
    }
  ],
  "result_field": ["email"]
}

What Each Field Means:

enrichment_data - Full data from the successful provider
result - Final extracted values (what you asked for)
steps - Details about each provider tried
- action - What was attempted
- provider - Which provider was used
- result - Outcome (completed/failed)
- cost - Credits used
result_field - Which fields were extracted

No Data Response

When enrichment returns no data:

Regular enrichments: "No data"
Waterfalls: Cell 1: "No data", Cell 2: Full JSON (shows why)

Jobs Panel

Track your enrichment executions:

Click the clipboard icon in the header
View recent jobs with:
- Enrichment name
- Status (completed, processing, failed)
- Timestamp
Click Refresh to update status
Click X to close

Caching System

How Caching Works

Results are automatically cached for 24 hours at three levels:

User Cache - Your personal cache
Document Cache - Shared with all collaborators
Script Cache - Backup cache

Benefits:

✅ No duplicate API calls
✅ Instant results for repeated queries
✅ Shared cache across team members
✅ 80-90% reduction in API costs

Cache Behavior

Cache Hits:

Same input = cached result (no API call)
Different user on same sheet = cached result
Sheet reload = cached result

Cache Miss:

New input values
After 24 hours
BYPASS_CACHE parameter used

Bypassing Cache

Per Formula:

=DATABAR_ENRICH(10, "email", A2, "BYPASS_CACHE")

When to Bypass:

Testing different providers
Data has changed at source
Need fresh verification

Rate Limiting

The extension automatically manages API rate limits:

20 concurrent requests maximum
300 requests per minute maximum
Automatic queuing when limits reached
30-second timeout for queued requests

What This Means:

Large batches are automatically throttled
No server overload
Fair usage across all users
Some requests may wait briefly during high volume

Credit Management

Checking Your Credits

Via Menu:

Databar.ai menu > Check Credits
View:
- Current balance
- Plan name
- Account email

Via Button:

Click Buy More Credits to visit pricing page

Estimated Costs

Regular Enrichments:

Cost shown in enrichment card
Example: "6 cr." per enrichment

Waterfalls:

Price range shown (e.g., "4-22 cr.")
Actual cost depends on which provider succeeds
First successful provider determines final cost

Cost Optimization Tips:

Order waterfall providers cheapest-first
Use caching (saves 80-90% of API calls)
Test with small samples first
Use BYPASS_CACHE sparingly

Common Workflows

Workflow 1: Verify Email List

Goal: Verify 500 emails

Steps:

Put emails in column A (A2:A501)
In B2: =DATABAR_ENRICH(10, "email", A2)
Drag down to B501
Extract status: In C2: =DATABAR_JSON_EXTRACT(B2, "status")
Drag down to C501

Result:

Column B: Full verification data (JSON)
Column C: Simple valid/invalid status
Cached for 24 hours (no re-runs)

Workflow 2: Find Emails with Waterfall

Goal: Find emails for 100 contacts

Steps:

Put first names in column A
Put last names in column B
Put companies in column C
In D2: =DATABAR_WATERFALL("email_getter", "first_name", A2, "last_name", B2, "company", C2, "612,833,87,380")
Drag down to D101

Result:

Column D: Found emails (concatenated)
Column E: Full waterfall data (JSON)
See which provider found each email in column E

Cost Analysis:

=DATABAR_JSON_EXTRACT(E2, "steps[0].cost")

Workflow 3: Enrich Company Data

Goal: Get company info for 200 domains

Steps:

Put domains in column A (A2:A201)
In B2: =DATABAR_ENRICH_EXPAND(5, "domain", A2, "name,industry,employees,revenue")
Drag down to B201

Result:

Columns B-E: name, industry, employees, revenue
Structured data ready for analysis
Headers automatically added

Workflow 4: Batch Processing Large Dataset

Goal: Process 5,000 contacts (one-time)

Steps:

Select column with input data (A2:A5001)
Databar.ai menu > Tools > Batch Enrich (Static Values)
Enter enrichment ID
Enter parameter name
Review cost estimate: ~30,000 credits
Confirm and wait (~15-20 minutes)
Static results in next column

Benefits:

No formulas (faster sheet)
Never recalculates
Progress updates every 10 rows
Error handling per row

Troubleshooting

Error: "API key not configured"

Solution:

Databar.ai menu > Configure API Key
Enter your API key from databar.ai
Test with Databar.ai menu > Test Connection

Error: "Invalid cell reference (#REF!)"

Causes:

Deleted a row/column referenced in formula
Cell reference is broken

Solution:

Check the formula cell references
Update to valid cell references
Re-enter the formula

Error: "Cannot pass a range/array as parameter"

Cause: Passing multiple cells (e.g., A2:A10) instead of single cell

Solution:

❌ Wrong: =DATABAR_ENRICH(10, "email", A2:A10)
✅ Right: =DATABAR_ENRICH(10, "email", A2)

Then drag the formula down to apply to each row.

Error: "Parameter cannot be empty"

Cause: Required parameter cell is blank

Solution:

Fill in the required input cells
Or use a static value in the formula:

=DATABAR_ENRICH(10, "email", "[email protected]")

Formula shows: "PROCESSING (Task: xxx)"

Cause: Enrichment taking longer than 30 seconds

Solution:

Wait a moment and the formula will auto-update (if cache refreshes)
OR use: =DATABAR_STATUS("task-id-from-message")
OR check Jobs panel in sidebar

"No data" result

Cause: Enrichment couldn't find data for the input

Possible reasons:

Invalid input (e.g., fake email)
Data not available from provider
All waterfall providers failed

Solution:

Verify input is correct
For waterfalls: Check the full JSON to see why each provider failed
Try different providers or enrichments

Results not updating after changing input

Cause: Formulas reference cached results

Solution: Use BYPASS_CACHE to force refresh:

=DATABAR_ENRICH(10, "email", A2, "BYPASS_CACHE")

Note: Remove BYPASS_CACHE after testing to avoid wasting credits.

Sheet is slow with many formulas

Causes:

500+ formulas in one sheet
Complex formulas or large JSON results

Solutions:

Use Batch Tool instead - No formulas, static values
Convert to values:
- Copy cells with formulas
- Paste as "Values only"
- Removes formulas, keeps data
Split across multiple sheets

"Rate limit exceeded" error

Cause: Too many requests too quickly

Solution:

Wait 30-60 seconds
Requests are automatically queued
For large batches, use Batch Tool (handles queuing automatically)

Best Practices

1. Start Small

Test with 5-10 rows first
Verify results before scaling up
Check costs with small samples

2. Use Caching Wisely

Let cache work (24 hours)
Only use BYPASS_CACHE when needed
Share sheets to leverage document cache

3. Optimize Waterfall Order

Put cheapest providers first
Remove expensive providers you don't need
Monitor which providers succeed most often

4. Structure Your Data

Use DATABAR_ENRICH_EXPAND for structured tables
Use DATABAR_JSON_EXTRACT to pull specific fields
Keep raw JSON in hidden columns for reference

5. Batch Large Operations

Use Batch Tool for 100+ rows
Avoids formula overhead
Faster sheet performance

6. Monitor Credits

Check balance regularly (Databar.ai menu > Check Credits)
Set up credit alerts on databar.ai
Review waterfall costs in full JSON

7. Document Your Formulas

Add notes explaining complex formulas
Document which enrichments you use
Keep a reference sheet with common patterns

Keyboard Shortcuts

Action

Shortcut

Open menu

Click Databar.ai in menu bar

Copy formula

Ctrl/Cmd + C in formula generator

Refresh sheet

Ctrl/Cmd + R

Recalculate formulas

Ctrl/Cmd + Shift + F9

Advanced Tips

Custom Function Combinations

Progressive Enrichment:

// Column A: Emails
// Column B: Verify emails
=DATABAR_ENRICH(10, "email", A2)

// Column C: Only enrich valid emails
=IF(DATABAR_JSON_EXTRACT(B2, "status")="valid", 
    DATABAR_ENRICH(20, "email", A2), 
    "Skipped")

Waterfall with Fallback:

// Try waterfall first
=IF(DATABAR_WATERFALL("email_getter", "first_name", A2, "last_name", B2, "company", C2, "612,833")="No data",
    "Not found",
    DATABAR_WATERFALL("email_getter", "first_name", A2, "last_name", B2, "company", C2, "612,833"))

Extract Multiple Fields at Once

// Instead of multiple DATABAR_JSON_EXTRACT calls:
=DATABAR_ENRICH_EXPAND(10, "email", A2, "status,score,domain")

// Then reference the expanded cells normally

Conditional Enrichment

// Only enrich if email is present
=IF(A2<>"", DATABAR_ENRICH(10, "email", A2), "No email")

FAQs

Q: How long are results cached? A: 24 hours across three cache levels.

Q: Can multiple users share cache? A: Yes, document cache is shared across all users of the same sheet.

Q: What happens if I run out of credits? A: API will return error. Add more credits at databar.ai/pricing.

Q: Can I use this in Google Apps Script? A: Yes, call functions like runEnrichment(enrichmentId, params) directly.

Q: How do I see my recent jobs? A: Open sidebar and click the clipboard icon (Jobs panel).

Q: Can I undo an enrichment? A: Yes, use Ctrl/Cmd + Z or delete the cells. Credits are not refunded.

Q: Does this work offline? A: No, requires internet connection to call Databar API.

Q: Can I use this on mobile? A: Yes, Google Sheets mobile app supports custom functions. Sidebar requires desktop.

Q: How do I report bugs? A: Contact [email protected] or use the help panel in the sidebar.

Support

Need Help?

📧 Email: [email protected]
📖 Docs: docs.databar.ai
💬 In-app: Click ? icon in sidebar

Feature Requests: Share your ideas at [email protected]

API Documentation: Visit api.databar.ai for full API reference.

Version History

Current Version: 1.0.0

Features:

✅ Regular enrichments with JSON and expanded output
✅ Waterfall enrichments with provider selection
✅ 24-hour multi-level caching
✅ Batch processing tool
✅ Rate limiting and queuing
✅ JSON extraction helper
✅ Interactive sidebar with formula generator
✅ Jobs tracking and management
✅ Credit balance checking
✅ Comprehensive error handling

Last updated: November 2024

PreviousNavigating the catalog

Last updated 0 minutes ago

Was this helpful?