save_byom() | Teradata Package for Python - 17.00 - save_byom() - Teradata Package for Python

Teradata® Package for Python User Guide

Product
Teradata Package for Python
Release Number
17.00
Published
November 2021
Last Update
2022-01-14
Content Type
User Guide
Publication ID
B700-4006-070K
Language
English (United States)
Last Update
2022-01-14

The save_model() API allows a user to save externally trained models in Vantage in a specified table. This function allows users to save various models stored in different formats such as PMML, MOJO, and so on. If the specified model table exists in Vantage, model data is saved in that table. Otherwise, model table is created first based on the user parameters and then model data is saved.

If the user specified table exists, then
  • The table must have at least two columns with names and types as specified below:
    • 'model_id' column of type VARCHAR of any length
    • 'model' column of type BLOB
  • User can choose to have additional columns to store additional information of the model. This information can be passed using additional_columns parameter. See argument description below for details.
If the user specified table does not exist, then
  • This function creates the table with the name specified in table_name.
  • The table is created in the schema specified in schema_name.

    If schema_name is not specified, then current schema is used.

  • The table is created with the following 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.

    • Data types 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.

Required Arguments:
  • model_id specifies the unique model identifier for this model.
  • model_file specifies the absolute path of the file which has model information.
  • table_name specifies the name of the table where model is saved.

    If a table with this table_name does not exist, this function creates the table according to additional_columns and additional_columns_types.

Optional Arguments:
  • schema_name specifies the name of the schema in which the table specified in table_name is looked up.

    If this argument is not specified, then table is looked up in the current schema.

  • additional_columns 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. Allowed types for the values passed in dictionary are:
    • int
    • float
    • str
    • bool
    • datetime.datetime
    • datetime.date
    • datetime.time
    additional_columns does not accept keys model_id and model.
  • additional_columns_types specifies the column type of additional columns. These column types are used while creating the table using the columns specified in the additional_columns argument.

    Additional column datatype information is passed as key value pair, where key is the column name and value is teradatasqlalchemy.types.

    • If any of the column type for additional columns are not specified in additional_columns_types, then it derives the column types. To get more information on column type mapping, refer to parameters using help(save_byom).
    • For columns model_id and model, column type must be mandatorily set to VARCHAR and BLOB respectively for the table. Thus, for the columns model_id and model, acceptable values for additional_columns_types are VARCHAR and BLOB respectively.
    • This argument is ignored if the table exists.

Example Setup

  • Import necessary modules.
    >>> import teradataml, os, datetime
    >>> # import save_byom from teradataml
    >>> from teradataml import save_byom
  • Get the model file path to use in the examples.
    >>> # Get the model file path to use it in examples
    >>> model_file = os.path.join(os.path.dirname(teradataml.__file__), "data", "models", "iris_kmeans_model")

Example 1: Create a table with additional columns and column types specified

This example creates a 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 a table with additional columns and column types not specified

This example creates a table "byom_model1" in the "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 a model in an existing table

This example saves a model in the existing table "byom_models".

>>> save_byom("model2",
              model_file,
              "byom_models",
              additional_columns={"Description": "KMeans model duplicated"}
              )
Model is saved.