# How to Create a Data Graph using Visual Builder


To create a data graph as YAML using [Rudder CLI]({{< ref "/dev-tools/rudder-cli/" >}}), see the [Data Graph YAML reference]({{< ref "/dev-tools/rudder-cli/data-graph.md" >}}).

## Video walkthrough

{{< youtube XL_wETXk1vI >}}

## Prerequisites

You need a connected **warehouse account** before you can build a data graph.

The steps to configure a warehouse connection are as follows:

{{< tabs tabTotal="4" >}}
{{% tab tabName="BigQuery" %}}

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

1. [Create a role and grant permissions]({{< ref "sources/reverse-etl/google-bigquery.md#step-1-creating-a-role-and-granting-permissions" >}}) in your GCP project.
2. [Create a service account]({{< ref "sources/reverse-etl/google-bigquery.md#step-2-creating-a-service-account-and-attaching-the-role-to-it" >}}) and attach the role to it.
3. [Create and download the JSON key]({{< ref "sources/reverse-etl/google-bigquery.md#step-3-creating-and-downloading-the-json-key" >}}) for the service account.
4. [Create the RudderStack schema]({{< ref "sources/reverse-etl/google-bigquery.md#creating-the-rudderstack-schema-and-granting-permissions" >}}) and grant permissions to the service account.

Then, configure the warehouse credentials:

| Setting  | <div style="width: 350px;">Description</div> |
| :----| :-----|
| 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]({{< ref "/sources/reverse-etl/google-bigquery#configuring-the-connection-credentials" >}}).

{{< /tab >}}
{{% tab tabName="Databricks" %}}

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

1. Add a new user by following the steps in the [Databricks documentation](https://docs.databricks.com/aws/en/admin/users-groups/users#add-a-user).
2. [Create RudderStack schema]({{< ref "sources/reverse-etl/databricks.md#creating-the-rudderstack-schema-and-granting-permissions" >}}) and grant permissions to the user.

Then, configure the warehouse credentials:

| Setting  | <div style="width: 350px;">Description</div> |
| :----| :-----|
| 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](https://docs.databricks.com/aws/en/catalogs#view-catalog-details). |

For more details on the above settings, see the [Databricks documentation]({{< ref "/sources/reverse-etl/databricks#configuring-the-connection-credentials" >}}).

{{< /tab >}}
{{% tab tabName="Redshift" %}}

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

1. [Create a new user]({{< ref "sources/reverse-etl/amazon-redshift.md#step-1-creating-a-new-user-in-redshift" >}}) in Redshift.
2. [Create RudderStack schema]({{< ref "sources/reverse-etl/amazon-redshift.md#creating-the-rudderstack-schema-and-granting-permissions" >}}) and grant permissions to the user.
3. [Grant user the required permissions]({{< ref "sources/reverse-etl/amazon-redshift.md#step-3-granting-permissions-on-your-schema-and-table" >}}) on your schema and table.

Then, configure the warehouse credentials:

| Setting  | <div style="width: 350px;">Description</div> |
| :----| :-----|
| 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]({{< ref "/sources/reverse-etl/amazon-redshift#configuring-the-connection-credentials" >}}).

{{< /tab >}}
{{% tab tabName="Snowflake" %}}

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

{{< warning >}}
You must have the **ACCOUNTADMIN** role to grant these permissions.
{{< /warning >}}

1. [Create a new role and user]({{< ref "sources/reverse-etl/snowflake.md#step-1-creating-a-new-role-and-user-in-snowflake" >}}) in Snowflake.
2. [Create RudderStack schema]({{< ref "sources/reverse-etl/snowflake.md#creating-the-rudderstack-schema-and-granting-permissions" >}}) and grant permissions to the role.
3. [Grant permissions]({{< ref "sources/reverse-etl/snowflake.md#step-3-granting-permissions-on-the-warehouse-database-schema-and-the-table" >}}) on your warehouse, database, schema, and table.

Then, configure the warehouse credentials:

