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
- 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.
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.
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:
- Platform: All platforms this event has been seen on.
- 30 Day Volume: The number of events Amplitude has received in the last 30 days for a particular event type.
- 30 Day Queries: The number of times this event has been used on charts in the last 30 days.
It also 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.
When in a chart, the dropdown is ordered by the categories you have created for each event. A blue information icon will appear inline with each event that you can hover over to show the description and more information about the event type.
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, click the input field below the event name from the Events view. To add descriptions for event properties, make sure you have "Show Properties" checked at the top so that each event's event properties will be shown.
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 is similar to the Settings page. For more information about these features, see the documentation here.
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.
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.
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.
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.