Creating Custom Labels with Data Mapping

Overview

Data mapping allows you to provide a CSV or Bigquery table to quickly add one or more new output key/value pairs based on one or more input matches.

Step 1: Create a New Data Mapping Label

Go to Custom Labels > Create Custom Label.

Enter a Rule Title to describe your mapping (e.g., “Map Projects → Business Units”).

Select the Data Mapping template as your creation method.

Key options (callouts in screenshot):

Rule Title – Enter a descriptive name to know what this custom label does.

Data Mapping – Select this template type.

CSV/BigQuery selector – Choose whether you’ll upload a CSV file or reference a BigQuery table.

Upload area – Drag & drop your file, or paste a BigQuery table path.

Attach file – Confirm the upload.

Save Draft – Save now and revisit later.

Step 2: File Format Requirements

Your file must follow a strict structure:

File type: CSV (≤ 20 MB) or BigQuery table.

First column (required): Primary input key (e.g., AccountID, BillingAccountName).

Remaining columns: Output labels (e.g., BusinessUnit, Team, App_Name).

Example CSV:

SubAccountName,Region,BusinessUnit,Environment proj-123,us-east1,Finance,Production proj-456,us-west2,Marketing,Development proj-789,europe-west1,R&D,Staging

Step 3: Configure Mappings (Preview Screen)

Once you click Attach file, you’ll move to the mapping preview page. This step allows you to tell the system which columns are inputs vs. outputs, and link input fields to cost dimensions in your billing data.

What you’ll do here:

Input File Column name – Each column header from your file is listed.

Flow selector – Choose whether the column is an INPUT (lookup key) or an OUTPUT (new label).

Match with Cost Data Field – For INPUTs, select which billing dimension (e.g., BillingAccountName) the column should match against.

Preview table – Shows how rows will be interpreted (inputs → outputs).

Example shown above:

Inputs: BillingAccountName (required first input key name)

Outputs: SubAccountName (required first output key name) Team (optional second output key name) and App_Name (optional third output key name).

Selection Input Preview: displays the top rows your file and any changes you made to the mappings (example: Account name > BillingAccountName) to confirm you will get your desired configuration.

Validation Rules

Input headers must exactly match internal dimension names (case-sensitive), this can be manually set after uploading.

Each row’s input values must exactly match billing data values.

Duplicate or conflicting rows will block publishing.

Blank outputs are allowed (treated as “no label assigned”).

Invalid file formats, hidden characters, or renamed headers will cause an error.