Skip to content

Personas Edits #3218

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rchinn1 merged 1 commit into from
Jul 14, 2022
Merged

Personas Edits #3218

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 37 additions & 37 deletions src/personas/sql-traits.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,24 @@ title: Personas SQL Traits



SQL Traits allow you to import user or account traits from your data warehouse back into Personas to build audiences or to enhance Segment data that you send to other Destinations.
Use SQL Traits to import user or account traits from your data warehouse back into Personas to build audiences or to enhance Segment data that you send to other Destinations.

SQL Traits are only limited by the data in your warehouse. Because anything you can write a query for can become a SQL Trait, you can add detail to your user and account profiles, resulting in more nuanced personalization.

This unlocks some interesting possibilities to help you meet your business goals.

- To improve your support team's customer satisfaction score (CSAT), you can create a SQL Trait of the most common ticket requests for a customer's industry by joining data from cloud sources like Zendesk and Salesforce. The resulting SQL Trait helps you anticipate the user's problems and accelerate potential solutions.
- To determine if a user resides in a specific area, you can query address data in your warehouse and send it as a `true` or `false` Trait to a Personas audience.
- To fill gaps in your customer profiles to include information before you implemented Segment, you can import historical Traits from your warehouse.
- To predict a customer's lifetime value (LTV), you can generate a complex query based on demographic and customer data in your warehouse. You can then use that information in a Personas audience to send personalized offers or recommend specific products.
- To inform your outreach efforts, you can use complex queries to build churn or product adoption models.
- To improve your support team's customer satisfaction score (CSAT), create a SQL Trait of the most common ticket requests for a customer's industry by joining data from cloud sources like Zendesk and Salesforce. The resulting SQL Trait helps you anticipate the user's problems and accelerate potential solutions.
- To determine if a user resides in a specific area, query address data in your warehouse and send it as a `true` or `false` Trait to a Personas audience.
- To fill gaps in your customer profiles to include information before you implemented Segment, import historical Traits from your warehouse.
- To predict a customer's lifetime value (LTV), generate a complex query based on demographic and customer data in your warehouse. You can then use that information in a Personas audience to send personalized offers or recommend specific products.
- To inform your outreach efforts, use complex queries to build churn or product adoption models.

Check out Segment's [SQL Traits blog post](https://segment.com/blog/sql-traits){:target="_blank"} for more customer case studies.


### Example: Cloud Sources Sync

