Data Models & Queries

View as Markdown
Last updated November 5, 2026

Cloud Connect Data Models

Cloud Connect uses a Data Model to link, or "connect," a user's external data warehouse to Lytics profiles. Each Data Model represents a set of records defined by a SQL query. Each Data Model also configures a join key that defines how the Data Model is joined to Lytics profiles.

After you create a Connection to your data warehouse, you can create Data Models from Data Pipeline > Cloud Connect > Data Models in the navigation bar:

Click to enlarge

Creating a Data Model

Click + Create New from the Data Models dashboard and complete the following steps.

  1. Select the Connection.

  2. Generate the SQL query. Currently, the main identifier must be of type string in the database.
    Click to enlarge
    Query Editor: Write and test standard SQL queries directly in Lytics. Alternatively, copy and paste queries you've tested in your BigQuery or Snowflake instance. When you click Test Query, Lytics returns 10 sample records.


  3. Test the query and validate the results.

Click to enlarge

  1. Configure the Data Model.

    Click to enlarge


    Name: Data Model name
    Slug: The Data Model name used in the membership and mapped field names in the audience builder. Choose a name that makes sense to the people who build audiences in the tool. If you don't enter a slug, it auto-populates from the model name.
    Description: A longer description of the Data Model.

    Map a Unique Identifier: Select a user profile field that is a unique identifier in the Lytics user table to map to an identifier in your incoming data source.

    Click to enlarge


Primary Key: Select a key in your data source — the column from your SQL query results that uniquely identifies each record.
External Lytics Key: Select a Lytics user profile field that corresponds to your primary key. Only identity ("by") fields are available for selection.

Activated Fields: Select source fields to activate. Lytics automatically creates the corresponding schema fields, populated by this Data Model. The available options come from the columns returned by your SQL query.

Field Mappings: Map source fields to Lytics fields. For each mapping, use the dropdowns to select a Source column from your SQL query results and a Lytics profile field where the data should be stored. You can add multiple mappings to bring in as many fields as needed.

Mapping constraints

  • Lytics target fields must already exist in your published schema.
  • You cannot map to Lytics identity ("by") fields.
  • Each Lytics field can appear only once in your mappings.

A warehouse JSON or OBJECT column (for example, a BigQuery JSON column or a Snowflake OBJECT/VARIANT) can be imported into a map-typed Lytics field, so a key-value structure in your warehouse lands as a proper map on the profile. The map[string]value and map[string]intsum types are not supported as destinations for this import.

Editing Field Mappings requires schema management permissions. If your role doesn't have them, the Field Mappings section is shown but disabled, with the message "Schema management permissions are required to edit field mappings." Activated Fields and the rest of the configuration remain editable.

Create Profiles: When checked, Lytics creates new profiles for all rows in the result set that don't already match an existing profile. When unchecked, Lytics updates only existing profiles with matching identifiers.

Sync Settings: Select how often the sync should run.

  • Hourly — runs every hour
  • Daily — runs once per day at the specified time
  • Weekly — runs once per week on the specified day and time
  • Monthly — runs once per month at the specified time

Depending on the frequency selected, additional options may appear for time of day, timezone, and day of week.

  1. Create the Data Model. After you add all the details, click Create Data Model in the top-right corner to save the configured Data Model.

Click to enlarge

  1. Activate the Data Model. In the Data Model list view, open the model you created and click Activate. Until you activate the Data Model, Lytics doesn't run its SQL query against your data warehouse or update Lytics profiles with the selected fields.

Click to enlarge

When building multiple Cloud Connect Data Models with the same primary key, you must select the same External Lytics Key mapping. Selecting a different Lytics key results in an error when you try to save the new Data Model.

Example Use Case

This scenario shows why you'd want to create an audience driven by a Cloud Connect Data Model instead of a standard Lytics audience. Your company sells e-bikes and wants to run a holiday campaign that sends a promotion to any customer who purchased an e-bike in November or December last year. Perhaps you also want to refine your audience to those who are interested in particular bike brands. All of this purchase and product data already exists in your Google BigQuery instance.

Instead of importing all that purchase history data into Lytics, you can write a SQL query to find which customers meet these audience criteria. When you copy this query into the Lytics Model Builder, you create a new audience in Lytics that updates at the frequency you choose.

Once the Data Model is activated, Lytics adds the Data Model's slug to the Datamodels field on each matching user profile, and any configured field mappings sync the corresponding data from your warehouse into the mapped Lytics profile fields. You can use the Datamodels field in the Audience Builder to target members of the Data Model, and the mapped fields for more dynamic audience rules.

Click to enlarge

SQL Translator

To skip writing a SQL query, describe the data you want the Data Model to fetch, and Lytics uses GenAI to translate the description into a SQL query for you. When creating the query, Lytics queries your database to ensure that the data is up to date and accurate.