### Spawn Hyper Process with Parameters

Source: https://tableau.github.io/hyper-db/docs/hyper-api/hyper_process

Starts a local Hyper database server with custom process parameters. This example sets the default database version to '2'. Telemetry is enabled.

```python
process_parameters = {"default_database_version": "2"}  
with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU,  
                  parameters=process_parameters) as hyper:  
    print(hyper.endpoint)  
```

--------------------------------

### Build Java Hyper API examples with Gradle

Source: https://tableau.github.io/hyper-db/docs/installation

Build the Java Hyper API examples using Gradle. This command should be run from the 'examples' directory.

```bash
gradle build
```

--------------------------------

### Run Java Hyper API examples with Gradle

Source: https://tableau.github.io/hyper-db/docs/installation

Run the Java Hyper API examples using Gradle. This command should be run from the 'examples' directory.

```bash
gradle run
```

--------------------------------

### Build C++ Hyper API examples (Linux/macOS)

Source: https://tableau.github.io/hyper-db/docs/installation

Build the C++ Hyper API examples on Linux or macOS using CMake.

```bash
cmake --build .
```

--------------------------------

### Install Tableau Hyper API from Wheel file (Windows)

Source: https://tableau.github.io/hyper-db/docs/installation

Install the Python Hyper API using a downloaded wheel file on Windows.

```bash
Scripts\pip install [*path_to_whl_file*]
```

--------------------------------

### Build C++ Hyper API examples (Windows)

Source: https://tableau.github.io/hyper-db/docs/installation

Build the C++ Hyper API examples on Windows using CMake, specifying a configuration (Debug or Release).

```bash
cmake --build . --config Debug
```

```bash
cmake --build . --config Release
```

--------------------------------

### Run C++ Hyper API examples (Linux/macOS)

Source: https://tableau.github.io/hyper-db/docs/installation

Run the built C++ Hyper API examples on Linux or macOS using ctest.

```bash
ctest --verbose
```

--------------------------------

### Run Python Hyper API example (Windows)

Source: https://tableau.github.io/hyper-db/docs/installation

Execute a Python Hyper API sample script on Windows within a virtual environment.

```bash
[venv_directory]\Scripts\python hyper-api-samples\Tableau-Supported\Python\insert_data_into_single_table.py
```

--------------------------------

### Execute SQL Commands and Queries

Source: https://tableau.github.io/hyper-db/docs/guides/sql_commands

Demonstrates starting a Hyper process, connecting to it, and executing SQL commands and various types of queries. Use this for general interaction with Hyper.

```python
from tableauhyperapi import HyperProcess, Telemetry, Connection  
  
with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:  
    with Connection(endpoint=hyper.endpoint) as connection:  
        connection.execute_command("""  
            CREATE TEMPORARY TABLE animals(name, legs) AS VALUES  
                ('dog', 4),  
                ('cat', 4),  
                ('bird', 2),  
                ('kangaroo', 2),  
                ('centipede', 100)  
            """)  
  
        with connection.execute_query("SELECT name FROM animals") as results:  
            for row in results:  
                print(row)  
  
        bipeds = connection.execute_list_query(  
            "SELECT name FROM animals WHERE legs = 2")  
        print(bipeds)  
  
        max_legs = connection.execute_scalar_query(  
            "SELECT MAX(legs) FROM animals")  
        print("max legs: ", max_legs)
```

--------------------------------

### Install Tableau Hyper API from Wheel file (Linux/macOS)

Source: https://tableau.github.io/hyper-db/docs/installation

Install the Python Hyper API using a downloaded wheel file on Linux or macOS.

```bash
bin/pip install [*path_to_whl_file*]
```

--------------------------------

### Run C++ Hyper API examples (Windows)

Source: https://tableau.github.io/hyper-db/docs/installation

Run the built C++ Hyper API examples on Windows using ctest, specifying a configuration (Debug or Release).

```bash
ctest --verbose -C Debug
```

```bash
ctest --verbose -C Release
```

--------------------------------

