teradataml.catalog.byom.save_byom = save_byom(model_id, model_file, table_name=None, 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.
    
    Notes:
        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:
        Optional 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".
        Notes:
            * One must either specify this argument or set the byom model catalog table
                name using set_byom_catalog().
            * If none of these arguments are set, exception is raised; If both arguments
                are set, the settings in save_byom() take precedence and is used for
                function execution when saving an model.
        Types: str
 
    schema_name:
        Optional Argument.
        Specifies the name of the schema/database in which the table specified in
        "table_name" is looked up.
        Notes:
            * One must either specify this argument and table_name argument
                or set the byom model catalog schema and table name using set_byom_catalog().
            * If none of these arguments are set, exception is raised; If both arguments
                are set, the settings in save_byom() take precedence and is used for
                function execution when saving an model.
            * If user specifies schema_name argument table_name argument has to be specified,
                else exception is raised.
        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.
    >>>
 
    # Example 3 - Set the cataloging parameters and save the model
    #             in the existing table "byom_models".
    >>> set_byom_catalog(table_name='byom_models', schema_name='alice')
    The model cataloging parameters are set to table_name='byom_models' and schema_name='alice'
    >>> save_byom('model3', model_file=model_file)
    Model is saved.
 
    # Example 4 - Set the cataloging table_name to 'byom_models'
    #             and save the model in table 'byom_licensed_models' other than model catalog table.
    >>> set_byom_catalog(table_name='byom_models', schema_name='alice')
    The model cataloging parameters are set to table_name='byom_models' and schema_name='alice'
    >>> save_byom('licensed_model2', model_file=model_file, table_name='byom_licensed_models',
    ...           additional_columns={"license_data": "A5sUL9KU_kP35Vq"})
    Created the model table 'byom_licensed_models' as it does not exist.
    Model is saved.
    >>>