ビジネスコンテキストを付与：Amazon QuickSight のレガシートピックからセマンティックデータセットへ移行

If you’ve been managing Amazon Quick legacy Topics alongside your datasets, you know the challenge: two assets that must stay perfectly synchronized, each with its own permissions, lineage, and versioning. Column synonyms drift. Calculated fields diverge. A rename in the dataset breaks the Legacy Topic silently. You can now use Amazon Quick to embed that business context directly into the dataset itself through Dataset Enrichment in the new data prep experience. Column descriptions, synonyms, calculated fields, custom instructions, and business rules all live alongside the data. Dataset Enrichment bakes business context directly into the dataset. Everything (permissions, semantics, AI context) travels with the data and is automatically inherited by anything built on top of it. One asset, one source of truth, one place to govern.

In this post, we walk through what Dataset Enrichment is, how it differs from legacy Topics, and provide three migration scenarios with step-by-step guidance so you can move your business context into the dataset layer with confidence.

Topic is now the multi-dataset semantic and reasoning layer, the construct where multiple datasets are composed, relationships are defined, business metrics are authored, and business terminology is mapped. Rather than introducing a net-new construct, we are re-purposing Topic to fulfill this role more completely. Moving dataset-intrinsic semantics down to where they belong, and elevating Topic to own the cross-dataset relationships, metrics, and business terminology that it was always meant to carry. This isn’t a cosmetic change. It establishes a clean, forward-looking architecture that supports both deterministic BI workflows and flexible AI-driven analytics from a shared semantic foundation. It also sets up the framework for catalog integration.

What is Topics (legacy)

Legacy Topics provided the initial approach to adding business context to datasets in Amazon Quick Sight. It stored column synonyms, calculated fields, named entities, filters, and custom instructions in a separate object that sat on top of the dataset, linked but independently managed. Going forward, we classify existing Topics as legacy. The new version of Topics is being elevated to a *multi-dataset semantic layer*. A single-entry point for cross-dataset Q&A that lets business users and AI workflows query across multiple enriched datasets in one conversation. Dataset Enrichment is the foundation that makes this possible: each dataset must carry its own semantic context before Topics can unify them at a higher level.

Key differences: Topics (legacy) vs. Dataset Enrichment (new data prep)

Legacy Topics

Dataset Enrichment

Where metadata lives

Separate legacy Topic object, linked to a dataset

Inside the dataset metadata itself

Column synonyms

Defined in Column Synonyms on the legacy Topic

Defined in Additional Notes on the column

Business rules & filters

Named Filters with structured conditions

Text-based rules in Custom Instructions

Calculated fields

Legacy Topic-level calculations (named expressions)

Calculated column (row-level transformation)

Named entities

Structured entity objects with synonyms

Text entries in Custom Instructions (dataset OUTPUT tab)

Custom instructions

Custom Instructions String on legacy Topic

Text entries in Custom Instructions (dataset OUTPUT tab)

Governance

Two assets to permission and audit

One asset to permission and audit

Semantic types

Properties of field

Properties of column

Aggregation levels

Properties of field

Handles by the agent at runtime based on the ask

What stays the same during migration

Not everything changes. These aspects of your Quick Sight environment remain unchanged during migration:

• Rules datasets don’t require migration. Rule-based logic continues to work as before.

• SPICE storage and Direct Query mode are unaffected. Your data access patterns remain the same regardless of whether you use Topics or Dataset Enrichment.

• Dashboards and analyses aren’t rebuilt. They use the enriched dataset.

• The user-facing Q&A interaction model doesn’t change. Users still ask questions in natural language through Amazon Quick chat. The difference is invisible to them.

Why move business context into the dataset?

When business metadata lives in a separate legacy Topic object, you manage two assets that must stay synchronized. Permissions, lineage, and discoverability all split across boundaries. Dataset Enrichment collapses this:

• Single source of truth. Business context travels with the data. There’s no separate asset to drift out of sync.