### Query Parquet Files from Pandas using Hyper

Source: https://tableau.github.io/hyper-db/docs/guides/pandas_integration

Run analytical queries on Parquet files using Hyper and retrieve the results as a pandas DataFrame. This example requires 'pantab' and 'tableauhyperapi' to be installed.

```python
import pandas as pd
import pantab
from tableauhyperapi import HyperProcess, Telemetry, Connection

with HyperProcess(Telemetry.DO_NOT_SEND_USAGE_DATA_TO_TABLEAU) as hyper:
    with Connection(hyper.endpoint) as connection:
        results_df = pantab.frame_from_hyper_query(connection, """
            SELECT
                YEAR(o_orderdate),
                CAST(SUM(o_totalprice) AS double precision)
            FROM external('orders_10rows.parquet')
            GROUP BY YEAR(o_orderdate)
            """)
        # The query result is now in a pandas data frame.
        # We have the whole power of the pandas ecosystem at our
        # fingertips - and we only print it... how boring...
        print(results_df)

```

--------------------------------

### Install Tableau Hyper API with pip

Source: https://tableau.github.io/hyper-db/docs/installation

Use this command to install the tableauhyperapi module for Python. Ensure you are in a virtual environment.

```bash
pip install tableauhyperapi
```

--------------------------------

### Run Python Hyper API example (Linux/macOS)

Source: https://tableau.github.io/hyper-db/docs/installation

Execute a Python Hyper API sample script on Linux or macOS within a virtual environment.

```bash
[venv_directory]/bin/python hyper-api-samples/Tableau-Supported/Python/insert_data_into_single_table.py
```

--------------------------------

### Install Tableau Hyper API using pip

Source: https://tableau.github.io/hyper-db/docs/releases

Install the Tableau Hyper API using pip. Ensure you are using pip version 19.3 or newer for Linux installations. Versions 20.0 and 20.1 of pip are known to have issues.

```bash
pip install tableauhyperapi
```

```bash
pip install --upgrade tableauhyperapi
```

--------------------------------

### Spawn Hyper Process with Custom Path

Source: https://tableau.github.io/hyper-db/docs/hyper-api/hyper_process

Starts a local Hyper database server using a specified hyperd binary path. This is useful for internal prototyping or testing different Hyper versions. Telemetry is disabled.

```python
from tableauhyperapi import HyperProcess, Telemetry  

HyperProcess(telemetry=Telemetry.DO_NOT_SEND_USAGE_DATA_TO_TABLEAU,  
             hyper_path="/home/avogelsgesang/development/hyper/build/bin") as hyper:  
    print(hyper.endpoint)  
```

--------------------------------

### Create a Hyper File with a Table and Insert Data

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/create_update

Use this script to create a new .hyper file, define a table schema, and insert up to 100 rows of data. Ensure the HyperProcess is started with appropriate telemetry and database version parameters.

```python
from tableauhyperapi import HyperProcess, Connection, Telemetry, CreateMode, \
    TableDefinition, TableName, SqlType, Inserter

with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU, \
            parameters = {"default_database_version": "2"}) as hyper:
    with Connection(hyper.endpoint, 'TrivialExample.hyper', CreateMode.CREATE_AND_REPLACE) as connection:
        # Create an `Extract` table inside an `Extract` schema
        connection.catalog.create_schema('Extract')
        example_table = TableDefinition(TableName('Extract','Extract'), [
            TableDefinition.Column('rowID', SqlType.big_int()),
            TableDefinition.Column('value', SqlType.big_int()),
        ])
        connection.catalog.create_table(example_table)

        # Insert data using the `Inserter` class
        with Inserter(connection, example_table) as inserter:
            for i in range (1, 101):
                inserter.add_row(
                    [ i, i ]
            )
            inserter.execute()
```

--------------------------------

### Load Data from PostgreSQL to Hyper using Pandas

Source: https://tableau.github.io/hyper-db/docs/guides/pandas_integration

