Metadata-Version: 2.3
Name: hana-cloud-interface
Version: 0.3.1
Summary: Runs a SQL command on SAP HANA Cloud using OAuth single sign on and returns a pandas or polars dataframe
Author: charlotte corpe
Author-email: charlotte corpe <charlotte.corpe@powerco.co.nz>
Requires-Dist: hdbcli
Requires-Dist: polars
Requires-Dist: pandas
Requires-Dist: hana-ml
Requires-Dist: platformdirs
Requires-Dist: selenium
Requires-Dist: webdriver-manager
Requires-Dist: ipykernel
Requires-Dist: requests-oauthlib
Requires-Dist: pyarrow
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Usage of the `hana_cloud_interface` package 

This package provides a simple interface to connect to SAP HANA Cloud databases and execute SQL queries. Below are some examples of how to use the package.


## initialising class
when initialising the class it has two optional args. 

- config_file : Path to the configuration file (JSON format) containing OAuth credentials and other settings. the config file only needs to be added on the first time running the class on a computer. 

- data_frame_type : Default data frame type for SQL query results. Options are 'pandas' or 'polars'. Default is 'pandas'.
if the data type is not added here it will need to be added for every time you run hana_sql function

```python
Hana_cloud_interface(config_file = 'location of configuration file',  df = 'pandas')
```

## hana_sql() function
Execute a SQL command on the HANA Cloud database and return the result as a DataFrame.

Args:
    sql_command (str, optional): The SQL command to execute. Defaults to 'validate', which only checks the connection.
    DF_type_local_override (str, optional): DataFrame type for this query ('pandas' or 'polars'). Overrides the global setting if provided. 

Returns:
    str: If sql_command is 'validate', returns a validation message.
    pandas.DataFrame or polars.DataFrame: The query result as a DataFrame, depending on the specified or default DataFrame type.

Raises:
    ValueError: If the DataFrame type is not specified or is invalid.

## hana_upload() function
Upload a DataFrame to the HANA Cloud database.

Args:
    data (pandas.DataFrame or polars.DataFrame): The data to upload. If a polars DataFrame is provided, it will be converted to pandas.
    data_name (str): The name of the table to create or replace in HANA Cloud.
    SCHEMA (str): The schema in which to create the table.

Returns:
    bool: True if the upload is successful.

Raises:
    Exception: If the upload fails due to connection or data issues.


## configuration file
the configuration file is a .json file
```python
{
    "CLIENT_ID": "",
    "CLIENT_SECRET": "",
    "AUTH_URL": "",
    "TOKEN_URL": "",
    "protected_url": "",
    "REDIRECT_URI": "",
    "SCOPE": "",
	"HC_prod_URL": ""
}
```

## example
the main function is very simple It takes a SQL command as a string and returns the data
```python
import hana_cloud_interface 

# initialise class
hci = Hana_cloud_interface(df='polars')

sql_command = """
SELECT top 10
    "data1"
    "data2"
FROM "table1"
"""
    
data = hci.hana_sql(sql_command)

```