• Automatic inheritance. Any dashboard, analysis, legacy Topic, or AI-powered chat feature built on the enriched dataset inherits the semantic context without additional configuration.

• Simpler governance. One asset to manage permissions, audit, and version control.

• AI-readiness. The dataset becomes self-describing for natural language querying. Amazon Quick’s chat experience can resolve ambiguous business language directly from dataset metadata without requiring a separate Topic.

What’s changed in the dataset definition as part of Dataset Enrichment

The new data prep experience introduces semantic_model_configuration on datasets. It has two layers:

Column-level metadata (inside TableMap):

Property

Purpose

Example

Description

What the field represents

“Unique ID for each sales transaction”

AdditionalNotes

Synonyms and alternative names users might say

“order id, sale id, receipt number”

Dataset-level metadata (inside SemanticMetadata):

Property

Purpose

Example

Description

Overall summary of what the dataset contains

“Sales fact table covering transactions, revenue, and margins”

CustomInstructions

Business logic, formulas, named entities, and rules

“Revenue = quantity * unit_price * (1 – discount_applied)”

Mapping from Legacy Topic fields to Dataset Enrichment:

Legacy Topic field

Dataset SemanticModel target

ColumnDescription

ColumnProperties.Description.Text

ColumnSynonyms[]

ColumnProperties.AdditionalNotes.Text (comma-joined)

CalculatedFields.Expression

DataPrepConfiguration → CreateColumnsStep

NamedEntities.EntityName + EntityDescription + Definition

CustomInstructions.InlineCustomInstruction.InstructionText (as “Entity Name: definition (fields: …) (synonyms: …)”)

Filters

CustomInstructions.InlineCustomInstruction.InstructionText (as “Business Rule – Name: Output Column Name IN [values]”)

CustomInstructionsString

CustomInstructions.InlineCustomInstruction.InstructionText

Solution overview

The migration is a four-step process. You identify your target dataset, locate the source legacy Topic, and run a Python script that extracts the legacy Topic’s metadata and writes it into the dataset’s SemanticModelConfiguration through the Quick Sight API. The script handles column descriptions, synonyms, calculated fields, named entities, filters, and custom instructions in a single pass. No manual UI work required.

Prerequisites

Before you begin, verify that you have the following in place:

• AWS Command Line Interface (AWS CLI) v2 (version 2.34.50 or later) installed and configured with valid credentials. Run aws sts get-caller-identity to confirm your session is active. See the AWS CLI installation guide for setup instructions. Verify with aws --version.

• Python 3.6 or later is required to run the mapping script in Step 3. Verify with python3 --version.

• Amazon Quick Enterprise edition with Q enabled. The migration relies on Quick Sight APIs that are only available in Enterprise accounts with the Q add-on active.

• A target dataset using the new data prep experience. The dataset must use DataPrepConfiguration (not LogicalTableMap) and have column IDs on all InputColumns. See Creating a dataset in new data prep for more details.

• An existing legacy Topic (source) with columns, descriptions, synonyms, and optionally calculated fields, entities, and filters that you want to migrate.

• AWS Identity and Access Management (IAM) permissions for the caller identity: quicksight:DescribeDataSet, quicksight:UpdateDataSet, and quicksight:DescribeTopic. See Quick Sight IAM actions for the full policy reference.

Migration scenarios

The right approach depends on your current setup. We cover three scenarios, from simplest to most involved.

Scenario 1: Legacy datasets with no legacy Topics

Your dataset was built using the classic Quick Sight experience and has no semantic layer of any kind. Users see raw column names (TXN_DT, CUST_ID, AMT_USD) in dashboards, filters, and tooltips. When someone types a natural language question in Amazon Quick chat, the system has zero context to work with: no descriptions, no synonyms, no business rules. A question like “what’s our revenue this quarter?” returns nothing because nothing maps the word “revenue” to any column in the schema.

Legacy datasets ( using LogicalTableMap rather than DataPrepConfiguration) don’t support Dataset Enrichment. There’s no in-place upgrade path currently. You can’t add SemanticModelConfiguration to a legacy dataset, and there’s no migration API that converts one to the other. You can choose to query the dataset directly with raw column names using Dataset Q&A feature.

