如何通过Hyper API获取Hyper文件中的物理列与远程字段信息

在Tableau中打开提取生成的Hyper文件并检查Extract.Extract数据源时，可查看字段名、物理列（Physical Column）和远程字段名（Remote Field name），但现有Hyper API代码只能获取字段名和字段类型，无法获取后两者。要拿到这些元数据，需查询Hyper文件内置的系统元数据表——Tableau会将这类专属元数据存储在_tableau_metadata架构的表中。

现有代码（仅获取基础字段信息） #

def GetHyperStructure(self, hyperfile):
    with HyperProcess(Telemetry.DO_NOT_SEND_USAGE_DATA_TO_TABLEAU) as hyper:
        with Connection(endpoint=hyper.endpoint, database=hyperfile) as connection:

            table_names = connection.catalog.get_table_names(schema="Extract")

            for table in table_names:
                table_definition = connection.catalog.get_table_definition(name=table)
                print(f"Table {table.name} has qualified name: {table}")
                for column in table_definition.columns:
                    print(f"Column {column.name} has type={column.type} and nullability={column.nullability}")

修改后的代码（获取物理列与远程字段名） #

通过查询_tableau_metadata.columns表，关联Extract架构下的目标表，即可获取所需的扩展元数据：

from tableauhyperapi import HyperProcess, Connection, Telemetry, TableName

def GetHyperStructureWithMetadata(self, hyperfile):
    with HyperProcess(Telemetry.DO_NOT_SEND_USAGE_DATA_TO_TABLEAU) as hyper:
        with Connection(endpoint=hyper.endpoint, database=hyperfile) as connection:

            table_names = connection.catalog.get_table_names(schema="Extract")

            for table in table_names:
                table_definition = connection.catalog.get_table_definition(name=table)
                print(f"Table {table.name} has qualified name: {table}")
                
                # 查询系统表获取物理列和远程字段名
                query = f"""
                    SELECT 
                        c.column_name,
                        c.physical_name,
                        c.remote_name
                    FROM 
                        _tableau_metadata.columns c
                    WHERE 
                        c.table_catalog = 'Extract'
                        AND c.table_schema = 'Extract'
                        AND c.table_name = '{table.name}'
                """
                
                with connection.execute_query(query) as result:
                    # 构建字段名到元数据的映射
                    column_metadata = {row[0]: {"physical_name": row[1], "remote_name": row[2]} for row in result}
                
                # 输出完整字段信息
                for column in table_definition.columns:
                    meta = column_metadata.get(column.name, {})
                    print(f"Column {column.name}:")
                    print(f"  Type: {column.type}, Nullability: {column.nullability}")
                    print(f"  Physical Column: {meta.get('physical_name', 'N/A')}")
                    print(f"  Remote Field Name: {meta.get('remote_name', 'N/A')}")

关键说明 #

• _tableau_metadata.columns是Tableau为Hyper文件维护的系统表，存储了所有列的额外元数据，包括物理列名、远程字段名等。
• 查询时需通过table_catalog、table_schema和table_name精准定位目标表，确保关联到正确的列信息。
• 若部分列无对应物理列或远程字段（如计算字段），会显示N/A。

内容的提问来源于stack exchange，提问作者user2555515