Data Import

Dimension Widening

Accessing Dimension Widening

Only users with Admin privileges at the Web Property level are able to manage Widening Data Sets. Only Admins with new ACLs will be able to grant (view-only) access of uploaded data to other users.

To administer Dimension Widening, click Admin from any screen in Google Analytics. Then, under PROPERTY, click Data Import.

Characteristics of Dimension Widening

  • Dimension Widening and Historic Data: Widening data is applied as hit data is processed. Hits that were processed before the Dimension Widening data set was created will not be widened.
  • Dimension Widening is irreversible: Once widened, hits cannot be un-widened. For this reason, you should create a test view for widening.
  • The maximum upload file size is 1GB.
  • You cannot widen using: custom variables, product dimensions and metrics, campaign dimensions, time-based dimension like hour, minute, etc., geo dimensions like country, city, etc.

Steps to use Dimension Widening

There are four steps to using Dimension Widening.

  1. Decide what data to widen (i.e. what data do you want to add to your reports that is not already captured in web hit data in Google Analytics?).
  2. Create any necessary Custom Dimensions and/or Metrics.
  3. Create a Data Set with one or more associated views (Dimension Widening is view-specific), rules defining what key dimensions and/or metrics you will widen from, and the dimensions and/or metrics you will widen to.
  4. Upload your Dimension Widening data in CSV format.
  5. View data in reports (creating any necessary custom reports you may need)

These steps are explained in detail below, and also in the step-by-step example.

Step 1: Decide what data to widen

Start by think about what reporting you want to add in your reports and analysis. For example, if you are a publisher and/or have a lot of article-based content on your site, it might be helpful to know what authors or subjects of content get the most page views - so you’d like to add author and subject metadata. You might have this data offline, perhaps in a Content Management System or a spreadsheet. Using Dimension Widening, you can import this data into Google Analytics.

Assuming article ID is included in the page URL that is captured in your hits data (in the Page dimension in Google Analytics), you can widen the article ID to author and subject by uploading a file containing article IDs and corresponding author names and subject categories. You can then create custom reports on page views by author ID or subject category to view the widened data.

Fundamental Concepts

Two fundamental concepts you’ll need to understand before you can use Dimension Widening are Key and Widen-To dimensions/metrics.

The Key is the existing Dimension or Metric you will use to widen from. In the above example, article ID is the Key. Note that the key can be a separate dimension OR a component of the Page URL (as in the above example). The Key can be composed of up to 3 dimensions or metrics. Whenever Dimension Widening sees a match between the Key values in a given hit, and one of the Key values in your uploaded data set, it adds the corresponding Widen-To dimensions and/or metrics to the hit.

For example, if the Page URL in given hit contains the article ID “article123” , and you had uploaded a csv file containing the row “article123,John Doe,Farming & Agriculture”, the author name “John Doe” and the subject “Farming & Agriculture” would be added to the hit. Widen-To dimensions/metrics are the data you add to Google Analytics through the widening process. In the above example, Author and Subject are the Widen-To dimensions.

Available Dimensions and Metrics

Currently, Dimension Widening can widen to and from a variety of dimensions and metrics, but not all. You’ll see the full list of dimensions and metrics that can be used in the user interface when you create your Data Set (see Data Set Schema, below) however, currently, you cannot widen using:

  • custom variables
  • product dimensions and metrics
  • campaign dimensions
  • time-based dimensions (hour, minute, etc)
  • geo-dimensions (country, city, etc)
Also note that if you’re using the ga.js based snippet on your site, and you want to widen to dimensions and metrics that don’t exist as standard dimensions or metrics in Google Analytics (e.g. author), you will have to overwrite an existing dimension (for example Page Title). It is strongly recommended that you set up a new view if you’re going to go take that approach. Overwriting in this way will permanently replace the data in that dimension with your Author widening data for the view that you select. In this example, Page Title would now contain Author Name data in the selected view.

However, if you have implemented Universal Analytics (analytics.js), then you can create a new Custom Dimension called “Author” and widen to that dimension. This approach is recommended over the approach described above, if possible.

Step 2: Create any necessary Custom Dimensions or Metrics (Universal Analytics only)

If you need to widen to dimensions or metrics that are not already provided in Google Analytics, AND if you have implemented Universal Analytics (analytics.js), then you should create new Custom Dimensions and/or Metrics (e.g. “Author”) and widen to them.

Step 3: Create and edit your Dimension Widening Data Set

