Skip to content

Commit 5dd7acd

Browse files
rchinn1rchinn1
committed
Subscription SQL Public Beta
1 parent 60d9588 commit 5dd7acd

File tree

3 files changed

+100
-0
lines changed

3 files changed

+100
-0
lines changed

‎src/_data/sidenav/main.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -324,6 +324,8 @@ sections:
324324
title: Subscription States
325325
- path: /engage/user-subscriptions/engage-source
326326
title: Engage Events Source
327+
- path: /engage/user-subscriptions/subscription-sql
328+
title: Subscription SQL
327329
- section_title: Profiles
328330
description: "See how to create audiences based on data."
329331
section:

‎src/engage/user-subscriptions/subscription-sql.md

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
title: Subscription SQL Sync
3+
plan: engage-foundations
4+
beta: true
5+
---
6+
7+
With Subscription SQL Sync, connect to your data warehouse and query user subscription data to Engage on a scheduled basis. Use your data warehouse as a single source of truth for subscription statuses and query from warehouses such as BigQuery, Redshift, or Snowflake.
8+
9+
On this page, you'll learn how to use SQL to sync subscription data from your warehouse to Engage.
10+
11+
## Getting started
12+
13+
To use Subscription SQL Sync, you need the following:
14+
- A warehouse connected to Segment
15+
- A Segment workspace
16+
- A user account with access to Engage in that workspace
17+
18+
> info ""
19+
> Segment supports Redshift, Postgres, Snowflake, Azure SQL, and BigQuery as data warehouse sources for SQL Traits. Visit [Segment's warehouse docs](/docs/connections/storage/warehouses/) for more on getting started with data warehouses.
20+
21+
> success ""
22+
> Before you begin with Subscription SQL, you may also want to visit the [subscription docs](/docs/engage/user-subscriptions/) to learn more about user subscriptions in Engage.
23+
24+
## Sync subscription data with SQL
25+
26+
You can sync with SQL from two locations in the Segment app. Navigate to **Profiles > Profile explorer** or **Engage > Audiences > Profile explorer**, then:
27+
28+
1. Click **Manage Subscription Statuses**, and select **Update Subscription Statuses**.
29+
2. Select **Sync with SQL**, and click **Configure**.
30+
31+
### Configure your SQL query
32+
33+
To configure subscription SQL, you can write your own query or click **Use Template** to use one of the templates Engage provides. For any new users that your query returns, Engage adds a new profile.
34+
35+
> success ""
36+
> Reset your SQL query by clicking **Reset Template**.
37+
38+
Queries must return at least one pair of the columns below with a value of `subscribed`, `unsubscribed`, or `did_not_subscribe`:
39+
- `email` and `segment_internal_email_subscription`
40+
- `phone` and `segment_internal_sms_subscription`
41+
42+
For more subscription SQL best practices, view the [query requirements](#query-requirements) below.
43+
44+
### Select a warehouse and preview your query
45+
46+
After you write your SQL query, click **Warehouse name** from the Configure screen to select the data warehouse you'd like to query.
47+
48+
Before you schedule your sync intervals, click **Preview** to preview and validate your results. To see subscription statuses for a particular profile, select a user row, then select the **Identities** tab.
49+
50+
### Select a warehouse and preview your query
51+
52+
After you write your SQL query, click **Warehouse name** from the Configure screen to select the data warehouse you'd like to query.
53+
54+
Before you schedule your sync intervals, click **Preview** to preview and validate your results. To see subscription statuses for a particular profile, select a user row, then select the Identities tab.
55+
56+
### Schedule sync intervals
57+
58+
After you connect a warehouse and preview your query, schedule sync intervals to import subscription data from your warehouse to Engage:
59+
60+
1. From the Configure screen, click **Schedule**.
61+
2. Add a SQL job name and description.
62+
3. Set the sync schedule.
63+
- Choose a time to start the SQL job and how often to run syncs.
64+
4. Click **Create** to create and save the SQL job.
65+
66+
> info ""
67+
> SQL queries are executed directly to your data warehouse, which could generate additional costs for pay-per-query warehouses.
68+
69+
### View SQL job history
70+
71+
Use the Update History page to view all SQL jobs.
72+
73+
1. Navigate to **Profiles > Profile explorer** or **Engage > Audiences > Profile explorer.**
74+
2. Click **Manage Subscription Statuses**.
75+
3. Select **View Update History**, then select the **SQL Jobs** tab.
76+
77+
From the Update History page you can view details for each SQL job including the creation date and time, compute status, and the number of users updated across all runs for a job. Click the job link to visit a particular SQL job Overview page.
78+
79+
## Query requirements
80+
81+
When you build your query, keep the following requirements in mind for the data your query returns:
82+
83+
- The query must return at least one column with `user_id`, `anonymous_id`, `email`, `phone` (or `group_id` for account traits if Profiles for B2B is enabled).
84+
- The query can't return more than 25 total columns.
85+
- The query must not include values for both `user_id` and `anonymous_id` for a given record.
86+
- The query must not return any `user_id`s, `anonymous_id`s, or `group_id`s with a `null` value.
87+
- The query must not return any records with duplicate `user_id`s.
88+
- The query must not return duplicate `email` or `phone` records that have different subscription statuses.
89+
- The query must not return more than 25 million rows.
90+
- Each record must be less than 16KB in size.

‎src/engage/user-subscriptions/subscription-states.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,14 @@ Uploading contacts with a CSV file works best for initial batches of contacts yo
8585

8686
To learn more about both options, reference the Engage documentation on using the [CSV uploader](/docs/engage/profiles/csv-upload/) and setting user subscriptions.
8787

88+
### Sync subscription statuses with SQL
89+
90+
Use SQL to import user subscription states from your data warehouse back to Engage. When you sync with SQL, you can query user subscription data at automated intervals. Pull subscription statuses on a per contact vector basis and use your data warehouse as a single source of truth for subscription data.
91+
92+
This option is especially useful if you don't have the ability to download CSVs with subscription information or can't invoke the subscription API.
93+
94+
View [Subscription SQL Sync](/docs/engage/user-subscriptions/subscription-sql/) for more information.
95+
8896
### Troubleshooting subscription states
8997

9098
On occasion, a user’s subscription state may not be up-to-date. For example, a user may have unsuccessfully attempted to unsubscribe from your marketing campaigns.

0 commit comments

Comments
 (0)