Ingest data from a PostgreSQL database into a Hyper file using pandas and pantab. Ensure pantab is installed via 'pip install pantab'.

```python
import pandas as pd
import pantab

animals_df = pd.read_sql('SELECT * FROM animals', 'postgres:///my_db_name')
pantab.frame_to_hyper(animals_df, "animals.hyper", table="animals")

```

--------------------------------

### Spawn Hyper Process with Telemetry

Source: https://tableau.github.io/hyper-db/docs/hyper-api/hyper_process

Starts a local Hyper database server and prints its connection string. Telemetry is enabled to send usage data to Tableau. The process is automatically shut down when exiting the 'with' block.

```python
from tableauhyperapi import HyperProcess, Telemetry  

with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:  
    print(hyper.endpoint)  
```

--------------------------------

### Load Data from Excel to Hyper using Pandas

Source: https://tableau.github.io/hyper-db/docs/guides/pandas_integration

Ingest data from an Excel file into a Hyper file using pandas and pantab. Ensure pantab is installed via 'pip install pantab'.

```python
import pandas as pd
import pantab

animals_df = pd.read_excel('animals.xlsx')
pantab.frame_to_hyper(animals_df, "animals.hyper", table="animals")

```

--------------------------------

### Select all columns from multiple schemas

Source: https://tableau.github.io/hyper-db/docs/releases

Example of selecting all columns from tables within specified schemas using three-part names. This syntax is supported in version 0.0.9273 and later.

```sql
SELECT schema_name.table_name.*, schema_name2.table_name.* FROM schema_name.table_name, schema_name2.table_name ...
```

--------------------------------

### Add Java Hyper API external JARs

Source: https://tableau.github.io/hyper-db/docs/installation

Example of JARs to add as external libraries when creating a new Java project with the Hyper API.

```java
tableauhyperapi.jar
tableauhyperapi-windows.jar (Windows), tableauhyperapi-linux.jar (Linux), tableauhyperapi-darwin.jar (macOS)
jna-5.6.0.jar
```

--------------------------------

### Upgrade Tableau Hyper API with pip

Source: https://tableau.github.io/hyper-db/docs/installation

Use this command to upgrade an existing tableauhyperapi installation to the latest version.

```bash
pip install --upgrade tableauhyperapi
```

--------------------------------

### Basic Connection and Query

Source: https://tableau.github.io/hyper-db/docs/hyper-api/connection

Demonstrates how to create a HyperProcess and establish a connection to it, then execute a simple scalar query.

```APIDOC
## Basic Connection and Query

### Description
This snippet shows the fundamental usage of `HyperProcess` and `Connection` to connect to a running Hyper instance and execute a basic SQL query.

### Method
`Connection` constructor

### Endpoint
N/A (SDK usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from tableauhyperapi import HyperProcess, Telemetry, Connection

with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:
    with Connection(endpoint=hyper.endpoint) as connection:
        print(connection.execute_scalar_query("SELECT 1+3"))
```

### Response
#### Success Response (200)
Output of the executed SQL query.

#### Response Example
```
4
```
```

--------------------------------

### Connecting to a Hyper File

Source: https://tableau.github.io/hyper-db/docs/hyper-api/connection

Illustrates how to create a connection to a specific Hyper file, with options for handling file existence.

```APIDOC
## Connecting to a Hyper File

### Description
This example demonstrates how to establish a connection to a `.hyper` file, specifying the file path and a `CreateMode` to control file creation behavior.

### Method
`Connection` constructor