A Dimension Widening Data Set is a container that holds data you upload to Google Analytics. For example, if you want to upload the subject and author information for articles on your site, create a Data Set to hold that specific information. Then, periodically upload the information for new articles to that Data Set. You only create each Data Set once, and can add information to it as you need to.

The Data Set table in Data Import lists the Data Sets that you and others have created for a given Web Property, specifies their types (for example, Cost Data, Dimension Widening), and includes the Custom Data Source ID (API Key) that you’ll need to use in order to upload or delete data from the Data Set via the API.

To create a Data Set:

  1. In Admin, navigate to the account and web property to which you want to upload data.
  2. Click Data Import under PROPERTY to access the Data Set table view.
  3. Click New Data Set.
  4. Select “Dimension Widening” as the Type.
  5. Provide a name for the data source (for example, “article metadata”), and a description.
  6. Select one or more views in which you want to view this data. You must add at least one view to a Data Set in order for it to be active. Removing all views from a Data Set renders the Data Set inactive. If you add a view to an existing Dimension Widening Data Set, the data for that view will be widened as of the date the view was added. Note: For the beta, we strongly recommend that you create a new view and then only link your Widening data set to this new view.
  7. Create a schema for the Data Set (see Data Set Schema, below). Note that if you want to widen to dimensions or metrics that don’t yet exist in your Web Property, such as author ID, you’ll need to create these as Custom Dimensions before you can include them in your Schema.
  8. Set Overwrite to On or Off. (See Overwrite, below.)
  9. Save the Data Set.

The Data Set is now ready for you to upload data, either via the API or by uploading a .csv file. You can come back and edit your Data Set at any time. Note, though that you may not edit the schema if you have uploaded data to the data set; you must first delete all the uploaded data.

Data Set Schema

The Data Set Schema defines how the data you upload into your Data Set will be used to widen the existing data in your hits. The Schema consists of a Key (one or more dimensions and/or metrics) and a set of Widen-To dimensions and/or metrics. To widen hit data, Dimension Widening looks for Key values in hits that match Key values in uploaded data. When a match is found, the corresponding Widen-To values for the matched Key are added to the existing hit data. (Note that Dimension Widening uploaded data may overwrite the hit data; see Overwrite, below.)

  • Key is the dimension or metric or set of dimensions and/or metrics that Google Analytics will use to join your uploaded data with your hit data. For example, if you intend to upload author names and subjects for each article ID, you would specify article ID as the key. The Key is composed of at least one dimension or metric, and can be composed of up to three dimension and/or metrics. For example, Page (URL) could be a key dimension, as could a custom dimension that you have defined, or a combination of Page (URL) and one or two custom dimensions. You can refine one or more dimensions in the key using Regex. You can also refine Page by query parameter. Read Upload Example: Dimension Widening to learn more.
  • Widen-To Dimensions are the dimensions for which you want to upload data to join to your hit data. For example, if you intend to provide author name and subject for each article ID, you would specify Author and Subject as Widen-To Dimensions, after having specified article ID as the key. For example, Page (URL) could be a key dimension, as could a custom dimension that you have defined, or a combination of Page (URL) and one or two custom dimensions. A list of available Key dimensions is provided in the dropdown menu in the Schema builder. You can refine one or more dimensions in the Key using Regex (regular expressions). You can also refine Page by query parameter. Read Upload Example: Dimension Widening to learn more.
  • Widen-To Metrics are the metrics for which you’ll be providing values that map to values of the key. For example, if the key is SKU, and you intend to provide a price for each value of SKU, you would specify Price as the metric. A list of available metrics is provided in the dropdown menu. The available Widen-To Metrics will vary based on what you chose as your Key dimensions.

You may include up to a total of nine dimensions and/or metrics in your schema, including Key and Widen-To dimensions and metrics

Overwrite

When you define the schema, you'll need to specify whether or not your uploaded data values should override the data values that Google Analytics collects from the hits. If you select On, Google Analytics will always use your uploaded data values, even when they conflict with hit values. If you select Off, Google Analytics will use data values from the hit. For example, if you upload Price data for each SKU and set Overwrite to On, your uploaded Price values will overwrite the Price values from ecommerce transaction hits. If you set Overwrite to Off, the Price values from the transaction will be used.

While it's possible to change your Overwrite setting later on, keep in mind that your existing data will not be reprocessed. It's best to make a careful decision when you define the schema.

Locked (Uneditable) Schemas

Once you have uploaded your first file to a Data Set, the schema will become locked for editing. In order to make it editable again, you must first delete all the data uploaded to the Data Set.

