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

Teradata® Package for Python Function Reference

Product
Teradata Package for Python
Release Number
17.00
Release Date
April 2021
Content Type
Programming Reference
Publication ID
B700-4008-070K
Language
English (United States)
teradataml.dataframe.dataframe.DataFrame.to_sql = to_sql(self, table_name, if_exists='fail', primary_index=None, temporary=False, schema_name=None, types=None, primary_time_index_name=None, timecode_column=None, timebucket_duration=None, timezero_date=None, columns_list=None, sequence_column=None, seq_max=None, set_table=False)
DESCRIPTION:
    Writes records stored in a teradataml DataFrame to Teradata Vantage.
 
PARAMETERS:
 
    table_name:
        Required Argument.
        Specifies the name of the table to be created in Teradata Vantage.
        Types: str
 
    schema_name:
        Optional Argument.
        Specifies the name of the SQL schema in Teradata Vantage to write to.
        Default Value: None (Use default Teradata Vantage schema).
        Types: str
 
        Note: schema_name will be ignored when temporary=True.
 
    if_exists:
        Optional Argument.
        Specifies the action to take when table already exists in Teradata Vantage.
        Default Value: 'fail'
        Permitted Values: 'fail', 'replace', 'append'
            - fail: If table exists, do nothing.
            - replace: If table exists, drop it, recreate it, and insert data.
            - append: If table exists, insert data. Create if does not exist.
        Types: str
 
        Note: Replacing a table with the contents of a teradataml DataFrame based on
              the same underlying table is not supported.
 
    primary_index:
        Optional Argument.
        Creates Teradata Table(s) with Primary index column(s) when specified.
        When None, No Primary Index Teradata tables are created.
        Default Value: None
        Types: str or List of Strings (str)
            Example:
                primary_index = 'my_primary_index'
                primary_index = ['my_primary_index1', 'my_primary_index2', 'my_primary_index3']
 
    temporary:
        Optional Argument.
        Creates Teradata SQL tables as permanent or volatile.
        When True,
        1. volatile tables are created, and
        2. schema_name is ignored.
        When False, permanent tables are created.
        Default Value: False
        Types: boolean
        
    types:
        Optional Argument.
        Specifies required data-types for requested columns to be saved in Vantage.
        Types: Python dictionary ({column_name1: type_value1, ... column_nameN: type_valueN})
        Default: None
 
        Note:
            1. This argument accepts a dictionary of columns names and their required teradatasqlalchemy types
               as key-value pairs, allowing to specify a subset of the columns of a specific type.
               When only a subset of all columns are provided, the column types for the rest are retained.
               When types argument is not provided, the column types are retained.
            2. This argument does not have any effect when the table specified using table_name and schema_name
               exists and if_exists = 'append'.
 
    primary_time_index_name:
        Optional Argument.
        Specifies a name for the Primary Time Index (PTI) when the table
        to be created must be a PTI table.
        Types: String
 
        Note: This argument is not required or used when the table to be created
              is not a PTI table. It will be ignored if specified without the timecode_column.
 
    timecode_column:
        Optional Argument.
        Required when the DataFrame must be saved as a PTI table.
        Specifies the column in the DataFrame that reflects the form
        of the timestamp data in the time series.
        This column will be the TD_TIMECODE column in the table created.
        It should be of SQL type TIMESTAMP(n), TIMESTAMP(n) WITH TIMEZONE, or DATE,
        corresponding to Python types datetime.datetime or datetime.date.
        Types: String
 
        Note: When you specify this parameter, an attempt to create a PTI table
              will be made. This argument is not required when the table to be created
              is not a PTI table. If this argument is specified, primary_index will be ignored.
 
    timezero_date:
        Optional Argument.
        Used when the DataFrame must be saved as a PTI table.
        Specifies the earliest time series data that the PTI table will accept;
        a date that precedes the earliest date in the time series data.
        Value specified must be of the following format: DATE 'YYYY-MM-DD'
        Default Value: DATE '1970-01-01'.
        Types: String
 
        Note: This argument is not required or used when the table to be created
              is not a PTI table. It will be ignored if specified without the timecode_column.
 
    timebucket_duration:
        Optional Argument.
        Required if columns_list is not specified or is None.
        Used when the DataFrame must be saved as a PTI table.
        Specifies a duration that serves to break up the time continuum in
        the time series data into discrete groups or buckets.
        Specified using the formal form time_unit(n), where n is a positive
        integer, and time_unit can be any of the following:
        CAL_YEARS, CAL_MONTHS, CAL_DAYS, WEEKS, DAYS, HOURS, MINUTES,
        SECONDS, MILLISECONDS, or MICROSECONDS.
        Types:  String
 
        Note: This argument is not required or used when the table to be created
              is not a PTI table. It will be ignored if specified without the timecode_column.
 
    columns_list:
        Optional Argument.
        Required if timebucket_duration is not specified.
        Used when the DataFrame must be saved as a PTI table.
        Specifies a list of one or more PTI table column names.
        Types: String or list of Strings
 
        Note: This argument is not required or used when the table to be created
              is not a PTI table. It will be ignored if specified without the timecode_column.
 
    sequence_column:
        Optional Argument.
        Used when the DataFrame must be saved as a PTI table.
        Specifies the column of type Integer containing the unique identifier for
        time series data readings when they are not unique in time.
        * When specified, implies SEQUENCED, meaning more than one reading from the same
          sensor may have the same timestamp.
          This column will be the TD_SEQNO column in the table created.
        * When not specified, implies NONSEQUENCED, meaning there is only one sensor reading
          per timestamp.
          This is the default.
        Types: str
 
        Note: This argument is not required or used when the table to be created
              is not a PTI table. It will be ignored if specified without the timecode_column.
 
    seq_max:
        Optional Argument.
        Used when the DataFrame must be saved as a PTI table.
        Specifies the maximum number of sensor data rows that can have the
        same timestamp. Can be used when 'sequenced' is True.
        Accepted range:  1 - 2147483647.
        Default Value: 20000.
        Types: int
 
        Note: This argument is not required or used when the table to be created
              is not a PTI table. It will be ignored if specified without the timecode_column.
 
    set_table:
        Optional Argument.
        Specifies a flag to determine whether to create a SET or a MULTISET table.
        When True, a SET table is created.
        When False, a MULTISET table is created.
        Default value: False
        Types: boolean
 
        Note: 1. Specifying set_table=True also requires specifying primary_index or timecode_column.
              2. Creating SET table (set_table=True) may result in loss of duplicate rows.
              3. This argument has no effect if the table already exists and if_exists='append'.
 
