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: This feature is only available to Enterprise customers who have purchased the Taxonomy product add-on.
To access Blueprint, click on either the Events, Event Properties, or User Properties subtab. Blueprint allows you to provide categories and descriptions for events and properties and was built to be the central source of truth for your instrumentation. Categories are high-level groups you can create for your events to organize them in the sidebar and event selection dropdowns. For example, here we have grouped our events into the categories of Onboarding, [Amplitude], Ads, Critical, Social, and so on. From Blueprint, you can also export CSV files of your event types, event properties, and user properties.
The Events subtab will show each visible event that has been seen for a project. There are 2 views, the detailed view and the list view. The detailed view allows you to edit descriptions for your events and event properties and categorize them, while the list view allows you to configure various settings for each event type. Blueprint allows you to configure the visibility and activity of events, event properties, and user properties, along with 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.
Note: This view will only show events that you can see in dropdowns for your project, so it will not show any hidden or deleted events.
The detailed view provides some information for you regarding each event:
- 30 Day Queries: The number of times this event has been used on charts in the last 30 days.
- 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.
- Platform: All platforms this event has been seen on.
It has 3 sort orders you can use to help find the right events:
- Most Queried: Shows you the event types most often used in charts in the last 30 days. Note: This will not take into account custom events.
- Highest Volume: Shows you the event types ordered by highest event totals in your project in the last 30 days.
- Most Recent: Shows you the new events most recently seen by Amplitude for the first time.
You can also toggle event properties in the view or show events that have not had a description added.
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, make sure you have "Show Properties" checked at the top so that each event's event properties will be shown. 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 list view does not show you event and event property descriptions. It allows you to edit the visibility and activity of multiple events and the visibility of multiple event properties at the same time. The list view will also inform you the first seen and last seen date for each event. 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.