Adds a sample which demonstrates how to publish a plain multi-table .hyper file to Tableau Server (without wrapping it into a TDSX file). This is supported in Tableau Online/Tableau Server starting with version 2021.4. Renamed the old sample which demonstrates how to wrap a multi-table extract into a TDSX file.

Author: jonas-eckhardt

Community-Supported/README.md

@@ -25,6 +25,8 @@ The community samples focus on individual use cases and are Python-only. They ha
 - [__publish-hyper__](https://github.com/tableau/hyper-api-samples/tree/main/Community-Supported/publish-hyper)
   - Simple example of publishing single-table `.hyper` file.
 - [__publish-multi-table-hyper__](https://github.com/tableau/hyper-api-samples/tree/main/Community-Supported/publish-multi-table-hyper)
+  - Demonstrates how to create a multi-table `.hyper` file and publish it to Tableau Server version 2021.4+.
+- [__publish-multi-table-hyper-legacy__](https://github.com/tableau/hyper-api-samples/tree/main/Community-Supported/publish-multi-table-hyper-legacy)
   - Demonstrates the full end-to-end workflow of how to create a multi-table `.hyper` file, place the extract into a `.tdsx`, and publish to Tableau Online or Server.
 - [__s3-to-hyper__](https://github.com/tableau/hyper-api-samples/tree/main/Community-Supported/s3-to-hyper)
   - Demonstrates how to create a `.hyper` file from a wildcard union on text files held in an AWS S3 bucket. The extract is then placed in a `.tdsx` file and published to Tableau Online or Server.

Community-Supported/publish-multi-table-hyper-legacy/README.md

@@ -0,0 +1,71 @@
+# publish-multi-table-hyper-legacy
+## __Publishing a Multi-Table Hyper File to Tableau Online/Server (for Tableau Server versions < 2021.4)__
+
+![Community Supported](https://img.shields.io/badge/Support%20Level-Community%20Supported-53bd92.svg)
+
+In contrast to single-table `.hyper` files, with multi-table `.hyper` files it is not obvious which data model you want to analyze in the data source on Tableau Server. Thus, when publishing to Tableau Server < 2021.4, you can only publish single-table `.hyper` files or need to wrap the `.hyper` file into a Packaged Data Source (.tdsx). Starting with version 2021.4, you can now publish multi-table `.hyper` files to Tableau Server and Tableau Online; the data model will be automatically inferred (as specified by assumed table constraints). 
+
+This sample demonstrates how to wrap the `.hyper` file into a Packaged Data Source (.tdsx). If you are looking for how to publish a plain multi-table `.hyper` file to Tableau Server 2021.4+,  have a look at [this sample](https://github.com/tableau/hyper-api-samples/tree/main/Community-Supported/publish-multi-table-hyper).
+
+This sample demonstrates how to leverage the Hyper API, Tableau Server Client Library, and Tableau Tools to do the following:
+- Create a multi-table `.hyper` file
+- Swap the newly created extract into an existing Packaged Data Source file (.tdsx)
+- Publish the data source to a specified project on Tableau Online/Server
+
+It should serve as a starting point for anyone looking to automate the publishing process of multi-table extracts and data sources to Tableau. 
+
+# Get started
+
+## __Prerequisites__
+To run the script, you will need:
+- Windows or Mac
+- Tableau Desktop v10.5 or higher
+- Python 3
+- Run `pip install -r requirements.txt`
+- Tableau Online/Server credentials or Personal Access Token
+
+## __Configuration File__
+Modify `config.json` and add the following fields:
+- Name of the `.hyper` file
+- Name of the .tdsx file
+- Server/Online url
+- Site name
+- Project name
+- Authentication information
+
+## __Data and Table Definitions__
+If you want to simply run the sample to test the publishing process, you do not need to make any changes to the python file. Ensure that you have installed the requirements, update the config file with authentication information and execute the python file.
+
+Once you are ready to use your own data, you will need to change the `build_tables()` and the `get_data()` functions. `build_tables()` returns the schema of all tables to be created (an array of `TableDefinition` objects, one for each table you want to create). `get_data()` returns the data to be inserted, one array for each table (an array of arrays, one containing the data to be inserted for each table). Those functions could be a part of an existing ETL workflow, grab the data from an API request, or pull CSVs from cloud storage like AWS, Azure, or GCP. In any case, writing that code is up to you. You can [check out this doc](https://help.tableau.com/current/api/hyper_api/en-us/reference/py/tableauhyperapi.html?tableauhyperapi.Inserter) information on how to pass data to Hyper's `inserter()` method and [this doc](https://help.tableau.com/current/api/hyper_api/en-us/reference/py/tableauhyperapi.html?tableauhyperapi.SqlType) for more information on the the Hyper API's SqlType class.
+
+__Note:__ The current example features two tables, but in theory, this could support as many as you'd like. Just be sure to add the proper table definitions and make sure that the order in the list of table data and table definitions properly match.
+
+## __Creating the .tdsx File__
+As mentioned, one key step needed for the automatic publishing of multi-table `.hyper` files is a Packaged Data Source, or .tdsx. As of now, this is a step that must be completed manually as a part of the setup process. _You will only need to do this once_. If a .tdsx is not present in the directory, the script will prompt you to create one. At this point, you should have entered the required config fields and have run the python script once to create the multi-table `.hyper` file.
+
+Packaged Data Sources contain important metadata needed for Tableau Desktop and Server/Online. This includes things like defined joins and join clauses, relationships, calculated fields, and more.
+
+To create the .tdsx, [follow these steps](https://help.tableau.com/current/pro/desktop/en-us/export_connection.htm):
+- Run the script without a data source present to create the initial `.hyper` file
+- Double-click the `.hyper` file to open it in Tableau Desktop
+- Click and drag the relevant tables and create the joins or relationships
+- Head to 'Sheet 1'
+- In the top-left corner, right-click on the data source and select 'Add to Saved Data Sources...'
+- Name the file to match the value in `config.json`
+- Select 'Tableau __Packaged__ Data Source (*.tdsx)' from the dropdown
+- Save it in the directory with the script and `.hyper` file
+
+Now you are free to rerun the script and validate the swapping and publishing process. Unless you change how the `.hyper` file is being created (schema, column names, joins, etc.), you will not need to remake the .tdsx again.
+
+## __Additional Customization__
+If you end up needing to change more about how the extract is built (e.g., inserting directly from a CSV file) then you will need to also change the `add_to_hyper()` function, but most likely nothing else.
+
+Leverage the [official Hyper API samples](https://github.com/tableau/hyper-api-samples/tree/master/Python) to learn more about what's possible.
+
+
+## __Resources__
+Check out these resources to learn more:
+- [Hyper API docs](https://help.tableau.com/current/api/hyper_api/en-us/index.html)
+- [TSC Docs](https://tableau.github.io/server-client-python/docs/)
+- [REST API docs](https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api.htm)
+- [Tableau Tools](https://github.com/bryantbhowell/tableau_tools)

Community-Supported/publish-multi-table-hyper-legacy/config.json

@@ -0,0 +1,9 @@
+{
+    "hyper_name": "extract.hyper",
+    "tdsx_name": "test.tdsx",
+    "server_address": "my.tableau.server",
+    "site_name": "my_site",
+    "project_name": "my_project",
+    "tableau_token_name": "token_name",
+    "tableau_token": "token_goes_here"
+}

Community-Supported/publish-multi-table-hyper-legacy/publish-multi-table-hyper.py

@@ -0,0 +1,169 @@
+# -----------------------------------------------------------------------------
+#
+# This file is the copyrighted property of Tableau Software and is protected
+# by registered patents and other applicable U.S. and international laws and
+# regulations.
+#
+# You may adapt this file and modify it to fit into your context and use it
+# as a template to start your own projects.
+#
+# -----------------------------------------------------------------------------
+
+from tableauhyperapi import *
+from tableau_tools import *
+from tableau_tools.tableau_documents import *
+import tableauserverclient as TSC
+import os, json, sys
+
+def get_data():
+    '''This function is responsible for returning the two tables as nested arrays, as shown with the example below.'''
+
+    # Sample data held as arrays. Column order must be consistent and match the table definitions defined below.
+    table_one = [[123, 40, 'John', 'Order#1'], [123, 90, 'Jane', 'Order#2'], [456, 110, 'John', 'Order#3'], [456, 80, 'Jane', 'Order#4']]
+    table_two = [[123, 'Lemonade', 'Beverage'], [456, 'Cookie', 'Food']]
+    
+    # Create an array of the data_tables to pass to Hyper
+    table_data = [table_one, table_two]
+    
+    return table_data
+
+def build_tables():
+    '''Builds the two tables for the multitable extract.'''
+    # Since the table names are not prefixed with an explicit schema name, the tables will reside in the default "public" namespace.
+    # It is important to match the order of the table definitions with the data tables returned in get_data()
+    table_one = TableDefinition(
+        table_name="sales", 
+        columns=[
+            TableDefinition.Column("Product Key", SqlType.int()),
+            TableDefinition.Column("Sales", SqlType.int()),
+            TableDefinition.Column("Customer", SqlType.text()),
+            TableDefinition.Column("Order ID", SqlType.text())
+        ]
+    )
+    table_two = TableDefinition(
+        table_name="products", 
+        columns=[
+            TableDefinition.Column("Product Key", SqlType.int()),
+            TableDefinition.Column("Product Name", SqlType.text()),
+            TableDefinition.Column("Category", SqlType.text())
+        ]
+    )
+    table_definitions = [table_one, table_two]
+    return table_definitions
+
+
+def load_config():
+    '''Loads a config file in the current directory called config.json.'''
+    
+    # Opens the config file and loads as a dictionary.    
+    try:
+        with open('config.json', 'r') as f:
+            config = json.load(f)
+            print("Config file loaded.")
+            return config
+    except:
+        message = 'Could not read config file.'
+        print("Unexpected error: ", sys.exc_info()[0])
+        sys.exit(message)
+
+
+def add_to_hyper(table_data, table_definitions, hyper_name):
+    '''Uses the Hyper API to build and insert data into the Hyper file.'''
+
+    # Starts the Hyper Process with telemetry enabled to send data to Tableau.
+    # To opt out, simply set telemetry=Telemetry.DO_NOT_SEND_USAGE_DATA_TO_TABLEAU.   
+    print("Starting Hyper process.")
+    with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:
+
+        # Creates new Hyper file "[hyper_name].hyper".
+        # Replaces file with CreateMode.CREATE_AND_REPLACE if it already exists.
+        print("Opening connection to Hyper file.")
+        with Connection(endpoint=hyper.endpoint, database=hyper_name, create_mode=CreateMode.CREATE_AND_REPLACE) as connection:
+            
+            # Creates multiple tables.
+            for data, definition in zip(table_data, table_definitions):
+                connection.catalog.create_table(definition)
+                print(f"Creating table {definition.table_name} in Hyper...")
+                
+                # Inserts data into table.
+                with Inserter(connection, definition) as inserter:
+                    print(f"Instering {len(data)} rows into table {definition.table_name}...")
+                    inserter.add_rows(data)
+                    inserter.execute()
+
+        print("The connection to the Hyper file has been closed.")
+    print("The Hyper process has been shut down.")
+
+
+def swap_hyper(hyper_name, tdsx_name, logger_obj=None):
+    '''Uses tableau_tools to open a local .tdsx file and replace the hyperfile.'''
+    
+    # Checks to see if TDSX exists, otherwise, as a one-time step, user will need to create using Desktop.
+    if os.path.exists(tdsx_name):
+        print("Found TDSX file.")
+    else:
+        message = "--Could not find existing TDSX file. Please use Desktop to create one from the newly created hyper file or update the config file.--"
+        sys.exit(message)
+    
+    # Uses tableau_tools to replace the hyper file in the TDSX.
+    try:
+        local_tds = TableauFileManager.open(filename=tdsx_name, logger_obj=logger_obj)
+    except TableauException as e:
+        sys.exit(e)
+    filenames = local_tds.get_filenames_in_package()
+    for filename in filenames:
+        if filename.find('.hyper') != -1:
+            print("Overwritting Hyper in original TDSX...")
+            local_tds.set_file_for_replacement(filename_in_package=filename,
+                                            replacement_filname_on_disk=hyper_name)
+            break
+    
+    # Overwrites the original TDSX file locally.
+    tdsx_name_before_extension, tdsx_name_extension = os.path.splitext(tdsx_name)
+    tdsx_updated_name = tdsx_name_before_extension + '_updated' + tdsx_name_extension
+    local_tds.save_new_file(new_filename_no_extension=tdsx_updated_name)
+    os.remove(tdsx_name)
+    os.rename(tdsx_updated_name, tdsx_name)
+
+
+def publish_to_server(site_name, server_address, project_name, tdsx_name, tableau_token_name, tableau_token):
+    '''Publishes updated, local .tdsx to Tableau, overwriting the original file.'''
+    
+    # Creates the auth object based on the config file.
+    tableau_auth = TSC.PersonalAccessTokenAuth(
+        token_name=tableau_token_name, personal_access_token=tableau_token, site_id=site_name)
+    server = TSC.Server(server_address)
+    print(f"Signing into to site: {site_name}.")
+
+    # Signs in and find the specified project.
+    with server.auth.sign_in(tableau_auth):
+        all_projects, pagination_item = server.projects.get()
+        for project in TSC.Pager(server.projects):
+            if project.name == project_name:
+                project_id = project.id
+        if project_id == None:
+            message = "Could not find project. Please update the config file."
+            sys.exit(message)
+        print(f"Publishing to {project_name}.")
+        
+        # Publishes the data source.
+        overwrite_true = TSC.Server.PublishMode.Overwrite
+        datasource = TSC.DatasourceItem(project_id)
+        file_path = os.path.join(os.getcwd(), tdsx_name)
+        datasource = server.datasources.publish(
+            datasource, file_path, overwrite_true)
+        print(f"Publishing of datasource '{tdsx_name}' complete.")
+
+
+# Run
+if __name__ == '__main__':
+    config = load_config() 
+    
+    try:
+        add_to_hyper(get_data(), build_tables(), config['hyper_name'])
+    except HyperException as e:
+        sys.exit(e)
+
+    swap_hyper(config['hyper_name'], config['tdsx_name'])
+    publish_to_server(config['site_name'], config['server_address'], config['project_name'],
+        config['tdsx_name'], config['tableau_token_name'], config['tableau_token'])

Community-Supported/publish-multi-table-hyper-legacy/requirements.txt

@@ -0,0 +1,3 @@
+tableauhyperapi==0.0.10899
+tableauserverclient==0.10
+tableau_tools==5.1.3