RETURNS:
    None
 
RAISES:
    TeradataMlException
 
EXAMPLES:
    >>> load_example_data("dataframe","admissions_train")
    >>> df = DataFrame("admissions_train")
    >>> df2 = df[(df.gpa == 4.00)]
    >>> df2.to_sql('to_sql_example', primary_index='id')
    >>> df3 = DataFrame('to_sql_example')
    >>> df3
       masters  gpa     stats programming admitted
    id
    13      no  4.0  Advanced      Novice        1
    29     yes  4.0    Novice    Beginner        0
    15     yes  4.0  Advanced    Advanced        1
    >>>
    >>> # Save as PTI table making sure it is a SET table
    >>> load_example_data("sessionize", "sessionize_table")
    >>> df4 = DataFrame('sessionize_table')
    >>> df4.to_sql("test_copyto_pti",
                   timecode_column='clicktime',
                   columns_list='event',
                   set_table=True
                  )
    >>> df5 = DataFrame('test_copyto_pti')
    >>> df5
                            TD_TIMECODE partition_id adid productid
    event
    click    2009-07-04 09:18:17.000000         1231    1      1001
    click    2009-07-24 04:18:10.000000         1167    2      1001
    click    2009-08-08 02:18:12.000000         9231    3      1001
    click    2009-08-11 00:01:24.000000         9231    3      1001
    page_02  2009-08-22 04:20:05.000000         1039    5      1001
    page_02  2009-08-27 23:03:05.000000         1039    5      1001
    view     2009-02-09 15:17:59.000000         1263    4      1001
    view     2009-03-09 21:17:59.000000         1199    2      1001
    view     2009-03-13 17:17:59.000000         1071    4      1001
    view     2009-03-19 01:17:59.000000         1199    1      1001