> For the complete documentation index, see [llms.txt](https://docs.finout.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.finout.io/user-guide/inform/virtual-tags/dictionary-virtual-tags.md).
# Dictionary Virtual Tags
### Overview
[Virtual Tags](https://docs.finout.io/user-guide/inform/virtual-tags) let you allocate and classify cloud costs using rule-based conditions. Dictionary Virtual Tags take a different approach: instead of writing rules, you supply an external mapping file that maps source values directly to destination values in a one-to-one relationship.
This is designed for situations where the number of distinct values is too large to manage through manual rules — such as mapping thousands of application IDs to application names, or mapping email addresses to squads or cost centers. Finout reads the mapping file from your S3 bucket daily, so any updates you make to the file are automatically reflected without any configuration changes on your end.
**When to use Dictionary Virtual Tags:**
* You need to map a high-cardinality dimension (hundreds or thousands of values) to a human-readable label.
* Your mapping data already lives in a system of record that can export a CSV file.
* Your mapping changes periodically and you want Finout to stay in sync automatically.
* You need time-bounded mapping — where the same source value maps to a different destination depending on the date.
{% hint style="info" %}
**Note:** Each dictionary Virtual Tag is a strict one-to-one mapping. A single source value maps to exactly one destination value. If you need to map values from multiple dimensions (e.g., AWS Account ID and GCP Project ID), first combine them into a single [Custom Virtual Tag](https://docs.finout.io/user-guide/inform/virtual-tags/custom-virtual-tags), then use that Virtual Tag as the source dimension for your dictionary.
{% endhint %}
### How It Works
You provide a CSV mapping file stored in an S3 bucket. Finout reads the file daily through a [Read Only Amazon S3 Bucket Endpoint](https://docs.finout.io/settings/endpoints/amazon-s3-bucket-endpoint) and derives a Virtual Tag from the mappings defined in the file. The tag is then available for filtering and grouping across MegaBill and all reporting surfaces just like any other Virtual Tag.
If you upload an updated version of the file to the same S3 prefix, Finout automatically picks up the latest file on the next daily sync.
### Prerequisites
Before setting up a Dictionary Virtual Tag, make sure you have:
* An S3 bucket in your AWS account where you can store the mapping file
* Permission to create an IAM role and inline policy in that AWS account
* A mapping file prepared in the required format detailed below
### Setup
#### Step 1 — Create the Mapping File
Prepare a CSV file that defines how each source value maps to a destination value.
**File Format**
* Only CSV files are supported. Finout will not process files in any other format.
* The file must use the following column headers exactly as shown. Headers are case-sensitive.
**Standard mapping**
Use this when each source value always maps to the same destination:
| Source | Destination |
| ------- | ----------- |
| value-a | Label A |
| value-b | Label B |
**Time-bounded mapping**
Use this when a source value should map to different destinations depending on the date:
| Source | Destination | From | To |
| ------- | ----------- | ---------- | ---------- |
| value-a | Label A | 2024-01-01 | 2024-06-30 |
| value-a | Label B | 2024-07-01 | |
{% hint style="info" %}
**Column details:**
* `Source` — the value as it appears in your MegaBill dimension. Must be an exact match; partial or fuzzy values will appear as *Untagged*.
* `Destination` — the label Finout assigns when the source value matches.
* `From` — the start date for this mapping row (inclusive). Required when using time-bounded mapping.
* `To` — the end date for this mapping row (inclusive). Leave empty if the mapping has no upper limit and should apply indefinitely from the `From` date.
{% endhint %}
**Date Format**
The date formats listed below are supported. Use a consistent format throughout the file and include the format you used when contacting support in Step 4 — Finout configures the mapping based on the format you specify.
* `YYYY-MM-DD`
* `MM/DD/YYYY`
* `DD/MM/YYYY`
**File Size & Validations**
* The file size limit is **500,000 rows**.
* Overlapping date ranges for the same source value are not permitted and will cause validation to fail.
* If time-bounded mapping is enabled, every row must have a `From` date. Rows with a missing `From` date will fail validation.
#### Step 2 — Upload the Mapping File to S3
Upload your CSV file to an S3 bucket in your AWS account. Keep the following in mind:
* **Use a dedicated prefix for each mapping file.** For example: `s3://your-bucket/dictionary/email-to-squad/`.
* Each dictionary Virtual Tag reads from a single **S3 prefix**. For updates, you can either replace the mapping file with a new version or upload an additional file if preferred. In the case of multiple files, Finout will read the one that was recently modified.
If you need multiple dictionaries (e.g., email-to-squad and email-to-cost-center), create a dedicated a dedicated prefix for it, and register it as a seperated S3 endpoint in Finout (see Step 3 below).
#### Step 3 — Create an S3 Endpoint in Finout
Finout connects to your S3 bucket through a Read Only Amazon S3 Bucket Endpoint. Follow the [Amazon S3 Bucket Endpoint guide](https://docs.finout.io/settings/endpoints/amazon-s3-bucket-endpoint) to create one, making sure to select **Read Only** under Bucket Access.
Give the endpoint a clear, descriptive name — you will reference it by name when contacting support in Step 4.
#### Step 4 — Contact Finout Support to Complete Setup
Once the mapping file is in place and the S3 endpoint is created, contact your customer success manager or email with the following information:
| Detail | Description |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **S3 Endpoint Name** | The name you gave the endpoint in Step 3 |
| **File Name** | The exact name of your CSV file (e.g., `dict_email_to_squad.csv`) |
| **Date Format** | The date format used in your `From` / `To` columns (e.g., `YYYY-MM-DD`) — only required if using time-bounded mapping |
| **Time-Bounded Mapping** | Whether your file includes `From` / `To` columns (`Yes` or `No`) |
Finout will configure the Dictionary Virtual Tag on your account and notify you when it is ready.
### Result
Once configured, the Dictionary Virtual Tag appears in your Virtual Tags list and is immediately available for filtering and grouping across MegaBill and all reporting surfaces. Values from the `Destination` column become the tag values. Any source value not present in the mapping file appears as *Untagged.*
### FAQs
**How often does Finout sync the mapping file?**
Finout processes the file once per day. In the prefix includes a single file, Finout will reingest based on modification date. In case of multiple files in the predix, a single file will be ingested, based on the modiciation date as well.
**What happens if a source value in my cost data is not in the mapping file?**
It appears as *Untagged* in Finout.
**Can I have multiple dictionary Virtual Tags for the same account?**
Yes. Each dictionary Virtual Tag maps to one file in one S3 prefix. Create a separate file, prefix, and dictionary Virtual Tag configuration for each mapping you need.
**Can I map a source value to multiple different destinations?**
No. Each dictionary Virtual Tag has a single `Source` column and a single `Destination` column — one mapping per file. If you need the same source dimension to produce multiple different destination tags (for example, AppSpace ID → Team and AppSpace ID → Cost Center), create a separate mapping file and a separate dictionary Virtual Tag for each. Each file should live in its own dedicated S3 prefix:
```
your-bucket/dictionary/appspace-to-team/mapping.csv
your-bucket/dictionary/appspace-to-costcenter/mapping.csv
```
**Can I use a Virtual Tag as the source dimension for a dictionary?**
Yes. Finout supports Virtual Tags as source values in a mapping file, in addition to native MegaBill dimensions. This is useful when you need to combine multiple dimensions — for example, merging AWS Account ID and GCP Project ID into a single Virtual Tag and then building a dictionary on top of it.
**What happens if my mapping file fails validation?**
The previous version of the mapping file remains active, and your Virtual Tag continues to serve values from the last successful file. Finout will notify you of any validation errors.
**What do I do if a row has a `To` date but no `From` date?**
Rows with a `To` date but no `From` date will fail validation. When using time-bounded mapping, every row must include a `From` date. The `To` date is optional — leave it empty if the mapping should apply indefinitely.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.finout.io/user-guide/inform/virtual-tags/dictionary-virtual-tags.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.