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

Teradata® Package for Python User Guide

Deployment
VantageCloud
VantageCore
Edition
Enterprise
IntelliFlex
VMware
Product
Teradata Package for Python
Release Number
20.00
Published
March 2024
Language
English (United States)
Last Update
2024-04-09
dita:mapPath
nvi1706202040305.ditamap
dita:ditavalPath
plt1683835213376.ditaval
dita:id
rkb1531260709148
Product Category
Teradata Vantage

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 in the following:
    • '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 the following argument description 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' column with type specified in additional_columns_types.

      If type is not specified, table is created with 'model_id' column as VARCHAR(128).

    • 'model' column with type specified in "additional_columns_types".

      If type is 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.
Optional Arguments:
  • 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.

    • You must either specify this argument, or set the byom model catalog table name using set_byom_catalog().
    • If none of them are set, exception is raised; If both of them are set, the settings in save_byom() take precedence and is used for function execution when saving an model.
  • schema_name specifies the name of the schema/database in which the table specified in table_name is looked up.

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

    • You must either specify this argument and the table_name argument, or set the byom model catalog schema name using set_byom_catalog().
    • If none of them are set, exception is raised; If both of them are set, the settings in save_byom() take precedence and is used for function execution when saving an model.
    • If you specify schema_name, table_name has to be specified, else exception is raised.
    The following table shows the system behavior based on different input combinations.
    In save_byom() In set_byom_catalog() System Behavior
    table_name schema_name table_name schema_name
    Set Set Set Set schema_name and table_name in save_byom() are used for function execution.
    Not set Not set schema_name and table_name in save_byom() is used for function execution.
    Not set Set Set table_name from save_byom() is used and schema name associated with the current context is used.
    Not set Set Set Set Exception is raised.
    Not set Set Set table_name and schema_name from set_byom_catalog() are used for function execution.
    Set Not set table_name from set_byom_catalog() is used and schema name associated with the current context is used.
    Not set Not set Exception is raised.
  • 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.
    >>> 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_models" with additional columns by specifying the type of the columns as listed in the following table 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_models1" in the "test" database, with additional columns by not specifying the type of the columns. 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.

Example 4: Use the BYOM model catalog information set at session level by set_byom_catalog()

This example shows when save_byom() function is called without arguments table_name and schema_name, system uses the BYOM model catalog information set at session level by the set_byom_catalog() function.

  • The model cataloging parameters are set using the set_byom_catalog() function.
    >>> 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'
  • The model is saved in the existing table specified by the arguments in set_byom_catalog() function.
    >>> save_byom('model3', model_file=model_file)
    Model is saved.

Example 5: Override session level parameters for BYOM model cataloging

This example shows that you can override the session level BYOM model catalog information set by the set_byom_catalog(), by passing the table as well as schema arguments explicitly.

  • The model cataloging table name is set to 'byom_models' using the set_byom_catalog() function.
    >>> 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'.
  • The model is saved in a different table 'byom_licensed_models' which is specified by the table_name argument in this save_byom() function.
    >>> 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.