Teradata Package for Python Function Reference - 17.00 - fastexport - Teradata Package for Python

Teradata® Package for Python Function Reference

Product
Teradata Package for Python
Release Number
17.00
Release Date
November 2021
Content Type
Programming Reference
Publication ID
B700-4008-070K
Language
English (United States)
teradataml.dataframe.data_transfer.fastexport = fastexport(df, export_to='pandas', index_column=None, catch_errors_warnings=False, **kwargs)
DESCRIPTION:
    The fastexport() API exports teradataml DataFrame to Pandas DataFrame
    using FastExport data transfer protocol.
    Note:
        1. Teradata recommends to use FastExport when number of rows in
           teradataml DataFrame are at least 100,000. To extract lesser rows
           ignore this function and go with regular to_pandas() function.
           FastExport opens multiple data transfer connections to the
           database.
        2. FastExport does not support all Teradata Database data types.
           For example, tables with BLOB and CLOB type columns cannot
           be extracted.
        3. FastExport cannot be used to extract data from a volatile or
           temporary table.
        4. For best efficiency, do not use DataFrame.groupby() and
           DataFrame.sort() with FastExport.
 
    For additional information about FastExport protocol through
    teradatasql driver, please refer to FASTEXPORT section of
    https://pypi.org/project/teradatasql/#FastExport driver documentation.
 
PARAMETERS:
    df:
        Required Argument.
        Specifies teradataml DataFrame that needs to be exported.
        Type: teradataml DataFrame.
 
    export_to:
        Optional Argument.
        Specifies a value that notifies where to export the data.
        Permitted Values:
            * "pandas": Export data to a Pandas DataFrame.
        Default Value: "pandas".
        Type: str.
 
    index_column:
        Optional Argument.
        Specifies column(s) to be used as index column for the converted
        object.
        Default Value: None.
        Types: str OR list of Strings (str).
 
    catch_errors_warnings:
        Optional Argument.
        Specifies whether to catch errors/warnings(if any) raised by
        fastexport protocol while converting teradataml DataFrame.
        When this and "to_pandas" arguments are set to True,
        fastexport() returns a tuple containing:
            a. Pandas DataFrame.
            b. Errors(if any) in a list thrown by fastexport.
            c. Warnings(if any) in a list thrown by fastexport.
        When set to False, prints the fastexport errors/warnings to the
        standard output, if there are any.
        Default Value: False.
        Types: bool.
 
    kwargs:
        Optional Argument.
        Specifies keyword arguments. Arguments "coerce_float" and
        "parse_dates" can be passed as keyword arguments.
            * "coerce_float" specifies whether to convert non-string,
              non-numeric objects to floating point.
            * "parse_dates" specifies columns to parse as dates.
        Note:
            For additional information about "coerce_float" and
            "parse_date" arguments please refer to:
            https://pandas.pydata.org/docs/reference/api/pandas.read_sql.html
 
RETURNS:
    When "to_pandas" and "catch_errors_warnings" are set to True, then the
    function returns a tuple containing:
        a. Pandas DataFrame.
        b. Errors, if any, thrown by fastexport in a list of strings.
        c. Warnings, if any, thrown by fastexport in a list of strings.
    When "to_pandas" is True and "catch_errors_warnings" is False, then the
    function returns a Pandas DataFrame.
 
EXAMPLES:
    >>> from teradataml import *
    >>> load_example_data("dataframe", "admissions_train")
    >>> df = DataFrame("admissions_train")
 
    # Print dataframe.
    >>> df
          masters   gpa     stats programming admitted
       id
       13      no  4.00  Advanced      Novice        1
       26     yes  3.57  Advanced    Advanced        1
       5       no  3.44    Novice      Novice        0
       19     yes  1.98  Advanced    Advanced        0
       15     yes  4.00  Advanced    Advanced        1
       40     yes  3.95    Novice    Beginner        0
       7      yes  2.33    Novice      Novice        1
       22     yes  3.46    Novice    Beginner        0
       36      no  3.00  Advanced      Novice        0
       38     yes  2.65  Advanced    Beginner        1
 
    # Example 1: Export teradataml DataFrame df to Pandas DataFrame using
    # fastexport().
    >>> fastexport(df)
        Errors: []
        Warnings: []
           masters   gpa     stats programming  admitted
        id
        38     yes  2.65  Advanced    Beginner         1
        26     yes  3.57  Advanced    Advanced         1
        5       no  3.44    Novice      Novice         0
        24      no  1.87  Advanced      Novice         1
        3       no  3.70    Novice    Beginner         1
        1      yes  3.95  Beginner    Beginner         0
        20     yes  3.90  Advanced    Advanced         1
        18     yes  3.81  Advanced    Advanced         1
        8       no  3.60  Beginner    Advanced         1
        25      no  3.96  Advanced    Advanced         1
        ...
 
    # Example 2: Export teradataml DataFrame df to Pandas DataFrame,
    # set index column, coerce_float and catch errors/warnings thrown by
    # fastexport.
    >>> pandas_df, err, warn = fastexport(df, index_column="gpa",
                                          catch_errors_warnings=True,
                                          coerce_float=True)
    # Print pandas DataFrame.
    >>> pandas_df
             id masters     stats programming  admitted
        gpa
        2.65  38     yes  Advanced    Beginner         1
        3.57  26     yes  Advanced    Advanced         1
        3.44   5      no    Novice      Novice         0
        1.87  24      no  Advanced      Novice         1
        3.70   3      no    Novice    Beginner         1
        3.95   1     yes  Beginner    Beginner         0
        3.90  20     yes  Advanced    Advanced         1
        3.81  18     yes  Advanced    Advanced         1
        3.60   8      no  Beginner    Advanced         1
        3.96  25      no  Advanced    Advanced         1
        3.76   2     yes  Beginner    Beginner         0
        3.83  17      no  Advanced    Advanced         1
 
        ...
    # Print errors list.
    >>> err
        []
    # Print warnings list.
    >>> warn
        []