Scenario 2: Legacy Topics with legacy datasets

A Topic sits on top of a legacy dataset, providing the semantic layer your users depend on, column synonyms, calculated fields, named entities, named filters, and custom instructions. Users query through the Topic and get results. But underneath, the dataset itself has no enrichment. It still uses LogicalTableMap and exposes raw column names with no descriptions or business context of its own.

Like Scenario 1, the underlying legacy dataset doesn’t support SemanticModelConfiguration. There’s no way to push your legacy Topic metadata into the dataset directly. The path forward is creating a new dataset using the new data prep experience, migrating your legacy Topic’s metadata into it as Dataset Enrichment, validating the results, and cutting over. Alternatively you can use the Dataset Q&A feature with the legacy dataset.

Scenario 3: Legacy Topics with new data prep datasets

Current state: You already use the new data prep experience for your dataset. It has DataPrepConfiguration with SourceTableMap, TransformStepMap, and DestinationTableMap. But a legacy Topic is still layered on top providing the semantic context your users rely on: column synonyms, calculated fields, named entities, filters, and custom instructions. The dataset structure supports enrichment natively. It hasn’t been applied yet. This is the only scenario where a direct, in-place migration is possible. Your dataset already speaks the right API language, so you don’t need to recreate it.

Because the dataset uses DataPrepConfiguration, you can pass SemanticModelConfiguration directly to the update-data-set API. This means you can also:

• Migrate column descriptions and synonyms from your legacy Topic into ColumnProperties.Description and ColumnProperties.AdditionalNotes on the dataset. Every column that had a ColumnDescription or ColumnSynonyms array in the legacy Topic gets an equivalent entry in the dataset’s semantic layer.

• Migrate calculated fields from legacy Topic-level expressions into CreateColumnsStep entries in DataPrepConfiguration. These become first-class computed columns in the dataset, visible in dashboards and available for natural language queries without a legacy Topic.

• Migrate named entities, filters, and custom instructions into CustomInstructions.InlineCustomInstruction.InstructionText. Entity definitions, business rules, and formula documentation are preserved as structured text that the chat system reads at query time.

• Keep the legacy Topic active during migration. Both the legacy Topic and the dataset enrichment can coexist temporarily. You validate the enriched dataset’s Q&A behavior against the legacy Topic’s and only remove the legacy Topic after you’re ready.

• Run the legacy Topic migration with a script. Because both describe-topic and update-data-set are API calls, the transformation can be automated end-to-end. Extract legacy Topic metadata, transform it, apply it to the dataset, and verify. No manual UI work required.

The following step automates the enrichment of an Amazon Quick Sight dataset with semantic metadata extracted from a Quick Sight legacy Topic. It transfers business context, column descriptions, synonyms, calculated fields, named entities, filters, and custom instructions from a legacy Topic directly into the dataset’s SemanticModelConfiguration.

Step overview

You need four pieces of information before running the script. Get the dataset ID and Topic ID (Legacy) from the Quick console URLs (shown in Steps 1 and 2), and confirm your AWS account ID and AWS Region.

Step

Action

Input

1

Get target dataset ID

Dataset ID

2

Get Topic ID

Topic ID

3

AWS Region

4

Run Enrich Dataset python script

Both IDs and Region

Required parameters

• ACCOUNT_ID = >

• REGION = <>

• DATASET_ID = >

• TOPIC_ID = <>

Step 1: Get target dataset ID

Open the Quick Sight console. In the left navigation panel, select Data, then switch to the Datasets tab. Select the dataset that you want to enrich. The dataset ID is the UUID at the end of your browser’s URL.

Example:

Step 2: Get the source legacy Topic ID

Open the Quick Sight console. In the left navigation panel, select Data, then switch to the Topics tab. Select the source legacy Topic that you want to migrate from. The Topic ID is the string at the end of your browser’s URL.

Example:

Step 3: Python code to enrich a dataset with information from