Teradata Package for Python Function Reference - 17.00 - __init__ - 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.table_operators.Script.__init__ = __init__(self, data=None, script_name=None, files_local_path=None, script_command=None, delimiter='\t', returns=None, auth=None, charset=None, quotechar=None, data_partition_column=None, data_hash_column=None, data_order_column=None, is_local_order=False, sort_ascending=True, nulls_first=True)
DESCRIPTION:
    The Script table operator function executes a user-installed script or
    any LINUX command inside database on Teradata Vantage.
 
PARAMETERS:
    script_command:
        Required Argument.
        Specifies the command/script to run.
        Types: str
 
    script_name:
        Required Argument.
        Specifies the name of user script.
        User script should have at least permissions of mode 644.
        Types: str
 
    files_local_path:
        Required Argument.
        Specifies the absolute local path where user script and all supporting
        files like model files, input data file reside.
        Types: str
 
    returns:
        Required Argument.
        Specifies output column definition.
        Types: Dictionary specifying column name to teradatasqlalchemy type mapping.
        Default: None
        Note:
            User can pass a dictionary (dict or OrderedDict) to the "returns" argument,
            with the keys ordered to represent the order of the output columns.
            Preferred type is OrderedDict.
 
    data:
        Optional Argument.
        Specifies a teradataml DataFrame containing the input data for the
        script.
 
    data_hash_column:
        Optional Argument.
        Specifies the column to be used for hashing.
        The rows in the data are redistributed to AMPs based on the hash value of
        the column specified.
        The user-installed script file then runs once on each AMP.
        If there is no "data_partition_column", then the entire result set,
        delivered by the function, constitutes a single group or partition.
        Types: str
        Note:
            "data_hash_column" can not be specified along with
            "data_partition_column", "is_local_order" and "data_order_column".
 
    data_partition_column:
        Optional Argument.
        Specifies Partition By columns for "data".
        Values to this argument can be provided as a list, if multiple
        columns are used for partition.
        Default Value: ANY
        Types: str OR list of Strings (str)
        Note:
            1) "data_partition_column" can not be specified along with
               "data_hash_column".
            2) "data_partition_column" can not be specified along with
               "is_local_order = True".
 
    is_local_order:
        Optional Argument.
        Specifies a boolean value to determine whether the input data is to be
        ordered locally or not. Order by specifies the order in which the
        values in a group, or partition, are sorted. Local Order By specifies
        orders qualified rows on each AMP in preparation to be input to a table
        function. This argument is ignored, if "data_order_column" is None. When
        set to True, data is ordered locally.
        Default Value: False
        Types: bool
        Note:
            1) "is_local_order" can not be specified along with "data_hash_column".
            2) When "is_local_order" is set to True, "data_order_column" should be
               specified, and the columns specified in "data_order_column" are
               used for local ordering.
 
    data_order_column:
        Optional Argument.
        Specifies Order By columns for "data".
        Values to this argument can be provided as a list, if multiple
        columns are used for ordering. This argument is used with in both cases:
        "is_local_order = True" and "is_local_order = False".
        Types: str OR list of Strings (str)
        Note:
            "data_order_column" can not be specified along with "data_hash_column".
 
    sort_ascending:
        Optional Argument.
        Specifies a boolean value to determine if the result set is to be sorted
        on the "data_order_column" column in ascending or descending order.
        The sorting is ascending when this argument is set to True, and descending
        when set to False. This argument is ignored, if "data_order_column" is
        None.
        Default Value: True
        Types: bool
 
    nulls_first:
        Optional Argument.
        Specifies a boolean value to determine whether NULLS are listed first or
        last during ordering. This argument is ignored, if "data_order_column" is
        None. NULLS are listed first when this argument is set to True, and last
        when set to False.
        Default Value: True
        Types: bool
 
    delimiter:
        Optional Argument.
        Specifies a delimiter to use when reading columns from a row and
        writing result columns.
        Default Value: "        " (tab)
        Types: str of length 1 character
        Notes:
            1) This argument cannot be same as "quotechar" argument.
            2) This argument cannot be a newline character i.e., '\n'.
 
    auth:
        Optional Argument.
        Specifies an authorization to use when running the script.
        Types: str
 
    charset:
        Optional Argument.
        Specifies the character encoding for data.
        Permitted Values: utf-16, latin
        Types: str
 
    quotechar:
        Optional Argument.
        Specifies a character that forces all input and output of the script
        to be quoted using this specified character.
        Using this argument enables the Advanced SQL Engine to distinguish
        between NULL fields and empty strings. A string with length zero is
        quoted, while NULL fields are not.
        If this character is found in the data, it will be escaped by a second
        quote character.
        Types: character of length 1
        Notes:
            1) This argument cannot be same as "delimiter" argument.
            2) This argument cannot be a newline character i.e., '\n'.
 
RETURNS:
    Script Object
 
RAISES:
    TeradataMlException
 
EXAMPLES:
    # Note - Refer to User Guide for setting search path and required permissions.
    # Load example data.
    load_example_data("Script", ["barrier"])
 
    # Example - The script mapper.py reads in a line of text input
    # ("Old Macdonald Had A Farm") from csv and splits the line into individual
    # words, emitting a new row for each word.
 
    # Create teradataml DataFrame objects.
    >>> barrierdf = DataFrame.from_table("barrier")
 
    # Set SEARCHUIFDBPATH.
    >>> get_context().execute("SET SESSION SEARCHUIFDBPATH = alice;")
 
    # Create a Script object that allows us to execute script on Vantage.
    >>> import teradataml, os
    >>> from teradatasqlalchemy import VARCHAR
    >>> td_path = os.path.dirname(teradataml.__file__)
    >>> sto = Script(data=barrierdf,
    ...              script_name='mapper.py',
    ...              files_local_path= os.path.join(td_path, 'data', 'scripts'),
    ...              script_command='python ./alice/mapper.py',
    ...              data_order_column="Id",
    ...              is_local_order=False,
    ...              nulls_first=False,
    ...              sort_ascending=False,
    ...              charset='latin',
    ...              returns=OrderedDict([("word", VARCHAR(15)),("count_input", VARCHAR(2))]))
 
    # Run user script locally within docker container and using data from csv.
    # This helps the user to fix script level issues outside Vantage.
    # Setup the environment by providing local path to docker image file.
    >>> sto.setup_sto_env(docker_image_location='/tmp/sto_sandbox_docker_image.tar'))
    Loading image from /tmp/sto_sandbox_docker_image.tar. It may take few minutes.
    Image loaded successfully.
    Starting a container for stosandbox:1.0 image.
    Container d7c73cb498c79a082180576bb5b10bb07b52efdd3026856146fc15e91147b19f
    started successfully.
 
    >>> sto.test_script(input_data_file='../barrier.csv', data_file_delimiter=',')
 
    ############ STDOUT Output ############
 
            word  count_input
    0          1            1
    1        Old            1
    2  Macdonald            1
    3        Had            1
    4          A            1
    5       Farm            1
    >>>
 
    # Script results look good. Now install file on Vantage.
    >>> sto.install_file(file_identifier='mapper',
    ...                  file_name='mapper.py',
    ...                  is_binary=False)
    File mapper.py installed in Vantage
 
    # Execute the user script on Vantage.
    >>> sto.execute_script()
    ############ STDOUT Output ############
 
            word count_input
    0  Macdonald           1
    1          A           1
    2       Farm           1
    3        Had           1
    4        Old           1
    5          1           1
 
    # Remove the installed file from Vantage.
    >>> sto.remove_file(file_identifier='mapper', force_remove=True)
    File mapper removed from Vantage