.CSV import and export

This article helps you:

  • Manage the events, event properties, and user properties of your tracking plan via .CSV import and export

  • Understand the data fields and values needed for importing and how they compare to exported files

In Amplitude Data, you can view and manage event types, event properties, and user properties piece by piece, but you may want to see a holistic view of your entire tracking plan's schema and make bulk changes to the schema instead.

Amplitude lets you import and export your schema via .CSV to plan new events and properties, edit categories and descriptions, and generate bulk changes.

This article will discuss the differences between using import and export for events and event properties versus user properties.

Events and event properties

Follow the below steps to import or export events and event properties:

  1. Navigate to Data, and click Events under your tracking plan in the left side pane.

  2. If you wish to import, click the import icon to open the import modal.

  3. If your import file is ready to upload and follows the expected schema for events and event properties, you can drag and drop your .CSV file or click Upload and choose the file from your desired location. If not, click template to download a template .CSV to update for importing.

    The imported events and event properties will appear in a branch named import.

  4. Once you’re sure the imported tracking plan updates are correct, you can merge the changes back into the main branch.

  5. If you want to export events and event properties from your tracking plan, click the export icon instead.

  6. In the export modal that appears, choose whether to download your tracking plan’s schema or a .CSV file template. Then, click Download.

Downloaded .CSV files of your tracking plan contain additional fields not required for import. The next section will define the events and event properties .CSV import file structure and the additional columns seen in the exported file.

Note

The import and export features do not support custom events, transformations, nor default Amplitude entities.

Events and event properties file schema

The events and event properties .CSV file requires a specific schema for a successful import. The table below highlights the required schema by entity type. There are some things to note: 

  • The file's header must contain all listed fields.
  • The fields can be in any order, but their names and values must be exact in spelling and capitalization to ensure a successful import process.
  • Some fields require a value depending on entity type, and are notated as such in the table below.

Action

  • Definition: Action to perform on a particular entity
  • Values:
    • Ignore: No changes will be made to the entity nor its subproperties
    • Remove: Event and property groups can be removed from the tracking plan. The remove value will not affect individual properties. Removing an event or property group will disassociate related properties, and will change a live property’s status to unexpected. The remove value does not delete an entity, nor does it stop ingestion.
    • <blank>: Creates or updates an entity and it’s associated sub-entities
  • For events, event properties, property groups property group properties

Array min items

  • Definition: Minimum number of items for a property with an array property value type
  • For event properties and property group properties

Array max items

  • Definition: Maximum number of items for a property with an array property value type
  • For event properties and property group properties

Array unique items

  • Definition: Denotes if an array property value type has unique items
  • Values:
    • TRUE: Array has unique items
    • <any>: Assumes array does not have unique items
  • For event properties and property group properties

Const value

  • Definition: Const value for properties with a const property value type
  • For event properties and property group properties

Enum values

  • Definition: Enum values for properties with an enum property value type
  • Format: Separate each enum value with a comma
  • For event properties and property group properties

Event activity

  • Definition: Description of an event’s activity
  • Values:
    • Active
    • Inactive. Marking an event as inactive is applied retroactively and immediately, and will exclude the event from the Any Active Event metric.
  • For events

Event category

  • Definition: Category of an event
  • For events

Event display name

  • Definition: Only applicable to optional display names of events
  • For events

Event property name

  • Definition: Name of the property
  • Required for event properties and property group properties

Event source

  • Definition: Sources associated with the event
  • For events

Number property value min

  • Definition: Minimum value of a property with number property value type
  • For event properties and property group properties

Number property value max

  • Definition: Maximum value of a property with number property value type
  • For event properties and property group properties

Number is integer

  • Definition: Denotes if a property with number property value type is an integer
  • Values:
    • True: Property is an integer
    • False or <blank>: Property is not an integer
  • For event properties and property group properties

Object type

  • Definition: Entity type
  • Values:
    • Event
    • Property Group
  • Required for events and property groups

Object name

  • Definition: Name of the event or property group
  • Required for events and property groups

Object description

  • Definition: Description of the entity
  • For events and property groups

Property type

  • Definition: Type of property associated with the event
  • Values:
    • Event Property
    • Event Property Group
  • Required for events

Property group names

  • Definition: Property group that is associated with the event
  • For events

Property description

  • Definition: Description of the property
  • For event properties and property group properties

Property value type

  • Definition: The value type of an event property or property group property
  • Values:
    • string
    • number
    • boolean
    • any
    • enum
    • const
  • For event properties and property group properties

Property required

  • Definition: Denotes the required status of the property
  • Values:
    • True: Property is required
    • False or <blank>: Property is optional
  • For event properties and property group properties

Property is array

  • Definition: Denotes if the property is an array
  • Values:
    • True: Property is an array
    • False or <blank>: Property is not an array
  • For event properties and property group properties

