AnalyticsVisualization Metadata Type Guide

Architectural Overview#

The AnalyticsVisualization metadata type represents a saved, reusable visualization asset within Salesforce’s Unified Analytics and Data Cloud reporting architecture. While traditional CRM Analytics embeds lenses and charts directly inside monolithic WaveDashboard JSON blobs, AnalyticsVisualization decouples individual visual views so architects can govern, version, and embed single-purpose charts across multiple workspaces and Lightning Record Pages.

From an enterprise architecture standpoint, modularizing charts as AnalyticsVisualization metadata reduces merge conflicts in Git. Multiple analytics engineers can iterate on separate KPI visualizations simultaneously without overwriting a single massive dashboard definition.

Directory Location and File Suffix#

Key Metadata Fields#

Declarative XML and Package Manifest Examples#

Below is an example of an AnalyticsVisualization metadata file defining a quarterly ARR breakdown chart, along with the package.xml manifest used to deploy it.

<?xml version="1.0" encoding="UTF-8"?>
<AnalyticsVisualization xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Quarterly ARR by Segment</masterLabel>
    <description>Tracks net-new and expansion ARR grouped by enterprise segment from the Revenue Semantic Model.</description>
    <folderName>Executive_Revenue_Workspace</folderName>
    <visualizationType>StackedBar</visualizationType>
</AnalyticsVisualization>

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>Quarterly_ARR_By_Segment</members>
        <name>AnalyticsVisualization</name>
    </types>
    <version>68.0</version>
</Package>

SFDX CLI Retrieval and Tooling Inspection#

Use the Salesforce CLI to retrieve and deploy AnalyticsVisualization assets across environments:

# Retrieve a specific AnalyticsVisualization asset
sf project retrieve start \
  --metadata AnalyticsVisualization:Quarterly_ARR_By_Segment \
  --target-org analytics-sandbox

# Retrieve all AnalyticsVisualization metadata in the org
sf project retrieve start \
  --metadata "AnalyticsVisualization:*" \
  --target-org analytics-sandbox

Senior Architect Best Practices and Gotchas#

1. Deploy Semantic Models First: An AnalyticsVisualization references fields and measures from its underlying dataset or Data Cloud Semantic Model. Always order your CI/CD deployment pipeline so Data Cloud data model objects (DMOs), calculated insights, and semantic models deploy prior to AnalyticsVisualization components.
2. Workspace Folder Permissions: Access to an AnalyticsVisualization is inherited from its parent container (folderName or AnalyticsWorkspace). If users see an “Insufficient Privileges” banner on an embedded Lightning page, verify both their PermissionSet license assignments and folder viewer shares.
3. Avoid Hardcoded Record IDs in Filters: When configuring default filters inside a visualization’s definition, filter by stable external keys or picklist API names rather than 18-character Salesforce Record IDs, which change across sandboxes.

Frequently asked questions

What is the purpose of the AnalyticsVisualization metadata type?

It stores the metadata definition of a standalone chart or visualization asset in Salesforce Unified Analytics and Data Cloud, binding a dataset or semantic model query to visual rendering properties.

Where are AnalyticsVisualization files located in an SFDX repository?

They are stored in the force-app/main/default/analyticsVisualizations/ directory with the file suffix .analyticsVisualization-meta.xml.

How does AnalyticsVisualization relate to AnalyticsWorkspace?

An AnalyticsVisualization is an individual visual asset that can be organized inside an AnalyticsWorkspace or embedded onto a Lightning App Builder page.

Can I deploy an AnalyticsVisualization without its underlying semantic model?

No, deploying an AnalyticsVisualization requires its referenced dataset, semantic data model, or workspace folder to already exist in the target org or be included in the same deployment package.