RudderStack Docs – Data Graph

Audiences: How to Create a Data Graph using Visual Builder

Mon, 01 Jan 0001 00:00:00 +0000

This guide lists the steps to create a Data Graph in the RudderStack dashboard using the visual builder.

To create a data graph as YAML using Rudder CLI, see the Data Graph YAML reference.

Overview

Creating a data graph in RudderStack via the visual builder involves:

Connecting a warehouse account — this acts as the source for the data graph
Defining entity models, and event models
Configuring relationships between the entities and events

Video walkthrough

Prerequisites

Your data graph is built on top of your warehouse data. Hence, you need a connected warehouse account before you can start building your data graph.

The steps to configure a warehouse connection are as follows:

Before configuring the warehouse credentials, you need to grant certain permissions on your BigQuery warehouse for RudderStack to access data from it.

Create a role and grant permissions in your GCP project.
Create a service account and attach the role to it.
Create and download the JSON key for the service account.
Create the RudderStack schema and grant permissions to the service account.

Then, configure the warehouse credentials:

Setting	Description
Name	Assign a name for the warehouse account.
Credentials	Add the contents of the GCP service account credentials JSON downloaded above.
Project ID	Specify your GCP project ID where your BigQuery database is located.
Service Account	Specify your GCP service account.

For more details on the above settings, see the BigQuery documentation.

Before configuring the warehouse credentials, you must grant certain permissions in your Databricks instance for RudderStack to access data from it.

Add a new user by following the steps in the Databricks documentation.
Create RudderStack schema and grant permissions to the user.

Then, configure the warehouse credentials:

Setting	Description
Name	Assign a name for the warehouse account.
Host	Enter the server hostname of your Databricks cluster or SQL warehouse.
Port	Enter the associated port number for the Databricks cluster or SQL warehouse.
Path	Enter the associated HTTP path.
Authentication Type	Select the authentication mechanism from the dropdown. RudderStack supports M2M OAuth and Personal Access Token.
Client ID	If authentication is set to M2M OAuth, enter the client ID for the service principal.
Client Secret	If authentication is set to M2M OAuth, enter the corresponding client secret.
Token	If authentication is set to Personal Access Token, enter your Databricks access token.
Catalog	Enter the name of your Unity catalog.

For more details on the above settings, see the Databricks documentation.

Before configuring the warehouse credentials, you must grant certain permissions on your Redshift warehouse for RudderStack to access data from it.

Create a new user in Redshift.
Create RudderStack schema and grant permissions to the user.
Grant user the required permissions on your schema and table.

Then, configure the warehouse credentials:

Setting	Description
Name	Assign a name for the warehouse account.
Host	Enter the host name of your Redshift service.
Port	Enter the port number associated with the Redshift database instance.
Database	Enter the database name of your Redshift instance from where RudderStack ingests the data.
User	Enter the name of the Redshift user created while granting permissions.
Authentication Type	Select the authentication mechanism from the dropdown. RudderStack supports IAM (recommended) and Username Password Authentication.
IAM Role ARN	If authentication is set to IAM, enter the ARN of the IAM role you created while granting permissions.
Cluster Identifier	If authentication is set to IAM, enter your AWS cluster ID.
Cluster Region	If authentication is set to IAM, enter your AWS cluster region.
Password	If authentication is set to Username Password Authentication, enter the password for the user specified in the User field.
SSL Mode	Select the SSL mode as Disable or Require depending on how RudderStack should connect to your Redshift instance.

For more details on the above settings, see the Amazon Redshift documentation.

Before configuring the warehouse credentials, you must grant certain permissions on your Snowflake warehouse for RudderStack to access data from it.

You must have the ACCOUNTADMIN role to grant these permissions.

Create a new role and user in Snowflake.
Create RudderStack schema and grant permissions to the role.
Grant permissions on your warehouse, database, schema, and table.

Then, configure the warehouse credentials:

Setting	Description
Name	Assign a name for the warehouse account.
Authentication Type	Select the user authentication mechanism from the dropdown. RudderStack supports Username Password Authentication and Key Pair Authentication.
Account	Specify the warehouse account ID that is a part of your Snowflake URL, for example, qya56091.us-east-1
Database	Enter the name of the database in which your data resides.
Warehouse	Specify the name of your data warehouse.
User	Enter the name of the user that has the required read/write access to the above database.
Role	Specify the role you want to assign to the above user. For syncing the data, you can use this role apart from the default role (`RUDDER_ROLE`) you created above.
Password	If authentication is set to Username Password Authentication, enter the password for the user specified in the User field.
Private Key	If authentication is set to Key Pair Authentication, enter the generated private key and make sure to include the delimiters.
Private Key Passphrase	If your private key is encrypted, specify the password you set while encrypting the private key. Note: The user authentication will fail if your private key is encrypted and you do not specify the passphrase.

