Skip to main content

Configuration Walkthrough: Account Model

This page walks through the FunnelStory UI step by step to configure the Account model. If you haven't set up a data connection yet, start with Prerequisites.

Opening the Account Model Configuration​

  1. In the left sidebar, click Configuration.
  2. Select Data Models from the dropdown.
  3. Click the Account model card.
  4. If this is your first time, click on the "+ New Data Model" button and select Account Model.

This opens the model configuration flow, which has three steps: Connect Data, Write Query, and Map Information.

Step 1: Connect Data​

In this step you select which data connection to use for the Account model.

Fields to fill in:​

  • Model Name: Give your model a descriptive name (e.g., "Accounts", "Customer Accounts", "Salesforce Accounts"). This is for your reference only.
  • Description (optional): Brief note about what this model pulls and from where.
  • Connection Type: Select the category of your data source. Options include databases (PostgreSQL, Snowflake, BigQuery, etc.), CRMs (Salesforce, HubSpot), and other integrations.
  • Connection: Select the specific connection you created in the prerequisites step.
  • Refresh Interval: Choose how often FunnelStory should re-pull data. Hourly for frequently changing data, daily for stable data.

Click Continue to proceed to the query step.

Step 2: Write Query​

This is where you tell FunnelStory exactly what data to pull from your data source.

The query editor​

The editor accepts different query formats depending on your connection type:

  • SQL databases and warehouses: Write standard SQL (PostgreSQL, MySQL, Snowflake, BigQuery, etc.)
  • Salesforce: Write SOQL block queries (special syntax with -- SOQL_START / -- SOQL_END markers)
  • HubSpot: Write HubSpot block queries (special syntax with -- HS_START / -- HS_END markers)

See Writing Queries for the full format reference for each data source type.

Required fields​

The editor displays a badge showing which fields your query should return. For the Account model, the expected fields are:

  • account_id (required -- the unique key)
  • name
  • domain
  • created_at

Your query column names don't have to match these exactly -- you'll map them in the next step. But your query must return data that can be mapped to at least account_id.

Validating the query​

Click Validate (or press Ctrl+Enter / Cmd+Enter) to test your query against the live data source. Validation will:

  • Execute the query (with a row limit for preview)
  • Report any syntax errors or connection issues
  • Show you a preview of the returned columns and data

A green "Query validated successfully" message means you're ready to proceed. If you see an error, fix the query and validate again.

Click Continue to proceed to field mapping.

Step 3: Map Information​

This step connects the columns from your query output to FunnelStory's account properties.

How mapping works​

Each row in the mapping table has:

  • Property (left side): The FunnelStory account property (e.g., account_id, name, domain, created_at)
  • Column (right side): A dropdown of columns from your query output. Select which column maps to each property.

The default properties (account_id, name, domain, created_at) are pre-populated. You must map at least account_id for the model to be valid.

Adding custom properties​

Click Add another field here at the bottom to map additional columns as custom account properties. Common additions include:

  • amount -- for ARR / contract value
  • expires_at -- for contract renewal date
  • parent_account_id -- for parent-child hierarchy
  • is_churned -- for churn status
  • csm_email / csm_name -- for auto-assigning accounts to CSMs

See Field Reference for the complete list of recognized properties and their expected data types.

Viewing query results​

Click Run Test to see the actual data your query returned. This helps verify you're mapping the right columns.

Saving the Model​

After mapping is complete, click Save Model. A dialog appears asking for:

  • Model Name: Confirm or update the name
  • Description: Optional
  • Activate Model?: Choose whether to save as Active (data will start refreshing immediately) or Draft (saved but not running)

If you're still iterating on the query or mappings, save as Draft and activate later. If you're confident in the configuration, save as Active.

Refreshing and Verifying​

After saving an active model:

  1. Click Refresh Model on the model card to trigger an immediate data pull.
  2. Navigate to the Accounts View (in the left sidebar) to confirm accounts are populating.
  3. Spot-check a few accounts to verify that names, domains, ARR values, and other properties look correct.

See Verification & Troubleshooting for detailed verification steps and common issues.

Next Steps​