SQL Traits allow you to import data from [object cloud sources](/docs/connections/sources/#object-cloud-sources) like Salesforce, Stripe, Zendesk, Hubspot, Marketo, Intercom, and more. For example, you can bring in Salesforce Leads or Accounts, Zendesk ticket behavior, or Stripe LTV calculations.
SQL Traits allow you to import data from [object cloud sources](/docs/connections/sources/#object-cloud-sources) like Salesforce, Stripe, Zendesk, Hubspot, Marketo, Intercom, and more. For example, bring in Salesforce Leads or Accounts, Zendesk ticket behavior, or Stripe LTV calculations.

The two examples below show SQL queries you can use to retrieve cloud-source information from your warehouse.

Expand Down Expand Up @@ -52,7 +52,7 @@ This query computes whether a user has an open ticket:
```


## Setting up SQL traits
## Setting up SQL Traits

To use SQL Traits, you need the following:

Expand All @@ -65,9 +65,9 @@ To use SQL Traits, you need the following:
Segment supports Redshift, Postgres, Snowflake, Azure SQL, and BigQuery as data warehouse sources for SQL Traits. Note that the BigQuery setup process _requires_ a service user.

> info "Safeguard your data"
> For any warehouse, we recommend that you create a separate read-only user for building SQL Traits.
> For any warehouse, Segment recommends that you create a separate read-only user for building SQL Traits.

#### Redshift, Postgres, Snowflake, Azure SQL Setup
#### Redshift, Postgres, Snowflake, Azure SQL setup

If you don't already have a data warehouse, use one of the following guides to get started:
- [Redshift Getting Started](/docs/connections/storage/catalog/redshift/#getting-started)
Expand All @@ -76,45 +76,45 @@ If you don't already have a data warehouse, use one of the following guides to g
- [Azure SQL Getting Started](/docs/connections/storage/catalog/azuresqldw/#getting-started)


#### BigQuery Setup
#### BigQuery setup

To connect BigQuery to Segment SQL Traits, follow these instructions to create a service account for Segment to use:

1. Navigate to the Google Developers Console.

2. Click the drop down to the left of the search bar and select the project that you want to connect.

![](images/bigquery_setup1.png)
![Select a project to connect from the drop down menu](images/bigquery_setup1.png)

> **Note**: If you don't see the project you want in the menu, click the account switcher in the upper right corner, and verify that you're logged in to the right Google account for the project.

3. Click the menu in the upper left and select **IAM & Admin**, then **Service accounts**.

5. Click **Create service account**.
5. Click **Create Service Account**.

![](images/bigquery_setup2.png)
![Click Create Service Account on the Service accounts screen](images/bigquery_setup2.png)

6. Give the service account a name like `segment-sqltraits`.

7. Under **Project Role**, add _only_ the `BigQuery Data Viewer` and `BigQuery Job User` roles.

![](images/bigquery_setup3a.png)
![Select a project role](images/bigquery_setup3a.png)

![](images/bigquery_setup3b.png)
![Add the BigQuery Data Viewer and BigQuery Job User roles](images/bigquery_setup3b.png)

> IMPORTANT: Do not add any other roles to the service account. Adding other roles can prevent Segment from connecting to the account.

6. Click **Create Key**.

![](images/bigquery_setup4.png)
![Click Create Key](images/bigquery_setup4.png)

7. Select `JSON` and click **Create**.

![](images/bigquery_setup5.png)
![Select Json and click Create](images/bigquery_setup5.png)

A file with the key is saved to your computer. Save this; you'll need it to set up the warehouse source in the next step.

![](images/bigquery_setup6.png)
![A file key saved to your computer](images/bigquery_setup6.png)

You're now ready to create a new BigQuery warehouse source, upload the JSON key you just downloaded, and complete the BigQuery setup.

Expand All @@ -124,35 +124,35 @@ Once your warehouse is up and running, follow these steps:

1. Navigate to the Personas settings (Personas > Settings tab > Warehouse Sources), and click **New Warehouse Source**.

![](images/warehouse_source_setup1.png)
![Click New Warehouse Source button on the Warehouse Sources screen](images/warehouse_source_setup1.png)

2. Select the type of warehouse you're connecting.

![](images/warehouse_source_setup2A.png)
![Select a warehouse to connect](images/warehouse_source_setup2A.png)

3. In the next screen, provide the connection credentials, and click **Save**.

![](images/warehouse_source_setup3.png)
![The Configure warehouse source screen](images/warehouse_source_setup3.png)

If you're connecting a BigQuery warehouse, use the JSON key file that you downloaded as the last step.

## Creating a SQL Trait

Before you create a SQL Trait, you must first preview it to validate your query. If you're new to SQL, try out one of the templates Segment offers.

### Preview the SQL trait
### Preview the SQL Trait

From the Personas screen, go to the Computed Traits tab, and click **New Computed Trait**. Next, choose SQL, and click **Configure**. Select the data warehouse that contains the data you want to query.

If you are sending data from [object cloud sources](/docs/connections/sources/#cloud-apps) to your warehouse, the SQL Traits UI has some pre-made templates you can try out.
If you're sending data from [object cloud sources](/docs/connections/sources/#cloud-apps) to your warehouse, the SQL Traits UI has some pre-made templates you can try out.

![Example template: preview all users with an open Zendesk ticket](images/sql_traits_preview1.png)

<!-- need to actually give a sample here -->

When you're building your query, keep the following requirements in mind for the data your query returns.

- The query must return a column with a `user_id`, `email`, or `anonymous_id` (or `group_id` for account traits, if you have Personas for B2B enabled). The query _cannot_ include values for both `user_id` and `anonymous_id`.
- The query must return a column with a `user_id`, `email`, or `anonymous_id` (or `group_id` for account traits, if you have Personas for B2B enabled). The query _cannot_ include values for both `user_id` and `anonymous_id`.
- The query must return at least one trait in addition to `user_id`/`anonymous_id`/`email`/`group_id`, and no more than 25 total columns.
- The query must not return any `user_id`s, `anonymous_id`s, or `group_id`s with a `null` value.
- The query must not return any records with duplicate `user_id`s.
Expand All @@ -162,7 +162,7 @@ When you're building your query, keep the following requirements in mind for the
A successful preview returns a sample of users and their traits.
If Segment recognizes a user already in Personas, it displays a green checkmark on their profile. Clicking the checkmark displays the user's profile. If a user has a question mark, Segment hasn't detected this `user_id` in Personas before.

![Click on a user to check out their profile. If a user has a question mark, we haven't seen this user_id in Personas before](images/sql_traits_preview2.png)
![Click on a user to check out their profile. If a user has a question mark, Segment hasn't seen this user_id in Personas before](images/sql_traits_preview2.png)


### Configure SQL Trait options
Expand All @@ -177,13 +177,13 @@ If you're building Personas audiences from this data, select "Compute without en

Click **Create Computed Trait** to save the Trait.

![](images/sql_traits_connect3.png)
![The Review and Create screen for a new computed trait](images/sql_traits_connect3.png)
Check **Compute without destinations** if you only want to send to Personas.

When you create a SQL Trait, Segment runs the query on the warehouse twice a day by default. You can customize the time at which Segment queries the data warehouse and the frequency, up to once per hour, from the SQL Trait's settings.
(If you're interested in a more frequent schedule, [contact Segment Support](https://segment.com/help/contact/){:target="_blank"}.)

For each row (user or account) in the query result, Personas sends an identify or group call with all the columns that were returned as Traits. For example, if you write a query that returns `user_id,has_open_ticket, num_tickets_90_days, avg_zendesk_rating_90days` we send an identify call with the following payload:
For each row (user or account) in the query result, Personas sends an identify or group call with all the columns that were returned as Traits. For example, if you write a query that returns `user_id, has_open_ticket, num_tickets_90_days, avg_zendesk_rating_90days` Segment sends an identify call with the following payload:

```sql
{
Expand Down Expand Up @@ -221,7 +221,7 @@ No. Personas only sends an identify/group call if the values in a row have chang

### I have a large (1M+) query of users to import, should I be worried?

If you're importing a large list of users and traits, you'll need to consider your API call usage as well as volume among the partners receiving your data. These vary depending on our partners, so [reach out to us](https://segment.com/help/contact/) for more information.
If you're importing a large list of users and traits, you'll need to consider your API call usage as well as volume among the partners receiving your data. These vary depending on our partners, so [reach out to Segment](https://segment.com/help/contact/){:target="_blank"} for more information.

### Is there a limit on the size of a SQL Trait's payload?

Expand All @@ -232,9 +232,9 @@ Yes, Segment limits request sizes to a maximum of 16kb. Records larger than this
### I'm getting a permissions error.

You might encounter a `permission denied for schema` error, like the following:
![](images/troubleshoot1.png)
![An example of a permission denied for schema error](images/troubleshoot1.png)

Segment usually displays this error because you're querying a schema and table that the current user cannot access. To check the table privileges for a specific grantee (user), go to [your warehouse source credentials in Personas](https://app.segment.com/goto-my-workspace/personas/settings/warehouse-sources/) to retrieve the user name.
Segment usually displays this error because you're querying a schema and table that the current user cannot access. To check the table privileges for a specific grantee (user), go to [your warehouse source credentials in Personas](https://app.segment.com/goto-my-workspace/personas/settings/warehouse-sources/){:target="_blank"} to retrieve the user name.

To grant access to a table, an admin usually needs to grant access to both a schema and table through the following similar commands:

Expand All @@ -249,13 +249,13 @@ Learn more about granting permissions using the following links:

### I'm seeing a maximum columns error.

![](images/troubleshoot2.png)
![An example of a maximum columns error](images/troubleshoot2.png)

Segment supports returning only 25 columns. [Contact us](https://segment.com/help/contact/) with a description of your use case if you need access to more than 25 columns.
Segment supports returning only 25 columns. [Contact Segment](https://segment.com/help/contact/){:target="_blank"} with a description of your use case if you need access to more than 25 columns.

### I'm seeing a duplicate `user_id` error.

![](images/troubleshoot3.png)
![An example of a duplicate user_id error](images/troubleshoot3.png)

Each query row must correspond to a unique user. Segment displays this error if it detects multiple rows with the same `user_id`. Use a `distinct` or `group by` statement to ensure that each row has a unique user_id.

Expand All @@ -265,10 +265,10 @@ Question marks in previews indicate one of two things:

**1. Segment doesn't recognize this `user_id`/`group_id` in Personas.**

In this case, for [sources connected to Personas](https://app.segment.com/goto-my-workspace/personas/settings/sources), Segment has not received any event (identify, track, page etc) with this `user_id`. This could still be a legitimate `user_id` for a number of reasons, but before syncing, make sure you rule out option two (below), as sending a different identifier as the `user_id` can corrupt your identity graph.
In this case, for [sources connected to Personas](https://app.segment.com/goto-my-workspace/personas/settings/sources){:target="_blank"}, Segment hasn't received any event (for example, identify, track, or page) with this `user_id`. This could still be a legitimate `user_id` for a number of reasons, but before syncing, make sure you rule out option two (below), as sending a different identifier as the `user_id` can corrupt your identity graph.

**2. You have the wrong `user_id` column.**

You might be returning a value for `user_id` that is inconsistent with how you track `user_id` elsewhere. Some customers want to return `email` as the `user_id`, or a partner's tool ID as the `user_id`. These conflict with Segment best practices and corrupt the identity graph if you then track `user_id` differently elsewhere in your apps.
You might be returning a value for `user_id` that's inconsistent with how you track `user_id` elsewhere. Some customers want to return `email` as the `user_id`, or a partner's tool ID as the `user_id`. These conflict with Segment best practices and corrupt the identity graph if you then track `user_id` differently elsewhere in your apps.

If you see only question marks in the preview, and have already tracked data historically with Segment, then you likely have the wrong column. If your cloud source doesn't have the database `user_id`, we recommend using a `JOIN` clause with an internal users table before sending the results back to Segment.
If you see only question marks in the preview, and have already tracked data historically with Segment, then you likely have the wrong column. If your cloud source doesn't have the database `user_id`, Segment recommends using a `JOIN` clause with an internal users table before sending the results back to Segment.
Loading