How to Create a Data Dictionary in Tableau

A great Tableau dashboard can feel like magic, showing complex data in a simple, visual story. But when your team starts asking, "Wait, is ‘revenue’ gross revenue or net?" or "What exactly does ‘active user’ mean?" the magic disappears. This article explains how to build a data dictionary directly within Tableau, creating a single source of truth that builds trust and makes your dashboards more useful for everyone.

What is a Data Dictionary (And Why Bother Creating One)?

Think of a data dictionary as a definitive "about" page for your data. It’s a central document or reference guide that clearly defines every data field in your dataset. It answers critical questions like:

• What is this field? A plain-English definition (e.g., "Customer LTV = The total predicted revenue a customer will generate over their lifetime.")
• How is it calculated? The specific formula for a calculated field (e.g., SUM([Profit]) / SUM([Sales]))
• What data type is it? Text, number, date, etc.
• Where did it come from? The original source table or system (e.g., Salesforce Opportunity Object)

Ignoring this step is a common source of data chaos. Imagine two marketers building separate reports on "conversion rate." One calculates it as Website Signups / Sessions, while the other uses Purchases / Unique Visitors. They present wildly different numbers in a meeting, confusion erupts, and suddenly nobody trusts the data. A data dictionary prevents this by creating a shared understanding of what every metric actually means.

It's your best defense against ambiguity, ensuring consistency, speeding up onboarding for new team members, and building organization-wide trust in your reporting.

Building an Interactive Data Dictionary Inside Tableau

While you could maintain a data dictionary in an external spreadsheet, building it right into your Tableau workbook makes it accessible and keeps the context alongside the visuals. We're going to build a simple, interactive definitions page using features you already have in Tableau: calculated fields and parameters. This approach turns your workbook into a self-contained, self-explanatory analytics tool.

Here’s a step-by-step breakdown of how to create one for your key performance indicators (KPIs).

Step 1: Identify Your Core Metrics

Before you build anything, decide which metrics need a dictionary. Don't try to document 500 fields at once. You'll get overwhelmed and give up. Start with the most important KPIs that appear on your main executive or team dashboards.

A good starting list might include 5-10 foundational metrics, such as:

• Total Sales
• Profit Margin
• Customer Acquisition Cost (CAC)
• Customer Lifetime Value (LTV)
• Marketing ROI
• Monthly Active Users (MAU)
• Conversion Rate

The goal is to provide clarity for the numbers your team relies on most. You can always expand your dictionary later.

Step 2: Create a Parameter to Select a KPI

Parameters in Tableau are workbook variables, like a dropdown menu, that users can control. We will use a parameter to allow users to select which KPI definition they want to see.

1. In the top-left Data pane, click the small dropdown arrow next to the search bar and select Create Parameter...
2. Name the parameter clearly, something like "Select a KPI to Define"
3. For Data type, choose String
4. For Allowable values, choose List
5. In the List of values section, manually add the name of each core metric you identified in Step 1. Your list should have two columns: "Value" and "Display As." For simplicity, you can make both columns identical.
6. Click OK. You should now see your new parameter in the bottom-left of the Data pane under the "Parameters" section. Right-click on it and select Show Parameter to make the dropdown menu visible on your worksheet.

Step 3: Create Calculated Fields for Definitions and Formulas

Now we’ll create two calculated fields that dynamically change based on the KPI selected in the parameter. One will show the plain-English definition, and the other will show the calculation logic.

Creating the 'KPI Definition' Field:

1. Click the dropdown arrow in the Data pane and select Create Calculated Field...
2. Name it "KPI Definition"
3. Use a <code>CASE</code> statement that links each value from your parameter to its corresponding definition. The structure looks like this:

CASE [Select a KPI to Define]
WHEN "Total Sales"
THEN "The total gross revenue from all completed orders before discounts, returns, or taxes. This reflects overall sales volume from the chosen period."

WHEN "Profit Margin"
THEN "The percentage of revenue that remains after subtracting the cost of goods sold (COGS). It is calculated as (Sales - COGS) / Sales. This measures overall profitability."

