Skip to content

Commit 3d9cdb8

Browse files
forstisabellaforstisabella
committed
updates from Kalyan's review
1 parent 1d3934c commit 3d9cdb8

File tree

3 files changed

+86
-79
lines changed

3 files changed

+86
-79
lines changed

‎src/connections/reverse-etl/index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,6 @@ Learn more about the system that powers Reverse ETL, supported destinations, and
7979
icon="projects.svg"
8080
href="https://segment.com/customers/mongodb/"
8181
title="Customer story: MongoDB"
82-
description="Learn how MongoDB used Reverse ETL to connect the work of analytics teams to downstream marketing and sales tools to deliver just-in-time communicates that increased customer satisfaction and engagement."
82+
description="Learn how MongoDB used Reverse ETL to connect the work of analytics teams to downstream marketing and sales tools to deliver just-in-time communications that increased customer satisfaction and engagement."
8383
%}
8484

‎src/connections/reverse-etl/manage-retl.md

Lines changed: 2 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,11 @@ The Reverse ETL sync overview tab, located under **Connections > Destinations**,
1212

1313
You can view the following information about each sync:
1414
- **Latest sync**: The status of your latest sync. Syncs can either be **In progress**, **Successful**, or **Failed**.
15-
- **Mapping**: The named mapping that powered the sync and a hyperlink to the mapping's overview page.
15+
- **Mapping**: The named mapping.
1616
- **Model**: The model that extracts data from your warehouse.
1717
- **Action**: The action that your destination uses to map information from your warehouse to your downstream destination.
1818
- **Mapping status**: The status of your mapping - either **Enabled** or **Disabled**.
1919

20-
You can also filter the sync overview table to return only **Enabled** or **Disabled** syncs.
21-
2220
## Sync history
2321
Check the status of your data extractions and see details of your syncs. Click into failed records to view additional details on the error, sample payloads to help you debug the issue, and recommended actions.
2422

@@ -37,7 +35,7 @@ To check the status of your extractions:
3735
> Segment retries events for 14 days following a total or partial sync failure. Before loading the failed records on a subsequent sync, Segment checks for the latest changes in your data to ensure the data loaded into your warehouse isn't stale. If the error causing the load failure is coming from an upstream tool, you can fix the error in the upstream tool to ensure the record loads on the next sync. --->
3836

3937
## Reset syncs
40-
You can reset your syncs so that your data is synced from the beginning. This means that Segment resyncs your entire dataset for the model. During the next sync, all records extracted by the model are sent to your destination, not just the records that changed since the last sync.
38+
Reverse ETL uses the Unique Identifier column to detect data changes, like new, updated, and deleted records. If you encounter an error, you can reset Segment’s tracking of this column and force Segment to manually add all records from your dataset.
4139

4240
To reset a sync:
4341
1. Select the three dots next to **Sync now**.
@@ -65,70 +63,3 @@ To subscribe to alerts:
6563

