The Taxonomy package provides instrumentation managers complete control over their instrumentation and end-users more confidence and clarity in their data. It is available as a product line extension for all Enterprise customers and includes three key features: Blueprint, Pipeline, and Architect. You can find these features in the Taxonomy tab in the top navigation bar of your Amplitude organization. Each project will have its own Taxonomy configuration, and you can switch projects with the dropdown:
Table of Contents
- Available Transformations
- Creating a Transformation
- Manage Transformations
- Transformations in Queries
- Export CSV
- Current Limitations
Note: Schema is available as part of the Taxonomy package. Instrumentation planning, data validation, and whitelisting is not included as part of the standard Taxonomy tab in the product.
The Schema contains the definition of the events, event properties, and event properties’ values collected by Amplitude. This feature gives you the ability to categorize and describe your event data, as well as automate the QA process for newly ingested data by proactively surfacing or blocking unintended or malformed data. You can even use Schema as a whitelist of the event data you want Amplitude to collect.
Event data that conforms to the Schema you have created is collected as normal, while violations to the Schema trigger notifications and will appear in the Schema violations view. This helps automate much of the data validation process when implementing new events or properties and can proactively surface corrupted or malformed event data.
Initializing the Schema
For a brand new Project, or one that you have been collecting data in for some time, the first thing you will want to do for that Project is initialize your Schema. The button to do so can be found at the top right hand side of Schema.
Initializing the Schema is your way of telling Amplitude take your current set of ingested data and begin looking out for changes or discrepancies from that point forward. Each time you make an edit to the Schema and publish changes, Amplitude will look out for changes and discrepancies from the newest version.
Editing the Schema
Whenever a set of instrumentation changes are being made to Amplitude, we encourage you to also update your Schema. This ensures that Amplitude can correctly validate the new data and you only receive email alerts for true violations. As an Admin or Manager, click the Edit button in the top right to make updates to your Schema.
In “Edit Mode”, there are several actions you can take:
- Add a new Event Type
- Add an Event Property to an Event
- Change the Type of an Event Property
Create a category using the category selector dropdown. Note: Categories are case-insensitive, meaning you can not have categories with the same name.
To add a description from the Taxonomy Tab, click the input field below the event name from the Events view. To add descriptions for event properties in the Events subtab, please click on "Show Event Properties" to see a dropdown of event properties. Event property descriptions created from this view are not global and will only apply to the event on that particular event. To create a global event property description, use the Event Properties subtab.
Clicking on each event will bring you to an Event Segmentation chart looking at event totals for the selected event over the last 30 days.
The Events subtab will show each visible event that has been seen for a project. This tab allows you to edit descriptions, categorize, and configure various settings for each event type. These settings include modifying the visibility and activity and deleting/blocking event types. Note: We highly recommend reading our documentation here so that you fully understand each type of configuration and the consequences of making these modifications to your data before making any changes.
Asides from Name, Display Name, Activity, and Visibility, this detailed view also provides the following information regarding each event. Please note that you can also sort events according to these metrics:
- 30 Day Queries: The number of times this event has been used on charts in the last 30 days. This will not take into account custom events.
- 30 Day Volume: The number of events Amplitude has received in the last 30 days for a particular event type.
- First Seen: The date this event type was first seen by Amplitude.
- Last Seen: The date this event type was last seen by Amplitude.
- Platform: All platforms this event has been seen on.
You can also toggle event properties in the view or show events that have not had a description added.
You can also block and delete event types from your project under this view, which you can also do from the Settings page. IMPORTANT NOTE: For more information about these features, see the documentation here. Since deleting data is permanent and irreversible, it is highly recommended that you fully understand this feature before using it.
The Event Properties tab will show you all event properties seen for a particular project. It will also show you the amount of queries on a particular event property in the last 30 days as well as the first seen and last seen date. Here you can create a global description for that event property, which means that this description will be the same across all event types the event property is attached to. If you do not wish the description to be global, then you should use the Events subtab to edit the event property description.
The User Properties subtab displays all user properties Amplitude has seen for your project. You can edit the visibility of user properties here. Marking a user property as hidden will remove it from all dropdown menus. The table will also show you the amount of queries on a particular user property in the last 30 days, the first seen date, and the last seen date. You can also block and delete event types from your project under this view, which you can also do from the Settings page. IMPORTANT NOTE: For more information about these features, see the documentation here. Since deleting data is permanent and irreversible, it is highly recommended that you fully understand this feature before using it.
When in a chart, the dropdown is ordered by the categories you have created for each event. Your descriptions will appear inline with each event or event property that you hover over which will enable you to read more information about the event or event property within the chart itself.
You can also add descriptions to events or event properties from directly within a chart. This will allow you to do so without having to navigate away from your chart into the Taxonomy tab.
Pipeline allows instrumentation managers to control the type of data that is accepted in. To navigate to Pipeline, click the Event Planning Center subtab.
You can enable the Waitroom by clicking on the green toggle next to "Enable Waitroom" in the Event Planning center subtab. When enabled, the Waitroom keeps track of new event types that Amplitude sees for the first time. While in the Waitroom, new event types will still be collected and processed but are automatically treated as inactive and hidden from the UI. With the Waitroom enabled, you can catch unexpected events that have not been approved such that they will not contribute to your active user counts or clutter the dropdown experience.
Planned events allow you to map out events in Amplitude before you instrument them. A planned event allows you to set the description, category, and activity before the event is sent to Amplitude.
If the Waiting Room is enabled, then once the event is seen by Amplitude it will be indicated in the "Seen?" column with the number of times it has been fired. Once seen, you can click on the event in order to view it in an Event Segmentation chart and verify that the inbound data appears the way you expected. If the data came through correctly, then you can approve the event from the Waiting Room which will make it visible in the UI and set it to the activity you specified for the planned event. If the data did not come through correctly, then you can reject it which will block the event from future ingestion and keep it hidden and inactive.
If the Waiting Room is not enabled, then Planned Events can be used as a way to document and specify the event types that you ultimately want to instrument.
With the Waiting Room enabled, an Unexpected Events table will appear in Pipeline as well. Events seen in the table here are both inactive and hidden from the UI. Unexpected events are those that are seen by Amplitude for the first time but were not Planned. Amplitude will check to see if the name of the event instrumented is exactly the same as the name of the Planned event and if it is not, then we will display it in the Unexpected Events table. The table will show you the libraries, platforms, 30-day volume, and the first seen date for each unexpected event. You can also click on the event name in order to view it in an Event Segmentation chart and determine whether you want to continue to collect the event or not.
Then, you can approve the event to make it active and visible in the UI or reject it, which will block the event from future ingestion and keep it hidden and inactive. To do this, click the box to the left of the event type and then click "APPROVE" or "REJECT". Note: Rejecting an event type will not delete it. If you wish to delete an unexpected event then you will have to delete it from the Settings page.
The Ingestion Blocklist subtab shows you all blocked events for a certain project. You can unblock events from this view.
Architect allows you to construct transformations on your event data in order to correct common implementation mistakes. To navigate to Architect, click on any of the subtabs.
These transformations are applied at query-time when we generate the results to a query. IMPORTANT NOTE: This does not affect the raw data. Transformations are retroactive, meaning they can be applied to all historical data and can be enabled or disabled at any point in time. This means you can make changes to your event data without having to touch your underlying code base. No matter when you recognize a mistake or want to make a change, you can use a transformation to correct all affected data, both historically and going forward.
Currently, events, event properties, and event property values are supported in the following types of transformations:
- Merge Events: This transformation allows you to merge events together.
- Example: Transform the event 'comment_reply_like' and the event 'comment_share' into the event 'comment'.
- Merge Events into Event Property Values: This transformation allows you to merge events into event property values. You can choose to create a new event and add the old events as event property values or add the old events as event property values to an already existing event.
- Example: Transform the event 'comment_reply_like' and the event 'comment_share' into the event 'commentable_type' with the event properties 'reply like' and 'share'.
- Merge Event Properties: This transformation allows you to merge event properties for all events.
- Example: In some cases, an event property is called 'title' and in other cases, the event property is called 'TITLE' but they represent the same thing on all events. Transform 'title' and 'TITLE' into 'Title', combining the data.
- Rename Value: This transformation allows you to re-assign event property values on all events. This transformation is useful if an event property has a number of misspellings or nonsensical values in dropdowns and will allow you to hide them from the UI or turn them into another value.
- Example: You can reassign the values of 'true' and 'TRUE' to 'True'.
Creating a Transformation
To create a transformation, select the events or properties you want to act on from the list view. If you are only interested in transforming event properties, then you can utilize the Event Properties subtab. Then, click "Transform" and choose the transformation you want to create.
Clicking the "Transform" button will launch "Draft Mode", which allows you to preview the transformation before publishing it to the rest of your organization. You are able to create new charts and look at existing ones to ensure the change will have the desired effect. Note: While the transformation is not published to the rest of your organization, changes you make to existing charts, behavioral cohorts, settings, visibility of events, etc. are not staged and take effect immediately.
Once you have verified the effect of the transformation, you can click "Publish" to push the change live for everyone in your organization.
The Manage Transformations subtab allows you to view all the current transformations in the current project. It will show you the user that created the transformation, when it was created, and what the transformation entails. You can also choose to remove any existing transformations from this subtab.
Transformations in Queries
If you are running a query that uses multiple transformations, then they will be executed in the following order:
- Merge Events
- Merge Events into Event Property Values
- Merge Event Properties
- Rename Value
In general, transformations of transformations are not currently supported. For example, if you merge an event 'App Open' to 'Open App', then you cannot use 'Open App' as the source for another transformation.
In Architect, you have the ability to export your event taxonomy as a CSV file. You can choose to export all your events and event properties or your user properties.
Transformations are not currently supported in the following chart types or features:
Amplitude has 4 different types of permission levels: Admin (A), Manager (M), Member (M), and Viewer (V). For more information on permission levels, see our Permissions documentation.
[AM--] Admins and Managers are able to:
- Describe and categorize events.
- Plan, approve, and reject events.
- Create and undo transformations.
[AMMV] All users can:
- See categories and descriptions.
- See planned and unexpected events.