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

teradataml/dataframe/sql.py

@@ -265,7 +265,7 @@ class _PandasTableExpression(TableExpression):
 
         existing = [(c.name, c) for c in self.c]
         new = [(label, expression) for label, expression in kw.items() if label not in current]
-        new = sorted(new, key = lambda x: x[0])
+        new = sorted(new, key=lambda x: x[0])
 
         for alias, expression in existing + new:
             if drop_columns and alias not in kw:
@@ -5480,6 +5480,7 @@ class _SQLColumnExpression(_LogicalColumnExpression,
         self._quotechar = kw.get("quotechar", None)
         self._udf_script = kw.get("udf_script", None)
         self.alias_name = self.compile() if (self._udf or self._udf_script) is None else None
+        self._debug = kw.get("debug", False)
 
     @property
     def expression(self):
@@ -7002,12 +7003,12 @@ class _SQLColumnExpression(_LogicalColumnExpression,
                 Specifies starting position to extract string from column.
                 Note:
                     Index position starts with 1 instead of 0.
-                Types: int
+                Types: int OR ColumnExpression
 
             length:
                 Required Argument.
                 Specifies the length of the string to extract from column.
-                Types: int
+                Types: int OR ColumnExpression
 
         RETURNS:
             ColumnExpression.
@@ -7040,8 +7041,20 @@ class _SQLColumnExpression(_LogicalColumnExpression,
                    emp_name  mgr_id mgr_name new_col
             emp_id
             500        Fred     400      Kim      on
+
+            # Example 3: Create a new column by passing ColumnExpression as
+            #            start_pos and length.
+            >>> df.assign(new_column = df.emp_name.substr(df.emp_id, df.mgr_id))
+                     emp_name  mgr_id mgr_name new_column
+            emp_id
+            1         Pat   2      Don        Pa
+
         """
-        return _SQLColumnExpression(func.substr(self.expression, start_pos, length),
+        # Handle cases where start_pos or length are ColumnExpressions.
+        start_pos_expr = start_pos.expression if isinstance(start_pos, _SQLColumnExpression) else start_pos
+        length_expr = length.expression if isinstance(length, _SQLColumnExpression) else length
+
+        return _SQLColumnExpression(func.substr(self.expression, start_pos_expr, length_expr),
                                     type=self.type)
 
     @collect_queryband(queryband="DFC_replace")
@@ -8954,8 +8967,8 @@ class _SQLColumnExpression(_LogicalColumnExpression,
         PARAMETERS:
             formatter:
                 Optional Argument.
-                Specifies the string to format the values of a column.
-                Type: str
+                Specifies the format for formatting the values of the column.
+                Type: str OR ColumnExpression 
                 Note:
                    * If 'formatter' is omitted, numeric values is converted to a string exactly
                      long enough to hold its significant digits.
@@ -9525,94 +9538,333 @@ class _SQLColumnExpression(_LogicalColumnExpression,
 
         EXAMPLES:
             # Load the data to run the example.
-            >>> load_example_data("uaf", "stock_data")
+            >>> load_example_data("teradataml", "tochar_data")
 
-            # Create a DataFrame on 'stock_data' table.
-            >>> df = DataFrame("stock_data")
+            # Create a DataFrame on 'tochar_data' table.
+            >>> df = DataFrame("tochar_data")
             >>> df
-                        seq_no timevalue  magnitude
-            data_set_id
-            556               3  19/01/16     61.080
-            556               5  19/01/30     63.810
-            556               6  19/02/06     63.354
-            556               7  19/02/13     63.871
-            556               9  19/02/27     61.490
-            556              10  19/03/06     61.524
-            556               8  19/02/20     61.886
-            556               4  19/01/23     63.900
-            556               2  19/01/09     61.617
-            556               1  19/01/02     60.900
+                int_col  float_col  date_col int_format float_format date_format
+            id                                                                  
+            3      1314     123.46  03/09/17       XXXX          TM9          DY
+            0      1234     234.56  03/09/17      9,999        999D9       MM-DD
+            2       789     123.46  03/09/17       0999       9999.9         DAY
+            1       456     234.56  03/09/17       $999      9.9EEEE        CCAD
+
             >>> df.tdtypes
-            column         type
-            data_set_id    INTEGER()
-            seq_no         INTEGER()
-            timevalue         DATE()
-            magnitude        FLOAT()
-
-            # Example 1: Convert 'seq_no' column to character type.
-            >>> res = df.assign(seq_no = df.seq_no.to_char())
+            COLUMN NAME	                                   TYPE
+            id                                        INTEGER()
+            int_col                                   INTEGER()
+            float_col                                   FLOAT()
+            date_col                                     DATE()
+            int_format      VARCHAR(length=20, charset='LATIN')
+            float_format    VARCHAR(length=20, charset='LATIN')
+            date_format     VARCHAR(length=20, charset='LATIN')
+
+            # Example 1: Convert 'int_col' column to character type.
+            >>> res = df.assign(int_col = df.int_col.to_char())
             >>> res
-                        seq_no timevalue  magnitude
-            data_set_id
-            556              3  19/01/16     61.080
-            556              5  19/01/30     63.810
-            556              6  19/02/06     63.354
-            556              7  19/02/13     63.871
-            556              9  19/02/27     61.490
-            556             10  19/03/06     61.524
-            556              8  19/02/20     61.886
-            556              4  19/01/23     63.900
-            556              2  19/01/09     61.617
-            556              1  19/01/02     60.900
+                int_col  float_col  date_col int_format float_format date_format
+            id                                                                 
+            0     1234     234.56  03/09/17      9,999        999D9       MM-DD
+            3     1314     123.46  03/09/17       XXXX          TM9          DY
+            2      789     123.46  03/09/17       0999       9999.9         DAY
+            1      456     234.56  03/09/17       $999      9.9EEEE        CCAD
+
             >>> res.tdtypes
-            columnn         type
-            data_set_id    INTEGER()
-            seq_no         VARCHAR()
-            timevalue         DATE()
-            magnitude        FLOAT()
-
-            # Example 2: Convert "magnitude" column to character type in '$99.9' format.
-            >>> res = df.assign(char_column = df.magnitude.to_char('$99.9'))
+            COLUMN NAME	                                   TYPE
+            id                                        INTEGER()
+            int_col                                   VARCHAR()
+            float_col                                   FLOAT()
+            date_col                                     DATE()
+            int_format      VARCHAR(length=20, charset='LATIN')
+            float_format    VARCHAR(length=20, charset='LATIN')
+            date_format     VARCHAR(length=20, charset='LATIN')
+
+            # Example 2: Convert 'float_col' column to character type in '$999.9' format.
+            >>> res = df.assign(char_col = df.float_col.to_char('$999.9'))
             >>> res
-                        seq_no timevalue  magnitude char_column
-            data_set_id
-            556               3  19/01/16     61.080       $61.1
-            556               5  19/01/30     63.810       $63.8
-            556               6  19/02/06     63.354       $63.4
-            556               7  19/02/13     63.871       $63.9
-            556               9  19/02/27     61.490       $61.5
-            556              10  19/03/06     61.524       $61.5
-            556               8  19/02/20     61.886       $61.9
-            556               4  19/01/23     63.900       $63.9
-            556               2  19/01/09     61.617       $61.6
-            556               1  19/01/02     60.900       $60.9
-
-            # Example 3: Convert "timevalue" column to character type in 'YYYY-DAY-MONTH' format
-            >>> res = df.assign(timevalue = df.timevalue.to_char('YYYY-DAY-MONTH'))
+                int_col  float_col  date_col int_format float_format date_format char_col
+            id                                                                           
+            0      1234     234.56  03/09/17      9,999        999D9       MM-DD   $234.6
+            3      1314     123.46  03/09/17       XXXX          TM9          DY   $123.5
+            2       789     123.46  03/09/17       0999       9999.9         DAY   $123.5
+            1       456     234.56  03/09/17       $999      9.9EEEE        CCAD   $234.6
+
+            # Example 3: Convert 'date_col' column to character type in 'YYYY-DAY-MONTH' format
+            >>> res = df.assign(char_col = df.date_col.to_char('YYYY-DAY-MONTH'))
             >>> res
-                        seq_no                 timevalue  magnitude
-            data_set_id
-            556               3  2019-WEDNESDAY-JANUARY       61.080
-            556               5  2019-WEDNESDAY-JANUARY       63.810
-            556               6  2019-WEDNESDAY-FEBRUARY      63.354
-            556               7  2019-WEDNESDAY-FEBRUARY      63.871
-            556               9  2019-WEDNESDAY-FEBRUARY      61.490
-            556              10  2019-WEDNESDAY-MARCH         61.524
-            556               8  2019-WEDNESDAY-FEBRUARY      61.886
-            556               4  2019-WEDNESDAY-JANUARY       63.900
-            556               2  2019-WEDNESDAY-JANUARY       61.617
-            556               1  2019-WEDNESDAY-JANUARY       60.900
+                int_col  float_col  date_col int_format float_format date_format                  char_col
+            id                                                                                            
+            3      1314   123.4600  03/09/17       XXXX          TM9          DY  1903-THURSDAY -SEPTEMBER
+            0      1234   234.5600  03/09/17      9,999        999D9       MM-DD  1903-THURSDAY -SEPTEMBER
+            2       789   123.4600  03/09/17       0999       9999.9         DAY  1903-THURSDAY -SEPTEMBER
+            1       456   234.5600  03/09/17       $999      9.9EEEE        CCAD  1903-THURSDAY -SEPTEMBER
+
+            # Example 4: Convert 'int_col' column to character type in 'int_format' column format.
+            >>> res = df.assign(char_col = df.int_col.to_char(df.int_format))
+            >>> res
+                int_col  float_col  date_col int_format float_format date_format char_col
+            id                                                                           
+            0      1234     234.56  03/09/17      9,999        999D9       MM-DD    1,234
+            3      1314     123.46  03/09/17       XXXX          TM9          DY      522
+            2       789     123.46  03/09/17       0999       9999.9         DAY     0789
+            1       456     234.56  03/09/17       $999      9.9EEEE        CCAD     $456
+
+            # Example 5: Convert 'float_col' column to character type in 'float_format' column format.
+            >>> res = df.assign(char_col = df.float_col.to_char(df.float_format))
+            >>> res
+                int_col  float_col  date_col int_format float_format date_format   char_col
+            id                                                                             
+            2       789     123.46  03/09/17       0999       9999.9         DAY      123.5
+            3      1314     123.46  03/09/17       XXXX          TM9          DY     123.46
+            1       456     234.56  03/09/17       $999      9.9EEEE        CCAD    2.3E+02
+            0      1234     234.56  03/09/17      9,999        999D9       MM-DD      234.6
+
+            # Example 4: Convert 'date_col' column to character type in 'date_format' column format.
+            >>> res = df.assign(char_col = df.date_col.to_char(df.date_format))
+            >>> res
+                int_col  float_col  date_col int_format float_format date_format   char_col
+            id                                                                             
+            0      1234     234.56  03/09/17      9,999        999D9       MM-DD      09-17
+            3      1314     123.46  03/09/17       XXXX          TM9          DY        THU
+            2       789     123.46  03/09/17       0999       9999.9         DAY   THURSDAY 
+            1       456     234.56  03/09/17       $999      9.9EEEE        CCAD       20AD
+
         """
         arg_validate = []
-        arg_validate.append(["formatter", formatter, True, (str), True])
+        arg_validate.append(["formatter", formatter, True, (str, ColumnExpression), True])
 
         # Validate argument types
         _Validators._validate_function_arguments(arg_validate)
 
         _args=[self.expression]
         if formatter:
+            formatter = formatter.expression if isinstance(formatter, ColumnExpression) else formatter
             _args.append(formatter)
         return _SQLColumnExpression(func.to_char(*_args), type=VARCHAR())
+    
+    def to_number(self, formatter=None):
+        """
+        DESCRIPTION:
+            Converts a string-like representation of a number to NUMBER type.
+            
+        PARAMETERS:
+            formatter:
+                Optional Argument.
+                Specifies a variable length string containing formatting characters
+                that define the format of the columns.
+                Type: str OR ColumnExpression
+                Note:
+                    * If 'formatter' is omitted, numeric values is converted to a string exactly
+                      long enough to hold its significant digits.
+
+                * Formatters:
+                    +--------------------------------------------------------------------------------------------------+
+                    |    FORMATTER                             DESCRIPTION                                             |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    , (comma)                             A comma in the specified position.                      |
+                    |                                          A comma cannot begin a number format.                   |
+                    |                                          A comma cannot appear to the right of a decimal         |
+                    |                                          character or period in a number format.                 |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "1,234"            "9,999"           1234     | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    . (period)                            A decimal point. Only one allowed in a format.          |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "12.34"            "99.99"          12.34     | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    $                                     A value with a leading dollar sign.                     |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "$1234"            "$9999"           1234     | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    0                                     Leading or trailing zeros.                              |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "0123"             "0999"            123      | |
+                    |                                              |   "1230"             "9990"            1230     | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    9                                     Specified number of digits.                             |
+                    |                                          Leading space if positive, minus if negative.           |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    "1234"            "9999"            1234     | |
+                    |                                              |   "-1234"            "9999"           -1234     | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    B                                     Blanks if integer part is zero.                         |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    "0"               "B9999"             0      | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    C                                     ISO currency symbol (from SDF ISOCurrency).             |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "USD123"            "C999"             123    | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    D                                     Radix separator for non-monetary values.                |
+                    |                                          From SDF RadixSeparator.                                |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "12.34"            "99D99"           12.34    | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    EEEE                                  Scientific notation.                                    |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "1.2E+04"         "9.9EEEE"          12000    | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    G                                     Group separator for non-monetary values.                |
+                    |                                          From SDF GroupSeparator.                                |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "1,234,567"       "9G999G999"       1234567   | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    L                                     Local currency (from SDF Currency element).             |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "$123"             "L999"              123    | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    MI                                    Trailing minus sign if value is negative.               |
+                    |                                          Can only appear in the last position.                   |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |   "1234-"            "9999MI"          -1234    | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    PR                                    Negative value in angle brackets.                       |
+                    |                                          Positive value with leading/trailing blank.             |
+                    |                                          Only in the last position.                              |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    " 123 "          "9999PR"            123     | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    S                                     Sign indicator: + / - at beginning or end.              |
+                    |                                          Can only appear in first or last position.              |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    "-1234"           "S9999"           -1234    | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    U                                     Dual currency (from SDF DualCurrency).                  |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    "$123"             "U999"             123    | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+                    |    X                                     Hexadecimal format.                                     |
+                    |                                          Accepts only non-negative values.                       |
+                    |                                          Must be preceded by 0 or FM.                            |
+                    |                                          Example:                                                |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    data             formatter         result    | |
+                    |                                              +-------------------------------------------------+ |
+                    |                                              |    "FF"                "XX"             255     | |
+                    |                                              +-------------------------------------------------+ |
+                    +--------------------------------------------------------------------------------------------------+
+        RAISES:
+            TypeError, ValueError, TeradataMlException
+            
+        RETURNS:
+            ColumnExpression
+            
+        EXAMPLES:
+            # Load the data to run the example.
+            >>> load_example_data("teradataml", "to_num_data")
+
+            # Create a DataFrame on 'to_num_data' table.
+            >>> df = DataFrame("to_num_data")
+            >>> df
+            price col_format
+            $1234      $9999
+            USD123      C999
+            78.12      99.99
+
+            #  Example 1: Convert 'price' column to number type without passing any formatter.
+            >>> res = df.assign(new_col=df.price.to_number())
+            >>> res
+            price col_format  new_col
+            $1234      $9999      NaN
+            USD123      C999      NaN
+            78.12      99.99    78.12
+
+            #  Example 2: Convert 'price' column to number type by passing formatter as string.
+            >>> res = df.assign(new_col=df.price.to_number('99.99'))
+            >>> res
+            price col_format  new_col
+            $1234      $9999      NaN
+            USD123      C999      NaN
+            78.12      99.99    78.12
+
+            #  Example 3: Convert 'price' column to number type by passing formatter as ColumnExpression.
+            >>> res = df.assign(new_col=df.price.to_number(df.col_format))
+            >>> res
+            price col_format  new_col
+             $1234     $9999     1234
+            USD123      C999      123
+             78.12     99.99    78.12
+
+            >>> df.tdtypes
+            price	    VARCHAR(length=20, charset='LATIN')
+            col_format	VARCHAR(length=20, charset='LATIN')
+            new_col	                               NUMBER()
+      
+        """
+
+        arg_validate = []
+        arg_validate.append(["formatter", formatter, True, (str, ColumnExpression), True])
+
+        # Validate argument types
+        _Validators._validate_function_arguments(arg_validate)
+        
+        _args = [self.expression]
+        if formatter is not None:
+            formatter = formatter.expression if isinstance(formatter, ColumnExpression) else formatter
+            _args.append(formatter)
+
+        return _SQLColumnExpression(func.to_number(*_args), type=NUMBER())
 
     def to_date(self, formatter=None):
         """
@@ -10978,4 +11230,4 @@ class _SQLColumnExpression(_LogicalColumnExpression,
             >>>
 
         """
-        return _SQLColumnExpression(literal_column(f"TD_ISFINITE({self.compile()})"), type=INTEGER)
+        return _SQLColumnExpression(literal_column(f"TD_ISFINITE({self.compile()})"), type=INTEGER)