6664
> success ""
6765
> If you opted to receive notifications by email, you can click **View active email addresses** to see the email addresses that are currently signed up to receive notifications.
68-
69-
## Supported object and arrays
70-
71-
When you set up destination actions in Reverse ETL, depending on the destination, some [mapping fields](/docs/connections/reverse-etl/setup/#step-4-create-mappings) may require data as an [object](/docs/connections/reverse-etl/manage-retl/#object-mapping) or [array](/docs/connections/reverse-etl/manage-retl/#array-mapping).
72-
73-
### Object mapping
74-
You can send data to a mapping field that requires object data. An example of object mapping is an `Order completed` model with a `Products` column that’s in object format.
75-
76-
Example:
77-
78-
```json
79-
{
80-
"product": {
81-
"id": 0001,
82-
"color": "pink",
83-
"name": "tshirt",
84-
"revenue": 20,
85-
"inventory": 500
86-
}
87-
}
88-
```
89-
90-
To send data to a mapping field that requires object data, you can choose between these two options:
91-
92-
Option | Details
93-
------ | --------
94-
Customize object | This enables you to manually set up the mapping fields with any data from the model. If the model contains some object data, you can select properties within the object to set up the mappings as well.
95-
Select object | This enables you to send all nested properties within an object. The model needs to provide data in the format of the object.
96-
97-
> success ""
98-
> Certain object mapping fields have a fixed list of properties they can accept. If the names of the nested properties in your object don't match with the destination properties, the data won't send. Segment recommends you to use **Customize Object** to ensure your mapping is successful.
99-
100-
101-
### Array mapping
102-
To send data to a mapping field that requires array data, the model must provide data in the format of an array of objects. An example is an `Order completed` model with a `Product purchased` column that’s in an array format.
103-
104-
Example:
105-
106-
```json
107-
[
108-
{
109-
"currency": "USD",
110-
"price": 40,
111-
"productName": "jacket",
112-
"purchaseTime": "2021-12-17 23:43:47.102",
113-
"quantity": 1
114-
},
115-
{
116-
"currency": "USD",
117-
"price": 5,
118-
"productName": "socks",
119-
"quantity": 2
120-
}
121-
]
122-
```
123-
124-
To send data to a mapping field that requires array data, you can choose between these two options:
125-
126-
Option | Details
127-
------ | --------
128-
Customize array | This enables you to select the specific nested properties to send to the destination.
129-
Select array | This enables you to send all nested properties within the array.
130-
131-
> success ""
132-
> Certain array mapping fields have a fixed list of properties they can accept. If the names of the nested properties in your array don't match the destination properties, the data won't send. Segment recommends you to use the **Customize array** option to ensure your mapping is successful.
133-
134-
Objects in an array don't need to have the same properties. If a user selects a missing property in the input object for a mapping field, the output object will miss the property.

‎src/connections/reverse-etl/setup.md

Lines changed: 83 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ To add your first model:
4949
4. Choose a column to use as the unique identifier for each record in the **Unique Identifier column** field.
5050
* The Unique Identifier should be a column with unique values per record to ensure checkpointing works as expected. It can potentially be a primary key. This column is used to detect new, updated, and deleted records.
5151
5. Click **Preview** to see a preview of the results of your SQL query. The data from the preview is extracted from the first 10 records of your warehouse.
52-
* Segment caches preview queries and result sets in the UI, and stores the preview cache at the source level. If you make two queries for the same source, Segment returns identical preview results. However, during the next synchronization, the latest data will be sent to the connected destinations.
52+
* Segment caches preview queries and result sets in the UI, and stores the preview cache at the source level.
5353
6. Click **Next**.
5454
7. Enter your **Model Name**.
5555
8. Click **Create Model**.
@@ -103,12 +103,6 @@ To create a mapping:
103103
9. Select the Schedule type for the times you want the model’s data to be extracted from your warehouse. You can choose from:
104104
* **Interval**: Extractions perform based on a selected time cycle.
105105
* **Day and time**: Extractions perform at specific times on selected days of the week.
106-
10. Select how often you want the schedule to sync in **Schedule configuration**.
107-
* For an **Interval** schedule type, you can choose from: 15 minutes, 30 minutes, 1 hour, 2 hours, 4 hours, 6 hours, 8 hours, 12 hours, 1 day.
108-
* 15 minutes is considered real-time for warehouse syncs
109-
* For a **Day and time** schedule type, you can choose the day(s) you’d like the schedule to sync as well as the time.
110-
* You can only choose to start the extraction at the top of the hour.
111-
* Scheduling multiple extractions to start at the same time inside the same data warehouse causes extraction errors.
112106
11. Define how to map the record columns from your model to your destination in the **Select Mappings** section.
113107
* You map the fields that come from your source to fields that the destination expects to find. Fields on the destination side depend on the type of action selected.
114108
* If you're setting up a destination action, depending on the destination, some mapping fields may require data to be in the form of an object or array. See the [supported objects and arrays for mapping](/docs/connections/reverse-etl/manage-retl/#supported-object-and-arrays).
@@ -120,6 +114,88 @@ To create a mapping:
120114

121115
To add multiple mappings from your warehouse to your destination, repeat steps 1-13 above.
122116

117+
### Supported object and arrays
118+
119+
When you set up destination actions in Reverse ETL, depending on the destination, some [mapping fields](/docs/connections/reverse-etl/setup/#step-4-create-mappings) may require data as an [object](/docs/connections/reverse-etl/manage-retl/#object-mapping) or [array](/docs/connections/reverse-etl/manage-retl/#array-mapping).
120+
121+
#### Object mapping
122+
You can send data to a mapping field that requires object data. An example of object mapping is an `Order completed` model with a `Products` column that’s in object format.
123+
124+
Example:
125+
126+
```json
127+
{
128+
"product": {
129+
"id": 0001,
130+
"color": "pink",
131+
"name": "tshirt",
132+
"revenue": 20,
133+
"inventory": 500
134+
}
135+
}
136+
```
137+
138+
To send data to a mapping field that requires object data, you can choose between these two options:
139+
140+
Option | Details
141+
------ | --------
142+
Customize object | This enables you to manually set up the mapping fields with any data from the model. If the model contains some object data, you can select properties within the object to set up the mappings as well.
143+
Select object | This enables you to send all nested properties within an object. The model needs to provide data in the format of the object.
144+
145+
> success ""
146+
> Certain object mapping fields have a fixed list of properties they can accept. If the names of the nested properties in your object don't match with the destination properties, the data won't send. Segment recommends you to use **Customize Object** to ensure your mapping is successful.
147+
148+
149+
#### Array mapping
150+
To send data to a mapping field that requires array data, the model must provide data in the format of an array of objects. An example is an `Order completed` model with a `Product purchased` column that’s in an array format.
151+
152+
Example:
153+
154+
```json
155+
[
156+
{
157+
"currency": "USD",
158+
"price": 40,
159+
"productName": "jacket",
160+
"purchaseTime": "2021-12-17 23:43:47.102",
161+
"quantity": 1
162+
},
163+
{
164+
"currency": "USD",
165+
"price": 5,
166+
"productName": "socks",
167+
"quantity": 2
168+
}
169+
]
170+
```
171+
172+
To send data to a mapping field that requires array data, you can choose between these two options:
173+
174+
Option | Details
175+
------ | --------
176+
Customize array | This enables you to select the specific nested properties to send to the destination.
177+
Select array | This enables you to send all nested properties within the array.
178+
179+
> success ""
180+
> Certain array mapping fields have a fixed list of properties they can accept. If the names of the nested properties in your array don't match the destination properties, the data won't send. Segment recommends you to use the **Customize array** option to ensure your mapping is successful.
181+
182+
Objects in an array don't need to have the same properties. If a user selects a missing property in the input object for a mapping field, the output object will miss the property.
183+
184+
### Null value management
185+
You can choose to exclude null values from optional mapping fields in your syncs to some destinations. Excluding null values helps you maintain data integrity in your downstream destinations, as syncing a null value for an optional field may overwrite an existing value in your downstream tool.
186+
187+
For example, if you opt to sync null values with your destination and an end user fills out a form but chooses to leave an optional telephone number field blank, the existing telephone number you have on file in your destination could be overwritten with the null value. By opting out of null values for your downstream destination, you would preserve the existing telephone number in your destination.
188+
189+
By default, Segment syncs null values from mapped fields to your downstream destinations. Some destinations do not allow the syncing of null values, and will reject requests that contain them. Segment disables the option to opt out of syncing null values for these destinations.
190+
191+
To opt out of including null values in your downstream syncs:
192+
Navigate to Connections > Destinations and select the Reverse ETL tab.
193+
Select the destination and the mapping you want to edit.
194+
Click Edit mapping.
195+
Under the "Optional fields" header, select the field you want to edit.
196+
In the field dropdown selection, disable the Sync null values toggle.
197+
198+
123199
### Edit your mapping
124200

125201
To edit your mapping:

0 commit comments

Comments
 (0)