For more details on the above settings, see the Snowflake documentation.

1: Connect the warehouse account

Navigate to Activate > Data Graph in the RudderStack dashboard.
In the Connect warehouse section, select the warehouse connection from the list of available connections. If there is no warehouse connection available, click Add account to create a new connection.

Note that:

To create a data graph, your RudderStack workspace must have at least one warehouse connection configured.

You can only connect one warehouse account to a data graph.

RudderStack supports the following warehouses currently:

Snowflake

BigQuery

Redshift

Databricks

Click Connect to connect the warehouse account to the data graph.

At this point, the data graph base definition (warehouse connection context) is established. You can now start defining the entities and events for the data graph.

2: Create an entity model

In the Add component section, select Entity model.

Choose the relevant Database, Schema, Table for the entity model.
Select the relevant Primary key from the dropdown.
To set the entity model as a root model, select Yes from the dropdown. Then, click Next.

Provide a name and description for the entity model.
Click Create to save the model.

You can now continue by adding more models to the data graph.

3: Create an event model

In the top right corner, click Add component and select Event.

Select the relevant Database and Schema for the event model.

If you configured a root model in the previous step, the Database and Schema fields will be pre-populated with the relevant values.

In the Table field, select a relevant table from the dropdown that contains timestamp information.
Select the relevant timestamp from the dropdown — this field defines the dimension of this event model. Then, click Next.

Provide a name and description for the event model.
Click Create to save the model.

You now have two models on the canvas of your data graph — an entity model and an event model.

4: Create relationships between models

There are two ways to create relationships between models:

By clicking on the model and selecting Add relationship from the sidebar
Using the drag-and-drop method

By clicking on the model

Click on the model from which you want to start the relationship.

Click Add relationship under Relationships.

In the relationship configuration view, select one of the existing models — you can also create a new model. Then, click Next.

Provide a name for the relationship.
Define the cardinality of the relationship. For example, as one customer can have many purchases, the cardinality should be 1:many.
Define the Join keys used to define the join condition and relate the two tables.

Click Create to save the relationship.

Using the drag-and-drop method

The drag and drop method is an alternate way of creating relationships between models. In this method, you visually connect one model with another on the canvas — a configuration pane opens where you can define the relationship details.

Suppose you have another entity model, Accounts, and you want to create a relationship between the entity model Customers (created previously) and this model.

Click the + sign that appears on the right side of the Customers model.
Drag the relationship line to the left of the Accounts model and drop it on the canvas.
In the configuration pane, define the relationship details and the cardinality, for example, many:1, indicating that an account can have many customers.

Define the Join keys used to join the models, for example, Account Key.
Click Create to save the relationship.
Use the Auto Layout functionality (described in Step 4) to reorganize the graph.

You can continue expanding your data graph with more entity and event models, and building relevant relationships between them.

Organize the layout

Once the data graph is created, the models may appear scattered on the canvas. Use the Auto Layout option on the bottom left of the canvas to organize the graph.

Audiences: Data Graph YAML Reference

Mon, 01 Jan 0001 00:00:00 +0000

This reference documents the YAML schema for defining a Data Graph with the Rudder CLI. Use it alongside the CLI to author, version-control, and sync data graph definitions as code.

File structure

A data graph YAML file has the following top-level structure:

version: "rudder/v1"
kind: "data-graph"
metadata:
 name: "ecommerce-data-graph"
spec:
 id: "ecommerce-data-graph"
 account_id: "<warehouse-account-id>"
 models:
 - ...

Top-level fields

Field	Type	Description
`version` Required	String	Schema version. Use `rudder/v1`.
`kind` Required	String	Resource kind. Must be `data-graph`.
`metadata.name` Required	String	Human-readable name for the data graph
`spec.id` Required	String	Unique ID for the data graph. Used as its stable identifier across syncs.
`spec.account_id` Required	String	The ID of the warehouse account the data graph reads from.
`spec.models` Required	List	List of entity and event models that make up the data graph. See Models for more information.

Models

The spec.models list contains all the entities and events the data graph exposes to the Audience Builder. Each model points at a warehouse table and optionally declares relationships to other models.

Model fields

