teradataml 20.0.0.2__py3-none-any.whl → 20.0.0.3__py3-none-any.whl

teradataml/dbutils/dbutils.py

@@ -37,7 +37,7 @@ from teradataml.utils.internal_buffer import _InternalBuffer
 
 
 @collect_queryband(queryband='DrpTbl')
-def db_drop_table(table_name, schema_name=None):
+def db_drop_table(table_name, schema_name=None, suppress_error=False):
     """
     DESCRIPTION:
         Drops the table from the given schema.
@@ -55,6 +55,12 @@ def db_drop_table(table_name, schema_name=None):
             Default Value: None
             Types: str
 
+        suppress_error:
+            Optional Argument
+            Specifies whether to raise error or not.
+            Default Value: False
+            Types: str
+
     RETURNS:
         True - if the operation is successful.
 
@@ -83,14 +89,18 @@ def db_drop_table(table_name, schema_name=None):
 
     try:
         return UtilFuncs._drop_table(table_name)
-    except TeradataMlException:
-        raise
-    except OperationalError:
-        raise
+    except (TeradataMlException, OperationalError):
+        if suppress_error:
+            pass
+        else:
+            raise
     except Exception as err:
-        raise TeradataMlException(Messages.get_message(MessageCodes.DROP_FAILED, "table",
-                                                       table_name),
-                                  MessageCodes.DROP_FAILED) from err
+        if suppress_error:
+            pass
+        else:
+            raise TeradataMlException(Messages.get_message(MessageCodes.DROP_FAILED, "table",
+                                                           table_name),
+                                      MessageCodes.DROP_FAILED) from err
 
 
 @collect_queryband(queryband='DrpVw')
@@ -173,6 +183,8 @@ def db_list_tables(schema_name=None, object_name=None, object_type='all'):
             a replacement for the percent.
             A '_' represents exactly one arbitrary character. Any single character is acceptable in the position in
             which the underscore character appears.
+            Note:
+                * If '%' is specified in 'object_name', then the '_' character is not evaluated for an arbitrary character.
             Default Value: None
             Types: str
             Example:
@@ -207,15 +219,15 @@ def db_list_tables(schema_name=None, object_name=None, object_type='all'):
         >>> execute_sql("create view temporary_view as (select 1 as dummy_col1, 2 as dummy_col2);")
         >>> db_list_tables(None , None, 'view')
 
-        # Example 3 - List all the object types in the default schema whose names begin with 'abc' followed by one
-        # arbitrary character and any number of characters in the end.
+        # Example 3 - List all the object types in the default schema whose names begin with 'abc' followed by any number
+        # of characters in the end.
         >>> execute_sql("create view abcd123 as (select 1 as dummy_col1, 2 as dummy_col2);")
-        >>> db_list_tables(None, 'abc_%', None)
+        >>> db_list_tables(None, 'abc%', None)
 
-        # Example 4 - List all the tables in the default schema whose names begin with 'adm_%' followed by one
-        # arbitrary character and any number of characters in the end.
+        # Example 4 - List all the tables in the default schema whose names begin with 'adm' followed by any number of
+        # characters and ends with 'train'.
         >>> load_example_data("dataframe", "admissions_train")
-        >>> db_list_tables(None, 'adm_%', 'table')
+        >>> db_list_tables(None, 'adm%train', 'table')
 
         # Example 5 - List all the views in the default schema whose names begin with any character but ends with 'abc'
         >>> execute_sql("create view view_abc as (select 1 as dummy_col1, 2 as dummy_col2);")
@@ -390,7 +402,7 @@ def _execute_transaction(queries):
             for query in queries:
                 cur.execute(query)
 
-            # Try committing the the transaction
+            # Try committing the transaction
             con.commit()
         except Exception:
             # Let's first rollback
@@ -402,6 +414,71 @@ def _execute_transaction(queries):
             cur.execute(auto_commit_on)
 
 
+def db_transaction(func):
+    """
+    DESCRIPTION:
+        Function to execute another function in a transaction.
+
+    PARAMETERS:
+        func:
+            Required Argument.
+            Specifies the function to be executed in a single transaction.
+            Types: function
+
+    RETURNS:
+        The object returned by "func".
+
+    RAISES:
+        TeradataMlException, OperationalError
+
+    EXAMPLES:
+        # Example: Declare a function to delete all the records from two tables
+        #          and execute the function in a transaction.
+        >>> @db_transaction
+        ... def insert_data(table1, table2):
+        ...     execute_sql("delete from {}".format(table1))
+        ...     execute_sql("delete from {}".format(table2))
+        ...     return True
+        >>> # Executing the above function in a transaction.
+        >>> insert_data("sales", "admissions_train")
+        True
+        >>>
+    """
+    def execute_transaction(*args, **kwargs):
+        auto_commit_off = "{fn teradata_nativesql}{fn teradata_autocommit_off}"
+        auto_commit_on = "{fn teradata_nativesql}{fn teradata_autocommit_on}"
+        con = None
+        cur = None
+
+        result = None
+        try:
+            con = tdmlctx.td_connection
+            if con is None:
+                raise TeradataMlException(Messages.get_message(MessageCodes.CONNECTION_FAILURE),
+                                          MessageCodes.CONNECTION_FAILURE)
+            con = con.connection
+            cur = con.cursor()
+            # Set auto_commit to OFF.
+            cur.execute(auto_commit_off)
+
+            # Execute function.
+            result = func(*args, **kwargs)
+
+            # Try committing the transaction.
+            con.commit()
+        except Exception:
+            # Let's first rollback.
+            con.rollback()
+            # Now, let's raise the error as is.
+            raise
+        finally:
+            # Finally, we must set auto_commit to ON.
+            cur.execute(auto_commit_on)
+
+        return result
+
+    return execute_transaction
+
 def _execute_stored_procedure(function_call, fetchWarnings=True, expect_none_result=False):
     """
     DESCRIPTION:
@@ -984,6 +1061,7 @@ def _create_table(table_name,
             pti = pti.no_primary_index()
 
         con_form=[]
+        foreign_constraints = []
         for c_name, parameters in kwargs.items():
             _Validators._validate_function_arguments([["constraint_type", c_name, True, str,
                                                        True, SQLConstants.CONSTRAINT.value]])
@@ -992,9 +1070,21 @@ def _create_table(table_name,
                 [con_form.append("{}('{}')".format("CheckConstraint", col)) for col in parameters]
             if c_name in 'foreign_key_constraint':
                 parameters = parameters if isinstance(parameters[0], tuple) else [tuple(parameters)]
-                for col in parameters:
-                    meta.reflect(bind=tdmlctx.get_context(), only=[col[2]])
-                    con_form.append("{}({},{})".format("ForeignKeyConstraint", col[0], col[1]))
+                # Every element in parameter is 3 elements.
+                # 1st element and 2nd element also a list. 3rd element is name of ForeignKey.
+                for fk_columns, fk_ref_columns, fk_name in parameters:
+                    fk_ref_column_objs = []
+
+                    # fk_ref_columns is in this format - table_name.column_name .
+                    # There is no provision for schema name here.
+                    # sqlalchemy is not accepting this notation here - schema_name.table_name.column_name
+                    # So, create Column Object and bind schema name and table name to it.
+                    for fk_ref_column in fk_ref_columns:
+                        ref_column_table, ref_column = fk_ref_column.split(".")
+                        t = Table(ref_column_table, MetaData(), Column(ref_column), schema=schema_name)
+                        fk_ref_column_objs.append(getattr(t, "c")[ref_column])
+                    foreign_constraints.append(ForeignKeyConstraint(fk_columns, fk_ref_column_objs, fk_name))
+
             if c_name in ['primary_key_constraint', 'unique_key_constraint']:
                 c_name = "UniqueConstraint" if c_name in 'unique_key_constraint' else 'PrimaryKeyConstraint'
                 parameters = UtilFuncs._as_list(parameters)
@@ -1008,6 +1098,8 @@ def _create_table(table_name,
                     "schema=schema_name)".format("" if con_form is None else ",".join(con_form))
 
         table=eval(table_str)
+        for foreign_constraint in foreign_constraints:
+            table.append_constraint(foreign_constraint)
         table.create(bind=tdmlctx.get_context())
 
     except Exception as err:
@@ -1015,6 +1107,333 @@ def _create_table(table_name,
         raise TeradataMlException(Messages.get_message(msg_code, "create table", str(err)), msg_code)
 
 
+def _create_database(schema_name, size='10e6', spool_size=None):
+    """
+    DESCRIPTION:
+        Internal function to create a database with the specified name and size.
+
+    PARAMETERS:
+        schema_name:
+            Required Argument.
+            Specifies the name of the database to create.
+            Types: str
+
+        size:
+            Optional Argument.
+            Specifies the number of bytes to allocate to new database.
+            Note:
+                Exponential notation can also be used.
+            Types: str or int
+
+        spool_size:
+            Optional Argument.
+            Specifies the number of bytes to allocate to new database
+            for spool space.
+            Note:
+                Exponential notation can also be used.
+            Types: str or int
+
+    RETURNS:
+        bool
+
+    RAISES:
+        TeradataMlException.
+
+    EXAMPLES:
+       >>> from teradataml.dbutils.dbutils import _create_database
+       >>> _create_database("db_name1", "10e5")
+    """
+    sql = "CREATE DATABASE {} FROM {} AS PERM = {}".format(
+        schema_name, tdmlctx._get_database_username(), size)
+
+    # If user pass spool size, create it with specified space.
+    if spool_size:
+        sql = "{} , SPOOL = {}".format(sql, spool_size)
+
+    execute_sql(sql)
+    return True
+
+
+def _update_data(update_columns_values, table_name, schema_name, datalake_name=None, update_conditions=None):
+    """
+    DESCRIPTION:
+        Internal function to update the data in a table.
+
+    PARAMETERS:
+        update_columns_values:
+            Required Argument.
+            Specifies the columns and it's values to update.
+            Types: dict
+
+        table_name:
+            Required Argument.
+            Specifies the name of the table to update.
+            Types: str
+
+        schema_name:
+            Required Argument.
+            Specifies the name of the database to update the data in the
+            table "table_name".
+            Types: str
+
+        datalake_name:
+            Optional Argument.
+            Specifies the name of the datalake to look for "schema_name".
+            Types: str
+
+        update_conditions:
+            Optional Argument.
+            Specifies the key columns and it's values which is used as condition
+            for updating the records.
+            Types: dict
+
+    RETURNS:
+        bool
+
+    RAISES:
+        TeradataMlException.
+
+    EXAMPLES:
+       >>> from teradataml.dbutils.dbutils import _update_data
+       >>> _update_data("db_name1", "tbl", update_conditions={"column1": "value1"})
+    """
+    # Prepare the update clause.
+    update_clause = ", ".join(("{} = ?".format(col) for col in update_columns_values))
+    update_values = tuple((_value for _value in update_columns_values.values()))
+
+    # If key_columns_values is passed, then prepare the SQL with where clause.
+    # Else, simply update every thing.
+    schema_name = "{}.{}".format(datalake_name, schema_name) if datalake_name else schema_name
+
+    get_str_ = lambda val: "'{}'".format(val) if isinstance(val, str) else val
+    if update_conditions:
+
+        # Prepare where clause.
+        where_ = []
+        for column, col_value in update_conditions.items():
+            if isinstance(col_value, list):
+                col_value = ", ".join(get_str_(val) for val in col_value)
+                col_value = "({})".format(col_value)
+                where_.append("{} IN {}".format(column, col_value))
+            else:
+                where_.append("{} = {}".format(column, col_value))
+
+        where_clause = " AND ".join(where_)
+
+        sql = f"""UPDATE {schema_name}.{table_name} SET {update_clause}
+                 WHERE {where_clause}
+            """
+
+        execute_sql(sql, (*update_values, ))
+
+    else:
+        sql = f"""UPDATE {schema_name}.{table_name} SET {update_clause}"""
+
+        execute_sql(sql, update_values)
+    return True
+
+
+def _insert_data(table_name, values, columns=None, schema_name=None, datalake_name=None):
+    """
+    DESCRIPTION:
+        Internal function to insert the data in a table.
+
+    PARAMETERS:
+        table_name:
+            Required Argument.
+            Specifies the name of the table to insert.
+            Types: str
+
+        values:
+            Required Argument.
+            Specifies the values to insert.
+            Types: tuple or list of tuple
+
+        columns:
+            Optional Argument.
+            Specifies the name of columns to be involved in insert.
+            Types: list
+
+        schema_name:
+            Optional Argument.
+            Specifies the name of the database to insert the data in the
+            table "table_name".
+            Types: str
+
+        datalake_name:
+            Optional Argument.
+            Specifies the name of the datalake to look for "schema_name".
+            Types: str
+
+    RETURNS:
+        bool
+
+    RAISES:
+        TeradataMlException.
+
+    EXAMPLES:
+       >>> from teradataml.dbutils.dbutils import _insert_data
+       >>> _insert_data("tbl", (1, 2, 3))
+    """
+    # Prepare the update clause.
+    if schema_name:
+        table_name = '"{}"."{}"'.format(schema_name, table_name)
+        if datalake_name:
+            table_name = '"{}"."{}"'.format(datalake_name, table_name)
+
+    values = UtilFuncs._as_list(values)
+
+    # Prepare columns clause.
+    if columns:
+        # Prepare question marks.
+        _q_marks = ["?"] * len(columns)
+        columns = "({})".format(", ".join(columns))
+    else:
+        columns = ""
+        _q_marks = ["?"] * (len(values[0]))
+
+    sql = "insert into {} {} values ({});".format(table_name, columns, ", ".join(_q_marks))
+    execute_sql(sql, values)
+
+    return True
+
+
+def _upsert_data(update_columns_values,
+                 insert_columns_values,
+                 upsert_conditions,
+                 table_name,
+                 schema_name,
+                 datalake_name=None):
+    """
+    DESCRIPTION:
+        Internal function to either insert or update the data to a table.
+
+    PARAMETERS:
+        update_columns_values:
+            Required Argument.
+            Specifies the columns and it's values to update.
+            Types: dict
+
+        insert_columns_values:
+            Required Argument.
+            Specifies the columns and it's values to insert.
+            Types: dict
+
+        upsert_conditions:
+            Required Argument.
+            Specifies the key columns and it's values which is used as condition
+            for updating the records.
+            Types: tuple
+
+        table_name:
+            Required Argument.
+            Specifies the name of the table to insert.
+            Types: str
+
+        schema_name:
+            Required Argument.
+            Specifies the name of the database to update the data in the
+            table "table_name".
+            Types: str
+
+        datalake_name:
+            Optional Argument.
+            Specifies the name of the datalake to look for "schema_name".
+            Types: str
+
+    RETURNS:
+        bool
+
+    RAISES:
+        TeradataMlException.
+
+    EXAMPLES:
+       >>> from teradataml.dbutils.dbutils import _upsert_data
+       >>> _upsert_data("db_name1",
+                        "tbl",
+                        update_columns_values={"column1": "value1"},
+                        insert_columns_values={"column1": "value2"},
+                        upsert_conditions={"key1": "val1"}
+                        )
+    """
+    # If user passes datalake name, then append the same to schema name.
+    if datalake_name:
+        schema_name = "{}.{}".format(datalake_name, schema_name)
+
+    # Prepare the update clause.
+    update_clause = ", ".join(("{} = ?".format(col) for col in update_columns_values))
+    update_values = tuple((_value for _value in update_columns_values.values()))
+
+    # Prepare the where clause and it's values.
+    where_clause = " AND ".join(("{} = ?".format(col) for col in upsert_conditions))
+    where_values = tuple((_value for _value in upsert_conditions.values()))
+
+    # Prepare the insert clause and it's values.
+    insert_values_clause = ", ".join(("?" for _ in range(len(insert_columns_values))))
+    insert_clause = "({}) values ({})".format(", ".join(insert_columns_values), insert_values_clause)
+    insert_values = tuple((_value for _value in insert_columns_values.values()))
+
+    sql = f"""UPDATE {schema_name}.{table_name} SET {update_clause}
+         WHERE {where_clause}
+       ELSE INSERT {schema_name}.{table_name} {insert_clause}
+    """
+    execute_sql(sql, (*update_values, *where_values, *insert_values))
+
+def _delete_data(table_name, schema_name=None, datalake_name=None, delete_conditions=None):
+    """
+    DESCRIPTION:
+        Internal function to delete the data in a table.
+
+    PARAMETERS:
+        table_name:
+            Required Argument.
+            Specifies the name of the table to delete.
+            Types: str
+
+        schema_name:
+            Optional Argument.
+            Specifies the name of the database to delete the data in the
+            table "table_name".
+            Types: str
+
+        datalake_name:
+            Optional Argument.
+            Specifies the name of the datalake to look for "schema_name".
+            Types: str
+
+        delete_conditions:
+            Optional Argument.
+            Specifies the ColumnExpression to use for removing the data.
+            Types: ColumnExpression
+
+    RETURNS:
+        int, specifies the number of records those are deleted.
+
+    RAISES:
+        TeradataMlException.
+
+    EXAMPLES:
+       >>> from teradataml.dbutils.dbutils import _delete_data
+       >>> _delete_data("tbl", "db_name1", delete_conditions={"column1": "value1"})
+    """
+    if schema_name:
+        table_name = '"{}"."{}"'.format(schema_name, table_name)
+
+    if datalake_name:
+        table_name = "{}.{}".format(datalake_name, table_name)
+
+    sqlbundle = SQLBundle()
+
+    sql = sqlbundle._get_sql_query(SQLConstants.SQL_DELETE_ALL_ROWS).format(table_name)
+
+    # If condition exist, the prepare where clause.
+    if delete_conditions:
+        where_clause = delete_conditions.compile()
+        sql = sqlbundle._get_sql_query(SQLConstants.SQL_DELETE_SPECIFIC_ROW).format(table_name, where_clause)
+
+    res = execute_sql(sql)
+    return res.rowcount
+
 @collect_queryband(queryband='LstKwrds')
 def list_td_reserved_keywords(key=None, raise_error=False):
     """
@@ -1471,3 +1890,122 @@ def unset_session_param(name):
 
     return True
 
+class _Authorize:
+    """ Parent class to either provide or revoke access on table(s). """
+    _property = None
+
+    def __init__(self, objects):
+        """
+        DESCRIPTION:
+            Constructor for creating Authorize object.
+
+        PARAMETERS:
+            objects:
+                Required Argument.
+                Specifies the name(s) of the database objects to be authorized.
+                Types: str OR list of str.
+
+        RETURNS:
+            Object of _Authorize.
+
+        RAISES:
+            None
+
+        EXAMPLES:
+            >>> auth = _Authorize('vfs_v1')
+        """
+        # Store the objects here. Then use this where ever required.
+        self._objects = objects
+        self._access_method = self.__class__.__name__.upper()
+
+    def read(self, user):
+        """
+        DESCRIPTION:
+            Authorize the read access.
+            Note:
+                One must have admin access to give read access to other "user".
+
+        PARAMETERS:
+            user:
+                Required Argument.
+                Specifies the name of the user to have read only access.
+                Types: str
+
+        RETURNS:
+            bool.
+
+        RAISES:
+            None
+
+        EXAMPLES:
+            >>> _Authorize('repo').read('BoB')
+        """
+        for object in self._objects:
+            sql = "{} SELECT ON {} {} {}".format(self._access_method, object, self._property, user)
+            execute_sql(sql)
+
+        return True
+
+    def write(self, user):
+        """
+        DESCRIPTION:
+            Authorize the write access.
+            Note:
+                One must have admin access to give write access to other "user".
+
+        PARAMETERS:
+            user:
+                Required Argument.
+                Specifies the name of the user to have write only access.
+                Types: str
+
+        RETURNS:
+            bool.
+
+        RAISES:
+            None
+
+        EXAMPLES:
+            >>> _Authorize('repo').write('BoB')
+        """
+        for access_type in ["INSERT", "UPDATE", "DELETE"]:
+            for object in self._objects:
+                sql = "{} {} ON {} {} {}".format(self._access_method, access_type, object, self._property, user)
+                execute_sql(sql)
+
+        return True
+
+    def read_write(self, user):
+        """
+        DESCRIPTION:
+            Authorize the read and write access.
+            Note:
+                One must have admin access to give read and write access to other "user".
+
+        PARAMETERS:
+            user:
+                Required Argument.
+                Specifies the name of the user to have read and write access.
+                Types: str
+
+        RETURNS:
+            bool.
+
+        RAISES:
+            None
+
+        EXAMPLES:
+            >>> _Authorize('repo').read_write('BoB')
+        """
+        self.read(user)
+        return self.write(user)
+
+
+class Grant(_Authorize):
+    """ Class to grant access to tables."""
+    _property = "TO"
+
+
+class Revoke(_Authorize):
+    """ Class to revoke access from tables."""
+    _property = "FROM"