### Endpoint
N/A (SDK usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from tableauhyperapi import HyperProcess, Telemetry, Connection, CreateMode

with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:
    with Connection(hyper.endpoint, 'TrivialExample.hyper', CreateMode.NONE) as connection:
        print(connection.execute_scalar_query('SELECT COUNT(*) FROM "my_table"'))
```

### Response
#### Success Response (200)
Output of the executed SQL query.

#### Response Example
```
0
```

### CreateMode Options

- **NONE**: The database file will not be created. It is expected that the database already exists. An error will be raised if it does not exist.
- **CREATE**: The database will be created. It is expected that the database does not exist. An error will be raised if the file already exists; a pre-existing file will not be overwritten.
- **CREATE_AND_REPLACE**: Create an empty database. If the database file already exists, replace it by a new, empty database.
- **CREATE_IF_NOT_EXISTS**: If the database file already exists, connect to it. Otherwise create a new, empty database and connect to it.
```

--------------------------------

### Connect to HyperProcess and Execute Query

Source: https://tableau.github.io/hyper-db/docs/hyper-api/connection

Establishes a connection to a running HyperProcess and executes a simple scalar query. Ensure HyperProcess is running before creating a connection.

```python
from tableauhyperapi import HyperProcess, Telemetry, Connection  

with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:  
    with Connection(endpoint=hyper.endpoint) as connection:  
        print(connection.execute_scalar_query("SELECT 1+3"))  
```

--------------------------------

### Connect to a Hyper File and Execute Query

Source: https://tableau.github.io/hyper-db/docs/hyper-api/connection

Connects to a specific .hyper file using a given CreateMode and executes a query against a table within that file. The CreateMode determines how the file is handled if it exists or not.

```python
from tableauhyperapi import HyperProcess, Telemetry, Connection, CreateMode  

with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:  
    with Connection(hyper.endpoint, 'TrivialExample.hyper', CreateMode.NONE) as connection:  
        print(connection.execute_scalar_query('SELECT COUNT(*) FROM "my_table"'))  
```

--------------------------------

### Load Data from CSV into Hyper Table

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/insert_csv

This snippet demonstrates how to create a Hyper table and load data into it from a CSV file using the `COPY FROM` command. It includes setting up the HyperProcess, defining the table schema, and executing the SQL command with CSV-specific options like delimiter and header.

```python
from pathlib import Path  
from tableauhyperapi import HyperProcess, Telemetry,  Connection, CreateMode, \ 
    TableDefinition, NOT_NULLABLE, SqlType, escape_string_literal  
  
customer_table = TableDefinition(  
    # Since the table name is not prefixed with an explicit schema name, the table will reside in the default "public" namespace.  
    table_name="Customer",  
    columns=[
        TableDefinition.Column("Customer ID", SqlType.text(), NOT_NULLABLE),  
        TableDefinition.Column("Customer Name", SqlType.text(), NOT_NULLABLE),  
        TableDefinition.Column("Loyalty Reward Points", SqlType.big_int(), NOT_NULLABLE),  
        TableDefinition.Column("Segment", SqlType.text(), NOT_NULLABLE)  
    ]  
)

path_to_database = Path("customer.hyper")  

with HyperProcess(telemetry=Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:  
    with Connection(endpoint=hyper.endpoint,  
                    database=path_to_database,  
                    create_mode=CreateMode.CREATE_AND_REPLACE,  
                    parameters=connection_parameters) as connection:  
        connection.catalog.create_table(customer_table)  

        # You can find the sample CSV file in https://github.com/tableau/hyper-api-samples/tree/main/Tableau-Supported/Python/data  
        path_to_csv = str(Path(__file__).parent / "data" / "customers.csv")  

        # Load all rows into the "Customers" table from the CSV file.  
        #  
        # You might have to adjust the COPY parameters to the format of your specific csv file.  
        # The example assumes that your columns are separated with the ',' character  
        # and that NULL values are encoded via the string 'NULL'.  
        # Also be aware that the `header` option is used in this example:  
        # It treats the first line of the csv file as a header and does not import it.  
        added_row_count = connection.execute_command(f"""  
            COPY {customer_table.table_name} from {escape_string_literal(path_to_csv)}  
            WITH (format => 'csv', NULL => 'NULL', delimiter => ',', header => true)  
        "")  

        print(f"{added_row_count} rows were loaded from the CSV file.")  
```

--------------------------------

### Configure C++ Hyper API project with CMake (Windows)

Source: https://tableau.github.io/hyper-db/docs/installation

Configure the C++ Hyper API project for building with Visual Studio on Windows using CMake.

```bash
cmake -G "Visual Studio 16 2019 Win64" .
```

--------------------------------

### Configure C++ Hyper API project with CMake (Linux/macOS)

Source: https://tableau.github.io/hyper-db/docs/installation

Configure the C++ Hyper API project for building on Linux or macOS using CMake.

```bash
cmake .
```

--------------------------------

### Correct SQL Syntax for Hyper

Source: https://tableau.github.io/hyper-db/docs/guides/sql_commands

Table names must be in double quotes and string constants in single quotes. Use utility functions for proper escaping.

```sql
INSERT INTO "Guest Names" VALUES('Francisco Eduardo')
```

--------------------------------

### Construct SQL with f-strings

Source: https://tableau.github.io/hyper-db/docs/guides/sql_commands

Utilize Python's f-strings to dynamically construct SQL commands, such as creating multiple temporary tables with unique names. Ensure proper escaping for production code.

```python
# Create 10 tables, just for fun...  
for id in range(0, 10):  
    connection.execute_command(f"""  
    CREATE TEMPORARY TABLE test_table_{id}(my_column int);  
    """)
```

--------------------------------

### Read Data from Hyper File

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/read

Opens a connection to a .hyper file and executes SQL queries to read data. Be cautious when selecting all data, as it may exceed Python's memory capacity. Use specific SQL queries for targeted data retrieval.

```python
from tableauhyperapi import HyperProcess, Connection, Telemetry, CreateMode, Inserter  

with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:  
    with Connection(hyper.endpoint, 'TrivialExample.hyper', CreateMode.NONE) as connection:  
        # Read all data from the table.  
        # But be careful with this! It might be a lot of data and Python  
        # might not be able to cope with that much data...  
        my_data = connection.execute_list_query("""  
            SELECT * FROM "Extract"."Extract"  
        ")  
        print(my_data)  

        # Maybe we are only interested in a more specific part of data?  
        # If so, use the power of SQL to only retrieve the data you are  
        # actually interested in!  
        max_in_table =  connection.execute_scalar_query("""  
            SELECT MAX(value) FROM "Extract"."Extract  
        ")  
        print(max_in_table)
```

--------------------------------

### Insert Geospatial Data with Expressions

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/geodata

Use the Inserter to create a Hyper file with a `tableau.tabgeography` column. Geospatial data is computed from text using CAST expressions.

```python
from tableauhyperapi import Connection, HyperProcess, SqlType, TableDefinition, \
    escape_string_literal, escape_name, NOT_NULLABLE, Telemetry, Inserter, CreateMode, TableName


with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU, 'myapp' ) as hyper:
    with Connection(hyper.endpoint, 'GeospatialExample.hyper', CreateMode.CREATE_AND_REPLACE) as connection:
        # Create a table with a `tableau.tabgeography` column
        connection.catalog.create_schema('Extract')
        geo_table = TableDefinition(TableName('Extract','Extract'), [
            TableDefinition.Column('Name', SqlType.text(), nullability=NOT_NULLABLE),
            TableDefinition.Column('Location',  SqlType.tabgeography(), nullability=NOT_NULLABLE),
         ])
        print("The geo_table is defined.")
        connection.catalog.create_table(geo_table)

        # Inserter definition contains the column definition for the values that are inserted
        # The data input has two text values Name and Location_as_text
        inserter_definition = [
            TableDefinition.Column(name='Name', type=SqlType.text(), nullability=NOT_NULLABLE),
            TableDefinition.Column(name='Location_as_text', type=SqlType.text(), nullability=NOT_NULLABLE)]

        # Column 'Name' is inserted into "Extract"."Extract" as-is.
        # Column 'Location' in "Extract"."Extract" of `tableau.tabgeography` type is computed from Column 'Location_as_text' of `text` type
        # using the expression 'CAST("Location_as_text") AS TABLEAU.TABGEOGRAPHY'.
        # Inserter.ColumnMapping is used for mapping the CAST expression to Column 'Location'.
        column_mappings = [
            'Name',
            Inserter.ColumnMapping('Location', f'CAST({escape_name("Location_as_text")} AS TABLEAU.TABGEOGRAPHY)')
        ]

        # Format the data as Well-known text (WKT)
        data_to_insert = [
            [ 'Seattle', "point(-122.338083 47.647528)" ],
            [ 'Munich' , "point(11.584329 48.139257)"  ]
        ]

        # Insert data into "Extract"."Extract" table with CAST expression.
        with Inserter(connection, geo_table, column_mappings, inserter_definition = inserter_definition) as inserter:
            inserter.add_rows(rows=data_to_insert)
            inserter.execute()
        print("The data was added to the table.")

```

--------------------------------

### Copy Geospatial Data from CSV

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/geodata

Import geospatial data from a CSV file into a Hyper table with a `tableau.tabgeography` column. Data must be in Well-known text (WKT) format.

```csv
Name, Location
Seattle, point(-122.338083 47.647528)
Munich , point(11.584329 48.139257)

```

```python
from tableauhyperapi import Connection, HyperProcess, SqlType, TableDefinition, \
    escape_string_literal, escape_name, NOT_NULLABLE, Telemetry, Inserter, CreateMode, TableName

# CSV file that contains location data in Well-known text (WKT) format
path_to_csv =  "locations.csv"

with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU, 'myapp' ) as hyper:
    with Connection(hyper.endpoint, 'GeospatialFromCSVExample.hyper', CreateMode.CREATE_AND_REPLACE) as connection:
        # Create a table with a `tableau.tabgeography` column
        connection.catalog.create_schema('Extract')
        geo_table = TableDefinition(TableName('Extract','Extract'), [
            TableDefinition.Column('Name', SqlType.text(), nullability=NOT_NULLABLE),
            TableDefinition.Column('Location',  SqlType.tabgeography(), nullability=NOT_NULLABLE)])
        connection.catalog.create_table(geo_table)

        # Load all rows into the geo_table from the CSV file.
        # `execute_command` executes a SQL statement and returns the impacted row count.
        count_in_geo_table = connection.execute_command(
             command=f"COPY {geo_table.table_name} from {escape_string_literal(path_to_csv)} with "
             f"(format csv, NULL 'NULL', delimiter ',', header)")
        print(f"The number of rows in table {geo_table.table_name} is {count_in_geo_table}.")

```

--------------------------------

### Rewrite Hyper File to Latest Version

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/optimize

This script checks the current database version of a Hyper file and rewrites it to a specified target version if it's older. It includes logic for backing up the original file and renaming the updated file.

```python
import os  
from tableauhyperapi import HyperProcess, Connection, Telemetry, CreateMode  
  
TARGET_DATABASE_VERSION = "2"  
  
with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU,  
            parameters = {"default_database_version": TARGET_DATABASE_VERSION}) as hyper:  
    should_update_version = False  
    with Connection(hyper.endpoint, 'existing.hyper', CreateMode.CREATE_IF_NOT_EXISTS) as connection:  
        # check the current version of the extract  
  
        version = connection.execute_scalar_query("SELECT database_version from pg_catalog.hyper_database")  
        if version < TARGET_DATABASE_VERSION:  
            print(f'found version {version}, upgrading to version {TARGET_DATABASE_VERSION}')  
            should_update_version = True  
  
    if should_update_version:  
        with Connection(hyper.endpoint) as connection:  
            connection.execute_command(f"""  
                CREATE DATABASE "updatedversion.hyper" WITH VERSION {TARGET_DATABASE_VERSION} FROM "existing.hyper"  
            """)  
        # make a backup of the existing hyper file - will overwrite any existing file  
        os.replace("existing.hyper", "existing.bak.hyper")  
  
        # rename the new file to match old database name  
        os.replace("updatedversion.hyper", "existing.hyper")  
    with Connection(hyper.endpoint, 'existing.hyper', CreateMode.CREATE_IF_NOT_EXISTS) as connection:  
        # perform normal operations on connection  
        ...
```

--------------------------------

### Update an Existing Hyper File by Deleting and Inserting Rows

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/create_update

Modify an existing .hyper file by connecting with CreateMode.NONE, deleting rows that meet a condition, and then appending new rows using the Inserter utility. This method is suitable for incremental updates.

```python
from tableauhyperapi import HyperProcess, Connection, Telemetry, CreateMode, Inserter

with HyperProcess(Telemetry.SEND_USAGE_DATA_TO_TABLEAU) as hyper:
    with Connection(hyper.endpoint, 'TrivialExample.hyper', CreateMode.NONE) as connection:
        # Delete every row where `value < 50`
        connection.execute_command("""
            DELETE FROM "Extract"."Extract" WHERE value < 50
        ")

        # Insert two new rows
        with Inserter(connection, TableName('Extract','Extract')) as inserter:
            inserter.add_row([101, 101])
            inserter.add_row([102, 102])
            inserter.execute()
```

--------------------------------

### Create Table for Geospatial Data

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/geodata

Defines and creates a table in a .hyper file with a SqlType.tabgeography() column for storing location data. This table is intended for use in Tableau.

```python
connection.catalog.create_schema('Extract')  
geo_table = TableDefinition(TableName('Extract','Extract'), [
    TableDefinition.Column('Name', SqlType.text(), nullability=NOT_NULLABLE),
    TableDefinition.Column('Location',  SqlType.tabgeography(), nullability=NOT_NULLABLE),
])  
connection.catalog.create_table(geo_table)  

```

--------------------------------

### Define Inserter for Text Data

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/geodata

Defines the input columns for the inserter as a list of TableDefinition.Column. Columns intended to be geospatial data are specified as SqlType.text() for initial insertion.

```python
# Inserter definition contains the column definition for the values that are inserted  
# The data input has two text values Name and Location_as_text  
inserter_definition = [
    TableDefinition.Column(name='Name', type=SqlType.text(), nullability=NOT_NULLABLE),
    TableDefinition.Column(name='Location_as_text', type=SqlType.text(), nullability=NOT_NULLABLE)]

```

--------------------------------

### Insert Geospatial Data using WKT

Source: https://tableau.github.io/hyper-db/docs/guides/hyper_file/geodata

Inserts rows of data, including Well-known text (WKT) formatted location strings, into a Hyper table. The Inserter uses the defined column mappings to convert WKT to the tableau.tabgeography type.

```python
data_to_insert = [
    [ 'Seattle', "point(-122.338083 47.647528)" ],
    [ 'Munich' , "point(11.584329 48.139257)" ]
]

with Inserter(connection, geo_table, column_mappings, inserter_definition = inserter_definition) as inserter:
    inserter.add_rows(rows=data_to_insert)
    inserter.execute()  

```

--------------------------------

### Execute SQL Commands with Escaped Identifiers and Strings

Source: https://tableau.github.io/hyper-db/docs/guides/sql_commands

Use `TableName` and `escape_string_literal` to safely format SQL statements, preventing syntax errors. This is useful for dynamic data insertion or deletion.

```python
table = TableName("Customers")
for name in ["Dennis Kane", "Dorothe Hagen"]:
    row_count = connection.execute_command(f"""
        DELETE FROM {table}
        WHERE "Name" = {escape_string_literal(name)}
        """)
```

--------------------------------

### Update TableDefinition name parameter (Python)

Source: https://tableau.github.io/hyper-db/docs/releases

Demonstrates the change in the `TableDefinition` method in the Hyper API for Python. The `name` parameter was changed to `table_name`. Keyword arguments are affected; positional arguments remain unchanged.

```python
airports_table = TableDefinition(name=TableName( "public", "airports"), ...)  
```

```python
airports_table = TableDefinition(table_name=TableName("public", "airports"), ... )  
```

```python
airports_table = TableDefinition(TableName("public", "airports"), ...)  
```