Field	Type	Description
`id` Required	String	Unique ID for the model within this data graph. Used as the target of relationships (see Relationships).
`display_name` Required	String	Name shown in the Audience Builder UI (for example, `Customers`, `Sales`).
`type` Required	String	Either `entity` (dimension-style table) or `event` (timestamped fact table).
`table` Required	String	Fully qualified warehouse table name, for example, `ECOMMERCE_DB.E_MART.DIM_CUSTOMERS`.
`description`	String	Human-readable description of the model. Shown as a tooltip in the builder.
`primary_id` Required	String	Column that uniquely identifies a row in the table. Required for entities; Optional for events.
`timestamp` Required	String	Column holding the event timestamp. Required when `type: event`. Used for time-window filtering in the Audience Builder. Optional for entities.
`relationships` Optional	List	List of relationships this model has to other models. See Relationships for more information.

Entity vs. event

Entity: A dimension-like table representing a business object (Customers, Products, Stores). Use type: entity and set primary_id.
Event: A fact-like table where each row represents something that happened at a point in time (Sales, Customer Interactions, Loyalty Points). Use type: event and set timestamp. Events can be filtered with a time window in the Audience Builder.

Relationships

Relationships connect two models so marketers can filter one model using conditions on related records (for example, “customers with 3 or more orders”). Relationships are declared on the source model under its relationships list.

Relationship fields

Field	Type	Description
`id` Required	String	Unique ID for the relationship within the source model.
`display_name` Required	String	Name shown in the Audience Builder UI (for example, `Has Sales`, `Belongs To Account`).
`cardinality` Required	String	One of `one-to-many`, `many-to-one`, or `one-to-one`. See Current limitations.
`target` Required	String	Reference to the target model in the form `#data-graph-model:<model-id>`.
`source_join_key` Required	String	Column on the source model used in the join.
`target_join_key` Required	String	Column on the target model used in the join.

Target reference format

Relationship targets use the #data-graph-model:<model-id> reference format, where <model-id> is the id of another model in the same data graph. For example:

target: "#data-graph-model:sales"

Complete example

The following example defines a small e-commerce data graph with two entities (Customers, Accounts), one event (Sales), and the relationships between them:

version: "rudder/v1"
kind: "data-graph"
metadata:
 name: "ecommerce-data-graph"
spec:
 id: "ecommerce-data-graph"
 account_id: "<warehouse-account-id>" # RudderStack generates this ID when you connect a warehouse to your RudderStack workspace.
 models:
 # --- Customers (entity) ---
 - id: "customers"
 display_name: "Customers"
 type: "entity"
 table: "ECOMMERCE_DB.E_MART.DIM_CUSTOMERS"
 description: "Customers with demographics and loyalty info"
 primary_id: "CUSTOMER_KEY"
 relationships:
 - id: "customer-has-sales"
 display_name: "Has Sales"
 cardinality: "one-to-many"
 target: "#data-graph-model:sales"
 source_join_key: "CUSTOMER_KEY"
 target_join_key: "CUSTOMER_KEY"
 - id: "customer-belongs-to-account"
 display_name: "Belongs To Account"
 cardinality: "many-to-one"
 target: "#data-graph-model:accounts"
 source_join_key: "ACCOUNT_KEY"
 target_join_key: "ACCOUNT_KEY"

 # --- Accounts (entity) ---
 - id: "accounts"
 display_name: "Accounts"
 type: "entity"
 table: "ECOMMERCE_DB.E_MART.DIM_ACCOUNTS"
 description: "Customer account records for individual, household, and corporate grouping"
 primary_id: "ACCOUNT_KEY"

 # --- Sales (event) ---
 - id: "sales"
 display_name: "Sales"
 type: "event"
 table: "ECOMMERCE_DB.E_MART.FACT_SALES"
 description: "Sales transactions with amounts, status, and store/channel links"
 timestamp: "CREATED_AT"

Sync to your workspace

Once your data graph YAML is ready, use the Rudder CLI to validate and sync it to your workspace:

rudder-cli apply -f data-graph.yaml

RudderStack Docs – Data Graph

Audiences: How to Create a Data Graph using Visual Builder

Overview

Video walkthrough

Prerequisites

1: Connect the warehouse account

2: Create an entity model

3: Create an event model

4: Create relationships between models

By clicking on the model

Using the drag-and-drop method

Organize the layout

See also

Audiences: Data Graph YAML Reference

File structure

Top-level fields

Models

Model fields

Entity vs. event

Relationships

Relationship fields

Target reference format

Complete example

Sync to your workspace

See also