Teradata Package for Python Function Reference | 20.00 - save_byom - Teradata Package for Python - Look here for syntax, methods and examples for the functions included in the Teradata Package for Python.
Teradata® Package for Python Function Reference - 20.00
- Deployment
- VantageCloud
- VantageCore
- Edition
- Enterprise
- IntelliFlex
- VMware
- Product
- Teradata Package for Python
- Release Number
- 20.00.00.03
- Published
- December 2024
- ft:locale
- en-US
- ft:lastEdition
- 2024-12-19
- dita:id
- TeradataPython_FxRef_Enterprise_2000
- lifecycle
- latest
- Product Category
- Teradata Vantage
- 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.
>>>