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

Teradata® Package for Python User Guide

Product
Teradata Package for Python
Release Number
17.00
Published
November 2021
Language
English (United States)
Last Update
2022-01-14
dita:mapPath
bol1585763678431.ditamap
dita:ditavalPath
ayr1485454803741.ditaval
dita:id
B700-4006
lifecycle
previous
Product Category
Teradata Vantage

The retrieve_byom() API allows a user to retrieve a saved model. Output of this function can be directly passed as input to the PMMLPredict and H2OPredict functions.

Some models, such as H2O-DAI, have licenses associated with the models.

When such models are used for scoring, users must retrieve the model by passing relevant license information. See the license argument for details.

Required Arguments:
  • model_id specifies the unique model identifier of the model to be retrieved.
  • table_name specifies the name of the table to retrieve external model from.
Optional Argument:
  • schema_name 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 the current schema.

License related optional arguments:
  • license specifies either the license key itself or name of the column that contains the license key, based on where the license key is stored:
    • If the license key is stored in a variable, users can pass it as string.

      license contains the license key itself.

    • If the license key is stored in a table, users pass the name of the column containing the license key.

      license contains the name of the column containing the license key. is_license_column must be set to True.

      Also, based on the table where the license information is stored,

      - If the license information is stored in the same model table as that of the model specified in the argument table_name, users only need to specify the name of the column containing the license key.

      - If the license information is stored in a table different from the one specified in the argument table_name, in addition to the column name, users can specify the table name and schema name using license_table_name and license_schema_name respectively.

  • is_license_column specifies whether the argument license is a license key or column name.

    - When set to True, license contains the name of the column that contains the license key.

    - Otherwise, license contains the actual license key.

  • license_table_name specifies the name of the table that holds the license key, if the license key is stored in a table other than the table specified in table_name.
  • license_schema_name specifies the name of the database associated with the license_table_name.

    If not specified, current database is used.

Example Setup

  • Import necessary modules.
    >>> import teradataml, os, datetime
    >>> from teradataml import save_byom, retrieve_byom, get_context
  • Get the model file path.
    >>> model_file = os.path.join(os.path.dirname(teradataml.__file__), "data", "models", "iris_kmeans_model")
  • Save four models with different parameters.
    • Save a model in the same database without license.
      >>> save_byom("model9", model_file, "byom_models")
      Model is saved.
    • Save a model in another database without license.
      >>> save_byom("model6", model_file, "byom_models", schema_name="test")
      Model is saved.
    • Save a model in the same database with associated license stored in a variable.
      >>> save_byom("model5", model_file, "byom_models")
      Model is saved.
    • Save a model in the same database with license key stored in an additional column "license_data" in the same table, for example 4 below.
      >>> save_byom("licensed_model1", model_file, "byom_licensed_models", additional_columns={"license_data": "A5sUL9KU_kP35Vq"})
      Created the model table "byom_licensed_models" as it does not exist.
      Model is saved.
  • Store a license in a variable "lic_key", for "model5" in example 3 below.
    >>> lic_key = "eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI"
    
  • Store a license in a table "license" in the column "license_key", for example 5 below.
    >>> # Store the license in a table.
    >>> lic_table = "create table license (id integer between 1 and 1,license_key varchar(2500)) unique primary index(id);"
    >>> get_context().execute(lic_table)
    <sqlalchemy.engine.cursor.LegacyCursorResult object at 0x0000014AAFF27080>
    >>> get_context().execute("insert into license values (1, "peBVRtjA-ib")")
    <sqlalchemy.engine.cursor.LegacyCursorResult object at 0x0000014AAFF27278>
    This table is also created in databse ""mldb", for example 6 below.

Example 1: Retrieve a model from a specific table

This example retrieves a model with id "model9" from the table "byom_models".

>>> df = retrieve_byom("model9", table_name="byom_models")
>>> df
                             model
model_id
model9    b"504B03041400080808..."

Example 2: Retrieve a model from a specific table in a specific database

This example retrieves a model with id "model6" from the table "byom_models" in the "test" database.

>>> df = retrieve_byom("model6", table_name="byom_models", schema_name="test")
>>> df
                             model
model_id
model6    b"504B03041400080808..."

Example 3: Retrieve a model from a specific table, with license key stored in a variable

This example retrieves a model with id "model5" from the table "byom_models" with license key stored in a variable "lic_key".

>>> df = retrieve_byom("model5", table_name="byom_models", license=lic_key)
>>> df
                             model                                                         license
model_id
model5    b"504B03041400080808..."  eZSy3peBVRtjA-ibVuvNw5A5sUL9KU_kP35Vq4ZNBQ3iGY6oVSpE6g97sFY2LI

Example 4: Retrieve a model from a specific table, with license key stored in the same table

This example retrieves a model with id "licensed_model1" from the table "byom_licensed_models", and associated license key stored in the same table in the column "license_data".

>>> df = retrieve_byom("licensed_model1",
                       table_name="byom_licensed_models",
                       license="license_data",
                       is_license_column=True)
>>> df
                                    model          license
model_id
licensed_model1  b"504B03041400080808..."  A5sUL9KU_kP35Vq

Example 5: Retrieve a model from a specific table, with license key stored in another table in the same database

This example retrieves a model with id "licensed_model1" from the table "byom_licensed_models", and associated license key is stored in the column "license_key" of another table "license".

>>> df = retrieve_byom("licensed_model1",
                       table_name="byom_licensed_models",
                       license="license_key",
                       is_license_column=True,
                       license_table_name="license")
>>> df
                                    model      license
model_id
licensed_model1  b"504B03041400080808..."  peBVRtjA-ib

Example 6: Retrieve a model from a specific table, with license key stored in a table in another database

>>> df = retrieve_byom('licensed_model1',
                       table_name='byom_licensed_models',
                       license='license_key',
                       is_license_column=True,
                       license_table_name='license',
                       license_schema_name='mldb')
>>> df
                                    model      license
model_id
licensed_model1  b'504B03041400080808...'  peBVRtjA-ib