WHEN "Customer Acquisition Cost (CAC)"
THEN "The average cost to acquire a single new customer. It's calculated by dividing the total marketing and sales expenses over a period by the number of new customers acquired in that period."

END

Add a <code>WHEN...THEN...</code> clause for each KPI in your parameter list. Use clear, simple language that someone outside your department can understand. Click OK.

Creating the 'KPI Calculation' Field:

1. Create another calculated field and name it "KPI Calculation"
2. Use a similar <code>CASE</code> statement, but this time, show the formula or technical breakdown.

CASE [Select a KPI to Define]
WHEN "Total Sales"
THEN "SUM([Revenue])"

WHEN "Profit Margin"
THEN "SUM([Profit]) / SUM([Revenue])"

WHEN "Customer Acquisition Cost (CAC)"
THEN "(SUM([Marketing Spend]) + SUM([Sales Spend])) / COUNTD([New Customer ID])"

END

This helps technical and non-technical users alike. Your marketing manager sees the plain-English definition, while an analyst on your team can see the exact field names used in the calculation, preventing drift. Click OK.

Step 4: Build Your Data Dictionary Worksheet

With your parameter and calculated fields ready, you can now build the user-facing view.

1. Create a new worksheet and name it "Data Dictionary"
2. Drag your "KPI Definition" calculated field onto the Text mark in the Marks card
3. Drag your "KPI Calculation" calculated field onto the Text mark as well
4. You'll notice the two fields appear next to each other. Click the Text mark to open the editor and format them for clarity. Arrange them with descriptive labels, like this:

**Definition:** <KPI Definition>

**Calculation Formula:** <KPI Calculation>

1. Increase the font size and use bolding to make it easy to read
2. Go to your parameter dropdown menu (the one you made visible in Step 2) and select different KPIs. You will see the definition and calculation text update instantly
3. Finally, tidy up the worksheet. You can edit the title to respond dynamically to the selection. Double-click the worksheet title and insert the parameter using the Insert button. Your title could be: "Definition for: [Select a KPI to Define]"

Step 5: Integrate it Into Your Dashboard

A data dictionary is useless if no one can find it.

• Create a new dashboard and place your "Data Dictionary" worksheet onto it
• Make this dashboard the very first tab in your workbook and give it a clear name like "Start Here" or "KPI Guide". This way, anyone opening the workbook sees it immediately
• For extra credit, add a small information icon (?) to your other dashboards. You can set up a "Go to Sheet" action so that when a user clicks the icon on any dashboard, it navigates them directly to your data dictionary dashboard. This embeds help exactly where users need it.

Best Practices for a Useful Data Dictionary

Once your dictionary is built, keep these principles in mind to ensure it remains a trusted resource:

• Write for Humans: Avoid technical jargon whenever possible. The definition of a marketing metric should be understandable to someone in finance. Ambiguity is what we’re trying to eliminate.
• Assign Clear Ownership: A data dictionary that is not updated is worse than no dictionary at all. Assign a person or a team (e.g., the data team or a lead analyst) the responsibility for updating definitions when business logic changes.
• Keep it Visible: Put the dictionary somewhere obvious. The first tab of a workbook or a linked icon on every dashboard makes it impossible to miss.
• Use Default Properties: Remember you can also add definitions to Tableau's metadata layer directly. In the Data pane, right-click any field and go to Default Properties -> Comment.... Add your definition there. Then, any user in the workbook can right-click the field and select Describe... to see your comment, data type, and summary stats. This is a great complement to your interactive dashboard.

Final Thoughts

Building a data dictionary in Tableau isn't about complex programming, it's a strategic move to build trust and promote data literacy. Using interactive elements like parameters and calculated fields, you can create a user-friendly guide inside your workbook, empowering everyone on your team to make decisions with confidence.

This attention to detail in custom workbooks is necessary, but it also shows where traditional BI tools often create friction. We think getting clear answers from your data shouldn't require building a manual. With Graphed you can connect directly to your marketing and sales platforms, so the foundational intelligence is already built-in. Instead of creating a guide to explain what "revenue" from Shopify or "campaign spend" from Facebook Ads means, you just ask questions in natural language. Graphed already understands the nuances and builds the right report instantly, turning analysis into a simple conversation instead of a documentation project.