Teradata Package for Python Function Reference | 20.00 - fastexport - Teradata Package for Python - Look here for syntax, methods and examples for the functions included in the Teradata Package for Python.

Teradata® Package for Python Function Reference - 20.00

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
VMware
Product
Teradata Package for Python
Release Number
20.00
Published
March 2024
Language
English (United States)
Last Update
2024-04-10
dita:id
TeradataPython_FxRef_Enterprise_2000
Product Category
Teradata Vantage
teradataml.dataframe.data_transfer.fastexport = fastexport(df, export_to='pandas', index_column=None, catch_errors_warnings=False, csv_file=None, **kwargs)
DESCRIPTION:
    The fastexport() API exports teradataml DataFrame to Pandas DataFrame
    or CSV file 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() or to_csv()
           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.
        Types: 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.
            * "csv": Export data to a given CSV file.
        Default Value: "pandas"
        Types: String
 
    index_column:
        Optional Argument.
        Specifies column(s) to be used as index column for the converted object.
        Note:
            Applicable only when 'export_to' is set to "pandas".
        Default Value: None.
        Types: String 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.
        Notes :
            1.  When 'export_to' is set to "pandas" and 'catch_errors_warnings' is 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.
 
 
            2.  When 'export_to' is set to "csv" and 'catch_errors_warnings' is set to True,
                fastexport() returns a tuple containing:
                    a. Errors(if any) in a list thrown by fastexport.
                    b. Warnings(if any) in a list thrown by fastexport.
        Default Value: False
        Types: bool
 
    csv_file:
        Optional Argument.
        Specifies the name of CSV file to which data is to be exported.
        Note:
            This is required argument when 'export_to' is set to "csv".
        Types: String
 
    kwargs:
        Optional Argument.
        Specifies keyword arguments. Accepts following keyword arguments:
 
        sep:
            Optional Argument.
            Specifies a single character string used to separate fields in a CSV file.
            Default Value: ","
            Notes:
                1. "sep" cannot be line feed ('\n') or carriage return ('\r').
                2. "sep" should not be same as "quotechar".
                3. Length of "sep" argument should be 1.
            Types: String
 
        quotechar:
            Optional Argument.
            Specifies a single character string used to quote fields in a CSV file.
            Default Value: """
            Notes:
                1. "quotechar" cannot be line feed ('\n') or carriage return ('\r').
                2. "quotechar" should not be same as "sep".
                3. Length of "quotechar" argument should be 1.
            Types: String
 
        coerce_float:
            Optional Argument.
            Specifies whether to convert non-string, non-numeric objects to floating point.
            Note:
                For additional information about "coerce_float" please refer to:
                https://pandas.pydata.org/docs/reference/api/pandas.read_sql.html
 
        parse_dates:
            Optional Argument.
            Specifies columns to parse as dates.
            Note:
                For additional information about "parse_date" please refer to:
                https://pandas.pydata.org/docs/reference/api/pandas.read_sql.html
 
        open_sessions:
            Optional Argument.
            specifies the number of Teradata sessions to be opened for fastexport.
            Note:
                If "open_sessions" argument is not provided, the default value
                is the smaller of 8 or the number of AMPs avaialble.
                For additional information about number of Teradata data-transfer
                sessions opened during fastexport, please refer to:
                https://pypi.org/project/teradatasql/#FastExport
            Types: Integer
 
 
RETURNS:
    1.  When 'export_to' is set to "pandas" and "catch_errors_warnings" is 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 'export_to' is set to "pandas" and "catch_errors_warnings" is set to False,
        then the function returns a Pandas DataFrame.
    2.  When 'export_to' is set to "csv" and "catch_errors_warnings" is set to True,
        then the function returns a tuple containing:
            a. Errors, if any, thrown by fastexport in a list of strings.
            b. Warnings, if any, thrown by fastexport in a list of strings.
 
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
        []
 
    # Example 3: Following example exports teradataml DataFrame df
    #            to Pandas DataFrame using fastexport() by opening specified
    #            number of Teradata data-transfer sessions.
    >>> fastexport(df, open_sessions=2)
        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 4: Following example exports teradataml DataFrame df
    #            to a given CSV file using fastexport().
    >>> fastexport(df, export_to="csv", csv_file="Test.csv")
        Data is successfully exported into Test.csv
 
    # Example 5: Following example exports teradataml DataFrame df
    #            to a given CSV file using fastexport() by opening specified
    #            number of Teradata data-transfer sessions.
    >>> fastexport(df, export_to="csv", csv_file="Test_1.csv", open_sessions=2)
        Data is successfully exported into Test_1.csv
 
    # Example 6: Following example exports teradataml DataFrame df
    #            to a given CSV file using fastexport() and catch errors/warnings
    #            thrown by fastexport.
    >>> err, warn = fastexport(df, export_to="csv", catch_errors_warnings=True,
                               csv_file="Test_3.csv")
        Data is successfully exported into Test_3.csv
    # Print errors list.
    >>> err
        []
    # Print warnings list.
    >>> warn
        []
 
    # Example 7: Export teradataml DataFrame to CSV file with '|' as field separator
    #            and single quote(') as field quote character.
    >>> fastexport(df, export_to="csv", csv_file="Test_4.csv",  sep = "|", quotechar="'")
        Data is successfully exported into Test_4.csv