teradataml.catalog.byom.save_byom = save_byom(model_id, model_file, table_name, schema_name=None, additional_columns=None, additional_columns_types=None)

DESCRIPTION:
    Function to save externally trained models in Teradata Vantage in the
    specified table. Function allows user to save various models stored in
    different formats such as PMML, MOJO etc. If the specified model table
    exists in Vantage, model data is saved in the same, otherwise model table
    is created first based on the user parameters and then model data is
    saved. See below 'Note' section for more details.
 
    Note:
        If user specified table exists, then
            a. Table must have at least two columns with names and types as
               specified below:
               * 'model_id' of type VARCHAR of any length and
               * 'model' column of type BLOB.
            b. User can choose to have the additional columns as well to store
               additional information of the model. This information can be passed
               using "additional_columns" parameter. See "additional_columns"
               argument description for more details.
        If user specified table does not exist, then
            a. Function creates the table with the name specified in "table_name".
            b. Table is created in the schema specified in "schema_name". If
               "schema_name" is not specified, then current schema is considered
               for "schema_name".
            c. Table is created with columns:
                * 'model_id' with type specified in "additional_columns_types". If
                  not specified, table is created with 'model_id' column as VARCHAR(128).
                * 'model' with type specified in "additional_columns_types". If
                  not specified, table is created with 'model' column as BLOB.
                * Columns specified in "additional_columns" parameter. See "additional_columns"
                  argument description for more details.
                * Datatypes of these additional columns are either taken from
                  the values passed to "additional_columns_types" or inferred
                  from the values passed to the "additional_columns". See
                  "additional_columns_types" argument description for more details.
 
PARAMETERS:
    model_id:
        Required Argument.
        Specifies the unique model identifier for model.
        Types: str.
 
    model_file:
        Required Argument.
        Specifies the absolute path of the file which has model information.
        Types: str
 
    table_name:
        Required Argument.
        Specifies the name of the table where model is saved. If "table_name"
        does not exist, this function creates table according to "additional_columns"
        and "additional_columns_types".
        Types: str
 
    schema_name:
        Optional Argument.
        Specifies the name of the schema in which the table specified in
        "table_name" is looked up. If not specified, then table is looked
        up in current schema.
        Types: str
 
    additional_columns:
        Optional Argument.
        Specifies the additional information about the model to be saved in the
        model table. Additional information about the model is passed as key value
        pair, where key is the name of the column and value is data to be stored
        in that column for the model being saved.
        Notes:
             1. Following are the allowed types for the values passed in dictionary:
                * int
                * float
                * str
                * bool
                * datetime.datetime
                * datetime.date
                * datetime.time
             2. "additional_columns" does not accept keys model_id and model.
        Types: str
 
    additional_columns_types:
        Optional Argument.
        Specifies the column type of additional columns. These column types are used
        while creating the table using the columns specified in "additional_columns"
        argument. Additional column datatype information is passed as key value pair
        with key being the column name and value as teradatasqlalchemy.types.
        Notes:
             1. If, any of the column type for additional columns are not specified in
                "additional_columns_types", it then derives the column type according
                the below table:
                +---------------------------+-----------------------------------------+
                |     Python Type           |        teradatasqlalchemy Type          |
                +---------------------------+-----------------------------------------+
                | str                       | VARCHAR(1024)                           |
                +---------------------------+-----------------------------------------+
                | int                       | INTEGER                                 |
                +---------------------------+-----------------------------------------+
                | bool                      | BYTEINT                                 |
                +---------------------------+-----------------------------------------+
                | float                     | FLOAT                                   |
                +---------------------------+-----------------------------------------+
                | datetime                  | TIMESTAMP                               |
                +---------------------------+-----------------------------------------+
                | date                      | DATE                                    |
                +---------------------------+-----------------------------------------+
                | time                      | TIME                                    |
                +---------------------------+-----------------------------------------+
             2. Columns model_id, with column type as VARCHAR and model, with column type
                as BLOB are mandatory for table. So, for the columns model_id and model,
                acceptable values for "additional_columns_types" are VARCHAR and BLOB
                respectively.
             3. This argument is ignored if table exists.
        Types: dict
 