Step 4: Upload Widening Data

You can upload data manually, or programmatically via the API. In either case, you’ll need to create a properly formatted .csv file containing your data.

Formatting Your Data File for Upload

Your data file should be in a .csv file containing a column for each of the dimensions / metrics you specified when you created your schema: one column for each key dimension, and one column for each Widen-To dimension or metric.

The first row of your .csv file is the header row. The header row lists each field (dimension/metric) in your file. Note, however, that your header row must list each field by its internal name, not the dimension/metric names that you selected in the UI when you defined your schema. To get the internal names for the header, click the link to your Data Set in the Data Sets Table view. You will see the corresponding internal names to the right of the display names. You may also click the Get Schema button at the bottom of the schema for a header that you can copy and paste for your csv file, or download a csv file template that has the correct header row.

For custom metrics of type currency, provide your data in micro units (for example, enter 1000000 for 1 dollar.)
Uploading Your Data Files

To upload data via the API, you’ll need to use the Custom Data Source ID (API Key) for the Data Set. You can find the Custom Data Source ID (API Key) next to the Data Set name in the Data Sets table. For information on how to use the API to upload, refer to the developer reference PDFs.

To manually upload data, click Manage Uploads next to the Data Set name In the Data Set table to access the Manage Uploads table view. The Manage Uploads table lists the files that you and others have uploaded for a given Data Set. Click the Upload File button to upload one or more csv files.

Processing Time and Status

Uploaded data needs to be processed before it can show up in reports. The processing status of each uploaded file is shown in the Manage Uploads table.

Once a file has uploaded successfully, it appears in the Manage Uploads table with the status “Pending”. To check the status of a file, click the “Refresh” button at the top of the Manage Uploads table.

Once a file has processed successfully, its status changes from “Pending” to “Completed”. Note: Once processing has completed, it takes up to 24 hours before the widening data begins to be applied to incoming hit data.

If a file fails to process, its status changes from “Pending” to “Failed”. See below for more information on Failed files.

Upload Quota

The following upload quotas apply:

  • 50 uploads / day / Web Property
  • 1TB total data uploaded per Web Property (Google Analytics Premium)
  • 50 Data Sets per Web Property (includes Dimension Widening and Cost Data Sets)
  • 1GB maximum upload file size

Failed Uploads and Upload Errors

If errors are found in an uploaded file, none of the data in the file will be processed, and the status of the file will show as “Failed”. Click the “view errors” link to see error messages. For a list of errors, see Upload Errors: Dimension Widening

Step 5: View data in reports

You may want to create a custom report to view the data you add through Dimension Widening. For example if you have widened from article ID (within the Page URL) to Author Name (a custom dimension you have created), this custom dimension will not appear in standard reports. To see the total number of pageviews per author, you would create a custom report with one metric (Pageviews) and one dimension (Author). Remember that Uploaded data needs to be processed before it can show up in reports. Once processing is complete, it may take up to 24 hours before the widening data will begin to be applied to incoming hit data.

Widening with Filters and Views

Data Sets and Views

You must add at least one view to a Data Set in order for it to be active. Removing all views from a Data Set renders the Data Set inactive. If you add a view to an existing Dimension Widening Data Set, the data for that view will be widened as of the date the view was added.

Widening and Filters

Widening happens before filtering; take this into account when applying filters.

Adding and Deleting Data in a Data Set

Deleting Upload Data Files

You may delete one or more files of data uploaded to your Dimension Widening Data Set. You can delete multiple files at a time by selecting them in Manage Uploads view, and clicking the Delete Selected button at the top of the table. Deleted data will no longer be used for widening, but data from remaining files will continue to be used for widening.

Duplicate Keys and Collisions

Key Collisions (Duplicate Keys)

Within a given Data Set, if you upload a file containing a key that has already been uploaded in an earlier file to the same Data Set, the widening values from the last processed file will take precedence. If you intend to upload files with duplicated keys, and the order of precedence is important to you, you should wait until each file has completed processing before uploading a subsequent file.

Empty Strings

An empty string will appear as “not set” in reports.

Limitations to Dimension Widening

Historic Data

Dimension Widening data is applied as hit data is processed. Hits that have already been processed before the data set is created will not be widened.

Widening is Irreversible

Dimension Widening is irreversible; once widened, hits cannot be un-widened. For this reason, you should always create a test view for widening.

Real-Time Reporting Not Supported

Real-Time reports do not display widened dimensions.