User Guides
Send query results to Amplitude¶
Amplitude is a self-service digital analytics platform to understand your users, drive conversions, and increase engagement, growth and revenue.
Beta
The Amplitude connector is in beta. Contact your Amperity representative to learn more.
The Amplitude connector sends user properties, events, group properties, audiences, and deletion requests from Amperity into an Amplitude project. What each row becomes is set by the Write mode setting on the orchestration that sends to this destination, and an orchestration performs a single write mode for the entire run.
Each row is addressed by a single identity. The query results must include a column named identity_value that carries that identity: the Amplitude user_id in user-properties and events modes, the group’s value in group-properties mode, the cohort member in cohort-push mode, or the identity to delete in user-deletion mode.
user-properties, group-properties, and cohort-push modes sync incrementally. Amperity sends only what changed since the last successful run and reports unchanged rows as sent from cache. events and user-deletion modes have no incremental tracking — they process every row in the query results on each run, so scope those queries to the rows you intend to send.
Note
This destination uses several of Amplitude’s REST APIs : the HTTP V2 and Batch Event Upload APIs for events, the Identify and Group Identify APIs for user and group properties, the Behavioral Cohorts API for audiences, and the User Privacy API for deletion requests.
The steps that are required to send user properties, events, group properties, audiences, and deletion requests to Amplitude from Amperity.
Caution
This destination is available for sending query results to Amplitude after it is configured by a Datagrid Operator or your Amperity representative.
If this destination cannot be selected for orchestrations ask your Datagrid Operator or Amperity representative to configure a destination for sending query results to Amplitude.
Build query¶
Build a query that returns a column named identity_value, along with whatever else the destination’s write mode sends.
The query results must include a column named identity_value. What else the query needs depends on the destination’s write mode:
user-properties and group-properties send every other column in the results as a property, so return only the columns you want written.
events also needs the two columns named by the Event name column and Timestamp column settings. Every other column becomes an event property.
cohort-push and user-deletion send nothing but
identity_value. Other columns in the results are ignored.
Return the identifier that Amplitude knows each user by, aliased to identity_value. The examples below use the Amperity ID; use a different column if your Amplitude project identifies users by one of your own IDs.
The following example returns predicted-value attributes for a user-properties orchestration. Every column other than identity_value is written as a user property:
SELECT
amperity_id AS identity_value,
predicted_customer_lifetime_value_tier,
predicted_clv_next_365d,
predicted_customer_lifecycle_status,
days_since_last_order
FROM Customer_360
WHERE amperity_id IS NOT NULL
A row whose identity_value is empty is dropped and reported as a failed row. In user-properties and events modes, so is a row whose identity_value is shorter than five characters. Five characters is Amplitude’s documented minimum id length for event ingest, and Amperity applies it to user properties as well.
The following example returns purchases for an events orchestration whose Event name column is event_name and whose Timestamp column is event_time. Every column other than those two and identity_value becomes an event property:
SELECT
amperity_id AS identity_value,
'purchase' AS event_name,
order_datetime AS event_time,
item_revenue,
product_category,
store_id
FROM Unified_Itemized_Transactions
WHERE amperity_id IS NOT NULL
Return the event time as an ISO 8601 timestamp that carries a time zone, as a date, or as a number already in epoch milliseconds. A datetime column such as order_datetime already arrives in a form Amplitude accepts.
Caution
A number in the timestamp column is sent to Amplitude unchanged. A value in epoch seconds lands in 1970 and a value in epoch microseconds lands far in the future, in both cases with no error and no warning. Multiply seconds by 1000 in the query, or return an ISO 8601 string instead.
A timestamp value that is empty, or that cannot be read as any of those three forms, does not fail the row — Amplitude records that event at the time it was received instead of when it happened.
Important
Amperity does not send Amplitude a deduplication key with an event, so an event that is sent twice is counted twice. An events orchestration re-sends every row in the query results on each run, so scope the query — with a date filter, for example — so that a run returns only events that have not been sent before.
Add orchestration¶
An orchestration defines the relationship between query results and a destination, including the destination and the frequency at which an orchestration runs.
Important
Select Attribute updates only on the orchestration for every write mode except cohort-push. An orchestration that is missing this setting fails before any data is sent.
Open the Activations page, select the Orchestrations tab, and then click the Add orchestration button. This opens the Add orchestration dialog box.
From the Object type dropdown, select Query.
From the Object dropdown, select the query for which results is sent to Amplitude.
From the Destination dropdown, select a destination that is configured for sending data to Amplitude.
Verify all settings.
Set the workflow to Manual. You can change this to automatic later, after verifying the end-to-end workflow.
Click Save.
Run orchestration¶
Run the orchestration manually to validate that it works.
Open the Activations page, select the Orchestrations tab, and then open the menu for the Amplitude orchestration. Select Run.
The Status column for the orchestration updates to say “Waiting to start”, after which the notifications pane updates to include a notification that shows the current status.
When the orchestration has run successfully, the status is updated to “Completed”.