RETURNS:
    None.
 
RAISES:
    TeradataMlException, TypeError, ValueError
 
EXAMPLES:
 
    >>> import teradataml, os, datetime
    >>> model_file = os.path.join(os.path.dirname(teradataml.__file__), 'data', 'models', 'iris_kmeans_model')
    >>> from teradataml import save_byom
 
    # Example 1 - Create table "byom_model" with additional columns by specifying the type
    #             of the columns as below and save the model in it.
    #             +---------------------------+-----------------------------------------+
    #             |     Column name           |        Column Type                      |
    #             +---------------------------+-----------------------------------------+
    #             | model_id                  | VARCHAR(128)                            |
    #             +---------------------------+-----------------------------------------+
    #             | model                     | BLOB                                    |
    #             +---------------------------+-----------------------------------------+
    #             | Description               | VARCHAR(2000)                           |
    #             +---------------------------+-----------------------------------------+
    #             | UserId                    | NUMBER(5)                               |
    #             +---------------------------+-----------------------------------------+
    #             | ProductionReady           | BYTEINT                                 |
    #             +---------------------------+-----------------------------------------+
    #             | ModelEfficiency           | NUMBER(11,10)                           |
    #             +---------------------------+-----------------------------------------+
    #             | ModelSavedTime            | TIMESTAMP                               |
    #             +---------------------------+-----------------------------------------+
    #             | ModelGeneratedDate        | DATE                                    |
    #             +---------------------------+-----------------------------------------+
    #             | ModelGeneratedTime        | TIME                                    |
    #             +---------------------------+-----------------------------------------+
    #
    >>> save_byom('model1',
    ...           model_file,
    ...           'byom_models',
    ...           additional_columns={"Description": "KMeans model",
    ...                               "UserId": "12345",
    ...                               "ProductionReady": False,
    ...                               "ModelEfficiency": 0.67412,
    ...                               "ModelSavedTime": datetime.datetime.now(),
    ...                               "ModelGeneratedDate":datetime.date.today(),
    ...                               "ModelGeneratedTime": datetime.time(hour=0,minute=5,second=45,microsecond=110)
    ...                               },
    ...           additional_columns_types={"Description": VARCHAR(2000),
    ...                                    "UserId": NUMBER(5),
    ...                                    "ProductionReady": BYTEINT,
    ...                                    "ModelEfficiency": NUMBER(11,10),
    ...                                    "ModelSavedTime": TIMESTAMP,
    ...                                    "ModelGeneratedDate": DATE,
    ...                                    "ModelGeneratedTime": TIME}
    ...           )
    Created the table 'byom_models' as it does not exist.
    Model is saved.
    >>>
 
    # Example 2 - Create table "byom_model1" in "test" DataBase, with additional columns
    #             by not specifying the type of the columns and once table is created,
    #             save the model in it.
    >>> save_byom('model1',
    ...           model_file,
    ...           'byom_models1',
    ...           additional_columns={"Description": "KMeans model",
    ...                               "UserId": "12346",
    ...                               "ProductionReady": False,
    ...                               "ModelEfficiency": 0.67412,
    ...                               "ModelSavedTime": datetime.datetime.now(),
    ...                               "ModelGeneratedDate":datetime.date.today(),
    ...                               "ModelGeneratedTime": datetime.time(hour=0,minute=5,second=45,microsecond=110)
    ...                               },
    ...           schema_name='test'
    ...           )
    Created the table 'byom_models1' as it does not exist.
    Model is saved.
    >>>
 
    # Example 3 - Save the model in the existing table "byom_models".
    >>> save_byom('model2',
    ...           model_file,
    ...           'byom_models',
    ...           additional_columns={"Description": "KMeans model duplicated"}
    ...           )
    Model is saved.
    >>>