Property regex

  • Definition: Regular expression (Regex) values for properties with a string property value type
  • For event properties and property group properties

String property value min length

  • Definition: Minimum length of a property with string property value type
  • For event properties and property group properties

String property value max length

  • Definition: Maximum length of a property with string property value type
  • For event properties and property group properties

Tags

  • Definition: Tags associated with an event
  • Format: separate each tag with a comma
  • For events

Additional fields .CSV export of events and event properties

The following list includes additional fields found in the .CSV export of your tracking plan’s events and event properties.

Action

  • Definition: The default action to perform on a particular entity. This field exists in the import template, but the downloaded file will automatically include default values.
  • Values:
    • Ignore: The user property is unexpected, blocked or deleted.
    • <blank>: The user property is planned or live.
  • For events, event properties, property groups property group properties

Event first seen

  • Definition: The date on which the event was first seen.
  • Format: mm/dd/yyyy
  • For events

Event last seen

  • Definition: The date on which the event was last seen.
  • Format: mm/dd/yyyy
  • For events

Property first seen

  • Definition: The date on which the property was first seen.
  • Format: mm/dd/yyyy
  • For property groups

Property last seen

  • Definition: The date on which the property was last seen.
  • Format: mm/dd/yyyy
  • For property groups

User properties

Follow the below steps to import or export user properties:

  1. Navigate to Data, and click Properties under Tracking Plan in the left side pane. Then click User Properties.
  2. Click the import icon to open the import modal.
  3. If your import file is ready to upload and follows the expected user properties schema, you can drag and drop your .CSV file or click Upload and choose the file from your desired location. If not, click template to download a template .CSV to update for importing.

The imported events and event properties will appear in a branch named import.

  1. Once you’re sure the imported tracking plan updates are correct, you can merge the changes back into the main branch.
  2. If you want to export user properties from your tracking plan, click the export icon instead.
  3. In the export modal that appears, choose whether to download your tracking plan’s schema or a .CSV file template. Then, click Download.

The next section will define the user properties .CSV import file structure and the additional columns seen in the user properties export.

User properties file schema

The list below highlights the required schema for the user properties .CSV file import. There are some things to note: 

  • The file's header must contain all listed fields.
  • The fields can be in any order, but their names and values must be exact in spelling and capitalization to ensure a successful import process.
  • Some fields require a value and are notated as such in the table below.

Action

  • Definition: Action to perform on a particular user property
  • Values:
    • Ignore: No changes will be made to the user property.
    • Remove: User property will be removed from the tracking plan. The remove value does not delete a user property, nor does it stop its ingestion.
    • <blank>: Creates the user property if it did not already exist; or updates the user property if it did exist.

Array min items

  • Definition: Minimum number of items for a property with an array property value type

Array max items

  • Definition: Maximum number of items for a property with an array property value type

Array unique items

  • Definition: Denotes if an array property value type has unique items
  • Values:
    • TRUE: Array has unique items
    • <any>: Assumes array does not have unique items

Const value

  • Definition: Const value for properties with a const property value type

Enum values

  • Definition: Enum values for properties with an enum property value type
  • Format: Separate each enum value with a comma

Number property value min

  • Definition: Minimum value of a property with number property value type

Number property value max

  • Definition: Maximum value of a property with number property value type

Number is integer

  • Definition: Denotes if a property with number property value type is an integer
  • Values:
    • True: Property is an integer
    • False or <blank>: Property is not an integer

Property type

  • Definition: User property type
  • Values: User property (required)

Property name

  • Definition: Name of the user property
  • This value is required

Property description

  • Definition: Description of the user property

Property value type

  • Definition: The value type of a user property
  • Values:
    • string
    • number
    • boolean
    • any
    • enum
    • const

Property is array

  • Definition: Denotes if the property is an array
  • Values:
    • True: Property is an array
    • False or <blank>: Property is not an array

Property regex

  • Definition: Regular expression (Regex) values for properties with a string property value type

String property value min length

  • Definition: Minimum length of a property with string property value type

String property value max length

  • Definition: Maximum length of a property with string property value type

Additional fields in .CSV export of user properties

The following list includes additional fields found in the .CSV export of your tracking plan’s user properties.

Action

  • Definition: The default action to perform on a particular entity. This field exists in the import template, but the downloaded file will automatically include default values.
  • Values:
    • Ignore: The user property is unexpected, blocked or deleted.
    • <blank>: The user property is planned or live.

Property first seen

  • Definition: The date on which the property was first seen.
  • Format: mm/dd/yyyy

Property last seen

  • Definition: The date on which the property was last seen.
  • Format: mm/dd/yyyy
Was this page helpful?

Thanks for your feedback!

June 19th, 2024

Need help? Contact Support

Visit Amplitude.com

Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.