Update sql-traits.md

pwseg · web-flow · commit 2fc5647b9f5a · 2021-12-31T14:16:44.000-06:00
diff --git a/src/personas/sql-traits.md b/src/personas/sql-traits.md
@@ -5,7 +5,7 @@ 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.
+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.
 
 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.
 
@@ -17,7 +17,7 @@ This unlocks some interesting possibilities to help you meet your business goals
 - 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.
 
-Check out our [SQL Traits blog post](https://segment.com/blog/sql-traits){:target="_blank"} for more customer case studies.
+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
@@ -27,7 +27,8 @@ SQL Traits allow you to import data from [object cloud sources](/docs/connection
 The two examples below show SQL queries you can use to retrieve cloud-source information from your warehouse.
 
 **Salesforce lead import**
-If you wanted to import data from the Salesforce leads and contacts table, you can use SQL similar to the following query:
+
+If you want to import data from the Salesforce leads and contacts table, you can use SQL similar to the following query:
 
 ```sql
     select external_id_c as user_id,
@@ -40,7 +41,7 @@ If you wanted to import data from the Salesforce leads and contacts table, you c
 
 **Has Open Ticket in Zendesk**
 
-This query computes whether a user has an open ticket.
+This query computes whether a user has an open ticket:
 
 ```sql
     select distinct u.external_id as user_id, true as has_open_ticket
@@ -61,32 +62,31 @@ To use SQL Traits, you need the following:
 
 ### Step 1. Set up a warehouse source
 
-Segment supports Redshift, Postgres, Snowflake, Azure SQL, and BigQuery as data warehouse sources for SQL Traits. The setup process for BigQuery is a bit different as it _requires_ a service user.
+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.
 
 #### Redshift, Postgres, Snowflake, Azure SQL Setup
 
-If you don't already have a data warehouse, follow one of the guides here first:
+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)
 - [Postgres Getting Started](/docs/connections/storage/catalog/postgres/#getting-started)
 - [Snowflake Getting Started](/docs/connections/storage/catalog/snowflake/#getting-started)
 - [Azure SQL Getting Started](/docs/connections/storage/catalog/azuresqldw/#getting-started)
 
-Remember to create a read-only service user!
 
 #### BigQuery Setup
 
-To connect BigQuery to Segment SQL Traits, you must create a service account for Segment to use.
+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)
 
-   > **Note**: If you don't see the project you want in the menu, click the account switcher in the upper right corner, and check that you're logged in to the right Google account for the project.
+   > **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**.
 
@@ -112,17 +112,15 @@ To connect BigQuery to Segment SQL Traits, you must create a service account for
 
    ![](images/bigquery_setup5.png)
 
-   A file with the key is saved to your computer. Save this, because you'll need it to set up the warehouse source in the next step.
+   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)
 
-   8. Create new BigQuery Warehouse Source in Personas
-
-   Now you can create a new BigQuery warehouse source, upload the JSON key you just downloaded, and complete the BigQuery setup
+   You're now ready to create a new BigQuery warehouse source, upload the JSON key you just downloaded, and complete the BigQuery setup.
 
 ### Step 2. Add the warehouse as a Personas Source
 
-Once your warehouse is up and running:
+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**.
 
@@ -152,16 +150,16 @@ If you are sending data from [object cloud sources](/docs/connections/sources/#c
 
 <!-- need to actually give a sample here -->
 
-When you're building your query, there are some requirements for the data your query returns.
+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).
-- It must return at least one additional trait in addition to `user_id`/`group_id`, and no more than 25 total columns
+- It must return at least one additional trait in addition to `user_id`/`group_id`, and no more than 25 total columns.
 - The query must not return any `user_id`s with a `null` value, or any duplicate `user_id`s.
 - The query must not return more than 25 million rows.
 - Each record must be less than 16kb in size to adhere to [Segment's maximum request size](/docs/connections/sources/catalog/libraries/server/http-api/#max-request-size).
 
 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. You can click that user to view the user's profile. If a user has a question mark, Segment hasn't detected this `user_id` in Personas before.
+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)
 
@@ -172,14 +170,14 @@ Once you're ready to import the SQL Trait, select the Destinations to which you
 
 ![Select destinations](images/sql_traits_connect1.png)
 
-Give your SQL Trait a name. This is used as a label for descriptive purposes. If you're importing multiple Traits, give it a name like "Zendesk Traits". The Trait names you use in audience-building or in your downstream tools correspond to the column names from the query.
+Give your SQL Trait a descriptive name. If you're importing multiple Traits, use a name like "Zendesk Traits". The Trait names you use in audience-building or in your downstream tools correspond to the column names from the query.
 
 If you're building Personas audiences from this data, select "Compute without enabled destinations".
 
 Click **Create Computed Trait** to save the Trait.
 
 ![](images/sql_traits_connect3.png)
-Check **Compute without destinations** if you only want to send to Personas
+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"}.)
@@ -198,25 +196,23 @@ For each row (user or account) in the query result, Personas sends an identify o
     }
 ```
 
-Happy Querying!
-
 ## FAQs
 
 ### Is there a limit to the result set that can be queried and imported?
 
-The result set is capped at 25 million rows.
+Yes. The result set is capped at 25 million rows.
 
 ### How often does Segment query the customer's data warehouse?
 
 For each SQL Trait you create, you can set a compute schedule to query the data warehouse up to once per hour. Your query may run at any given time during the hour you select.
 
 ### What identifiers can I use to query a list?
 
-You can currently query based on `email`, `user_id` or `anonymous_id`. If Segment doesn't locate a match based on the chosen identifier, it creates a new profile. See more below.
+You can query based on `email`, `user_id` or `anonymous_id`. If Segment doesn't locate a match based on the chosen identifier, it creates a new profile. See more below.
 
 ### Can I use SQL Traits to create users in Segment? Or do SQL Traits only append Traits to existing users?
 
-Yes. The Personas engine sends an `identify` call if there is no match between the identifier you chose and an existing record. When this happens, Segment creates a new user profile. (This identify call happens in the back-end, and doesn't show up in your Debugger.)
+Yes. The Personas engine sends an identify call if there is no match between the identifier you chose and an existing record. When this happens, Segment creates a new user profile. This identify call takes place in the back-end and doesn't show up in your Debugger.
 
 ### Does Personas send identify/group calls on every run?
 
@@ -234,42 +230,44 @@ Yes, Segment limits request sizes to a maximum of 16kb. Records larger than this
 
 ### I'm getting a permissions error.
 
-You might encounter a similar permissions error:
+You might encounter a `permission denied for schema` error, like the following:
 ![](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. To grant access to a table, an admin usually needs to grant access to both a schema and table through the following similar commands:
+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. 
+
+To grant access to a table, an admin usually needs to grant access to both a schema and table through the following similar commands:
 
 ```sql
     GRANT USAGE ON SCHEMA ecommerce TO segment_user;
     GRANT SELECT ON TABLE ecommerce.users TO segment_user;
 ```
 
-Learn more about granting permissions:
-- https://www.postgresql.org/docs/9.0/sql-grant.html
-- https://stackoverflow.com/questions/17338621/what-grant-usage-on-schema-exactly-do
+Learn more about granting permissions using the following links:
+- [PostgreSQL Grants](https://www.postgresql.org/docs/current/sql-grant.html){:target="_blank"}
+- [What does 'Grant usage on schema' do?](https://stackoverflow.com/questions/17338621/what-grant-usage-on-schema-exactly-do){:target="_blank"}
 
 ### I'm seeing a maximum columns error.
 
 ![](images/troubleshoot2.png)
 
-Segment currently supports returning only 25 columns. [Contact us](https://segment.com/help/contact/) with a description of your use case if you need to access more.
+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.
 
 ### I'm seeing 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.
 
-### I'm seeing some users/accounts in my preview with questions marks. What does that mean?
+### I'm seeing some users/accounts in my preview with question marks. What does that mean?
 
-This could mean one of two things:
+Question marks in previews indicate one of two things:
 
-**1. Segment doesn't recognize this `user_id`/`group_id` in Personas**
+**1. Segment doesn't recognize this `user_id`/`group_id` in Personas.**
 
-This means for the [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 2 (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), 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.
 
-**2. You have the wrong `user_id` column**
+**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 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.
 
 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.
