Merge branch 'master' into DOC-280_postgres

Author: markzegarelli

src/personas/images/warehouse_source_setup2A.png

@@ -5,29 +5,29 @@ 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 what data you have in your warehouse. Anything you can write a query for can become a SQL Trait, which allows you to add more details to your user and account profiles, which allows better and more nuanced personalization.
+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.
 
-- Imagine you want to increase the CSAT (customer satisfaction score) of your Support team. You could create a SQL Trait of most common ticket requests for a customers' industry by joining data from cloud sources like Zendesk and Salesforce, so you can better anticipate the user's problems and speed up their solution.
-- If you wanted to determine if a user is a resident of a specific area, you could query address data in your Warehouse and send this information as a true or false trait to a Personas audience.
-- If you wanted to fill gaps in your customer profiles to include information from before you implemented Segment, you could import historical traits from your warehouse to fill in the gaps.
-- If you wanted to more accurately predict lifetime value (LTV) for a customer, you can generate a complex query based on demographic and customer data in your warehouse, and use that information in a Personas audience to send personalized offers or recommend specific products.
-- You could use similarly complex queries to build churn or product adoption models that cannot be easily calculated using Personas Computed Traits, and use them to inform your outreach efforts.
+- 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.
 
-Check out our [blog post](https://segment.com/blog/sql-traits) for more customer case studies.
+Check out our [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) such as Salesforce, Stripe, Zendesk, Hubspot, Marketo, Intercom and more. For example, you could bring in Salesforce Leads or Accounts, syncing 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, you can bring in Salesforce Leads or Accounts, Zendesk ticket behavior, or Stripe LTV calculations.
 
-The two examples below show SQL queries you could use to get cloud-source information from your warehouse.
+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 could use SQL similar to the following query:
+If you wanted 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,
@@ -53,24 +53,26 @@ This query computes whether a user has an open ticket.
 
 ## Setting up SQL traits
 
-To use SQL traits you need:
+To use SQL Traits, you need the following:
 
-- a Warehouse connected to Segment
+- a warehouse connected to Segment
 - a Personas-enabled Segment workspace
 - a user account with access to Personas in that workspace
 
 ### Step 1. Set up a warehouse source
 
-We currently support Redshift, Postgres, Snowflake, and BigQuery as data warehouse sources for SQL traits. The set up process for BigQuery is a bit different as it _requires_ a service user.
+Segment supports Redshift, Postgres, Snowflake, Azure, and BigQuery as data warehouse sources for SQL Traits. The setup process for BigQuery is a bit different as it _requires_ a service user.
 
-For any warehouse, we recommend that you create a separate read-only user for building SQL traits.
+> info "Safeguard your data"
+> For any warehouse, we recommend that you create a separate read-only user for building SQL Traits.
 
 #### Redshift, Postgres, Snowflake Setup
 
 If you don't already have a data warehouse, follow one of the guides here first:
 - [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 Getting Started](/docs/connections/storage/catalog/azuresqldw/#getting-started)
 
 Remember to create a read-only service user!
 
@@ -80,7 +82,7 @@ To connect BigQuery to Segment SQL Traits, you must create a service account for
 
 1. Navigate to the Google Developers Console.
 
-2. Click the drop down to the left of the search bar and select the project to which you want to connect.
+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)
 
@@ -92,7 +94,7 @@ To connect BigQuery to Segment SQL Traits, you must create a service account for
 
    ![](images/bigquery_setup2.png)
 
-6. Give the service account a name - we recommend something like `segment-sqltraits`.
+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.
 
@@ -110,7 +112,7 @@ 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, because you'll need it to set up the warehouse source in the next step.
 
    ![](images/bigquery_setup6.png)
 
@@ -128,7 +130,7 @@ Once your warehouse is up and running:
 
 2. Select the type of warehouse you're connecting.
 
-   ![](images/warehouse_source_setup2.png)
+   ![](images/warehouse_source_setup2A.png)
 
 3. In the next screen, provide the connection credentials, and click **Save**.
 
@@ -138,13 +140,13 @@ Once your warehouse is up and running:
 
 ## Creating a SQL Trait
 
-Before you create a SQL trait, you must first preview it to validate your query. If you've never used SQL before, we have a few templates you can use to try it out.
+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
 
-From the Personas screen, go to the Computed Traits tab, and click create a new SQL trait. Select the data warehouse that contains the data you want to query.
+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](https://segment.com/docs/connections/sources/#cloud-apps) to your warehouse, the SQL traits UI has some pre-made templates you can try out.
+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.
 
 ![Example template: preview all users with an open Zendesk ticket](images/sql_traits_preview1.png)
 
@@ -159,29 +161,29 @@ When you're building your query, there are some requirements for the data your q
 - 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 we have seen a user before in Personas, their profile shows a green checkmark. You can click that user to view their user profile. If a user has a question mark, we haven't seen this `user_id` in Personas before.
+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.
 
 ![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)
 
 
 ### Configure SQL Trait options
 
-Once you're ready to import the SQL trait, select the destinations that you want to send this data to, **or** if you want to build Personas audiences from this data, you don't need to select destinations, and can just click **Skip**.
+Once you're ready to import the SQL Trait, select the Destinations to which you want to send the data.  If you prefer to build Personas audiences directly from the data instead of sending it to a Destination, click **Skip**.
 
 ![Select destinations](images/sql_traits_connect1.png)
 
-Give your SQL trait a name. This is used as a label only, 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 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.
 
 If you're building Personas audiences from this data, select "Compute without enabled destinations".
 
-Click **Create Computed Trait** to save the trait.
+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
 
-When you create a SQL trait, Segment runs the query on the warehouse twice a day by default. (If you're interested in a more frequent or customizable schedule, [contact us](https://segment.com/help/contact/).)
+When you create a SQL Trait, Segment runs the query on the warehouse twice a day by default. (If you're interested in a more frequent or customizable 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` we send an identify call with the following payload:
 
 ```sql
     {
@@ -203,38 +205,38 @@ Happy Querying!
 
 The result set is capped at 10 million rows.
 
-### How often are you querying the customer's data warehouse?
+### How often does Segment query the customer's data warehouse?
 
-We query the data warehouse every 12 hours by default, but can query up to hourly. [contact us](https://segment.com/help/contact/) if you need more customizable schedules.
+Segment queries the data warehouse every 12 hours by default, but can query up to hourly. [Contact us](https://segment.com/help/contact/) for customized schedules.
 
 ### What identifiers can I use to query a list?
 
-You can currently query based on `email`, `user_id` or `anonymous_id`. If we don't locate a match based on the chosen identifier, a new user profile is created. See question below.
+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.
 
-### Can you use SQL traits to create users in Segment? Or do SQL traits only append traits to existing users?
+### 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 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 happens in the back-end, and doesn't show up in your Debugger.)
 
 ### Does Personas send identify/group calls on every run?
 
-No, Personas only sends an identify/group call if the values in a row have changed from previous runs.
+No. Personas only sends an identify/group call if the values in a row have changed from previous runs.
 
 ### 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, the biggest consideration is the API call usage and volume among the partners you are sending the data to. These vary depending on our partners, so [contact us](https://segment.com/help/contact/) if you are concerned about this.
+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.
 
 ### Is there a limit on the size of a SQL Trait's payload?
 
 Yes, Segment limits request sizes to a maximum of 16kb. Records larger than this are discarded.
 
 ## Troubleshooting
 
-### I am getting a permissions error.
+### I'm getting a permissions error.
 
 You might encounter a similar permissions error:
 ![](images/troubleshoot1.png)
 
-This is usually because you are querying a schema and table that the current user does not have access to. 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. Typically to grant access to a table, an admin 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;
@@ -245,28 +247,28 @@ 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
 
-### I am seeing a maximum columns error.
+### I'm seeing a maximum columns error.
 
 ![](images/troubleshoot2.png)
 
-We currently support 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 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.
 
-### I am seeing a duplicate user_id error.
+### I'm seeing a duplicate `user_id` error.
 
 ![](images/troubleshoot3.png)
 
-We require that each row of the query corresponds to a unique user. We throw this error if we see multiple rows with the same `user_id`. Use a `distinct` or `group by` statement to ensure that each row has a unique user_id.
+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 am seeing some users/accounts in my preview with questions marks. What does that mean?
+### I'm seeing some users/accounts in my preview with questions marks. What does that mean?
 
 This could mean one of two things:
 
-**1. We haven't seen this `user_id`/`group_id` before 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) we have 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.
+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.
 
 **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. We've seen cases where some customers want to return `email` as the `user_id`, or a partner's tool id as the `user_id`. These are against our best practices and corrupt the identity graph if you are then tracking `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 probably just have the wrong column. If you cloud source doesn't have the database `user_id`, we recommend JOINing 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`, we recommend using a `JOIN` clause with an internal users table before sending the results back to Segment.