| Setting  | <div style="width: 350px;">Description</div> |
| :----| :-----|
| 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](https://docs.snowflake.com/en/user-guide/key-pair-auth#generate-the-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. <br /><br />**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]({{< ref "/sources/reverse-etl/snowflake#configuring-the-connection-credentials" >}}).

{{< /tab >}}
{{< /tabs >}}

## 1: Connect the warehouse account

1. Navigate to **Activate** > **Data Graph** in the RudderStack dashboard.
2. 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.

{{< image src="images/audiences/data-graph/create-data-graph-1.webp" alt="Connect warehouse account" >}}

{{< info >}}
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]({{< ref "/sources/reverse-etl/snowflake" >}})
  - [BigQuery]({{< ref "/sources/reverse-etl/google-bigquery" >}})
  - [Redshift]({{< ref "/sources/reverse-etl/amazon-redshift" >}})
  - [Databricks]({{< ref "/sources/reverse-etl/databricks" >}})
{{< /info >}}

3. Connect the warehouse account to the data graph. You can now start defining entities and events.

## 2: Create an entity model

1. In the **Add component** section, select **Entity model**.

{{< image src="images/audiences/data-graph/create-data-graph-2.webp" alt="Add entity model" >}}

2. Choose the **Database**, **Schema**, and **Table** for the entity model.
3. Select the **Primary key**.
4. To set the entity model as a root model, select **Yes**.

{{< info >}}
**What is a root entity model?**

A root entity model is the central, anchor entity in the data graph — typically the entity around which audiences are built (for example, user, account, etc.). You can relate other entity models to it through defined relationships in the data graph, and these related entity models are reachable from the root for filtering and segmentation.
{{< /info >}}

{{< image src="images/audiences/data-graph/create-data-graph-3.webp" alt="Configure entity model" >}}

5. Provide a name and description for the entity model and save it.

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

## 3: Create an event model

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

{{< image src="images/audiences/data-graph/create-data-graph-4.webp" alt="Create event model" >}}

2. Select the **Database** and **Schema** for the event model.

{{< info >}}
If you configured an entity model in the previous step, the **Database** and **Schema** fields are pre-populated.
{{< /info >}}

3. In the **Table** field, select a table that contains timestamp information.
4. Select the timestamp column — this defines the time dimension of the event model.

{{< image src="images/audiences/data-graph/create-data-graph-5-new.webp" alt="Configure event model" >}}

5. Provide a name and description for the event model and save it.

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](#by-clicking-on-the-model) and selecting **Add relationship** from the sidebar
- [Using the drag-and-drop method](#using-the-drag-and-drop-method)

#### By clicking on the model

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

{{< image src="images/audiences/data-graph/create-data-graph-7.webp" alt="Create relationship between entity and event model" >}}

2. Click **Add relationship** under **Relationships**.

{{< image src="images/audiences/data-graph/create-data-graph-8.webp" alt="Create relationship between entity and event model" >}}

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

{{< image src="images/audiences/data-graph/create-data-graph-9.webp" alt="Create relationship between entity and event model" >}}

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

{{< image src="images/audiences/data-graph/create-data-graph-10.webp" alt="Create relationship between entity and event model" >}}

#### Using the drag-and-drop method

{{< info >}}
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.
{{< /info >}}

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

{{< image src="images/audiences/data-graph/create-data-graph-14.webp" alt="Drag-and-drop relationship between entity and event model" >}}

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

{{< image src="images/audiences/data-graph/create-data-graph-11.webp" alt="Create drag-and-drop relationship between entity and event model" >}}

4. Define the **Join keys** used to join the models, for example, **Account Key**.
5. Click **Create** to save the relationship.
6. Use the **Auto Layout** functionality (described in [Step 4](#step-4-organize-the-layout)) to reorganize the graph.

{{< image src="images/audiences/data-graph/create-data-graph-12.webp" alt="Organized layout of the data graph" >}}

You can continue expanding the data graph with more entity and event models and relationships.

## 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.

{{< image src="images/audiences/data-graph/sample-data-graph.webp" alt="Sample data graph for an ecommerce store" >}}

## See also

- [How to Create an Audience from a Data Graph]({{< ref "audiences/audience-builder/create-audience.md" >}})
- [Create a Data Graph using Rudder CLI]({{< ref "/audiences/data-graph/cli-reference.md" >}})

<br />